UcxControllerCreate function (ucxcontroller.h)

Article
02/22/2024

Creates a host controller object.

Syntax

NTSTATUS UcxControllerCreate(
  [in]           WDFDEVICE              Device,
  [in]           PUCX_CONTROLLER_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]          UCXCONTROLLER          *Controller
);

Parameters

[in] Device

A handle to the framework device object that the client driver retrieved in the previous call to WdfDeviceCreate.

[in] Config

A pointer to a caller-allocated UCX_CONTROLLER_CONFIG structure that the client driver initialized by calling UCX_CONTROLLER_CONFIG_INIT. The structure contains configuration information required to create the object.

[in, optional] Attributes

A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that specifies attributes for the controller object.

[out] Controller

A pointer to a variable that receives a handle to the new controller object.

Return value

The method returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one an appropriate NTSTATUS error code.

Remarks

The client driver for the host controller must call this method after the WdfDeviceCreate call. The parent of the new host controller object is the framework device object.

During this call, the client driver-supplied event callback implementations are also registered. Supply function pointers to those functions by call setting appropriate members of UCX_CONTROLLER_CONFIG.

If the parent type is PCI, then initialize the UCX_CONTROLLER_CONFIG by calling UCX_CONTROLLER_CONFIG_SET_PCI_INFO. If the parent is ACPI, call UCX_CONTROLLER_CONFIG_SET_ACPI_INFO instead.

The method creates various queues required to handle IOCTL requests sent to the USB device.

The method registers a device interface GUID_DEVINTERFACE_USB_HOST_CONTROLLER and symbolic link so that user mode components can open a handle to the controller.

Examples


    WDF_OBJECT_ATTRIBUTES                   objectAttributes;
    UCX_CONTROLLER_CONFIG                   ucxControllerConfig;
    UCXCONTROLLER                           ucxController;
    PUCX_CONTROLLER_CONTEXT                 ucxControllerContext;

    // Create the controller
    //
    UCX_CONTROLLER_CONFIG_INIT(&ucxControllerConfig, "");
    ucxControllerConfig.EvtControllerUsbDeviceAdd = UsbDevice_EvtControllerUsbDeviceAdd;
    ucxControllerConfig.EvtControllerQueryUsbCapability = Controller_EvtControllerQueryUsbCapability;
    ucxControllerConfig.EvtControllerReset = Controller_EvtControllerReset;
    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&objectAttributes, UCX_CONTROLLER_CONTEXT);
    
    status = UcxControllerCreate(wdfDevice,
        &ucxControllerConfig,
        &objectAttributes,
        &ucxController);

    if (!NT_SUCCESS(status)) {
        DbgTrace(TL_ERROR, Controller, "UcxControllerCreate Failed %!STATUS!", status);
        goto Controller_WdfEvtDeviceAddEnd;
    }

    DbgTrace(TL_INFO, Controller, "UCX Controller created.");

    controllerContext->UcxController = ucxController;

    ucxControllerContext = GetUcxControllerContext(ucxController);
    ucxControllerContext->WdfDevice = wdfDevice;

Requirements

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

Share via