1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
---
page_type: sample
description: "Demonstrates how to perform full speed, high speed, and SuperSpeed transfers to and from bulk and isochronous endpoints of a generic USB device."
languages:
- cpp
products:
- windows
- windows-wdk
---
# Usbsamp Generic USB Driver
The USBSAMP sample demonstrates how to perform full speed, high speed, and SuperSpeed transfers to and from bulk and isochronous endpoints of a generic USB device. USBSAMP is based on the [Kernel Mode Driver Framework](https://docs.microsoft.com/windows-hardware/drivers/kernel/) (KMDF). Superspeed bulk and isochronous transfers only work when the Microsoft USB 3.0 stack is loaded.
The sample also contains a console test application that initiates bulk (including stream) and isochronous transfers and obtains data from the device's I/O endpoints. The application also demonstrates how to use GUID-based device names and pipe names generated by the operating system using the **SetupDiXXX** user-mode APIs.
For information about USB, see [Universal Serial Bus (USB) Drivers](https://docs.microsoft.com/windows-hardware/drivers/usbcon/).
## Universal Windows Driver Compliant
This sample builds a Universal Windows Driver. It uses only APIs and DDIs that are included in OneCoreUAP.
## Hardware requirements
The sample driver can be loaded as the function driver for any of these devices:
- OSR FX2 learning kit. You can get the kit from [OSR Online](https://www.osronline.com/). For more information, see the specification for the [OSR USB FX-2 Learning Kit](https://www.osronline.com/hardware/OSRFX2_32.pdf)
- [MUTT devices](https://docs.microsoft.com/windows-hardware/drivers/usbcon/microsoft-usb-test-tool--mutt--devices). To order those devices, see [How to get MUTT devices](https://docs.microsoft.com/windows-hardware/drivers/usbcon/microsoft-usb-test-tool--mutt--devices#how-to-get-mutt-devices).
- Intel 82930 USB test board.
If you have a different USB device, you can still use the driver by adding the device's hardware ID to the INX file. Note that the data transfer scenarios will work only with the endpoints supported by the device.
## Set the configuration and platform in Visual Studio
In Visual Studio, in Solution Explorer, right click **Solution 'usbsamp' (3 projects)**, and choose **Configuration Manager**. Set the configuration and the platform. Make sure that the configuration and platform are the same for both the driver project and the package project. Do not check the **Deploy** boxes.
## Build the sample using Visual Studio
In Visual Studio, on the **Build** menu, choose **Build Solution**.
For more information about using Visual Studio to build a driver package, see [Building a Driver with Visual Studio and the WDK](https://docs.microsoft.com/windows-hardware/drivers/develop/building-a-driver).
## Locate the built driver
In File Explorer, navigate to the folder that contains your built driver package. The location of this folder varies depending on what you set for configuration and platform. For example, if your settings are Debug and x64, the driver is in your solution folder under sys\\driver\\Debug\\usbsamp.
The driver folder contains these files:
| File | Description |
| --- | --- |
| usbsamp.sys | The driver file |
| usbsamp.inf | An information (INF) file that contains information needed to install the driver. |
| kmdfsamples.cat | A signed catalog file, which serves as the signature for the entire package. |
## Run the sample
The computer where you install the driver is called the *target computer* or the *test computer*. Typically this is a separate computer from where you develop and build the driver package. The computer where you develop and build the driver is called the *host computer*.
The process of moving the driver package to the target computer and installing the driver is called *deploying the driver*. You can deploy the USBSAMP sample automatically or manually.
### Automatic deployment
Before you automatically deploy a driver, you must provision the target computer. For instructions, see [Provision a computer for driver deployment and testing (WDK 10)](https://docs.microsoft.com/windows-hardware/drivers/gettingstarted/provision-a-target-computer-wdk-8-1).
1. On the host computer, in Visual Studio, in Solution Explorer, right click **package** (lower case), and choose **Properties**. Navigate to **Configuration Properties \> Driver Install \> Deployment**.
1. Check **Enable deployment**, and check **Remove previous driver versions before deployment**. For **Target Computer Name**, select the name of a target computer that you provisioned previously. Select **Install and Verify**. Click **OK**.
1. On the **Build** menu, choose **Deploy Package** or **Build Solution**.
### Manual deployment
Before you manually deploy a driver, you must turn on test signing and install a certificate on the target computer. You also need to copy the [DevCon](https://docs.microsoft.com/windows-hardware/drivers/devtest/devcon) tool to the target computer. For instructions, see [Preparing a Computer for Manual Driver Deployment](https://docs.microsoft.com/windows-hardware/drivers/develop/preparing-a-computer-for-manual-driver-deployment).
1. Copy all of the files in your driver package to a folder on the target computer (for example, c:\\Usbsamp).
1. On the target computer, open a Command Prompt window as Administrator. Navigate to your driver package folder, and enter the following command:
`devcon install usbsamp.inf USB\VID_045E&PID_078F`
## View the device in Device Manager
On the target computer, in a Command Prompt window, enter **devmgmt** to open Device Manager. In Device Manager, on the **View** menu, choose **Devices by type**. In the device tree, locate the device. For example the device name might be **WDF Sample for FX2 MUTT device** under the**Sample Device** node.
## Build the sample using MSBuild
As an alternative to building the USBSAMP sample in Visual Studio, you can build it in a Visual Studio Command Prompt window. In Visual Studio, on the **Tools** menu, choose **Visual Studio Command Prompt**. In the Visual Studio Command Prompt window, navigate to the folder that has the solution file, Usbsamp.sln. Use the MSBuild command to build the solution. Here are some examples:
`msbuild /p:configuration="Debug" /p:platform="x64" Usbsamp.sln`
`msbuild /p:configuration="Release" /p:platform="Win32" Usbsamp.sln`
For more information about using MSBuild to build a driver package, see [Building a Driver with Visual Studio and the WDK](https://docs.microsoft.com/windows-hardware/drivers/develop/building-a-driver).
## Testing the sample
The sample includes a test application, usbsamp.exe. This console application enumerates the interface registered by the driver and opens the device to send Read, Write, or DeviceIoControl requests based on the command line options. To test the sample,
1. In Visual Studio, choose **Solution Explorer** from the **View** menu. Locate the application project named **usbsamp**, under the **Exe** folder.
1. Right-click and choose **Build**. For example, if your settings are Debug and x64, the application executable is in your solution folder under the exe\\Debug\\usbsamp.exe.
1. Run the executable on the target machine.
- To view all descriptors and endpoint information, use the following command.
`usbsamp.exe -u`
You can use the preceding command to view pipe numbers for read and write requests.
- To send a Read-Write request, use the following command.
`usbsamp.exe -r 1024 -w 1024 -c 100 -v`
The preceding command first writes 1024 bytes of data to bulk out endpoint (pipe 1), then reads 1024 bytes from bulk in endpoint (pipe 0), and compares the read buffer with write buffer to see if they match. If the buffer contents match, it performs this operation 100 times.
- To send Read-Write requests to bulk endpoints, use any of the following commands, simultaneously. If Read-Write requests are sent to a SuperSpeed bulk endpoint with streams, the sample driver always uses the first underlying stream associated with that endpoint. The driver is multi-thread safe so it can handle multiple requests at a time.
`usbsamp.exe -r 65536`
The preceding command reads 65536 bytes from pipe 0.
`usbsamp.exe -w 65536`
The preceding command writes 65536 bytes to pipe 1.
`usbsamp.exe -r 65536 -i pipe02`
The preceding command reads 65536 bytes from pipe 2.
`usbsamp.exe -w 65536 -o pipe03`
The preceding command writes 65536 bytes to pipe 3.
- To send Read and Write requests to isochronous endpoints you can use one or more of these commands simultaneously.
`usbsamp.exe -r 512 -i pipe04`
The preceding command reads 512 bytes from pipe 4.
`usbsamp.exe -w 512 -o pipe05`
The preceding command writes 512 bytes to pipe 5.
`usbsamp.exe -w 1024 -o pipe05 -r 1024 -i pipe04 -c 100 -v`
The preceding command writes 1024 bytes to pipe 5, then reads 1024 bytes from pipe 4, and compares the buffers to see if they match. If the buffer contents match, it performs this operation 100 times.
- To skip validation of the data to be read or written in a particular request, use the command with **-x** option as follows:
usbsamp.exe -r 1024 -w 1024 -c 100 -x
|
