USB/IP Client for Windows

• Fully compatible with USB/IP protocol
• Works with Linux USB/IP server at least for kernels 4.19 - 6.8
• Is not ready for production use, can cause BSOD. Create a restore point before installing USBip.
• The driver is not signed, Windows Test Signing Mode must be enabled
• Do not set testsigning off when USBip is installed, see
• You can donate to purchase an EV certificate which is required for signing the driver, please read
• Devices that work (the list is incomplete)

Requirements

• Windows 10 x64 Version 1809 (OS build 17763) and later
• Windows 11 ARM64
• Server must support USB/IP protocol v.1.1.1

Key features

• UDE driver is an USB/IP client
• USB class upper filter driver usbip2_filter is used as companion for UDE driver
• Winsock Kernel NPI is used
  • The driver establishes TCP/IP connection with a server and does data exchange
  • This implies low latency and high throughput, absence of frequent CPU context switching and a lot of syscalls
• Zero copy of transfer buffers is implemented for network send and receive operations
  • Memory Descriptor List is used to send multiple buffers in a single call (vectored I/O)
  • WskSend reads data from URB transfer buffer
  • WskReceive writes data to URB transfer buffer
• A dedicated thread is created for each virtual device to receive data from a server

Differences with cezanne/usbip-win

• The 2-Clause BSD License since release 0.9.7.0
  • If you decide to WHQL the drivers, make sure to base them on this release or newer, since the GPL 3.0 license used prior to this release is not compatible with WHQL.
• Brand new UDE driver, not inherited from the parent repo
• Full-featured GUI app
• Userspace code is fully rewritten (libusbip and usbip utility)
• SDK for third party developers (libusbip public API)
• InnoSetup installer is used for installation of drivers and userspace stuff
• Windows 10 version 1809 or later is required
• C++ 20 is used for all projects
• Visual Studio 2022 is used
• Server (stub driver) is removed
• x64/arm64 builds only

Build

Build Tools

• Visual Studio 2022
• SDK for Windows 11, version 24H2 (10.0.26100.1742)
• WDK for Windows 11, version 24H2 (10.0.26100.2161)

Build Visual Studio solution

• Install git
  • Run Visual Studio Installer
  • Select "Individual components" tab
  • Type "git" in search box
  • Check "Git for Windows"
  • Install selected items
• Clone project using git or download an archive from github and extract source code
• Run bootstrap.bat
• Open usbip_win2.sln
• Set certificate driver signing for package project
  • Right-click on the Project > Properties > Driver Signing > Test Certificate
  • Enter usbip.pfx (password: usbip)
• Build the solution
• All output files are created under {x64,ARM64}/{Debug,Release} folders.

Setup USB/IP server on Ubuntu Linux

• Install required packages
  • Linux sudo apt install linux-tools-generic linux-cloud-tools-generic
  • Raspberry Pi sudo apt install usbip hwdata usbutils
• Load modules and run the daemon

sudo modprobe -a usbip-core usbip-host
sudo usbipd -D

• List available USB devices
  • usbip list -l

 - busid 3-2 (1005:b113)
   Apacer Technology, Inc. : Handy Steno/AH123 / Handy Steno 2.0/HT203 (1005:b113)
 - busid 3-3.2 (07ca:513b)
   AVerMedia Technologies, Inc. : unknown product (07ca:513b)

• Bind desired USB device
  • sudo usbip bind -b 3-2

usbip: info: bind device on busid 3-2: complete

• Your device 3-2 now can be used by usbip client

Setup USB/IP on Windows

Enable Windows Test Signing Mode

• bcdedit.exe /set testsigning on
• Reboot the system to apply

Install USB/IP

• Create a restore point to undo possible system crashes
  • In the search box on the taskbar, type 'Create a restore point', and select it from the list of results
  • On the System Protection tab in System Properties
    • Make sure system drive protection is enabled
    • Select Create
    • Type a description for the restore point, and then select Create
• Download and run an installer from releases
• Some antivirus programs issue false positives for InnoSetup installer

Use usbip.exe to attach remote device(s)

• Query available USB devices on the server
  • usbip.exe list -r <usbip server ip>

Exportable USB devices
======================
 - 192.168.1.9
        3-2: unknown vendor : unknown product (1005:b113)
           : /sys/devices/pci0000:00/0000:00:14.0/usb3/3-2
           : (Defined at Interface level) (00/00/00)

• Attach desired remote USB device using its busid
  • usbip.exe attach -r <usbip server ip> -b 3-2

successfully attached to port 1

• New USB device should appear in the system, use it as usual
• Detach the remote USB device using its usb port, pass -all to detach all remote devices
  • usbip.exe detach -p 1

port 1 is successfully detached

Uninstallation of USB/IP

• Uninstall USB/IP app
• Disable test signing
  • bcdedit.exe /set testsigning off
  • Reboot the system to apply
• If an uninstaller is corrupted, run these commands as Administrator
• If you copy commands to a .bat file, use %%P and %%~nxP in FOR statement

set APPDIR=C:\Program Files\USBip
set HWID=ROOT\USBIP_WIN2\UDE

"%APPDIR%\usbip.exe" detach --all

"%APPDIR%\devnode.exe" remove %HWID% root
rem pnputil.exe /remove-device /deviceid %HWID% /subtree

rem WARNING: use %%P and %%~nxP if you run this command in a .bat file
FOR /f %P IN ('findstr /M /L %HWID% C:\WINDOWS\INF\oem*.inf') DO pnputil.exe /delete-driver %~nxP /uninstall

"%APPDIR%\classfilter.exe" uninstall "%APPDIR%\usbip2_filter.inf" DefaultUninstall.NTamd64
rd /S /Q "%APPDIR%"

Disable Windows Test Signing Mode without removing USB/IP

• Can be useful if you want to temporary disable test signing
• After that, USBip will not work until the test signing will be reenabled
• usbip2_filter driver must be disabled, otherwise all USB controllers/devices will not work

devcon.exe classfilter usb upper !usbip2_filter
bcdedit.exe /set testsigning off

• To enable it again

devcon.exe classfilter usb upper +usbip2_filter
bcdedit.exe /set testsigning on

• If devcon.exe is not installed
  • Run regedit.exe
  • Open key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{36fc9e60-c465-11cf-8056-444553540000}
  • Remove usbip2_filter line from UpperFilters multi-string value to disable the driver
  • Add this line to enable the driver

Obtaining USB/IP logs on Windows

• WPP Software Tracing is used
• Use the tools for software tracing, such as TraceView, Tracelog, Tracefmt, and Tracepdb to configure, start, and stop tracing sessions and to display and filter trace messages
• These tools are included in the Windows Driver Kit
• Pick "Select Components/Program DataBase files" during USBip installation
• Start log sessions for drivers (run commands as Administrator)

rem change to your WDK version
set PATH=%PATH%;C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x64

set NAME=usbip

tracelog.exe -stop %NAME%-flt
tracelog.exe -stop %NAME%-ude

del /F %NAME%-*.*
tracepdb.exe -f "C:\Program Files\USBip\*.pdb" -s -p %TEMP%\%NAME%

tracelog.exe -start %NAME%-flt -guid #90c336ed-69fb-43d6-b800-1552d72d200b -f %NAME%-flt.etl -flag 0x3 -level 5
tracelog.exe -start %NAME%-ude -guid #ed18c9c5-8322-48ae-bf78-d01d898a1562 -f %NAME%-ude.etl -flag 0xF -level 5

• Reproduce the issue
• Stop log sessions and get plain text logs (run commands as Administrator)
• If you copy commands to a .bat file, double '%' in TRACE_FORMAT_PREFIX

rem change to your WDK version
set PATH=%PATH%;C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x64

set NAME=usbip
set TRACE_FORMAT_PREFIX=[%9]%3!04x! %!LEVEL! %!FUNC!:

tracelog.exe -stop %NAME%-flt
tracelog.exe -stop %NAME%-ude

tracefmt.exe -nosummary -p %TEMP%\%NAME% -o %NAME%-flt.txt %NAME%-flt.etl
tracefmt.exe -nosummary -p %TEMP%\%NAME% -o %NAME%-ude.txt %NAME%-ude.etl

rem sed -i "s/TRACE_LEVEL_CRITICAL/CRT/;s/TRACE_LEVEL_ERROR/ERR/;s/TRACE_LEVEL_WARNING/WRN/;s/TRACE_LEVEL_INFORMATION/INF/;s/TRACE_LEVEL_VERBOSE/VRB/" %NAME%-*.txt
rem sed -i "s/`anonymous namespace':://" %NAME%-*.txt
rem del /F sed*

Debugging BSOD

• Enable kernel memory dump
  • Open "System Properties" dialog box
  • Select "Advanced" tab
  • Click on "Settings" in "Startup and Recovery"
  • "System failure", "Write debugging information", pick "Automatic Memory Dump" or "Kernel Memory Dump"
  • Check "Overwrite any existing file"
• Start WPP tracing session for drivers as described in the previous topic
• When BSOD has occured
  • Reboot PC if automatic reboot is not set
  • Run Windows debugger WinDbg.exe as Administrator
  • Press Ctrl+D to open crash dump in C:\Windows
  • Run following commands and copy the output

.sympath+ C:\Program Files\USBip
!wmitrace.searchpath +%TEMP%\usbip
!analyze -v
!wdfkd.wdfsearchpath %TEMP%\USBip
!wdfkd.wdfsettraceprefix [%9]%3!04x! %!LEVEL! %!FUNC!:
!wdfkd.wdflogdump usbip2_ude -d
!wdfkd.wdflogdump usbip2_ude -f

Obtaining USB/IP log on Linux

sudo killall usbipd
sudo modprobe -r usbip-host usbip-vudc vhci-hcd usbip-core
sudo modprobe usbip-core usbip_debug_flag=0xFFFFFFFF
sudo modprobe -a usbip-host usbip-vudc vhci-hcd
sudo usbipd -D
dmesg --follow | tee ~/usbip.log

Testing the driver

• Driver Verifier is used for testing
• Run verifier.exe as Administrator
• Enable testing

verifier /rc 1 2 4 5 6 8 9 12 18 34  10 11 14 15 16 17 20 24 26 33 35 36 /driver usbip2_filter.sys usbip2_ude.sys

• Be aware that rule class 26 "Code integrity checking" forces to use NonPagedPoolNx instead of NonPagedPool
• Query driver statistics

verifier /query

• Disable testing

verifier /reset

• To run Static Driver Verifier, set "Treat Warnings As Errors" to "No" for libdrv, usbip2_filter, usbip2_ude projects

If you like this project