主控制器驱动程序使用的 UCX 对象和句柄

  • 项目

UCX 扩展了 WDF 对象功能，以定义其自己的特定于 USB 的 UCX 对象。 UCX 使用这些对象将请求排队到任何基础主机控制器驱动程序。

总结

  • 主机控制器驱动程序使用 UCX 对象来处理与控制器、其根中心和所有终结点相关的操作。
  • UCX 对象由主机控制器驱动程序创建，每个对象的生存期由 UCX 管理。

重要的 API

UCX 扩展了 WDF 对象功能，以定义其自己的特定于 USB 的 UCX 对象。 UCX 使用这些对象将请求排队到任何基础主机控制器驱动程序。

有关 WDF 对象的更多详细信息，请参阅 框架对象简介。

UCXCONTROLLER：主机控制器对象

表示由主机控制器驱动程序创建的主控制器。 驱动程序必须为每个主机控制器实例创建一个主机控制器对象。 通常通过调用 UcxControllerCreate 方法在 EvtDriverDeviceAdd 回调中创建。

当主机控制器驱动程序创建 对象时，驱动程序将注册由 UCX 调用的回调函数的实现。 驱动程序应另外标识主控制器连接的总线类型，例如 ACPI 或 PCI。 驱动程序还通过使用传递给 UcxControllerCreate 调用的 UCX_CONTROLLER_CONFIG 结构提供主机控制器设备信息。

若要处理 I/O 请求，主机控制器驱动程序必须注册GUID_DEVINTERFACE_USB_HOST_CONTROLLER设备接口。 驱动程序不需要实现此接口中定义的 IOCTL。 相反，UCX 客户端通过调用 UcxIoDeviceControl 将在此接口上收到的 IOCTL 请求传递给 UCX。

下面是与 UCX 调用的主控制器对象关联的回调函数。 这些函数必须由主机控制器驱动程序实现。

*
EVT_UCX_CONTROLLER_USBDEVICE_ADD当中心驱动程序通过与根中心和/或外部中心 () 交互确定总线上存在新设备时调用。

*
EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY由 UCX 调用以收集有关 USB 主机控制器支持的各种功能的信息。

*EVT_UCX_CONTROLLER_RESET
由 UCX 调用以重置控制器硬件，可能是为了响应检测到的错误。

*
EVT_UCX_CONTROLLER_GET_CURRENT_FRAMENUMBER用于从主机控制器检索当前帧编号，中心驱动程序使用该编号来计划常时等量传输。

UCXROOTHUB：根中心对象

获取和控制主机控制器的根端口的状态。 通常由主机控制器驱动程序在 EvtDriverDeviceAdd 回调中创建，方法是在创建主机控制器对象后调用 UcxRootHubCreate 方法。 每个主机控制器实例应只有一个根中心对象。 在 UcxRootHubCreate 调用中，驱动程序注册其回调实现。


EVT_UCX_ROOTHUB_GET_INFO返回根集线器的 USB 2.0 和 USB 3.0 端口数。

EVT_UCX_ROOTHUB_GET_20PORT_INFO
返回有关 usb 2.0 或 USB 3.0 端口的信息 (*EVT_UCX_ROOTHUB_GET_30PORT_INFO 根集线器的) 。

创建并初始化根中心对象后，中心驱动程序通过发送中断和控制传输来与根中心端口交互。 UCX 通过调用由主机控制器驱动程序实现的这些回调函数来帮助进行这些传输。


EVT_UCX_ROOTHUB_CONTROL_URB处理 USB 集线器的功能控制请求。

EVT_UCX_ROOTHUB_INTERRUPT_TX
处理有关已更改端口的信息的请求。

有关详细信息，请参阅 主控制器驱动程序的根中心回调函数。

UCXUSBDEVICE：USB 设备对象

表示连接到总线的物理 USB 设备。 通常由主机控制器驱动程序通过调用 UcxUsbDeviceCreate 方法在EVT_UCX_CONTROLLER_USBDEVICE_ADD回调中创建。

创建 对象时，主机控制器驱动程序会向 UcxUsbDeviceCreate 调用注册其回调函数的实现。

这些回调函数旨在使控制器和驱动程序随时了解 USB 设备的当前状态。


EVT_UCX_USBDEVICE_ENABLE准备控制器以执行到设备默认终结点的传输。

EVT_UCX_USBDEVICE_DISABLE
释放与设备及其默认终结点关联的控制器资源。


EVT_UCX_USBDEVICE_ADDRESS将地址程序设置为控制器，并将SET_ADDRESS传输发送到设备，使其进入寻址状态。


EVT_UCX_USBDEVICE_ENDPOINTS_CONFIGURE将非默认终结点程序化到控制器中，和/或释放其他非默认终结点。


EVT_UCX_USBDEVICE_RESET控制器通知，指示设备已重置，在这种情况下，驱动程序将采取任何必要的操作来将控制器与 USB 设备同步。


EVT_UCX_USBDEVICE_UPDATE通知控制器与设备相关的各种信息位。

EVT_UCX_USBDEVICE_HUB_INFO
有关中心属性的通知（如果 UCXUSBDEVICE 句柄适用于中心设备）。


EVT_UCX_USBDEVICE_ENDPOINT_ADD通知驱动程序为设备创建终结点。 默认终结点的EVT_UCX_USBDEVICE_DEFAULT_ENDPOINT_ADD 。

当已挂起的 USB 3.0 设备上的接口发出唤醒信号时，驱动程序应调用 UcxUsbDeviceRemoteWakeNotification 来通知 UCX。

创建对象后，对象的生存期由 UCX 管理，驱动程序不得删除该对象。

UCXENDPOINT：终结点对象

表示 USB 设备对象上的终结点。 终结点对象由主机控制器在 EVT_UCX_USBDEVICE_DEFAULT_ENDPOINT_ADD 或 EVT_UCX_USBDEVICE_ENDPOINT_ADD 回调期间创建。 创建终结点对象时，驱动程序将注册其回调函数。

驱动程序还会为每个终结点创建一个框架队列对象，并通过调用 UcxEndpointSetWdfIoQueue 将该队列的 WDFQUEUE 传递给 UCX。 创建终结点后，对象的生存期及其关联队列由 UCX 管理，驱动程序不得删除这些对象本身。

终结点对象实现多个回调函数，这些函数允许驱动程序通过与终结点相关的操作帮助 UCX。


EVT_UCX_ENDPOINT_ABORT中止与终结点关联的队列。

EVT_UCX_ENDPOINT_OK_TO_CANCEL_TRANSFERS
通知控制器驱动程序它可以在终结点上完成取消的传输。


EVT_UCX_ENDPOINT_PURGE完成终结点上所有未完成的 I/O 请求。

EVT_UCX_ENDPOINT_START
启动与终结点关联的队列。

EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD
创建静态流。

EVT_UCX_ENDPOINT_RESET
通知驱动程序重置控制器对终结点的编程。

当主机控制器驱动程序在终结点上收到 USB 3.0 无 Ping 响应错误时，驱动程序必须调用 UcxEndpointNoPingResponseError。 该调用会导致 USB 设备对象接收 EVT_UCX_USBDEVICE_UPDATE。 有关详细信息，请参阅 在主机控制器驱动程序中配置 USB 终结点。

UCXSTREAMS：Stream 对象

表示通过单个终结点连接到设备的多个管道。 主机控制器驱动程序通过调用 UcxStaticStreamsCreate 在EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD回调中创建流对象。

在 UcxStaticStreamsCreate 调用期间，主机控制器驱动程序注册其回调函数。 对于特定的终结点对象，驱动程序可以确定是否创建了流对象，并通过调用 UcxEndpointGetStaticStreamsReferenced 返回 UCXSTREAMS 句柄。

创建对象后，驱动程序为每个流创建一个框架队列对象，并通过调用 UcxStaticStreamsSetStreamInfo 将 WDFQUEUE 句柄发送到 UCX。

流对象为主机控制器提供多个回调函数，以帮助 UCX 管理静态流。

EVT_UCX_ENDPOINT_STATIC_STREAMS_DISABLE
释放终结点的所有流的控制器资源。


EVT_UCX_ENDPOINT_STATIC_STREAMS_ENABLE为此终结点启用所有流的控制器硬件。

对象和关联队列的生存期由 UCX 管理，驱动程序不得删除对象。