linux-kernel - [PATCH] tools: usb: usbip: Update README

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-id: <20161213195218.10847-1-k.opasiak@samsung.com>
Date:   Tue, 13 Dec 2016 20:52:18 +0100
From:   Krzysztof Opasiak <k.opasiak@...sung.com>
To:     shuahkh@....samsung.com, shuah@...nel.org
Cc:     valentina.manea.m@...il.com, gregkh@...uxfoundation.org,
        linux-kernel@...r.kernel.org, linux-usb@...r.kernel.org,
        Krzysztof Opasiak <k.opasiak@...sung.com>
Subject: [PATCH] tools: usb: usbip: Update README

Update README file:
- remove outdated parts
- clarify terminology and general structure
- add some description of vUDC

Signed-off-by: Krzysztof Opasiak <k.opasiak@...sung.com>
---
 tools/usb/usbip/README | 56 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 55 insertions(+), 1 deletion(-)

diff --git a/tools/usb/usbip/README b/tools/usb/usbip/README
index 831f49fea3ce..148d13814306 100644
--- a/tools/usb/usbip/README
+++ b/tools/usb/usbip/README
@@ -4,10 +4,32 @@
 # Copyright (C) 2011 matt mooney <mfm@...eddisk.com>
 #               2005-2008 Takahiro Hirofuchi
 
+[Overview]
+USB/IP protocol allows to pass USB device from server to client over the
+network. The USB device may be either physical device connected to a server or
+software entity created on a server using USB gadget subsystem.
+Whole project consists of four parts:
+
+    - usbip-vhci
+        Kernel module which provides a virtual USB Host Controller and allows
+        to import a USB device from a remote machine. Used on a client side.
+
+    - usbip-host (stub driver)
+        Kernel module which provides a USB device driver which can be bound to
+        a physical USB device to make it exportable. Used on a server side.
+
+    - usbip-vudc
+        Kernel module which provides a virtual USB Device Controller and allows
+        to export a USB device created using USB Gadget Subsystem. Used on
+        a server side.
+
+    - usbip-utils
+        A set of userspace tools used to handle connection and management.
+        Used on both sides.
 
 [Requirements]
     - USB/IP device drivers
-	Found in the staging directory of the Linux kernel.
+        Found in the drivers/usb/usbip/ directory of the Linux kernel tree.
 
     - libudev >= 2.0
 	libudev library
@@ -36,6 +58,10 @@
 
 
 [Usage]
+On a server side there are two entities which can be shared.
+First of them is physical usb device connected to the machine.
+To make it available below steps should be executed:
+
     server:# (Physically attach your USB device.)
 
     server:# insmod usbip-core.ko
@@ -52,6 +78,30 @@
 	- The USB device 1-2 is now exportable to other hosts!
 	- Use `usbip unbind --busid 1-2' to stop exporting the device.
 
+Second of shareable entities is USB Gadget created using USB Gadget Subsystem
+on a server machine. To make it available below steps should be executed:
+
+    server:# (Create your USB gadget)
+        - Currently the most preferable way of creating a new USB gadget
+          is ConfigFS Composite Gadget. Please refer to its documentation
+          for details.
+        - See vudc_server_example.sh for a short example of USB gadget creation
+
+    server:# insmod usbip-core.ko
+    server:# insmod usbip-vudc.ko
+        - To create more than one instance of vudc use num module param
+
+    server:# (Bind gadget to one of available vudc)
+        - Assign your new gadget to USB/IP UDC
+        - Using ConfigFS interface you may do this simply by:
+            server:# cd /sys/kernel/config/usb_gadget/<gadget_name>
+            server:# echo "usbip-vudc.0" > UDC
+
+    server:# usbipd -D --device
+        - Start usbip daemon.
+
+To attach new device to client machine below commands should be used:
+
     client:# insmod usbip-core.ko
     client:# insmod vhci-hcd.ko
 
@@ -60,6 +110,8 @@
 
     client:# usbip attach --remote <host> --busid 1-2
 	- Connect the remote USB device.
+	- When using vudc on a server side busid is really vudc instance name.
+	  For example: usbip-vudc.0
 
     client:# usbip port
 	- Show virtual port status.
@@ -192,6 +244,8 @@ Detach the imported device:
 	- http://usbip.wiki.sourceforge.net/how-to-debug-usbip
     - usbip-host.ko must be bound to the target device.
 	- See /proc/bus/usb/devices and find "Driver=..." lines of the device.
+    - Target USB gadget must be bound to vudc
+      (using USB gadget susbsys, not usbip bind command)
     - Shutdown firewall.
 	- usbip now uses TCP port 3240.
     - Disable SELinux.
-- 
2.9.3