Skip to content

xwize/usbip-win

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

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.17xxx
    • VS 2017(v141): requires >= 10.0.18xxx
  • 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

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

    • Tested on Ubuntu 16.04
    • Kernel 4.15.0-29 (USB/IP kernel module crash was observed on some other version)
    • # modprobe vhci-hcd
  • Install USB/IP test certificate

    • Install driver/usbip_test.pfx (password: usbip)
    • Certificate should be installed into "Trusted Root Certification Authority" and "Trusted Publishers" on local machine (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 output folder.
    • userspace/usb.ids
    • driver/stub/usbip_stub.inx
  • Find USB device id

    • You can get device 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

    • This command replaces an 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

  • Prepare a linux machine as a USB/IP server

    • tested on Ubuntu 16.04(Kernerl 4.15.0-29)
    • # modprobe usbip-host
  • 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" on local machine(not current user)
  • Enable test signing

    • bcdedit.exe /set TESTSIGNING ON
    • reboot the system to apply
  • Copy usbip.exe, usbip_vhci.sys, usbip_vhci.inf, usbip_vhci.cer, usbip_vhci.cat into a folder in target machine

    • You can find usbip.exe, usbip_vhci.sys, usbip_vhci.cer, usbip_vhci.inf in output folder.
    • usbip_vhci.cat can be found from usbip_vhci subfolder of output folder
  • Install USB/IP vhci driver

    • 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, and then click Next.
    • Click Finish at 'Completing the Add/Remove Hardware Wizard.'
  • Attach a remote USB device

    • usbip.exe attach -r <usbip server ip> -b 2-2

Reporting Bug

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

How to get windows kernel log

  • 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 on 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(2016R1A6A3A11930295).

About

USB/IP for Windows

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • C 99.1%
  • Roff 0.9%