USB device driver programming reference

  • 아티클
  • 읽는 데 7분 걸림

These programming elements are used by drivers for USB peripheral devices.

  • Export functions for USB device drivers
    • WDM export functions and macros
    • WDF export functions
    • USB Device Redirection functions
    • Deprecated functions
  • Callback functions for USB client drivers
    • Bus Driver Interface functions for USB Client Drivers
    • Generic Parent Driver functions
  • I/O control codes for USB device drivers
    • Kernel-Mode IOCTLs
    • Deprecated and Reserved USB IOCTLs
  • Related topics

Export functions for USB device drivers

WDM export functions and macros

This section lists the routines that a Windows Driver Model (WDM)-based USB client driver can call to communicate with the Microsoft-provided USB driver stack.

The following table lists the routines that are available in Windows Driver Kit (WDK) for Windows 8. These routines are defined in Usbdlib.h and the client driver requires the Usbdex.lib library. The library gets loaded and statically linked to the client driver module when it is built. A client driver that calls these routines can run on Windows Vista and later versions of Windows.

Routine Description
USBD_AssignUrbToIoStackLocation Associate an URB that is allocated by USBD_UrbAllocate, USBD_SelectConfigUrbAllocateAndBuild, or USBD_SelectInterfaceUrbAllocateAndBuild, with the IRP.
USBD_CreateHandle Registers a client driver with the underlying USB driver stack.
USBD_CloseHandle Closes a USBD handle obtained in a previous call to USBD_CreateHandle.
USBD_IsInterfaceVersionSupported Checks whether the underlying USB driver stack supports a particular USBD interface version.
USBD_IsochUrbAllocate Allocates and formats an URB structure for an isochronous transfer request.
USBD_QueryUsbCapability Determine whether the underlying USB driver stack support a specific capability.
USBD_SelectConfigUrbAllocateAndBuild Allocates and formats a URB structure that is required to select a configuration for a USB device.
USBD_SelectInterfaceUrbAllocateAndBuild Allocates and formats a URB structure that is required to select an interface for a USB device.
USBD_UrbAllocate Allocates an URB structure for a request.
USBD_UrbFree Releases the URB that is allocated by USBD_UrbAllocate, USBD_SelectConfigUrbAllocateAndBuild, or USBD_SelectInterfaceUrbAllocateAndBuild.

 

The following table lists routines that are available in Windows Vista and later versions of the operating system.

Routine Description
GET_ISO_URB_SIZE Returns the number of bytes required to hold an isochronous transfer request.
GET_SELECT_CONFIGURATION_REQUEST_SIZE Returns the number of bytes required to create a select-configuration URB.
GET_SELECT_INTERFACE_REQUEST_SIZE Returns the number of bytes required to create a select-interface URB.
GET_USBD_INTERFACE_SIZE Returns the number of bytes required to hold a USBD_INTERFACE_INFORMATION interface descriptor with its associated endpoint descriptors.
UsbBuildFeatureRequest Formats an URB with the parameters necessary to request that a feature be turned on or off on a USB device.
UsbBuildGetDescriptorRequest Formats an URB with the parameters necessary to obtain descriptor information from the host controller driver (HCD).
UsbBuildGetStatusRequest Formats an URB to obtain status from a device, interface, endpoint, or other device-defined target on a USB device.
UsbBuildInterruptOrBulkTransferRequest Formats an URB to send or receive data on a bulk pipe, or to receive data from an interrupt pipe.
UsbBuildOpenStaticStreamsRequest Formats an URB structure to open streams in a specific bulk endpoint.
UsbBuildOsFeatureDescriptorRequest Formats an URB to request a Microsoft OS feature descriptor.
UsbBuildSelectConfigurationRequest Formats an URB with the parameters necessary to select a configuration on a USB device.
UsbBuildSelectInterfaceRequest Formats an URB with the parameters necessary to select an alternate setting for an interface on a USB device.
UsbBuildVendorRequest Formats an URB to send a vendor or class-specific command to a USB device, interface, endpoint, or other device-defined target.
USBD_CreateConfigurationRequestEx Allocates and formats an URB to select a configuration for a USB device.
USBD_GetInterfaceLength Obtains the length of a given interface descriptor, including the length of all endpoint descriptors contained within the interface.
USBD_GetPdoRegistryParameter Retrieves the value from the specified key in the USB device's hardware registry.
USBD_ParseConfigurationDescriptorEx Searches a given configuration descriptor and returns a pointer to an interface that matches the given search criteria.
USBD_ParseDescriptors Searches a given configuration descriptor and returns a pointer to the first descriptor that matches the search criteria.
USBD_ValidateConfigurationDescriptor Validates all descriptors returned by a device in its response to a configuration descriptor request.

 

WDF export functions

WDF USB Reference (KMDF and UMDF 2.0)

Reference information for KMDF and UMDF 2.0 client drivers. Starting in UMDF version 2.0, you can write a UMDF-based client driver in the C programming language that calls most KMDF methods. These methods are not supported in UMDF 2.0:

UMDF 1.x USB Reference

Reference information for user-mode client drivers that use UMDF interfaces versions 1.11 and earlier. The must be written by using the COM programming model.

USB Device Redirection functions

USB Device Redirection is controlled by the Redirection Policy Manager (RPM). RPM is a kernel-mode export driver that is available in Windows 7. By using RPM, third-party developers can load an alternate driver in place of the original USB device driver. RPM abstracts the redirection functionality provided by Microsoft. One of the clients for RPM is a Windows Virtual PC, a client virtualization solution for Windows 7.

For more information, see USB Device Redirection.

Routine Description
RPMGetAvailableDevices Returns a list of the attached USB devices (except hubs and HIDs).
RPMLoadAlternateDriverForDevice Loads the client-specified alternate driver for a device that is connected on a particular hub and connection index.
RPMRegisterAlternateDriver Enables a client application to register itself in order to perform driver redirection operations for a USB device.
RPMUnloadAlternateDriverForDevice Unloads the client-specified registered driver for a device that is connected on a particular hub and connection index.
RPMUnregisterAlternateDriver Allows a previously registered client to unregister itself.

 

Deprecated functions

The following functions have been deprecated. Do not use.

Callback functions for USB client drivers

These are the callback routines that a USB client can implement.

Bus Driver Interface functions for USB Client Drivers

In Windows Vista, and Windows 7, instead of linking directly to Usbd.sys, a USB client driver can query the USB bus driver for an interface. The client driver can then call the following routines associated with the bus driver interface.

Version 0 of the bus interface contains the following routines:

Routine Description
GetUSBDIVersion Gets the USB interface version number and the version number of the USB specification that defines the interface, along with information about host controller capabilities.
QueryBusInformation Gets information about the bus.
QueryBusTime Gets the current 32-bit USB frame number.
SubmitIsoOutUrb Not implemented.

 

Version 1 of the bus interface contains all of the version 0 routines and the following routine:

Routine Description
IsDeviceHighSpeed Returns TRUE if the device is operating at high speed.

 

Version 2 of the bus interface contains all of the version 1 routines and the following routines:

Routine Description
EnumLogEntry Not supported. Do not use.

 

Version 3 of the bus interface contains all of the version 2 routines and the following routines:

Routine Description
QueryBusTimeEx This routine is not implemented.
QueryControllerType Gets information about the USB host controller to which the USB device is attached.

 

Generic Parent Driver functions

In Windows Vista, the USB Generic Parent Driver (Usbccgp.sys) can query vendor-supplied filter drivers for an interface. Vendor-supplied filter drivers can provide the USBC_DEVICE_CONFIGURATION_INTERFACE_V1 structure to assist the generic parent driver in defining interface collections. The members of this structure point to several callback routines that are implemented by the filter driver. These implementations are used by the generic parent driver while enumerating the interface collections. Version 0 of the generic parent interface calls the following routines:

Routine Description
USBC_START_DEVICE_CALLBACK Allows a USB client driver to provide a custom definition of the interface collections on a device.

 

For information about the callback routine mechanism, see Customizing Enumeration of Interface Collections for Composite Devices.

I/O control codes for USB device drivers

Windows Driver Model (WDM) clients of the Universal Serial Bus (USB) driver stack communicate to the USB driver stack, by submitting an IRP with major code IRP_MJ_INTERNAL_DEVICE_CONTROL, and a minor code corresponding to an IOCTL value.

This topic provides a list the IOCTL values that client drivers can use. Kernel-mode I/O requests are for the exclusive use of client drivers. User-mode I/O requests can be used by client drivers and user-mode applications.

Kernel-Mode IOCTLs

USB client drivers can receive or send any of the following I/O requests in kernel mode:

I/O Request Description
IOCTL_INTERNAL_USB_CYCLE_PORT Simulates a device unplug and replug on the port associated with the PDO.
IOCTL_INTERNAL_USB_GET_BUS_INFO Queries the bus driver for certain bus information.
IOCTL_INTERNAL_USB_GET_CONTROLLER_NAME Queries the bus driver for the device name of the USB host controller.
IOCTL_INTERNAL_USB_GET_DEVICE_CONFIG_INFO Gets information about a USB device and the hub it is attached to.
IOCTL_INTERNAL_USB_GET_HUB_NAME Retrieves the Unicode symbolic name for the target PDO if the PDO is for a hub.
IOCTL_INTERNAL_USB_GET_PORT_STATUS Gets the status of the PDO.
IOCTL_INTERNAL_USB_GET_TOPOLOGY_ADDRESS Retrieves information about the host controller the USB device is attached to, and the device's location in the USB device tree.
IOCTL_INTERNAL_USB_REGISTER_COMPOSITE_DEVICE Registers the parent driver of a USB multi-function device (composite driver) with the underlying USB driver stack.
IOCTL_INTERNAL_USB_RESET_PORT Reset the upstream port of the device it manages.
IOCTL_INTERNAL_USB_SUBMIT_IDLE_NOTIFICATION Informs the USB bus driver that a device is idle and can be suspended.
IOCTL_INTERNAL_USB_SUBMIT_URB Submit an URB to the bus driver.
IOCTL_INTERNAL_USB_UNREGISTER_COMPOSITE_DEVICE Unregisters the parent driver of a USB multi-function device (composite driver) and releases all resources associated with registration.
IOCTL_INTERNAL_USB_REQUEST_REMOTE_WAKE_NOTIFICATION Sent by the parent driver of a USB multi-function device (composite driver) to request remote wake-up notifications from a specific function in the device.

 

Deprecated and Reserved USB IOCTLs

The following I/O requests have been deprecated or reserved for internal use. USB client drivers must not use these I/O requests:

USB

 

 

Send comments about this topic to Microsoft