Skip to content

Commit

Permalink
new vhci driver based on kmdf UDE
Browse files Browse the repository at this point in the history
The old WDM-based vhci could not fully support USB libraries and
applications such as #111 because it did not implement many USB host
contoller & hub functionalities. They were impossible to be properly
developed with poor MS documents. However, MS has already implemented
most things via USB device emulation(UDE).

Now, usbip-win provides a vhci driver using UDE. It is experimental
and more tests are required.
  • Loading branch information
cezanne committed Jun 30, 2020
1 parent 9623f29 commit 96015c3
Show file tree
Hide file tree
Showing 51 changed files with 4,150 additions and 24 deletions.
56 changes: 35 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,6 @@
- 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
Expand Down Expand Up @@ -70,7 +69,6 @@ usbip.exe list -l
- 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`

Expand All @@ -80,10 +78,8 @@ usbip.exe list -l
- tested on Ubuntu 16.04 (Kernerl 4.15.0-29)
- `# modprobe usbip-host`
- You can use virtual [usbip-vstub](https://github.com/cezanne/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
Expand All @@ -92,27 +88,44 @@ usbip.exe list -l
- Enable test signing
- `> bcdedit.exe /set TESTSIGNING ON`
- reboot the system to apply
- Copy `usbip.exe`, `usbip_vhci.sys`, `usbip_vhci.inf`, `usbip_root.inf`, `usbip_vhci.cat` into a folder in target machine
- Copy vhci driver files into a folder in target machine
- Currently, there are 2 versions for a vhci driver: vhci(old) and vhci(ude)
- vhci(ude) is newly developed to fully support USB applications using MS UDE framework.
- If you're testing vhci(ude), copy `usbip.exe`, `usbip_vhci_udf.sys`, `usbip_vhci_udf.inf`, `usbip_vhci_udf.cat` into a folder in target machine
- If you're testing vhci(old), 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](https://github.com/cezanne/usbip-win/releases) 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`
- Install manually
- 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".
- Using usbip.exe install command
- Run PowerShell or CMD as an Administrator
- if using vhci(ude), `PS> usbip.exe install_ude`
- if using vhci(old), `PS> usbip.exe install`
- Install manually(new ude vhci)
- 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".
- Install manually(old vhci)
- 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
- `> usbip.exe attach -r <usbip server ip> -b 2-2`
- if using vhci(ude), `> usbip.exe attach_ude -r <usbip server ip> -b 2-2`
- if using vhci(old), `> usbip.exe attach -r <usbip server ip> -b 2-2`
- Uninstall driver
- `PS> usbip.exe uninstall`
- if using vhci(ude), `PS> usbip.exe uninstall_ude`
- if using vhci(old),`PS> usbip.exe uninstall`

### Reporting Bug
- usbip-win is not yet ready for production use. We could find problems with more detailed logs.
Expand Down Expand Up @@ -143,8 +156,9 @@ Windows Registry Editor Version 5.00

#### How to get linux kernel log
- Sometimes linux kernel log is required

```
# dmesg --follow | tee kernel_log.txt
\# dmesg --follow | tee kernel_log.txt
```

<hr>
Expand Down
15 changes: 15 additions & 0 deletions driver/vhci_ude/custom_wpp.ini
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
DEFINE_CPLX_TYPE(SETUPPKT, DBG_SETUPPKT, PCUCHAR, ItemString, "s", _SETUPPKT_, 0, 1);
WPP_FLAGS(-DDBG_SETUPPKT(x) WPP_LOGPAIR(1024, dbg_usb_setup_packet(x)));
DEFINE_CPLX_TYPE(URBR, WPP_URBR, purb_req_t, ItemString, "s", _URBR_, 0, 1);
WPP_FLAGS(-DWPP_URBR(x) WPP_LOGPAIR((128), (dbg_urbr(x))));
DEFINE_CPLX_TYPE(URBFUNC, WPP_URBFUNC, USHORT, ItemString, "s", _URBFUNC_, 0, 1);
WPP_FLAGS(-DWPP_URBFUNC(x) WPP_LOGPAIR((256), (dbg_urbfunc(x))));
DEFINE_CPLX_TYPE(IOCTL, WPP_IOCTL, unsigned int, ItemString, "s", _IOCTL_, 0, 1);
WPP_FLAGS(-DWPP_IOCTL(x) WPP_LOGPAIR((256), (dbg_vhci_ioctl_code(x))));
USEPREFIX (TRD, " %!FUNC!:");
USEPREFIX (TRW, "(WW)%!FUNC!:");
USEPREFIX (TRE, "(EE)%!FUNC!:");
FUNC TRD{LEVEL=TRACE_LEVEL_INFORMATION}(FLAGS, MSG, ...);
FUNC TRW{LEVEL=TRACE_LEVEL_WARNING}(FLAGS, MSG, ...);
FUNC TRE{LEVEL=TRACE_LEVEL_ERROR}(FLAGS, MSG, ...);
CUSTOM_TYPE(epconf, ItemEnum(_UDECX_ENDPOINTS_CONFIGURE_TYPE));
11 changes: 11 additions & 0 deletions driver/vhci_ude/gencat.bat
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
cd %1
if exist vhci_ude_cat del /s /q vhci_ude_cat
mkdir vhci_ude_cat
cd vhci_ude_cat
copy ..\usbip_vhci_ude.sys
copy ..\usbip_vhci_ude.inf
inf2cat /driver:.\ /os:%2 /uselocaltime
signtool sign /f %3 /p usbip usbip_vhci_ude.cat
copy /y usbip_vhci_ude.cat ..
cd ..
del /s /q vhci_ude_cat
86 changes: 86 additions & 0 deletions driver/vhci_ude/usbip_vhci_ude.inf
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
;
; usbip_vhci_ude.inf
;

[Version]
Signature="$WINDOWS NT$"
Class=USB
ClassGuid={36FC9E60-C465-11CF-8056-444553540000}
Provider=%ManufacturerName%
CatalogFile=usbip_vhci_ude.cat
DriverVer=

[DestinationDirs]
DefaultDestDir = 12
vhci_Device_CoInstaller_CopyFiles = 11

[SourceDisksNames]
1 = %DiskName%,,,""

[SourceDisksFiles]
usbip_vhci_ude.sys = 1,,
WdfCoInstaller$KMDFCOINSTALLERVERSION$.dll=1 ; make sure the number matches with SourceDisksNames

;*****************************************
; Install Section
;*****************************************

[Manufacturer]
%ManufacturerName%=Standard,NT$ARCH$

[Standard.NT$ARCH$]
%vhci.DeviceDesc%=vhci_Device, ROOT\VHCI_ude

[vhci_Device.NT]
CopyFiles=Drivers_Dir

[Drivers_Dir]
usbip_vhci_ude.sys

[vhci_Device.NT.HW]
AddReg=vhci_AddReg

[vhci_AddReg]
; By default, USBDevice class uses iProduct descriptor to name the device in
; Device Manager on Windows 8 and higher.
; Uncomment for this device to use %DeviceName% on Windows 8 and higher:
;HKR,,FriendlyName,,%vhci.DeviceDesc%

;-------------- Service installation
[vhci_Device.NT.Services]
AddService = usbip_vhci_ude,%SPSVCINST_ASSOCSERVICE%, vhci_Service_Inst

; -------------- vhci driver install sections
[vhci_Service_Inst]
DisplayName = %vhci.SVCDESC%
ServiceType = 1 ; SERVICE_KERNEL_DRIVER
StartType = 3 ; SERVICE_DEMAND_START
ErrorControl = 1 ; SERVICE_ERROR_NORMAL
ServiceBinary = %12%\usbip_vhci_ude.sys

;
;--- vhci_Device Coinstaller installation ------
;

[vhci_Device.NT.CoInstallers]
AddReg=vhci_Device_CoInstaller_AddReg
CopyFiles=vhci_Device_CoInstaller_CopyFiles

[vhci_Device_CoInstaller_AddReg]
HKR,,CoInstallers32,0x00010000, "WdfCoInstaller$KMDFCOINSTALLERVERSION$.dll,WdfCoInstaller"

[vhci_Device_CoInstaller_CopyFiles]
WdfCoInstaller$KMDFCOINSTALLERVERSION$.dll

[vhci_Device.NT.Wdf]
KmdfService = usbip_vhci_ude, usbip_vhci_wdfsect
[usbip_vhci_wdfsect]
KmdfLibraryVersion = $KMDFVERSION$

[Strings]
SPSVCINST_ASSOCSERVICE= 0x00000002
ManufacturerName="usbip-win project"
DiskName = "usbip-win VHCI(ude) Disk"
vhci.DeviceDesc = "usbip-win VHCI(ude)"
vhci.SVCDESC = "usbip-win vhci(ude) Service"
REG_MULTI_SZ = 0x00010000
Loading

0 comments on commit 96015c3

Please sign in to comment.