Emulated USB host controller driver programming reference
This section provides reference information about writing Windows drivers that present non-USB devices as emulated USB devices. By using the WDF class extension-client driver model, you can write a driver that translates USB-level constructs (reset, data transfers) to the actual underlying bus by using the hardware’s interface. The class extension and the client driver represent an emulated host controller with a root hub that is capable of presenting an attached device to the system as an USB device.
In this architecture, the class extension is the Microsoft-provided driver (udecx.sys): USB device emulation class extension (UdeCx). This is an in-box driver included Windows 10.
The client driver is written by an IHV/OEM. This section refers to that driver as the UDE client driver.
The driver pair loads as the FDO in the host controller device stack. The UDE client driver communicates with Udecx by using a set of methods and event callback functions to handle device requests and notify the class extension about various events.
This section describes the event callback functions that are defined by UdeCx. These functions are implemented by your client driver for the emulated device. UdeCx invokes these functions to notify the client driver about events.
| Function | Description |
|---|---|
The USB device emulation class extension (UdeCx) invokes this callback function to request the client driver to create a dynamic endpoint on the virtual USB device. |
|
The USB device emulation class extension (UdeCx) invokes this callback function to change the configuration by selecting an alternate setting, disabling current endpoints, or adding dynamic endpoints. |
|
The USB device emulation class extension (UdeCx) invokes this callback function to request the client driver to create the default control endpoint on the virtual USB device. |
|
The USB device emulation class extension (UdeCx) invokes this callback function when it gets a request to bring the virtual USB device out of a low power state to working state. |
|
The USB device emulation class extension (UdeCx) invokes this callback function when it gets a request to send the virtual USB device to a low power state. |
|
The USB device emulation class extension (UdeCx) invokes this callback function when it gets a request to change the function state of the specified interface of the virtual USB 3.0 device. |
|
The USB device emulation class extension (UdeCx) invokes this callback function to reset an endpoint of the virtual USB device. |
|
The USB device emulation class extension (UdeCx) invokes this callback function to start processing I/O requests on the specified endpoint of the virtual USB device. |
|
The USB device emulation class extension (UdeCx) invokes this callback function to stop queuing I/O requests to the endpoint's queue and cancel unprocessed requests. |
|
The UDE client driver's implementation to reset the emulated host controller or the devices attached to it. |
|
The UDE client driver's implementation to determine the capabilities that are supported by the emulated USB host controller. |
This section describes the driver support methods that are implemented by the UdeCx library. Your client driver calls these methods to communicate with UdeCx.
| Function | Description |
|---|---|
Initializes a UDECX_USB_DEVICE_PLUG_IN_OPTIONS structure. |
|
Initializes a UDECX_WDF_DEVICE_CONFIG structure. |
|
Initializes device initialization operations when the Plug and Play (PnP) manager reports the existence of a device. |
|
Initializes a framework device object to support operations related to a host controller and a virtual USB device attached to the controller. |
|
Informs the USB device emulation class extension (UdeCx) that the reset operation on the specified controller has competed. |
|
Attempts to handle an IOCTL request sent by a user-mode software. |
|
Allocates memory for a UDECXUSBDEVICE_INIT structure that is used to initialize a virtual USB device. |
|
Sets the USB speed of the virtual USB device to create. |
|
Initializes a WDF-allocated structure with pointers to callback functions. |
|
Indicates the type of endpoint (simple or dynamic) in the initialization parameters that the client driver uses to create the virtual USB device. |
|
Adds a USB descriptor to the initialization parameters used to create a virtual USB device. |
|
Adds a USB descriptor to the initialization parameters used to create a virtual USB device. |
|
Adds a USB string descriptor to the initialization parameters used to create a virtual USB device. |
|
Adds a USB string descriptor to the initialization parameters used to create a virtual USB device. |
|
Creates a USB Device Emulation (UDE) device object. |
|
Releases the resources that were allocated by the UdecxUsbDeviceInitAllocate call. |
|
Notifies the USB device emulation class extension (UdeCx) that the USB device has been plugged in the specified port. |
|
Completes an asynchronous request for bringing the device out of a low power state. |
|
Completes an asynchronous request for sending the device to a low power state. |
|
Completes an asynchronous request for changing the power state of a particular function of a virtual USB 3.0 device. |
|
Initiates wake up from a low link power state for a virtual USB 2.0 device. |
|
Initiates wake up of the specified function from a low power state. This applies to virtual USB 3.0 devices. |
|
Disconnects the virtual USB device. |
|
Allocates memory for an initialization structure that is used to create a simple endpoint for the specified virtual USB device. |
|
Release the resources that were allocated by the UdecxUsbSimpleEndpointInitAllocate call. |
|
Sets the address of the endpoint in the initialization parameters of the simple endpoint to create. |
|
Sets pointers to UDE client driver-implemented callback functions in the initialization parameters of the simple endpoint to create. |
|
Creates a UDE endpoint object. |
|
Sets a framework queue object with a UDE endpoint. |
|
Completes an asynchronous request for canceling all I/O requests queued to the specified endpoint. |
|
Retrieves a USB control setup packet from a specified framework request object. |
|
Retrieves the transfer buffer of an URB from the specified framework request object sent to the endpoint queue. |
|
Sets the number of bytes transferred for the URB contained within a framework request object. |
|
Completes the URB request with a USB-specific completion status code. |
|
Completes the URB request with an NTSTATUS code. |
Related topics
Architecture: USB Device Emulation (UDE)