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

EVT_UDECX_USB_DEVICE_ENDPOINT_ADD

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.

EVT_UDECX_USB_DEVICE_ENDPOINTS_CONFIGURE

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.

EVT_UDECX_USB_DEVICE_DEFAULT_ENDPOINT_ADD

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.

EVT_UDECX_USB_DEVICE_D0_ENTRY

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.

EVT_UDECX_USB_DEVICE_D0_EXIT

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.

EVT_UDECX_USB_DEVICE_SET_FUNCTION_SUSPEND_AND_WAKE

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.

EVT_UDECX_USB_ENDPOINT_RESET

The USB device emulation class extension (UdeCx) invokes this callback function to reset an endpoint of the virtual USB device.

EVT_UDECX_USB_ENDPOINT_START

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.

EVT_UDECX_USB_ENDPOINT_PURGE

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.

EVT_UDECX_WDF_DEVICE_RESET

The UDE client driver's implementation to reset the emulated host controller or the devices attached to it.

EVT_UDECX_WDF_DEVICE_QUERY_USB_CAPABILITY

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

UDECX_USB_DEVICE_PLUG_IN_OPTIONS_INIT

Initializes a UDECX_USB_DEVICE_PLUG_IN_OPTIONS structure.

UDECX_WDF_DEVICE_CONFIG_INIT

Initializes a UDECX_WDF_DEVICE_CONFIG structure.

UdecxInitializeWdfDeviceInit

Initializes device initialization operations when the Plug and Play (PnP) manager reports the existence of a device.

UdecxWdfDeviceAddUsbDeviceEmulation

Initializes a framework device object to support operations related to a host controller and a virtual USB device attached to the controller.

UdecxWdfDeviceResetComplete

Informs the USB device emulation class extension (UdeCx) that the reset operation on the specified controller has competed.

UdecxWdfDeviceTryHandleUserIoctl

Attempts to handle an IOCTL request sent by a user-mode software.

UdecxUsbDeviceInitAllocate

Allocates memory for a UDECXUSBDEVICE_INIT structure that is used to initialize a virtual USB device.

UdecxUsbDeviceInitSetSpeed

Sets the USB speed of the virtual USB device to create.

UdecxUsbDeviceInitSetStateChangeCallbacks

Initializes a WDF-allocated structure with pointers to callback functions.

UdecxUsbDeviceInitSetEndpointsType

Indicates the type of endpoint (simple or dynamic) in the initialization parameters that the client driver uses to create the virtual USB device.

UdecxUsbDeviceInitAddDescriptor

Adds a USB descriptor to the initialization parameters used to create a virtual USB device.

UdecxUsbDeviceInitAddDescriptorWithIndex

Adds a USB descriptor to the initialization parameters used to create a virtual USB device.

UdecxUsbDeviceInitAddStringDescriptor

Adds a USB string descriptor to the initialization parameters used to create a virtual USB device.

UdecxUsbDeviceInitAddStringDescriptorRaw

Adds a USB string descriptor to the initialization parameters used to create a virtual USB device.

UdecxUsbDeviceCreate

Creates a USB Device Emulation (UDE) device object.

UdecxUsbDeviceInitFree

Releases the resources that were allocated by the UdecxUsbDeviceInitAllocate call.

UdecxUsbDevicePlugIn

Notifies the USB device emulation class extension (UdeCx) that the USB device has been plugged in the specified port.

UdecxUsbDeviceLinkPowerEntryComplete

Completes an asynchronous request for bringing the device out of a low power state.

UdecxUsbDeviceLinkPowerExitComplete

Completes an asynchronous request for sending the device to a low power state.

UdecxUsbDeviceSetFunctionSuspendAndWakeComplete

Completes an asynchronous request for changing the power state of a particular function of a virtual USB 3.0 device.

UdecxUsbDeviceSignalWake

Initiates wake up from a low link power state for a virtual USB 2.0 device.

UdecxUsbDeviceSignalFunctionWake

Initiates wake up of the specified function from a low power state. This applies to virtual USB 3.0 devices.

UdecxUsbDevicePlugOutAndDelete

Disconnects the virtual USB device.

UdecxUsbSimpleEndpointInitAllocate

Allocates memory for an initialization structure that is used to create a simple endpoint for the specified virtual USB device.

UdecxUsbEndpointInitFree

Release the resources that were allocated by the UdecxUsbSimpleEndpointInitAllocate call.

UdecxUsbEndpointInitSetEndpointAddress

Sets the address of the endpoint in the initialization parameters of the simple endpoint to create.

UdecxUsbEndpointInitSetCallbacks

Sets pointers to UDE client driver-implemented callback functions in the initialization parameters of the simple endpoint to create.

UdecxUsbEndpointCreate

Creates a UDE endpoint object.

UdecxUsbEndpointSetWdfIoQueue

Sets a framework queue object with a UDE endpoint.

UdecxUsbEndpointPurgeComplete

Completes an asynchronous request for canceling all I/O requests queued to the specified endpoint.

UdecxUrbRetrieveControlSetupPacket

Retrieves a USB control setup packet from a specified framework request object.

UdecxUrbRetrieveBuffer

Retrieves the transfer buffer of an URB from the specified framework request object sent to the endpoint queue.

UdecxUrbSetBytesCompleted

Sets the number of bytes transferred for the URB contained within a framework request object.

UdecxUrbComplete

Completes the URB request with a USB-specific completion status code.

UdecxUrbCompleteWithNtStatus

Completes the URB request with an NTSTATUS code.

Architecture: USB Device Emulation (UDE)

Write a UDE client driver

Send comments about this topic to Microsoft