1 # 2 # README for usbip-utils 3 # 4 # Copyright (C) 2011 matt mooney <mfm@muteddisk.com> 5 # 2005-2008 Takahiro Hirofuchi 6 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. 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] 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 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 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 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 --------------------------- 128 Physically 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 134 In another terminal, let's look up what USB devices are physically 135 attached 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 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. 168 169 Mark 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 --------------------------- 189 First, let's list available remote devices that are marked as 190 exportable 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 221 Attach a remote USB device: 222 223 deux:# usbip attach --remote 10.0.0.3 --busid 1-1 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 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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.