DSF USB Loopback Device Simulation
Description
The DSF USB loopback device simulation code sample shows how to build a USB simulation based on the Device Simulation Framework (DSF). The code shows how to set up the simulated device to look like a USB device, and the two methods that DSF supports for handling USB data. A test script also shows how you can test the device.
Theory of Operation
Running the Sample
A pre-compiled version of the loopback simulation code is included when you install DSF from the Microsoft Windows Driver Kit (WDK). To run the code, you can use this supplied version or you can use a version that you have compiled by using the WDK build environment. To use a version you have compiled, simply replace the supplied version with your own and run regsvr32 SoftUSBLoopback.dll to register your custom version of the simulation. The supplied DLL is already registered, so there is no need for you to register that file.
To exercise the code, you can use a VBScript file called RunLoopbackSample.wsf that is installed with DSF in the Program Files\dsf directory. Before running the script, you must add a simulated USB controller on the target system. To install the simulated USB controller, you need to run softehcicfg.exe /install.
To exercise the loopback device, run cscript RunLoopbackSample.wsf. The script causes a new device to be created. The new device then plugs itself into the simulated USB controller that you just installed. The host system behaves as though a new device has been plugged in and loads the appropriate driver. In this case, Usbsamp.sys is the driver that is required to enumerate the device, because the loopback device emulates an Intel Bulk USB test board. After the device has been enumerated on the USB bus, you can choose to run the device in either polled mode or event mode. For more information about how to create and install a Usbsamp.sys driver, see UsbSamp. For more information about the polled and event modes of operation, see the Polled Mode and Event-Driven Mode sections in this topic.
When the device has no data to process, it sends an event to the script that asks if you want to continue. If you do not provide any input, it is assumed that you choose to continue. If you choose not to continue, the device is unplugged and you are asked to press ENTER to end the script.
To exchange data with the loopback device, you must run the Usbsamp.exe test application. You can locate this test application in the src\usb\usbsamp directory of your WDK installation. By running usbsamp.exe /u, you can see how the device and the endpoints are configured.
To send and receive 512 bytes from the device, run the following command.
usbsamp.exe -r 512 -w 512 -i 0 -o 1
The amount of data can be adjusted to any value that is required. The IN endpoint is 0, and the OUT endpoint is 1. These values need to remain constant because the endpoints only work in one direction.
Note The Usbsamp.sys driver and Usbsamp.exe test application replace the BulkUSB.sys driver and RwBulk.exe test program from earlier versions of the WDK. For more information about Usbsamp, see UsbSamp.
Handling Device Requests
The SoftUSBLoopback device is a simple example of a USB simulated device. The device does not handle any device requests. The device expects only to have standard USB device requests sent to it, so the DSF infrastructure will handle these requests. A device is required only to handle vendor-specific and class-specific requests.
Event-Driven Mode
The device can run in either polled or event-driven mode.
In the event-driven model, the loopback device receives data from the host controller whenever there is data to be processed, through a call to the OnWriteTransfer function. OnWriteTransfer is called for the OUT endpoint when an OUT transaction is received from the host. This call occurs on an arbitrary thread, because the event is sent from kernel mode. The device then simply passes this data to the IN endpoint by calling the function QueueINData. This call adds data to the IN endpoint queue. When the IN endpoint receives a request for data from the host controller, the data is simply read from the queue.
Polled Mode
In the polled mode model, the device periodically queries the OUT endpoint to determine if there is any data that needs to be processed. The device calls DrainOUTQueue with maxTransfers set to 0, which indicates that the device wants to know how many items are in the queue. If there is data present, the device reads the data from the endpoint, one request at a time, by using the DrainOUTQueue function. The device then passes this data to the IN endpoint by calling the function QueueINData. This call adds data to the IN endpoint queue. When the IN endpoint receives a request for data from the host controller, the data is read from the queue.
Building the Sample
You can find the sample code for the USB loopback device in the src\test\dsf\usb\softusbloopback directory. To build the executable by using a WDK build environment, run build -cZP. This command produces a DLL called SoftUSBLoopback.dll.
Alternatively, you can build this sample by using Microsoft Visual Studio 2005 or later.
Send comments about this topic to Microsoft
Build date: 9/21/2010