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