- This project aims to support both a USB/IP server and a client on Windows platform.
- 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_stubandusbip_vhciprojects' Target OS version toWindows 7.- Right-click on the
Project > Properties > Driver Settings > Target OS version > Windows 7 - The recent tag version which supports is v0.1.0. All versions after v0.1.0 do not support Windows 7 or 8 because usbip-win started to use kernel libraries of Windows 10.
- Right-click on the
- 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)
- VS 2019 (v142): requires >= 10.0.18xxx
- VS 2017 (v141): requires >= 10.0.17xxx
- Windows Driver Kit Windows 10, version 1903 (10.0.18362)
- WDK 10.0.17134 (1803), 10.0.17763 (1809) and 10.0.18346 are also tested.
- Open
usbip_win.sln - If VS 2017 is used, SDK version for userspace projects (
usbip,usbip_common,usbipd,stubctl) should be adjusted. - Set certificate driver signing for
usbip_stubandusbip_vhciprojects- Right-click on the
Project > Properties > Driver Signing > Test Certificate - Browse to
driver/usbip_test.pfx(password: usbip)
- Right-click on the
- Build solution or desired project
- All output files are created under {Debug,Release}/{x64,x86} folder.
- Prepare a Linux machine as a USB/IP client or Windows usbip-win VHCI client (tested on Ubuntu 16.04 with kernel 4.15.0-29 - USB/IP kernel module crash was observed on some other versions)
# modprobe vhci-hcd
- Install USB/IP test certificate
- Install
driver/usbip_test.pfx(password: usbip) - Certificate should be installed into
- "Trusted Root Certification Authority" in "Local Computer" (not current user) and
- "Trusted Publishers" in "Local Computer" (not current user)
- Install
- Enable test signing
> bcdedit.exe /set TESTSIGNING ON- reboot the system to apply
- Copy
usbip.exe,usbipd.exe,usb.ids,usbip_stub.sys,usbip_stub.inxinto a folder in target machine- You can find
usbip.exe,usbipd.exe,usbip_stub.sysin the output folder after build or on release page. userspace/usb.idsdriver/stub/usbip_stub.inx
- You can find
- Find USB Device ID
- You can get id from usbip listing
> usbip.exe list -l
- Bus id is always 1. So output from
usbip.exelisting is shown as:
- You can get id from usbip listing
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)
- Bind USB device to usbip stub
- The next command replaces the existing function driver with usbip stub driver
- This should be executed using administrator privilege
usbip_stub.inxandusbip_stub.sysfiles should be in the same folder asusbip.exe
> usbip.exe bind -b 1-59
- The next command replaces the existing function driver with usbip stub driver
- Run
usbipd.exe> usbipd.exe -d -4- TCP port
3240should be allowed by firewall
- Attach USB/IP device on Linux machine
# usbip attach -r <usbip server ip> -b 1-59
- Currently, there are 2 versions for a VHCI driver with different installation procedures:
vhci(wdm): original version, implemented via WDM (Windows Driver Model);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).
- Prepare a Linux machine as a USB/IP server or Windows usbip-win stub server - (tested on Ubuntu 16.04 (kernel 4.15.0-29), 18.04, 20.04)
# modprobe usbip-host- You can use virtual usbip-vstub as a stub server
- Run usbipd on a USB/IP server (Linux)
# usbipd -4 -d
- Install USB/IP test certificate
- Install
driver/usbip_test.pfx(password: usbip) - Certificate should be installed into
- "Trusted Root Certification Authority" in "Local Computer" (not current user) and
- "Trusted Publishers" in "Local Computer" (not current user)
- Install
- Enable test signing
> bcdedit.exe /set TESTSIGNING ON- reboot the system to apply
- Copy VHCI driver files into a folder in target machine
- If you're testing
vhci(ude), copyusbip.exe,usbip_vhci_ude.sys,usbip_vhci_ude.inf,usbip_vhci_ude.catinto a folder in target machine; - If you're testing
vhci(wdm), copyusbip.exe,usbip_vhci.sys,usbip_vhci.inf,usbip_root.inf,usbip_vhci.catinto a folder in target machine; - You can find all files in output folder after build or on release page.
- If you're testing
- Install USB/IP VHCI driver
- You can install using
usbip.exeor manually - Using
usbip.exeinstall command- Run PowerShell or CMD as an Administrator
PS> usbip.exe install- The previous command will install a UDE driver or a WDM driver depending on the available files
- (UDE version first)
PS> usbip.exe install -uif UDE driver onlyPS> usbip.exe install -wif WDM driver only
- Manual Installation for vhci(ude)
- 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".
- Manual Installation for vhci(wdm)
- 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".
- You can install using
- Attach a remote USB device
PS> usbip.exe attach -r <usbip server ip> -b 2-2
- Uninstall driver
PS> usbip.exe uninstall
- Disable test signing
> bcdedit.exe /set TESTSIGNING OFF- reboot the system to apply
usbip-winis not yet ready for production use. We could find the problems with detailed logs.
- Set registry key to enable a debug filter
usbip-winuses DbgPrintEx API for kernel logging.- save following as
.regfile and run or manually insert the registry key - reboot the system to apply
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 is a good tool to view the logs.
- If your testing machine suffer from BSOD (Blue Screen of Death), you should get it via remote debugging.
WinDbgon virtual machines would be good to get logs.
- A new vhci(ude) implementation uses WPP SW tracing instead of DbgPrintEx.
DebugView.execannot catch a VHCI debug messageTraceView.exeis a good utility for a new approach, which is included in WDK.
usbip_vhci_ude.pdbfile 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.pdbas 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 of Death), you should get it via remote debugging.
WinDbgon virtual machines would be good to get logs
- usbip-win transmits usbip packets via a userland forwarder.
- forwarder log is the best to look into usbip packet internals.
- edit
usbip_forward.cto defineDEBUG_PDUat the head of the file - compile
usbip.exeorusbipd.exe debug_pdu.logis created at the path where an executable runs.
- Sometimes Linux kernel log is required
# dmesg --follow | tee kernel_log.txt
This project was supported by Basic Science Research Program through the National Research Foundation of Korea(NRF) funded by the Ministry of Education(2020R1I1A1A01066121).
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent