EVT_SERCX2_APPLY_CONFIG 콜백 함수(sercx.h)

EvtSerCx2ApplyConfig 이벤트 콜백 함수는 직렬 컨트롤러 하드웨어에 적용할 디바이스별 구성 설정 목록을 직렬 컨트롤러 드라이버에 공급하기 위해 SerCx2(직렬 프레임워크 확장) 버전 2에서 호출됩니다.

통사론

EVT_SERCX2_APPLY_CONFIG EvtSercx2ApplyConfig;

NTSTATUS EvtSercx2ApplyConfig(
  [in] WDFDEVICE Device,
  [in] PVOID ConnectionParameters
)
{...}

매개 변수

[in] Device

직렬 컨트롤러를 나타내는 프레임워크 디바이스 개체에 대한 WDFDEVICE 핸들입니다. 직렬 컨트롤러 드라이버는 EvtDriverDeviceAdd 콜백 함수에서 이 개체를 만들었습니다. 자세한 내용은 SerCx2InitializeDevice참조하세요.

[in] ConnectionParameters

연결 매개 변수 구조에 대한 포인터입니다. 이 함수는 포인터를 적절한 포인터 형식으로 캐스팅하고, 데이터 구조를 구문 분석하여 구성 설정을 가져오고, 이러한 설정을 직렬 컨트롤러 하드웨어에 적용해야 합니다. 연결 매개 변수 구조는 하드웨어 플랫폼 공급업체에 의해 정의되며 SerCx2와 운영 체제 모두에 불투명합니다. 자세한 내용은 비고를 참조하세요.

반환 값

EvtSerCx2ApplyConfig 함수는 호출에 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 적절한 오류 상태 코드를 반환합니다.

발언

직렬 컨트롤러 드라이버는 이 함수를 구현해야 합니다. 드라이버는 직렬 컨트롤러에 대한 프레임워크 디바이스 개체의 초기화를 완료하는 SerCx2InitializeDevice 메서드 호출에 함수를 등록합니다.

SerCx2는 직렬 컨트롤러를 초기화하는 동안 EvtSerCx2ApplyConfig 함수를 호출하여 하드웨어가 유효한 초기 상태인지 확인합니다. 또한 이 함수는 클라이언트가 직렬 컨트롤러에 IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION 요청을 보낼 때마다 호출됩니다.

SerCx2는 직렬 컨트롤러 디바이스에 대한 ACPI 리소스 설명자의 공급업체 정의 데이터 필드에서 구성 매개 변수를 가져옵니다. ACPI 펌웨어가 이러한 구성 설정을 저장하는 데 사용하는 데이터 형식은 직렬 컨트롤러 드라이버에서 예상한 것과 동일한 데이터 형식이어야 합니다. 자세한 내용은 ACPI 5.0 사양UART 직렬 버스 연결 설명자 대한 설명을 참조하세요.

클라이언트가 SerCx2에서 관리하는 직렬 포트에 IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION 요청을 보내면 SerCx2는 EvtSerCx2ApplyConfig 함수를 호출하여 구성 매개 변수를 직렬 컨트롤러 드라이버에 전달합니다. 이 콜백이 반환되면 SerCx2는 요청을 완료하고 콜백의 반환 값을 요청에 대한 상태 코드로 사용합니다.

예제

EvtSerCx2ApplyConfig 콜백 함수를 정의하려면 먼저 정의하는 콜백 함수의 형식을 식별하는 함수 선언을 제공해야 합니다. Windows는 드라이버에 대한 콜백 함수 형식 집합을 제공합니다. 콜백 함수 형식을 사용하여 함수를 선언하면 드라이버, SDV(정적 드라이버 검증 도구) 및 기타 확인 도구에 대한 코드 분석을 데 도움이 되며 Windows 운영 체제용 드라이버를 작성하기 위한 요구 사항입니다.

예를 들어 명명된 MyApplyConfig 콜백 함수를 정의하려면 이 코드 예제와 같이 EVT_SERCX2_APPLY_CONFIG 함수 형식을 사용합니다.

EVT_SERCX2_APPLY_CONFIG  MyApplyConfig;

그런 다음 다음과 같이 콜백 함수를 구현합니다.

_Use_decl_annotations_
NTSTATUS
  MyApplyConfig(
    WDFDEVICE  Device,
    PVOID  ConnectionParameters
    )
  {...}

EVT_SERCX2_APPLY_CONFIG 함수 형식은 Sercx.h 헤더 파일에 정의됩니다. 코드 분석 도구를 실행할 때 오류를 보다 정확하게 식별하려면 함수 정의에 Use_decl_annotations 주석을 추가해야 합니다. Use_decl_annotations 주석은 헤더 파일의 EVT_SERCX2_APPLY_CONFIG 함수 형식에 적용되는 주석이 사용되는지 확인합니다. 함수 선언 요구 사항에 대한 자세한 내용은 KMDF 드라이버함수 역할 형식을 사용하여 함수 선언을 참조하세요. Use_decl_annotations대한 자세한 내용은 함수 동작주석을 참조하세요.

다음 코드 예제에서는 UART에 대한 EvtSerCx2ApplyConfig 함수의 부분 구현을 보여 줍니다.

//
// Define the UART ACPI descriptor, plus any vendor-specific
// data that is needed by the serial controller (UART) driver.
//

#define ANYSIZE_ARRAY 1
#include <pshpack1.h>

//
// Common resource name descriptor
//
typedef struct _PNP_IO_DESCRIPTOR_RESOURCE_NAME {
    UCHAR ResourceIndex;
    UCHAR ResourceName[ANYSIZE_ARRAY];
} PNP_IO_DESCRIPTOR_RESOURCE_NAME, *PPNP_IO_DESCRIPTOR_RESOURCE_NAME;

//
// Bus descriptor for a UART
//
typedef struct _PNP_UART_SERIAL_BUS_DESCRIPTOR {
    PNP_SERIAL_BUS_DESCRIPTOR SerialBusDescriptor;
    ULONG BaudRate;
    USHORT RxBufferSize;
    USHORT TxBufferSize;
    UCHAR Parity;
    // Include any optional vendor data here:
    ...
    // Append the PNP_IO_DESCRIPTOR_RESOURCE_NAME here:
    ....
} PNP_UART_SERIAL_BUS_DESCRIPTOR, *PPNP_UART_SERIAL_BUS_DESCRIPTOR;

#include <poppack.h>

EVT_SERCX_APPLY_CONFIG MyApplyConfig;

//
// Implementation of an EvtSerCx2ApplyConfig callback function
//
_Use_decl_annotations_
VOID
  MyApplyConfig(
    WDFDEVICE Device,
    PVOID ConnectionParameters
    )
{
    NTSTATUS status = STATUS_SUCCESS; 
    PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER connection;
    PPNP_SERIAL_BUS_DESCRIPTOR descriptor;
    PPNP_UART_SERIAL_BUS_DESCRIPTOR uartDescriptor;

    if (ConnectionParameters == NULL)
    {
        status = STATUS_INVALID_PARAMETER; 
    }

    if (NT_SUCCESS(status))
    {
        connection = (PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER)ConnectionParameters;

        if (connection->PropertiesLength < sizeof(PNP_SERIAL_BUS_DESCRIPTOR))
        {
            status = STATUS_INVALID_PARAMETER;
        }
    }

    if (NT_SUCCESS(status))
    {
        descriptor = (PPNP_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties;

        if (descriptor->SerialBusType != UART_SERIAL_BUS_TYPE)
        {
            status = STATUS_INVALID_PARAMETER;
        }
    }

    if (NT_SUCCESS(status))
    {
        uartDescriptor = (PPNP_UART_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties; 

        // Apply the platform-specific configuration settings
        // from the UART descriptor here:
        ...
    }

    return status;
}

이전 코드 예제의 pshpack1.h 및 poppack.h 헤더 파일은 컴파일러에서 사용하는 구조체 맞춤 모드를 제어합니다. PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER 및 PPNP_SERIAL_BUS_DESCRIPTOR 포인터 형식은 RH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER 및 PNP_SERIAL_BUS_DESCRIPTOR 구조체에 대한 포인터입니다. PNP_UART_SERIAL_BUS_DESCRIPTOR 구조체의 멤버에 대한 자세한 내용은 ACPI 5.0 사양표 6-193을 참조하세요.

요구 사항

참고 항목

IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION

PNP_SERIAL_BUS_DESCRIPTOR

RH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER

SerCx2InitializeDevice