EVT_UCX_USBDEVICE_ENDPOINT_ADD 콜백 함수(ucxusbdevice.h)

아티클
02/26/2024

UCX가 USB 디바이스에 대한 새 엔드포인트를 추가하기 위해 호출하는 클라이언트 드라이버의 구현입니다.

구문

EVT_UCX_USBDEVICE_ENDPOINT_ADD EvtUcxUsbdeviceEndpointAdd;

NTSTATUS EvtUcxUsbdeviceEndpointAdd(
  [in]           UCXCONTROLLER UcxController,
  [in]           UCXUSBDEVICE UcxUsbDevice,
  [in]           PUSB_ENDPOINT_DESCRIPTOR UsbEndpointDescriptor,
  [in]           ULONG UsbEndpointDescriptorBufferLength,
  [in, optional] PUSB_SUPERSPEED_ENDPOINT_COMPANION_DESCRIPTOR SuperSpeedEndpointCompanionDescriptor,
  [in]           PUCXENDPOINT_INIT UcxEndpointInit
)
{...}

매개 변수

[in] UcxController

UcxControllerCreate 메서드에 대한 이전 호출에서 클라이언트 드라이버가 받은 UCX 컨트롤러에 대한 핸들입니다.

[in] UcxUsbDevice

USB 디바이스를 나타내는 UCX 개체에 대한 핸들입니다.

[in] UsbEndpointDescriptor

생성되는 엔드포인트에 대한 USB 설명자가 포함된 위치에 대한 포인터입니다.

[in] UsbEndpointDescriptorBufferLength

설명자의 길이(바이트)입니다.

[in, optional] SuperSpeedEndpointCompanionDescriptor

초고속 포트에 대한 추가 설명자입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

[in] UcxEndpointInit

초기화 정보를 포함하는 불투명 구조체에 대한 포인터입니다. 엔드포인트 개체에 대한 콜백은 이 구조체와 연결됩니다. 이 구조체는 UCX에서 관리됩니다.

반환 값

작업이 성공하면 콜백 함수는 STATUS_SUCCESS 반환하거나 NT_SUCCESS(상태)이 TRUE인 다른 상태 값을 반환해야 합니다. 그렇지 않으면 NT_SUCCESS(상태)가 FALSE와 같은 상태 값을 반환해야 합니다.

설명

UCX 클라이언트 드라이버는 UcxUsbDeviceCreate 메서드를 호출하여 이 콜백 함수를 UCX(USB 호스트 컨트롤러 확장)에 등록합니다.

콜백 함수는 UcxEndpointCreate 를 호출하여 새 엔드포인트 개체를 만들고 엔드포인트 개체 콜백 함수를 등록합니다.

그런 다음 콜백 함수는 일반적으로 엔드포인트 개체와 연결된 WDF 큐를 만듭니다. 큐는 클래스 확장이 시작될 때까지 요청을 받지 않습니다.

예제

NTSTATUS
Endpoint_EvtUcxUsbDeviceEndpointAdd(
    UCXCONTROLLER                                   UcxController,
    UCXUSBDEVICE                                    UcxUsbDevice,
    PUSB_ENDPOINT_DESCRIPTOR                        UsbEndpointDescriptor,
    ULONG                                           UsbEndpointDescriptorBufferLength,
    PUSB_SUPERSPEED_ENDPOINT_COMPANION_DESCRIPTOR   SuperSpeedEndpointCompanionDescriptor,
    PUCXENDPOINT_INIT                               UcxEndpointInit
)

{
    NTSTATUS                        status = STATUS_SUCCESS;

    UCX_ENDPOINT_EVENT_CALLBACKS    ucxEndpointEventCallbacks;
    WDF_OBJECT_ATTRIBUTES           objectAttributes;

    PUCX_CONTROLLER_CONTEXT         ucxControllerContext;

    UCXENDPOINT                     ucxEndpoint;
    PUCX_ENDPOINT_CONTEXT           ucxEndpointContext;

    WDF_IO_QUEUE_CONFIG             queueConfig;

    UNREFERENCED_PARAMETER(UsbEndpointDescriptor);
    UNREFERENCED_PARAMETER(UsbEndpointDescriptorBufferLength);
    UNREFERENCED_PARAMETER(SuperSpeedEndpointCompanionDescriptor);

    UCX_ENDPOINT_EVENT_CALLBACKS_INIT(&ucxEndpointEventCallbacks,
                                      Endpoint_EvtUcxEndpointPurge,
                                      Endpoint_EvtUcxEndpointStart,
                                      Endpoint_EvtUcxEndpointAbort,
                                      Endpoint_EvtUcxEndpointReset,
                                      Endpoint_EvtUcxEndpointOkToCancelTransfers,
                                      Endpoint_EvtUcxEndpointStaticStreamsAdd,
                                      Endpoint_EvtUcxEndpointStaticStreamsEnable,
                                      Endpoint_EvtUcxEndpointStaticStreamsDisable,
                                      Endpoint_EvtUcxEndpointEnableForwardProgress);

    UcxEndpointInitSetEventCallbacks(UcxEndpointInit, &ucxEndpointEventCallbacks);

    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&objectAttributes, UCX_ENDPOINT_CONTEXT);

    ucxControllerContext = GetUcxControllerContext(UcxController);

    status = UcxEndpointCreate(UcxUsbDevice,
        &UcxEndpointInit,
        &objectAttributes,
        &ucxEndpoint);

    if (!NT_SUCCESS(status)) {
        DbgTrace(TL_ERROR, Endpoint, "UcxEndpoint Failed %!STATUS!", status);
        goto EvtUsbDeviceEndpointAddEnd;
    }

    DbgTrace(TL_INFO, Endpoint, "UcxEndpoint created");

    ucxEndpointContext = GetUcxEndpointContext(ucxEndpoint);

    ucxEndpointContext->IsDefault = FALSE;
    ucxEndpointContext->MaxPacketSize = MAX_PACKET_SIZE;

    WDF_IO_QUEUE_CONFIG_INIT(&queueConfig, WdfIoQueueDispatchManual);

    status = WdfIoQueueCreate(ucxControllerContext->WdfDevice,
        &queueConfig,
        WDF_NO_OBJECT_ATTRIBUTES,
        &ucxEndpointContext->IoQueue);

    if (!NT_SUCCESS(status)) {
        DbgTrace(TL_ERROR, Endpoint, "WdfIoQueueCreate Failed %!STATUS!", status);
        goto EvtUsbDeviceEndpointAddEnd;
    }

    UcxEndpointSetWdfIoQueue(ucxEndpoint, ucxEndpointContext->IoQueue);

EvtUsbDeviceEndpointAddEnd:

    return status;
}