README
1#
2# README for usbip-utils
3#
4# Copyright (C) 2011 matt mooney <mfm@muteddisk.com>
5# 2005-2008 Takahiro Hirofuchi
6
7[Overview]
8USB/IP protocol allows to pass USB device from server to client over the
9network. Server is a machine which provides (shares) a USB device. Client is
10a machine which uses USB device provided by server over the network.
11The USB device may be either physical device connected to a server or
12software entity created on a server using USB gadget subsystem.
13Whole 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]
62On a server side there are two entities which can be shared.
63First of them is physical usb device connected to the machine.
64To 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
82Second of shareable entities is USB Gadget created using USB Gadget Subsystem
83on 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
104To 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---------------------------
128Physically 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
134In another terminal, let's look up what USB devices are physically
135attached 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
164A USB storage device of busid 3-3.2 is now bound to the usb-storage
165driver. To export this device, we first mark the device as
166"exportable"; the device is bound to the usbip-host driver. Please
167remember you can not export a USB hub.
168
169Mark 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---------------------------
189First, let's list available remote devices that are marked as
190exportable 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
221Attach a remote USB device:
222
223 deux:# usbip attach --remote 10.0.0.3 --busid 1-1
224 port 0 attached
225
226Show 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
237Detach 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
246 - usbip-host.ko must be bound to the target device.
247 - See /sys/kernel/debug/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 bind command)
250 - Shutdown firewall.
251 - usbip now uses TCP port 3240.
252 - Disable SELinux.
253 - Check the kernel and daemon messages.
254
255
256[Contact]
257 Mailing List: linux-usb@vger.kernel.org
258