Skip to content

Latest commit

 

History

History
179 lines (161 loc) · 9.04 KB

README.md

File metadata and controls

179 lines (161 loc) · 9.04 KB
Raw

usbip-win2

This repo has been de facto superseded by usbip-win2.

USB/IP for Windows

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

Build

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

Build Tools

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

Build Process

  • 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_stub and usbip_vhci projects
    • Right-click on the Project > Properties > Driver Signing > Test Certificate
    • Browse to driver/usbip_test.pfx (password: usbip)
  • Build solution or desired project
  • All output files are created under {Debug,Release}/{x64,x86} folder.

Install

Windows USB/IP server

  • 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
      1. "Trusted Root Certification Authority" in "Local Computer" (not current user) and
      2. "Trusted Publishers" in "Local Computer" (not current user)
  • 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.inx into a folder in target machine
    • You can find usbip.exe, usbipd.exe, usbip_stub.sys in the output folder after build or on release page.
    • userspace/usb.ids
    • driver/stub/usbip_stub.inx
  • Find USB Device ID
    • You can get id from usbip listing
      • > 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)
  • 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.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
  • Attach USB/IP device on Linux machine
    • # usbip attach -r <usbip server ip> -b 1-59

Windows USB/IP client

  • 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
      1. "Trusted Root Certification Authority" in "Local Computer" (not current user) and
      2. "Trusted Publishers" in "Local Computer" (not current user)
  • 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), copy usbip.exe, usbip_vhci_ude.sys, usbip_vhci_ude.inf, usbip_vhci_ude.cat into a folder in target machine;
    • 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;
    • You can find all files in output folder after build or on release page.
  • Install USB/IP VHCI driver
    • You can install using usbip.exe or manually
    • Using usbip.exe install 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 -u if UDE driver only
      • PS> usbip.exe install -w if 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".
  • 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

Reporting Bugs

  • usbip-win is not yet ready for production use. We could find the problems with detailed logs.

How to get Windows kernel log for vhci(wdm)

  • Set registry key to enable a debug filter 
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.
  • If your testing machine suffer from BSOD (Blue Screen of Death), you should get it via remote debugging.
    • WinDbg on virtual machines would be good to get logs.

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 of Death), you should get it via remote debugging.
    • WinDbg on virtual machines would be good to get logs

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

How to get linux kernel log

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