| 1 |
# |
| 2 |
# README for usbip-utils |
| 3 |
# |
| 4 |
# Copyright (C) 2011 matt mooney <[email protected]> |
| 5 |
# 2005-2008 Takahiro Hirofuchi |
| 6 |
|
| 7 |
[Overview] |
| 8 |
USB/IP protocol allows to pass USB device from server to client over the |
| 9 |
network. Server is a machine which provides (shares) a USB device. Client is |
| 10 |
a machine which uses USB device provided by server over the network. |
| 11 |
The USB device may be either physical device connected to a server or |
| 12 |
software entity created on a server using USB gadget subsystem. |
| 13 |
Whole project consists of four parts: |
| 14 |
|
| 15 |
- usbip-vhci |
| 16 |
A client side kernel module which provides a virtual USB Host Controller |
| 17 |
and allows to import a USB device from a remote machine. |
| 18 |
|
| 19 |
- usbip-host (stub driver) |
| 20 |
A server side module which provides a USB device driver which can be |
| 21 |
bound to a physical USB device to make it exportable. |
| 22 |
|
| 23 |
- usbip-vudc |
| 24 |
A server side module which provides a virtual USB Device Controller and allows |
| 25 |
to export a USB device created using USB Gadget Subsystem. |
| 26 |
|
| 27 |
- usbip-utils |
| 28 |
A set of userspace tools used to handle connection and management. |
| 29 |
Used on both sides. |
| 30 |
|
| 31 |
[Requirements] |
| 32 |
- USB/IP device drivers |
| 33 |
Found in the drivers/usb/usbip/ directory of the Linux kernel tree. |
| 34 |
|
| 35 |
- libudev >= 2.0 |
| 36 |
libudev library |
| 37 |
|
| 38 |
- libwrap0-dev |
| 39 |
tcp wrapper library |
| 40 |
|
| 41 |
- gcc >= 4.0 |
| 42 |
|
| 43 |
- libtool, automake >= 1.9, autoconf >= 2.5.0, pkg-config |
| 44 |
|
| 45 |
[Optional] |
| 46 |
- hwdata |
| 47 |
Contains USB device identification data. |
| 48 |
|
| 49 |
|
| 50 |
[Install] |
| 51 |
0. Generate configuration scripts. |
| 52 |
$ ./autogen.sh |
| 53 |
|
| 54 |
1. Compile & install the userspace utilities. |
| 55 |
$ ./configure [--with-tcp-wrappers=no] [--with-usbids-dir=<dir>] |
| 56 |
$ make install |
| 57 |
|
| 58 |
2. Compile & install USB/IP drivers. |
| 59 |
|
| 60 |
|
| 61 |
[Usage] |
| 62 |
On a server side there are two entities which can be shared. |
| 63 |
First of them is physical usb device connected to the machine. |
| 64 |
To make it available below steps should be executed: |
| 65 |
|
| 66 |
server:# (Physically attach your USB device.) |
| 67 |
|
| 68 |
server:# insmod usbip-core.ko |
| 69 |
server:# insmod usbip-host.ko |
| 70 |
|
| 71 |
server:# usbipd -D |
| 72 |
- Start usbip daemon. |
| 73 |
|
| 74 |
server:# usbip list -l |
| 75 |
- List driver assignments for USB devices. |
| 76 |
|
| 77 |
server:# usbip bind --busid 1-2 |
| 78 |
- Bind usbip-host.ko to the device with busid 1-2. |
| 79 |
- The USB device 1-2 is now exportable to other hosts! |
| 80 |
- Use `usbip unbind --busid 1-2' to stop exporting the device. |
| 81 |
|
| 82 |
Second of shareable entities is USB Gadget created using USB Gadget Subsystem |
| 83 |
on a server machine. To make it available below steps should be executed: |
| 84 |
|
| 85 |
server:# (Create your USB gadget) |
| 86 |
- Currently the most preferable way of creating a new USB gadget |
| 87 |
is ConfigFS Composite Gadget. Please refer to its documentation |
| 88 |
for details. |
| 89 |
- See vudc_server_example.sh for a short example of USB gadget creation |
| 90 |
|
| 91 |
server:# insmod usbip-core.ko |
| 92 |
server:# insmod usbip-vudc.ko |
| 93 |
- To create more than one instance of vudc use num module param |
| 94 |
|
| 95 |
server:# (Bind gadget to one of available vudc) |
| 96 |
- Assign your new gadget to USB/IP UDC |
| 97 |
- Using ConfigFS interface you may do this simply by: |
| 98 |
server:# cd /sys/kernel/config/usb_gadget/<gadget_name> |
| 99 |
server:# echo "usbip-vudc.0" > UDC |
| 100 |
|
| 101 |
server:# usbipd -D --device |
| 102 |
- Start usbip daemon. |
| 103 |
|
| 104 |
To attach new device to client machine below commands should be used: |
| 105 |
|
| 106 |
client:# insmod usbip-core.ko |
| 107 |
client:# insmod vhci-hcd.ko |
| 108 |
|
| 109 |
client:# usbip list --remote <host> |
| 110 |
- List exported USB devices on the <host>. |
| 111 |
|
| 112 |
client:# usbip attach --remote <host> --busid 1-2 |
| 113 |
- Connect the remote USB device. |
| 114 |
- When using vudc on a server side busid is really vudc instance name. |
| 115 |
For example: usbip-vudc.0 |
| 116 |
|
| 117 |
client:# usbip port |
| 118 |
- Show virtual port status. |
| 119 |
|
| 120 |
client:# usbip detach --port <port> |
| 121 |
- Detach the USB device. |
| 122 |
|
| 123 |
|
| 124 |
[Example] |
| 125 |
--------------------------- |
| 126 |
SERVER SIDE |
| 127 |
--------------------------- |
| 128 |
Physically attach your USB devices to this host. |
| 129 |
|
| 130 |
trois:# insmod path/to/usbip-core.ko |
| 131 |
trois:# insmod path/to/usbip-host.ko |
| 132 |
trois:# usbipd -D |
| 133 |
|
| 134 |
In another terminal, let's look up what USB devices are physically |
| 135 |
attached to this host. |
| 136 |
|
| 137 |
trois:# usbip list -l |
| 138 |
Local USB devices |
| 139 |
================= |
| 140 |
- busid 1-1 (05a9:a511) |
| 141 |
1-1:1.0 |
| 142 |
|
| 143 |
- busid 3-2 (0711:0902) |
| 144 |
3-2:1.0 |
| 145 |
|
| 146 |
- busid 3-3.1 (08bb:2702) |
| 147 |
3-3.1:1.0 |
| 148 |
3-3.1:1.1 |
| 149 |
|
| 150 |
- busid 3-3.2 (04bb:0206) |
| 151 |
3-3.2:1.0 |
| 152 |
|
| 153 |
- busid 3-3 (0409:0058) |
| 154 |
3-3:1.0 |
| 155 |
|
| 156 |
- busid 4-1 (046d:08b2) |
| 157 |
4-1:1.0 |
| 158 |
4-1:1.1 |
| 159 |
4-1:1.2 |
| 160 |
|
| 161 |
- busid 5-2 (058f:9254) |
| 162 |
5-2:1.0 |
| 163 |
|
| 164 |
A USB storage device of busid 3-3.2 is now bound to the usb-storage |
| 165 |
driver. To export this device, we first mark the device as |
| 166 |
"exportable"; the device is bound to the usbip-host driver. Please |
| 167 |
remember you can not export a USB hub. |
| 168 |
|
| 169 |
Mark the device of busid 3-3.2 as exportable: |
| 170 |
|
| 171 |
trois:# usbip --debug bind --busid 3-3.2 |
| 172 |
... |
| 173 |
usbip debug: usbip_bind.c:162:[unbind_other] 3-3.2:1.0 -> usb-storage |
| 174 |
... |
| 175 |
bind device on busid 3-3.2: complete |
| 176 |
|
| 177 |
trois:# usbip list -l |
| 178 |
Local USB devices |
| 179 |
================= |
| 180 |
... |
| 181 |
|
| 182 |
- busid 3-3.2 (04bb:0206) |
| 183 |
3-3.2:1.0 |
| 184 |
... |
| 185 |
|
| 186 |
--------------------------- |
| 187 |
CLIENT SIDE |
| 188 |
--------------------------- |
| 189 |
First, let's list available remote devices that are marked as |
| 190 |
exportable on the host. |
| 191 |
|
| 192 |
deux:# insmod path/to/usbip-core.ko |
| 193 |
deux:# insmod path/to/vhci-hcd.ko |
| 194 |
|
| 195 |
deux:# usbip list --remote 10.0.0.3 |
| 196 |
Exportable USB devices |
| 197 |
====================== |
| 198 |
- 10.0.0.3 |
| 199 |
1-1: Prolific Technology, Inc. : unknown product (067b:3507) |
| 200 |
: /sys/devices/pci0000:00/0000:00:1f.2/usb1/1-1 |
| 201 |
: (Defined at Interface level) / unknown subclass / unknown protocol (00/00/00) |
| 202 |
: 0 - Mass Storage / SCSI / Bulk (Zip) (08/06/50) |
| 203 |
|
| 204 |
1-2.2.1: Apple Computer, Inc. : unknown product (05ac:0203) |
| 205 |
: /sys/devices/pci0000:00/0000:00:1f.2/usb1/1-2/1-2.2/1-2.2.1 |
| 206 |
: (Defined at Interface level) / unknown subclass / unknown protocol (00/00/00) |
| 207 |
: 0 - Human Interface Devices / Boot Interface Subclass / Keyboard (03/01/01) |
| 208 |
|
| 209 |
1-2.2.3: OmniVision Technologies, Inc. : OV511+ WebCam (05a9:a511) |
| 210 |
: /sys/devices/pci0000:00/0000:00:1f.2/usb1/1-2/1-2.2/1-2.2.3 |
| 211 |
: (Defined at Interface level) / unknown subclass / unknown protocol (00/00/00) |
| 212 |
: 0 - Vendor Specific Class / unknown subclass / unknown protocol (ff/00/00) |
| 213 |
|
| 214 |
3-1: Logitech, Inc. : QuickCam Pro 4000 (046d:08b2) |
| 215 |
: /sys/devices/pci0000:00/0000:00:1e.0/0000:02:0a.0/usb3/3-1 |
| 216 |
: (Defined at Interface level) / unknown subclass / unknown protocol (00/00/00) |
| 217 |
: 0 - Data / unknown subclass / unknown protocol (0a/ff/00) |
| 218 |
: 1 - Audio / Control Device / unknown protocol (01/01/00) |
| 219 |
: 2 - Audio / Streaming / unknown protocol (01/02/00) |
| 220 |
|
| 221 |
Attach a remote USB device: |
| 222 |
|
| 223 |
deux:# usbip attach --remote 10.0.0.3 --busid 1-1 |
| 224 |
port 0 attached |
| 225 |
|
| 226 |
Show the devices attached to this client: |
| 227 |
|
| 228 |
deux:# usbip port |
| 229 |
Port 00: <Port in Use> at Full Speed(12Mbps) |
| 230 |
Prolific Technology, Inc. : unknown product (067b:3507) |
| 231 |
6-1 -> usbip://10.0.0.3:3240/1-1 (remote bus/dev 001/004) |
| 232 |
6-1:1.0 used by usb-storage |
| 233 |
/sys/class/scsi_device/0:0:0:0/device |
| 234 |
/sys/class/scsi_host/host0/device |
| 235 |
/sys/block/sda/device |
| 236 |
|
| 237 |
Detach the imported device: |
| 238 |
|
| 239 |
deux:# usbip detach --port 0 |
| 240 |
port 0 detached |
| 241 |
|
| 242 |
|
| 243 |
[Checklist] |
| 244 |
- usbip-host.ko must be bound to the target device. |
| 245 |
- See /sys/kernel/debug/usb/devices and find "Driver=..." lines of the device. |
| 246 |
- Target USB gadget must be bound to vudc |
| 247 |
(using USB gadget susbsys, not usbip bind command) |
| 248 |
- Shutdown firewall. |
| 249 |
- usbip now uses TCP port 3240. |
| 250 |
- Disable SELinux. |
| 251 |
- Check the kernel and daemon messages. |
| 252 |
|
| 253 |
|
| 254 |
[Contact] |
| 255 |
Mailing List: [email protected] |