README.md 8.85 KB
Newer Older
1
# USB/IP for Windows
George Hopkins's avatar
George Hopkins committed
2

3
- This project aims to support both a USB/IP server and a client on Windows platform.
4

George Hopkins's avatar
George Hopkins committed
5

6
## Build
George Hopkins's avatar
George Hopkins committed
7

8
9
10
11
12
### Notes
- Build is tested on Windows 10 x64 and the projects are configured for this target by default.
- x86/x64 platforms should be supported. However, we don't have an x86 setup for testing at the moment.
- For Windows 7 users, change usbip\_stub and usbip\_vhci projects' Target OS version to Windows 7.
  - Right-click on the project > Properties > Driver Settings > Target OS version > Windows 7
13
  - The recent tag version which supports is v0.1.0. All upper versions do not support Win7 or 8 because usbip-win started to use kernel libraries of Win10.
14

15
### Build Tools
16
17
18
- Visual Studio 2019 Community(v142)
  - Build with VS 2017(v141) is also possible if platform toolset in setting is configured to v141
- Windows SDK 10.0.18362.0(recommended)
謝致邦 (XIE Zhibang)'s avatar
謝致邦 (XIE Zhibang) committed
19
20
  - VS 2019(v142): requires >= 10.0.18xxx
  - VS 2017(v141): requires >= 10.0.17xxx
21
22
- Windows Driver Kit Windows 10, version 1903 (10.0.18362)
  - WDK 10.0.17134(1803), 10.0.17763(1809), 10.0.18346 are also tested
23
24
25

### Build Process
- Open usbip_win.sln
26
- If VS 2017 is used, SDK version for userspace projects(usbip, usbip_common, usbipd, stubctl) should be adjusted.
27
28
29
30
31
- Set certificate driver signing for usbip\_stub and usbip\_vhci projects.
  - Right-click on the project > Properties > Driver Signing > Test Certificate
  - Browse to driver/usbip\_test.pfx
- Build solution or desired project.

32
33
34
35
- All output files are created under {Debug,Release}/{x64,x86} folder

## Install

36
### Windows USB/IP server
37

38
- Prepare a linux machine as a USB/IP client (or windows usbip-win vhci client)
39
40
  - Tested on Ubuntu 16.04
  - Kernel 4.15.0-29 (USB/IP kernel module crash was observed on some other version)
41
  - `# modprobe vhci-hcd`
42
- Install USB/IP test certificate
43
44
45
46
  - Install `driver/usbip_test.pfx` (password: usbip)
  - Certificate should be installed into
    1. "Trusted Root Certification Authority" in "Local Computer" (not current user) and
    2. "Trusted Publishers" in "Local Computer" (not current user)
47
- Enable test signing
48
  - `> bcdedit.exe /set TESTSIGNING ON`
49
  - reboot the system to apply
50
51
52
53
- Copy `usbip.exe`, `usbipd.exe`, `usb.ids`, `usbip_stub.sys`, `usbip_stub.inx` into a folder in target machine
  - You can find `usbip.exe`, `usbipd.exe`, `usbip_stub.sys` in output folder after build or on [release](https://github.com/cezanne/usbip-win/releases) page.
  - `userspace/usb.ids`
  - `driver/stub/usbip_stub.inx`
54
- Find USB device id
55
  - You can get device id from usbip listing
56
57
58
59
60
61
62
63
64
    - `> usbip.exe list -l`
  - Bus id is always 1. So output from `usbip.exe` listing is shown as:
```
usbip.exe list -l
 - busid 1-59 (045e:00cb)
   Microsoft Corp. : Basic Optical Mouse v2.0 (045e:00cb)
 - busid 1-30 (80ee:0021)
   VirtualBox : USB Tablet (80ee:0021)
```
65
- Bind USB device to usbip stub
66
  - This command replaces an existing function driver with usbip stub driver
67
68
69
70
71
72
    - This should be executed using administrator privilege
    - `usbip_stub.inx` and `usbip_stub.sys` files should be in the same folder as `usbip.exe`
  - `> usbip.exe bind -b 1-59`
- Run `usbipd.exe`
  - `> usbipd.exe -d -4`
	- TCP port `3240` should be allowed by firewall
73
- Attach USB/IP device on linux machine
74
  - `# usbip attach -r <usbip server ip> -b 1-59`
75

76
### Windows USB/IP client
77
- Currently, there are 2 versions for a vhci driver
78
	  - vhci(wdm): original version, implemented via WDM(Windows Driver Model)
79
80
81
	  - vhci(ude): newly developed version to fully support USB applications and implemented via UDE(USB Device Emulation) which is MS provided USB virtualization framework over KMDF(Kernel-Model Driver Framework)
	  - Installation procedures for 2 versions are different.
- Prepare a linux machine as a USB/IP server (or windows usbip-win stub server)
82
  - tested on Ubuntu 16.04(Kernel 4.15.0-29), 18.04, 20.04
83
  - `# modprobe usbip-host`
84
  - You can use virtual [usbip-vstub](https://github.com/cezanne/usbip-vstub) as a stub server
85
86
- Run usbipd on a USB/IP server (Linux)
  - `# usbipd -4 -d`
87
- Install USB/IP test certificate
88
89
90
91
  - Install `driver/usbip_test.pfx` (password: usbip)
  - Certificate should be installed into
    1. "Trusted Root Certification Authority" in "Local Computer" (not current user) and
    2. "Trusted Publishers" in "Local Computer" (not current user)
92
- Enable test signing
93
  - `> bcdedit.exe /set TESTSIGNING ON`
94
  - reboot the system to apply
95
- Copy vhci driver files into a folder in target machine
96

97
  - If you're testing vhci(ude), copy `usbip.exe`, `usbip_vhci_ude.sys`, `usbip_vhci_ude.inf`, `usbip_vhci_ude.cat` into a folder in target machine
98
  - If you're testing vhci(wdm), copy `usbip.exe`, `usbip_vhci.sys`, `usbip_vhci.inf`, `usbip_root.inf`, `usbip_vhci.cat` into a folder in target machine
99
  - You can find all files in output folder after build or on [release](https://github.com/cezanne/usbip-win/releases) page.
100
- Install USB/IP VHCI driver
101
  - You can install using usbip.exe or manually
102
103
  - Using usbip.exe install command
     - Run PowerShell or CMD as an Administrator
104
     - `PS> usbip.exe install`
105
106
     - Upper command will install a ude driver or a wdm driver depending on the available files
       - (ude version first)
107
108
     - `PS> usbip.exe install -u` if ude driver only
     - `PS> usbip.exe install -w` if wdm driver only
109
  - Manual Installation for vhci(ude)
110
111
112
113
114
115
116
117
118
     - Run PowerShell or CMD as an Administrator
     - `PS> pnputil /add-driver usbip_vhci_ude.inf`
     - Start Device manager
     - Choose "Add Legacy Hardware" from the "Action" menu.
     - Select "Install the hardware that I manually select from the list".
     - Click "Next".
     - Click "Have Disk", click "Browse", choose the copied folder, and click "OK".
     - Click on the "usbip-win VHCI(ude)", and then click "Next".
     - Click Finish at "Completing the Add/Remove Hardware Wizard".	 
119
  - Manual Installation for vhci(wdm)
120
121
122
123
124
125
126
127
128
     - Run PowerShell or CMD as an Administrator
     - `PS> pnputil /add-driver usbip_vhci.inf`
     - Start Device manager
     - Choose "Add Legacy Hardware" from the "Action" menu.
     - Select "Install the hardware that I manually select from the list".
     - Click "Next".
     - Click "Have Disk", click "Browse", choose the copied folder, and click "OK".
     - Click on the "USB/IP VHCI Root", and then click "Next".
     - Click Finish at "Completing the Add/Remove Hardware Wizard".
129
- Attach a remote USB device
130
  - `PS> usbip.exe attach -r <usbip server ip> -b 2-2`
131
- Uninstall driver
132
  - `PS> usbip.exe uninstall`
133
134
135
- Disable test signing
  - `> bcdedit.exe /set TESTSIGNING OFF`
  - reboot the system to apply
136

137
138
139
### Reporting Bug
- usbip-win is not yet ready for production use. We could find problems with more detailed logs.

140
#### How to get windows kernel log for vhci(wdm)
141
142
143
144
145
146
147
148
149
150
151
152
153
- Set registry key to enable a debug filter
  - usbip-win uses [DbgPrintEx API for kernel logging](https://docs.microsoft.com/en-us/windows-hardware/drivers/devtest/reading-and-filtering-debugging-messages).
  - save following as .reg and run or manually insert a registry key
  - restart is required
```
Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Debug Print Filter]
"IHVDRIVER"=dword:ffffffff
```
- Run a debugging log viewer program before you test
  - [DebugView](https://docs.microsoft.com/en-us/sysinternals/downloads/debugview) is a good tool to view the logs
  
154
- If your testing machine suffer from BSOD (blue screen on death), you should get it via remote debugging.
155
156
  - WinDbg on virtual machines would be good to get logs

157
158
159
160
161
162
163
164
165
166
167
168
169
#### How to get windows kernel log for vhci(ude)

- A new vhci(ude) implementation uses WPP SW tracing instead of DbgPrintEx.
  - DebugView.exe cannot catch a vhci debug message
    - TraceView.exe is a good utility for a new approach, which is included in WDK.
- usbip_vhci_ude.pdb file is required to add a trace provider easily.
- Create a new session log in TraceView.exe
  - Choose PDB file radio button in \"*Provider Control GUID Setup*\" popup dialog
  - Specify usbip_vhci_ude.pdb as a PDB file
- You can send real-time trace messages to WinDbg by modifying in \"*Advanced Log Session Options*\".
- If your testing machine suffer from BSOD (blue screen on death), you should get it via remote debugging.
  - WinDbg on virtual machines would be good to get logs

170
171
172
#### How to get usbip forwarder log
- usbip-win transmits usbip packets via a userland forwarder.
  - forwarder log is the best to look into usbip packet internals. 
173
174
175
- edit `usbip_forward.c` to define `DEBUG_PDU` at the head of the file
- compile `usbip.exe` or `usbipd.exe`
- `debug_pdu.log` is created at the path where an executable runs.  
176
177
178

#### How to get linux kernel log
- Sometimes linux kernel log is required
179

180
```
181
# dmesg --follow | tee kernel_log.txt
182
183
```

184
<hr>
KyungWoon Cho's avatar
KyungWoon Cho committed
185
<sub>This project was supported by Basic Science Research Program through the National Research Foundation of Korea(NRF) funded by the Ministry of Education(2020R1I1A1A01066121).</sub>