xref: /openbmc/linux/tools/usb/usbip/README (revision ba61bb17)
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 -> ov511
142
143     - busid 3-2 (0711:0902)
144	     3-2:1.0 -> none
145
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
149
150     - busid 3-3.2 (04bb:0206)
151	     3-3.2:1.0 -> usb-storage
152
153     - busid 3-3 (0409:0058)
154	     3-3:1.0 -> hub
155
156     - busid 4-1 (046d:08b2)
157	     4-1:1.0 -> none
158	     4-1:1.1 -> none
159	     4-1:1.2 -> none
160
161     - busid 5-2 (058f:9254)
162	     5-2:1.0 -> hub
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 -> usbip-host
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