258 lines · plain
1#2# README for usbip-utils3#4# Copyright (C) 2011 matt mooney <mfm@muteddisk.com>5# 2005-2008 Takahiro Hirofuchi6 7[Overview]8USB/IP protocol allows to pass USB device from server to client over the9network. Server is a machine which provides (shares) a USB device. Client is10a machine which uses USB device provided by server over the network.11The USB device may be either physical device connected to a server or12software entity created on a server using USB gadget subsystem.13Whole project consists of four parts:14 15 - usbip-vhci16 A client side kernel module which provides a virtual USB Host Controller17 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 be21 bound to a physical USB device to make it exportable.22 23 - usbip-vudc24 A server side module which provides a virtual USB Device Controller and allows25 to export a USB device created using USB Gadget Subsystem.26 27 - usbip-utils28 A set of userspace tools used to handle connection and management.29 Used on both sides.30 31[Requirements]32 - USB/IP device drivers33 Found in the drivers/usb/usbip/ directory of the Linux kernel tree.34 35 - libudev >= 2.036 libudev library37 38 - libwrap0-dev39 tcp wrapper library40 41 - gcc >= 4.042 43 - libtool, automake >= 1.9, autoconf >= 2.5.0, pkg-config44 45[Optional]46 - hwdata47 Contains USB device identification data.48 49 50[Install]51 0. Generate configuration scripts.52 $ ./autogen.sh53 54 1. Compile & install the userspace utilities.55 $ ./configure [--with-tcp-wrappers=no] [--with-usbids-dir=<dir>]56 $ make install57 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.ko69 server:# insmod usbip-host.ko70 71 server:# usbipd -D72 - Start usbip daemon.73 74 server:# usbip list -l75 - List driver assignments for USB devices.76 77 server:# usbip bind --busid 1-278 - 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 Subsystem83on 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 gadget87 is ConfigFS Composite Gadget. Please refer to its documentation88 for details.89 - See vudc_server_example.sh for a short example of USB gadget creation90 91 server:# insmod usbip-core.ko92 server:# insmod usbip-vudc.ko93 - To create more than one instance of vudc use num module param94 95 server:# (Bind gadget to one of available vudc)96 - Assign your new gadget to USB/IP UDC97 - 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" > UDC100 101 server:# usbipd -D --device102 - Start usbip daemon.103 104To attach new device to client machine below commands should be used:105 106 client:# insmod usbip-core.ko107 client:# insmod vhci-hcd.ko108 109 client:# usbip list --remote <host>110 - List exported USB devices on the <host>.111 112 client:# usbip attach --remote <host> --busid 1-2113 - Connect the remote USB device.114 - When using vudc on a server side busid is really vudc instance name.115 For example: usbip-vudc.0116 117 client:# usbip port118 - Show virtual port status.119 120 client:# usbip detach --port <port>121 - Detach the USB device.122 123 124[Example]125---------------------------126 SERVER SIDE127---------------------------128Physically attach your USB devices to this host.129 130 trois:# insmod path/to/usbip-core.ko131 trois:# insmod path/to/usbip-host.ko132 trois:# usbipd -D133 134In another terminal, let's look up what USB devices are physically135attached to this host.136 137 trois:# usbip list -l138 Local USB devices139 =================140 - busid 1-1 (05a9:a511)141 1-1:1.0142 143 - busid 3-2 (0711:0902)144 3-2:1.0145 146 - busid 3-3.1 (08bb:2702)147 3-3.1:1.0148 3-3.1:1.1149 150 - busid 3-3.2 (04bb:0206)151 3-3.2:1.0152 153 - busid 3-3 (0409:0058)154 3-3:1.0155 156 - busid 4-1 (046d:08b2)157 4-1:1.0158 4-1:1.1159 4-1:1.2160 161 - busid 5-2 (058f:9254)162 5-2:1.0163 164A USB storage device of busid 3-3.2 is now bound to the usb-storage165driver. To export this device, we first mark the device as166"exportable"; the device is bound to the usbip-host driver. Please167remember 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.2172 ...173 usbip debug: usbip_bind.c:162:[unbind_other] 3-3.2:1.0 -> usb-storage174 ...175 bind device on busid 3-3.2: complete176 177 trois:# usbip list -l178 Local USB devices179 =================180 ...181 182 - busid 3-3.2 (04bb:0206)183 3-3.2:1.0184 ...185 186---------------------------187 CLIENT SIDE188---------------------------189First, let's list available remote devices that are marked as190exportable on the host.191 192 deux:# insmod path/to/usbip-core.ko193 deux:# insmod path/to/vhci-hcd.ko194 195 deux:# usbip list --remote 10.0.0.3196 Exportable USB devices197 ======================198 - 10.0.0.3199 1-1: Prolific Technology, Inc. : unknown product (067b:3507)200 : /sys/devices/pci0000:00/0000:00:1f.2/usb1/1-1201 : (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.1206 : (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.3211 : (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-1216 : (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-1224 port 0 attached225 226Show the devices attached to this client:227 228 deux:# usbip port229 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-storage233 /sys/class/scsi_device/0:0:0:0/device234 /sys/class/scsi_host/host0/device235 /sys/block/sda/device236 237Detach the imported device:238 239 deux:# usbip detach --port 0240 port 0 detached241 242 243[Checklist]244 - See 'Debug Tips' on the project wiki.245 - http://usbip.wiki.sourceforge.net/how-to-debug-usbip246 - 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 vudc249 (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.org258