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