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