0001 #
0002 # README for usbip-utils
0003 #
0004 # Copyright (C) 2011 matt mooney <mfm@muteddisk.com>
0005 # 2005-2008 Takahiro Hirofuchi
0006
0007 [Overview]
0008 USB/IP protocol allows to pass USB device from server to client over the
0009 network. Server is a machine which provides (shares) a USB device. Client is
0010 a machine which uses USB device provided by server over the network.
0011 The USB device may be either physical device connected to a server or
0012 software entity created on a server using USB gadget subsystem.
0013 Whole project consists of four parts:
0014
0015 - usbip-vhci
0016 A client side kernel module which provides a virtual USB Host Controller
0017 and allows to import a USB device from a remote machine.
0018
0019 - usbip-host (stub driver)
0020 A server side module which provides a USB device driver which can be
0021 bound to a physical USB device to make it exportable.
0022
0023 - usbip-vudc
0024 A server side module which provides a virtual USB Device Controller and allows
0025 to export a USB device created using USB Gadget Subsystem.
0026
0027 - usbip-utils
0028 A set of userspace tools used to handle connection and management.
0029 Used on both sides.
0030
0031 [Requirements]
0032 - USB/IP device drivers
0033 Found in the drivers/usb/usbip/ directory of the Linux kernel tree.
0034
0035 - libudev >= 2.0
0036 libudev library
0037
0038 - libwrap0-dev
0039 tcp wrapper library
0040
0041 - gcc >= 4.0
0042
0043 - libtool, automake >= 1.9, autoconf >= 2.5.0, pkg-config
0044
0045 [Optional]
0046 - hwdata
0047 Contains USB device identification data.
0048
0049
0050 [Install]
0051 0. Generate configuration scripts.
0052 $ ./autogen.sh
0053
0054 1. Compile & install the userspace utilities.
0055 $ ./configure [--with-tcp-wrappers=no] [--with-usbids-dir=<dir>]
0056 $ make install
0057
0058 2. Compile & install USB/IP drivers.
0059
0060
0061 [Usage]
0062 On a server side there are two entities which can be shared.
0063 First of them is physical usb device connected to the machine.
0064 To make it available below steps should be executed:
0065
0066 server:# (Physically attach your USB device.)
0067
0068 server:# insmod usbip-core.ko
0069 server:# insmod usbip-host.ko
0070
0071 server:# usbipd -D
0072 - Start usbip daemon.
0073
0074 server:# usbip list -l
0075 - List driver assignments for USB devices.
0076
0077 server:# usbip bind --busid 1-2
0078 - Bind usbip-host.ko to the device with busid 1-2.
0079 - The USB device 1-2 is now exportable to other hosts!
0080 - Use `usbip unbind --busid 1-2' to stop exporting the device.
0081
0082 Second of shareable entities is USB Gadget created using USB Gadget Subsystem
0083 on a server machine. To make it available below steps should be executed:
0084
0085 server:# (Create your USB gadget)
0086 - Currently the most preferable way of creating a new USB gadget
0087 is ConfigFS Composite Gadget. Please refer to its documentation
0088 for details.
0089 - See vudc_server_example.sh for a short example of USB gadget creation
0090
0091 server:# insmod usbip-core.ko
0092 server:# insmod usbip-vudc.ko
0093 - To create more than one instance of vudc use num module param
0094
0095 server:# (Bind gadget to one of available vudc)
0096 - Assign your new gadget to USB/IP UDC
0097 - Using ConfigFS interface you may do this simply by:
0098 server:# cd /sys/kernel/config/usb_gadget/<gadget_name>
0099 server:# echo "usbip-vudc.0" > UDC
0100
0101 server:# usbipd -D --device
0102 - Start usbip daemon.
0103
0104 To attach new device to client machine below commands should be used:
0105
0106 client:# insmod usbip-core.ko
0107 client:# insmod vhci-hcd.ko
0108
0109 client:# usbip list --remote <host>
0110 - List exported USB devices on the <host>.
0111
0112 client:# usbip attach --remote <host> --busid 1-2
0113 - Connect the remote USB device.
0114 - When using vudc on a server side busid is really vudc instance name.
0115 For example: usbip-vudc.0
0116
0117 client:# usbip port
0118 - Show virtual port status.
0119
0120 client:# usbip detach --port <port>
0121 - Detach the USB device.
0122
0123
0124 [Example]
0125 ---------------------------
0126 SERVER SIDE
0127 ---------------------------
0128 Physically attach your USB devices to this host.
0129
0130 trois:# insmod path/to/usbip-core.ko
0131 trois:# insmod path/to/usbip-host.ko
0132 trois:# usbipd -D
0133
0134 In another terminal, let's look up what USB devices are physically
0135 attached to this host.
0136
0137 trois:# usbip list -l
0138 Local USB devices
0139 =================
0140 - busid 1-1 (05a9:a511)
0141 1-1:1.0
0142
0143 - busid 3-2 (0711:0902)
0144 3-2:1.0
0145
0146 - busid 3-3.1 (08bb:2702)
0147 3-3.1:1.0
0148 3-3.1:1.1
0149
0150 - busid 3-3.2 (04bb:0206)
0151 3-3.2:1.0
0152
0153 - busid 3-3 (0409:0058)
0154 3-3:1.0
0155
0156 - busid 4-1 (046d:08b2)
0157 4-1:1.0
0158 4-1:1.1
0159 4-1:1.2
0160
0161 - busid 5-2 (058f:9254)
0162 5-2:1.0
0163
0164 A USB storage device of busid 3-3.2 is now bound to the usb-storage
0165 driver. To export this device, we first mark the device as
0166 "exportable"; the device is bound to the usbip-host driver. Please
0167 remember you can not export a USB hub.
0168
0169 Mark the device of busid 3-3.2 as exportable:
0170
0171 trois:# usbip --debug bind --busid 3-3.2
0172 ...
0173 usbip debug: usbip_bind.c:162:[unbind_other] 3-3.2:1.0 -> usb-storage
0174 ...
0175 bind device on busid 3-3.2: complete
0176
0177 trois:# usbip list -l
0178 Local USB devices
0179 =================
0180 ...
0181
0182 - busid 3-3.2 (04bb:0206)
0183 3-3.2:1.0
0184 ...
0185
0186 ---------------------------
0187 CLIENT SIDE
0188 ---------------------------
0189 First, let's list available remote devices that are marked as
0190 exportable on the host.
0191
0192 deux:# insmod path/to/usbip-core.ko
0193 deux:# insmod path/to/vhci-hcd.ko
0194
0195 deux:# usbip list --remote 10.0.0.3
0196 Exportable USB devices
0197 ======================
0198 - 10.0.0.3
0199 1-1: Prolific Technology, Inc. : unknown product (067b:3507)
0200 : /sys/devices/pci0000:00/0000:00:1f.2/usb1/1-1
0201 : (Defined at Interface level) / unknown subclass / unknown protocol (00/00/00)
0202 : 0 - Mass Storage / SCSI / Bulk (Zip) (08/06/50)
0203
0204 1-2.2.1: Apple Computer, Inc. : unknown product (05ac:0203)
0205 : /sys/devices/pci0000:00/0000:00:1f.2/usb1/1-2/1-2.2/1-2.2.1
0206 : (Defined at Interface level) / unknown subclass / unknown protocol (00/00/00)
0207 : 0 - Human Interface Devices / Boot Interface Subclass / Keyboard (03/01/01)
0208
0209 1-2.2.3: OmniVision Technologies, Inc. : OV511+ WebCam (05a9:a511)
0210 : /sys/devices/pci0000:00/0000:00:1f.2/usb1/1-2/1-2.2/1-2.2.3
0211 : (Defined at Interface level) / unknown subclass / unknown protocol (00/00/00)
0212 : 0 - Vendor Specific Class / unknown subclass / unknown protocol (ff/00/00)
0213
0214 3-1: Logitech, Inc. : QuickCam Pro 4000 (046d:08b2)
0215 : /sys/devices/pci0000:00/0000:00:1e.0/0000:02:0a.0/usb3/3-1
0216 : (Defined at Interface level) / unknown subclass / unknown protocol (00/00/00)
0217 : 0 - Data / unknown subclass / unknown protocol (0a/ff/00)
0218 : 1 - Audio / Control Device / unknown protocol (01/01/00)
0219 : 2 - Audio / Streaming / unknown protocol (01/02/00)
0220
0221 Attach a remote USB device:
0222
0223 deux:# usbip attach --remote 10.0.0.3 --busid 1-1
0224 port 0 attached
0225
0226 Show the devices attached to this client:
0227
0228 deux:# usbip port
0229 Port 00: <Port in Use> at Full Speed(12Mbps)
0230 Prolific Technology, Inc. : unknown product (067b:3507)
0231 6-1 -> usbip://10.0.0.3:3240/1-1 (remote bus/dev 001/004)
0232 6-1:1.0 used by usb-storage
0233 /sys/class/scsi_device/0:0:0:0/device
0234 /sys/class/scsi_host/host0/device
0235 /sys/block/sda/device
0236
0237 Detach the imported device:
0238
0239 deux:# usbip detach --port 0
0240 port 0 detached
0241
0242
0243 [Checklist]
0244 - See 'Debug Tips' on the project wiki.
0245 - http://usbip.wiki.sourceforge.net/how-to-debug-usbip
0246 - usbip-host.ko must be bound to the target device.
0247 - See /sys/kernel/debug/usb/devices and find "Driver=..." lines of the device.
0248 - Target USB gadget must be bound to vudc
0249 (using USB gadget susbsys, not usbip bind command)
0250 - Shutdown firewall.
0251 - usbip now uses TCP port 3240.
0252 - Disable SELinux.
0253 - Check the kernel and daemon messages.
0254
0255
0256 [Contact]
0257 Mailing List: linux-usb@vger.kernel.org
