EVT_UCX_USBDEVICE_ENDPOINT_ADD funzione di callback (ucxusbdevice.h)

Articolo
02/29/2024

Implementazione del driver client che UCX chiama per aggiungere un nuovo endpoint per un dispositivo USB.

Sintassi

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
)
{...}

Parametri

[in] UcxController

Handle al controller UCX ricevuto dal driver client in una chiamata precedente al metodo UcxControllerCreate .

[in] UcxUsbDevice

Handle a un oggetto UCX che rappresenta il dispositivo USB.

[in] UsbEndpointDescriptor

Puntatore a una posizione contenente un descrittore USB per l'endpoint creato.

[in] UsbEndpointDescriptorBufferLength

Lunghezza in byte del descrittore.

[in, optional] SuperSpeedEndpointCompanionDescriptor

Descrittore aggiuntivo per una porta con velocità superiore. Questo parametro è facoltativo e può essere NULL.

[in] UcxEndpointInit

Puntatore a una struttura opaca contenente informazioni di inizializzazione. I callback per l'oggetto endpoint sono associati a questa struttura. Questa struttura è gestita da UCX.

Valore restituito

Se l'operazione ha esito positivo, la funzione di callback deve restituire STATUS_SUCCESS o un altro valore di stato per cui NT_SUCCESS(stato) equivale a TRUE. In caso contrario, deve restituire un valore di stato per il quale NT_SUCCESS(stato) equivale a FALSE.

Commenti

Il driver client UCX registra questa funzione di callback con l'estensione del controller host USB (UCX) chiamando il metodo UcxUsbDeviceCreate .

La funzione di callback chiama UcxEndpointCreate per creare un nuovo oggetto endpoint e registrare le funzioni di callback dell'oggetto endpoint.

La funzione di callback crea in genere una coda WDF associata all'oggetto endpoint. La coda non riceve richieste fino all'avvio dell'estensione della classe.

Esempio

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;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Windows
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	ucxusbdevice.h (include Ucxclass.h)
IRQL	PASSIVE_LEVEL