Commit | Line | Data |
---|---|---|
0945b4fe TH |
1 | # |
2 | # README for usbip-utils | |
3 | # | |
89415218 | 4 | # Copyright (C) 2011 matt mooney <mfm@muteddisk.com> |
5 | # 2005-2008 Takahiro Hirofuchi | |
0945b4fe | 6 | |
444d9309 KO |
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. | |
0945b4fe TH |
30 | |
31 | [Requirements] | |
32 | - USB/IP device drivers | |
444d9309 | 33 | Found in the drivers/usb/usbip/ directory of the Linux kernel tree. |
0945b4fe | 34 | |
98ada08a VM |
35 | - libudev >= 2.0 |
36 | libudev library | |
0945b4fe TH |
37 | |
38 | - libwrap0-dev | |
89415218 | 39 | tcp wrapper library |
0945b4fe TH |
40 | |
41 | - gcc >= 4.0 | |
42 | ||
0945b4fe TH |
43 | - libtool, automake >= 1.9, autoconf >= 2.5.0, pkg-config |
44 | ||
04f7bb9d VM |
45 | [Optional] |
46 | - hwdata | |
47 | Contains USB device identification data. | |
48 | ||
89415218 | 49 | |
0945b4fe | 50 | [Install] |
89415218 | 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 | |
0945b4fe | 57 | |
89415218 | 58 | 2. Compile & install USB/IP drivers. |
0945b4fe | 59 | |
0945b4fe TH |
60 | |
61 | [Usage] | |
444d9309 KO |
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 | ||
89415218 | 66 | server:# (Physically attach your USB device.) |
0945b4fe | 67 | |
220973dd | 68 | server:# insmod usbip-core.ko |
69 | server:# insmod usbip-host.ko | |
0945b4fe TH |
70 | |
71 | server:# usbipd -D | |
89415218 | 72 | - Start usbip daemon. |
0945b4fe | 73 | |
89415218 | 74 | server:# usbip list -l |
75 | - List driver assignments for USB devices. | |
0945b4fe | 76 | |
89415218 | 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. | |
0945b4fe | 81 | |
444d9309 KO |
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 | ||
220973dd | 106 | client:# insmod usbip-core.ko |
0945b4fe | 107 | client:# insmod vhci-hcd.ko |
0945b4fe | 108 | |
89415218 | 109 | client:# usbip list --remote <host> |
110 | - List exported USB devices on the <host>. | |
111 | ||
80e4b943 | 112 | client:# usbip attach --remote <host> --busid 1-2 |
89415218 | 113 | - Connect the remote USB device. |
444d9309 KO |
114 | - When using vudc on a server side busid is really vudc instance name. |
115 | For example: usbip-vudc.0 | |
0945b4fe | 116 | |
89415218 | 117 | client:# usbip port |
118 | - Show virtual port status. | |
0945b4fe | 119 | |
89415218 | 120 | client:# usbip detach --port <port> |
121 | - Detach the USB device. | |
0945b4fe | 122 | |
0945b4fe | 123 | |
89415218 | 124 | [Example] |
125 | --------------------------- | |
126 | SERVER SIDE | |
127 | --------------------------- | |
128 | Physically attach your USB devices to this host. | |
0945b4fe | 129 | |
89415218 | 130 | trois:# insmod path/to/usbip-core.ko |
131 | trois:# insmod path/to/usbip-host.ko | |
132 | trois:# usbipd -D | |
0945b4fe | 133 | |
89415218 | 134 | In another terminal, let's look up what USB devices are physically |
135 | attached to this host. | |
0945b4fe | 136 | |
45dd9a98 | 137 | trois:# usbip list -l |
89415218 | 138 | Local USB devices |
139 | ================= | |
140 | - busid 1-1 (05a9:a511) | |
141 | 1-1:1.0 -> ov511 | |
9abec452 | 142 | |
89415218 | 143 | - busid 3-2 (0711:0902) |
144 | 3-2:1.0 -> none | |
9abec452 | 145 | |
89415218 | 146 | - busid 3-3.1 (08bb:2702) |
147 | 3-3.1:1.0 -> snd-usb-audio | |
148 | 3-3.1:1.1 -> snd-usb-audio | |
9abec452 | 149 | |
89415218 | 150 | - busid 3-3.2 (04bb:0206) |
151 | 3-3.2:1.0 -> usb-storage | |
9abec452 | 152 | |
89415218 | 153 | - busid 3-3 (0409:0058) |
154 | 3-3:1.0 -> hub | |
9abec452 | 155 | |
89415218 | 156 | - busid 4-1 (046d:08b2) |
157 | 4-1:1.0 -> none | |
158 | 4-1:1.1 -> none | |
159 | 4-1:1.2 -> none | |
9abec452 | 160 | |
89415218 | 161 | - busid 5-2 (058f:9254) |
162 | 5-2:1.0 -> hub | |
9abec452 | 163 | |
89415218 | 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. | |
0945b4fe | 168 | |
89415218 | 169 | Mark the device of busid 3-3.2 as exportable: |
9abec452 | 170 | |
89415218 | 171 | trois:# usbip --debug bind --busid 3-3.2 |
172 | ... | |
45dd9a98 | 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 | |
0945b4fe | 176 | |
89415218 | 177 | trois:# usbip list -l |
178 | Local USB devices | |
179 | ================= | |
180 | ... | |
0945b4fe | 181 | |
89415218 | 182 | - busid 3-3.2 (04bb:0206) |
183 | 3-3.2:1.0 -> usbip-host | |
184 | ... | |
0945b4fe | 185 | |
89415218 | 186 | --------------------------- |
187 | CLIENT SIDE | |
188 | --------------------------- | |
189 | First, let's list available remote devices that are marked as | |
190 | exportable on the host. | |
0945b4fe | 191 | |
89415218 | 192 | deux:# insmod path/to/usbip-core.ko |
193 | deux:# insmod path/to/vhci-hcd.ko | |
0945b4fe | 194 | |
89415218 | 195 | deux:# usbip list --remote 10.0.0.3 |
45dd9a98 | 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) | |
89415218 | 220 | |
221 | Attach a remote USB device: | |
222 | ||
80e4b943 | 223 | deux:# usbip attach --remote 10.0.0.3 --busid 1-1 |
89415218 | 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 | - See 'Debug Tips' on the project wiki. | |
245 | - http://usbip.wiki.sourceforge.net/how-to-debug-usbip | |
220973dd | 246 | - usbip-host.ko must be bound to the target device. |
21470e32 | 247 | - See /sys/kernel/debug/usb/devices and find "Driver=..." lines of the device. |
444d9309 KO |
248 | - Target USB gadget must be bound to vudc |
249 | (using USB gadget susbsys, not usbip bind command) | |
0945b4fe | 250 | - Shutdown firewall. |
89415218 | 251 | - usbip now uses TCP port 3240. |
0945b4fe | 252 | - Disable SELinux. |
89415218 | 253 | - Check the kernel and daemon messages. |
0945b4fe TH |
254 | |
255 | ||
256 | [Contact] | |
89415218 | 257 | Mailing List: linux-usb@vger.kernel.org |