- 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).