tools/usb/usbip/README

   1 #
   2 # README for usbip-utils
   3 #
   4 # Copyright (C) 2011 matt mooney <mfm@muteddisk.com>
   5 #               2005-2008 Takahiro Hirofuchi
   6
   7
   8 [Requirements]
   9     - USB/IP device drivers
  10         Found in the staging directory of the Linux kernel.
  11
  12     - libudev >= 2.0
  13         libudev library
  14
  15     - libwrap0-dev
  16         tcp wrapper library
  17
  18     - gcc >= 4.0
  19
  20     - libtool, automake >= 1.9, autoconf >= 2.5.0, pkg-config
  21
  22 [Optional]
  23     - hwdata
  24         Contains USB device identification data.
  25
  26
  27 [Install]
  28     0. Generate configuration scripts.
  29         $ ./autogen.sh
  30
  31     1. Compile & install the userspace utilities.
  32         $ ./configure [--with-tcp-wrappers=no] [--with-usbids-dir=<dir>]
  33         $ make install
  34
  35     2. Compile & install USB/IP drivers.
  36
  37
  38 [Usage]
  39     server:# (Physically attach your USB device.)
  40
  41     server:# insmod usbip-core.ko
  42     server:# insmod usbip-host.ko
  43
  44     server:# usbipd -D
  45         - Start usbip daemon.
  46
  47     server:# usbip list -l
  48         - List driver assignments for USB devices.
  49
  50     server:# usbip bind --busid 1-2
  51         - Bind usbip-host.ko to the device with busid 1-2.
  52         - The USB device 1-2 is now exportable to other hosts!
  53         - Use `usbip unbind --busid 1-2' to stop exporting the device.
  54
  55     client:# insmod usbip-core.ko
  56     client:# insmod vhci-hcd.ko
  57
  58     client:# usbip list --remote <host>
  59         - List exported USB devices on the <host>.
  60
  61     client:# usbip attach --remote <host> --busid 1-2
  62         - Connect the remote USB device.
  63
  64     client:# usbip port
  65         - Show virtual port status.
  66
  67     client:# usbip detach --port <port>
  68         - Detach the USB device.
  69
  70
  71 [Example]
  72 ---------------------------
  73         SERVER SIDE
  74 ---------------------------
  75 Physically attach your USB devices to this host.
  76
  77     trois:# insmod path/to/usbip-core.ko
  78     trois:# insmod path/to/usbip-host.ko
  79     trois:# usbipd -D
  80
  81 In another terminal, let's look up what USB devices are physically
  82 attached to this host.
  83
  84     trois:# usbip list -l
  85     Local USB devices
  86     =================
  87      - busid 1-1 (05a9:a511)
  88              1-1:1.0 -> ov511
  89
  90      - busid 3-2 (0711:0902)
  91              3-2:1.0 -> none
  92
  93      - busid 3-3.1 (08bb:2702)
  94              3-3.1:1.0 -> snd-usb-audio
  95              3-3.1:1.1 -> snd-usb-audio
  96
  97      - busid 3-3.2 (04bb:0206)
  98              3-3.2:1.0 -> usb-storage
  99
 100      - busid 3-3 (0409:0058)
 101              3-3:1.0 -> hub
 102
 103      - busid 4-1 (046d:08b2)
 104              4-1:1.0 -> none
 105              4-1:1.1 -> none
 106              4-1:1.2 -> none
 107
 108      - busid 5-2 (058f:9254)
 109              5-2:1.0 -> hub
 110
 111 A USB storage device of busid 3-3.2 is now bound to the usb-storage
 112 driver. To export this device, we first mark the device as
 113 "exportable"; the device is bound to the usbip-host driver. Please
 114 remember you can not export a USB hub.
 115
 116 Mark the device of busid 3-3.2 as exportable:
 117
 118     trois:# usbip --debug bind --busid 3-3.2
 119     ...
 120     usbip debug: usbip_bind.c:162:[unbind_other] 3-3.2:1.0 -> usb-storage
 121     ...
 122     bind device on busid 3-3.2: complete
 123
 124     trois:# usbip list -l
 125     Local USB devices
 126     =================
 127     ...
 128
 129      - busid 3-3.2 (04bb:0206)
 130              3-3.2:1.0 -> usbip-host
 131     ...
 132
 133 ---------------------------
 134         CLIENT SIDE
 135 ---------------------------
 136 First, let's list available remote devices that are marked as
 137 exportable on the host.
 138
 139     deux:# insmod path/to/usbip-core.ko
 140     deux:# insmod path/to/vhci-hcd.ko
 141
 142     deux:# usbip list --remote 10.0.0.3
 143     Exportable USB devices
 144     ======================
 145      - 10.0.0.3
 146             1-1: Prolific Technology, Inc. : unknown product (067b:3507)
 147                : /sys/devices/pci0000:00/0000:00:1f.2/usb1/1-1
 148                : (Defined at Interface level) / unknown subclass / unknown protocol (00/00/00)
 149                :  0 - Mass Storage / SCSI / Bulk (Zip) (08/06/50)
 150
 151         1-2.2.1: Apple Computer, Inc. : unknown product (05ac:0203)
 152                : /sys/devices/pci0000:00/0000:00:1f.2/usb1/1-2/1-2.2/1-2.2.1
 153                : (Defined at Interface level) / unknown subclass / unknown protocol (00/00/00)
 154                :  0 - Human Interface Devices / Boot Interface Subclass / Keyboard (03/01/01)
 155
 156         1-2.2.3: OmniVision Technologies, Inc. : OV511+ WebCam (05a9:a511)
 157                : /sys/devices/pci0000:00/0000:00:1f.2/usb1/1-2/1-2.2/1-2.2.3
 158                : (Defined at Interface level) / unknown subclass / unknown protocol (00/00/00)
 159                :  0 - Vendor Specific Class / unknown subclass / unknown protocol (ff/00/00)
 160
 161             3-1: Logitech, Inc. : QuickCam Pro 4000 (046d:08b2)
 162                : /sys/devices/pci0000:00/0000:00:1e.0/0000:02:0a.0/usb3/3-1
 163                : (Defined at Interface level) / unknown subclass / unknown protocol (00/00/00)
 164                :  0 - Data / unknown subclass / unknown protocol (0a/ff/00)
 165                :  1 - Audio / Control Device / unknown protocol (01/01/00)
 166                :  2 - Audio / Streaming / unknown protocol (01/02/00)
 167
 168 Attach a remote USB device:
 169
 170     deux:# usbip attach --remote 10.0.0.3 --busid 1-1
 171     port 0 attached
 172
 173 Show the devices attached to this client:
 174
 175     deux:# usbip port
 176     Port 00: <Port in Use> at Full Speed(12Mbps)
 177            Prolific Technology, Inc. : unknown product (067b:3507)
 178            6-1 -> usbip://10.0.0.3:3240/1-1  (remote bus/dev 001/004)
 179            6-1:1.0 used by usb-storage
 180                           /sys/class/scsi_device/0:0:0:0/device
 181                           /sys/class/scsi_host/host0/device
 182                           /sys/block/sda/device
 183
 184 Detach the imported device:
 185
 186     deux:# usbip detach --port 0
 187     port 0 detached
 188
 189
 190 [Checklist]
 191     - See 'Debug Tips' on the project wiki.
 192         - http://usbip.wiki.sourceforge.net/how-to-debug-usbip
 193     - usbip-host.ko must be bound to the target device.
 194         - See /proc/bus/usb/devices and find "Driver=..." lines of the device.
 195     - Shutdown firewall.
 196         - usbip now uses TCP port 3240.
 197     - Disable SELinux.
 198     - Check the kernel and daemon messages.
 199
 200
 201 [Contact]
 202     Mailing List: linux-usb@vger.kernel.org