EVT_UCX_CONTROLLER_USBDEVICE_ADD callback function (ucxcontroller.h)

Article
02/22/2024

The client driver's implementation that UCX calls when a new USB device is detected.

Syntax

EVT_UCX_CONTROLLER_USBDEVICE_ADD EvtUcxControllerUsbdeviceAdd;

NTSTATUS EvtUcxControllerUsbdeviceAdd(
  [in] UCXCONTROLLER UcxController,
  [in] PUCXUSBDEVICE_INFO UcxUsbDeviceInfo,
  [in] PUCXUSBDEVICE_INIT UsbDeviceInit
)
{...}

Parameters

[in] UcxController

A handle to the UCX controller that the client driver received in a previous call to the UcxControllerCreate method.

[in] UcxUsbDeviceInfo

Pointer to a UCXUSBDEVICE_INFO structure.

[in] UsbDeviceInit

Pointer to an opaque structure containing initialization information. Callbacks for the device object are associated with this structure. This structure is managed by UCX.

Return value

If the operation is successful, the callback function must return STATUS_SUCCESS, or another status value for which NT_SUCCESS(status) equals TRUE. Otherwise it must return a status value for which NT_SUCCESS(status) equals FALSE.

Remarks

The UCX client driver registers its EVT_UCX_CONTROLLER_USBDEVICE_ADD implementation with the USB host controller extension (UCX) by calling the UcxControllerCreate method.

This callback function creates a new USB device object and registers the USB device object callback functions by calling UcxUsbDeviceCreate. The function may need to allocate the common buffer that will be used as the device context.

Examples

NTSTATUS
UsbDevice_EvtControllerUsbDeviceAdd(
    UCXCONTROLLER       UcxController,
    PUCXUSBDEVICE_INFO  UsbDeviceInfo,
    PUCXUSBDEVICE_INIT  UsbDeviceInit
)

{
    NTSTATUS                        status = STATUS_SUCCESS;

    WDF_OBJECT_ATTRIBUTES           objectAttributes;
    UCX_USBDEVICE_EVENT_CALLBACKS   callbacks;

    UCXUSBDEVICE                    ucxUsbDevice;
    PUCX_USB_DEVICE_CONTEXT         ucxUsbDeviceContext;

    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&objectAttributes, UCX_USB_DEVICE_CONTEXT);

    //
    // Set the event callbacks for the USB device.
    //
    UCX_USBDEVICE_EVENT_CALLBACKS_INIT(&callbacks,
                                       UsbDevice_EvtUcxUsbDeviceEndpointsConfigure,
                                       UsbDevice_EvtUcxUsbDeviceEnable,
                                       UsbDevice_EvtUcxUsbDeviceDisable,
                                       UsbDevice_EvtUcxUsbDeviceReset,
                                       UsbDevice_EvtUcxUsbDeviceAddress,
                                       UsbDevice_EvtUcxUsbDeviceUpdate,
                                       UsbDevice_EvtUcxUsbDeviceHubInfo,
                                       Endpoint_EvtUcxUsbDeviceDefaultEndpointAdd,
                                       Endpoint_EvtUcxUsbDeviceEndpointAdd);

    UcxUsbDeviceInitSetEventCallbacks(UsbDeviceInit, &callbacks);

    //
    // Create the device
    //
    status = UcxUsbDeviceCreate(UcxController,
                                &UsbDeviceInit,
                                &objectAttributes,
                                &ucxUsbDevice);

    if (!NT_SUCCESS(status)) {
        DbgTrace(TL_ERROR, UsbDevice, "UcxUsbDeviceCreate Failed %!STATUS!", status);
        goto EvtControllerUsbDeviceAddEnd;
    }

    ucxUsbDeviceContext = GetUcxUsbDeviceContext(ucxUsbDevice);
    ucxUsbDeviceContext->DeviceSpeed = UsbDeviceInfo->DeviceSpeed;
    ucxUsbDeviceContext->TtHub = UsbDeviceInfo->TtHub;
    RtlCopyMemory(&ucxUsbDeviceContext->PortPath,
                  &UsbDeviceInfo->PortPath,
                  sizeof(USB_DEVICE_PORT_PATH));

    DbgTrace(TL_INFO, UsbDevice, "UsbDevice_EvtControllerUsbDeviceAdd");

EvtControllerUsbDeviceAddEnd:

    return status;
}

Requirements

Requirement	Value
Target Platform	Windows
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	ucxcontroller.h (include Ucxclass.h)
IRQL	PASSIVE_LEVEL

Share via