DSF USB Device Simulator (SoftUSBDevice)

The SoftUSBDevice object (ISoftUSBDevice) and its associated objects are the basis of every simulated USB device. You create a USB device simulator by producing a user-mode executable module (in any form) that creates a SoftUSBDevice object and sets its properties to determine the configuration of the device. The SoftUSBDevice object communicates directly with the controller and can handle all standard USB device requests by using the property values that the device simulator configures. The following diagram illustrates the SoftUSBDevice object model.

Diagram illustrating the SoftUSB object model

The objects in the preceding diagram represent the hierarchy of descriptors in a USB device. The SoftUSBDevice object has properties that comprise the device descriptor that is defined by the USB 2.0 specification. Many of the properties of SoftUSBDevice (and its associated objects) are named according to the descriptor fields that are defined by the USB 2.0 specification.

You can configure devices as USB 2.0 or USB 1.1 by setting the SoftUSBDevice::USB property. The SoftUSBDevice::DSFDevice property references the DSFDevice object that represents the USB device (because DSF requires that all simulated devices be represented by a DSFDevice object). When the device simulator has completed its simulation, it must call the SoftUSBDevice::Destroy method to allow the object to clean up any resources that are allocated during its operation.

The SoftUSBConfiguration object (ISoftUSBConfiguration) has properties that comprise a configuration descriptor. The SoftUSBDevice::Configurations property returns a collection that contains a SoftUSBConfiguration object for each configuration that the device defines. The device simulator must populate this collection.

The SoftUSBDevice::USB1xConfigurations property returns a collection that contains the set of configurations that a USB 2.0 device uses when it is connected to an external hub at a USB 1.x speed. The SoftUSBDevice.DeviceQualifier method returns a SoftUSBDeviceQualifier object (ISoftUSBDeviceQualifier) that defines the device's device qualifier descriptor.

The SoftUSBInterface object (ISoftUSBInterface) has properties that comprise an interface descriptor. The SoftUSBInterface::Number and SoftUSBInterface::AlternateSetting property hold the interface and alternate numbers for the interface. The set of interfaces for a configuration are referenced by the collection that the SoftUSBConfiguration::Interfaces property returns. The device simulator must populate this collection. This collection contains a SoftUSBInterface object for each interface alternate that the configuration defines. At run time, the SoftUSBConfiguration::AlternateForInterface method returns the SoftUSBInterface object that references the host's currently selected alternate for a given interface.

The SoftUSBEndpoint object (ISoftUSBEndpoint) has properties that comprise an endpoint descriptor. The SoftUSBInterface::Endpoints property references a collection of SoftUSBEndpoint objects that represent all of the endpoints that the interface defines. The device simulator must populate this collection. The SoftUSBDevice::Endpoint0 property references the control endpoint for the device. The SoftUSBEndpoint object that is used to represent the control endpoint is created automatically by the SoftUSDevice object.

SoftUSBEndpoint is also the object that the device simulator uses to control transmission of data to and from the device. An endpoint can use event-driven or polled data transfer. For an event-driven endpoint, the device simulator must install an event sink on the endpoint's ISoftUSBEndpointEvents connection point. This interface defines events for data moving from the host to an endpoint (OnWriteTransfer) and for data moving from an endpoint to the host (OnReadTransfer). The device simulator can ACK, NAK, ERR, or STALL these events to determine the response that the host will receive. In addition, events are defined for use by the control endpoint that enable the device simulator to handle non-standard device requests (such as OnDeviceRequest or OnDeviceRequestComplete) and, in the rare case where it is needed, to override the handling of standard device requests (OnSetupTransfer).

For a polled endpoint, the SoftUSBEndpoint object maintains queues for incoming and outgoing data and the device simulator must move data in or out of these queues periodically. The SoftUSBEndpoint::QueueINData method adds data to the inbound queue. The SoftUSBEndpoint::DrainOUTQueue method removes data from the outbound queue. For control endpoints, the device simulator can use the SoftUSBEndpoint::QueueDeviceRequestResponse method to enqueue a response to an expected non-standard device request. The queues can be tuned for the maximum amount of data held and for the length of time to hold inbound data before it becomes stale.

SoftUSBString objects (ISoftUSBString) define string descriptors. The SoftUSBDevice.Strings property references a collection of SoftUSBString objects that comprise the set of string descriptors that the device defines. The string descriptor index that is specified within other descriptors (for example, the SoftUSBDevice.Manufacturer property) determines the index of the corresponding SoftUSBString object in this collection.

For device-specific descriptor data, SoftUSBConfiguration, SoftUSBInterface, and SoftUSBEndpoint all have a DeviceSpecificDescriptor property that you can set to an array of bytes that will be appended to the corresponding descriptor that is returned to the host. When DeviceSpecificDescriptor is set, the corresponding descriptor's length field is adjusted to reflect the additional device-specific data.

Except for the SoftUSBString object, all objects have a Context property that returns a DSFPropertyBag object (IDSFPropertyBag) that you can use to store arbitrary data with the object. This property enables both simulators and test applications to store context data with the object.

Send comments about this topic to Microsoft

Build date: 9/21/2010