Hello, > > This patch adds function and usage of new connect operation, > disconnect > > operation and application(vhci)-side daemon to README and manuals. > > This should be the first patch for the series. That would have saved > me lot of time. Please move this patch up. OK. I will move the documentation patch to 1/10. > > At this point, the wording, 'server' and 'client' are ambiguous in > > several place. > > > > For existing attach command, the daemon runs device side machine and > > attach command is executed in application side machine. Then 'server' > > is used for device side and 'client' is for application side. > > > > For the new connect command, the daemon runs applications side > machine > > and connect command is executed in device side machine. Now, 'server' > > and 'client' run in different machine than before. > > > > To avoid confusion, to represent things to be done in device side node > > by both command and daemon, words 'device-side' is used instead of > > 'server'. To represent things to be done is application side node by > > both command and daemon, 'applicationr-side' are used instead of > > 'client'. > > > > EXISTING) - invites devices from application(vhci)-side > > +------+ > +------------------+ > > device--+ STUB | | application/VHCI | > > +------+ > +------------------+ > > (server) (client) > > 1) # usbipd ... start daemon > > = = = > > 2) # usbip list --local > > 3) # usbip bind > > <--- list bound devices --- 4) # usbip list --remote > > <--- import a device ------ 5) # usbip attach > > = = = > > X disconnected 6) # usbip detach > > 7) usbip unbind > > > > NEW) - dedicates devices from device(stub)-side > > +------+ > +------------------+ > > device--+ STUB | | application/VHCI | > > +------+ > +------------------+ > > (client) (server) > > 1) # usbipa ... start > daemon > > Make the left side server and right side client. I think you might be > using server and client network terminology. I would like to see server > as the system that has the device physically attached to. > I still want to see server as the one that is connected to the device. > It is just that in this new proposed model, server is exporting devices. --- same comment as 03/10 --- I know that existing USB/IP users are familiar with word 'server'. It was consistent to client-server model. In new operation, to call server the device side node will cause confusion because it is a client as client-server model. So I think it's better to use 'device-side' and 'application-side' to specify nodes. These word can intuitively denote the nodes. In this version, I marked (server) and (client) but I will remove them because it causes existing user's confusion. > Also does usbip run here in user mode. Can any user run uspip and initiate > export? If so, I don't think I can take this patch series. I don't like to > see non root being able to export and/or make attached devices public. New commands and daemon needs root privilege same as 'bind', 'unbind' and 'attach'. They use same sysfs interface to 'bind', 'unbind' and 'attach'. Docs are section 8 as administrator and daemon. In README, '#' prompts are used to represent super user. > > = = = > > 2) # usbip list --local > > 3) # usbip connect --- export a device ------> > > = = = > > 4) # usbip disconnect --- un-export a device ---> > > > > Bind and unbind are done in connect and disconnect internally. > > > > Signed-off-by: Nobuo Iwata <nobuo.iwata@xxxxxxxxxxxxxxx> > > --- > > tools/usb/usbip/Makefile.am | 2 +- > > tools/usb/usbip/README | 81 > ++++++++++++++++----- > > tools/usb/usbip/doc/usbip.8 | 136 > ++++++++++++++++++++++++++++------- > > tools/usb/usbip/doc/usbipa.8 | 78 ++++++++++++++++++++ > > tools/usb/usbip/doc/usbipd.8 | 38 +++++----- > > 5 files changed, 275 insertions(+), 60 deletions(-) > > > > diff --git a/tools/usb/usbip/Makefile.am > b/tools/usb/usbip/Makefile.am > > index 66f8bf0..f371ed9 100644 > > --- a/tools/usb/usbip/Makefile.am > > +++ b/tools/usb/usbip/Makefile.am > > @@ -3,4 +3,4 @@ includedir = @includedir@/usbip > > include_HEADERS := $(addprefix libsrc/, \ > > usbip_common.h vhci_driver.h usbip_host_driver.h) > > > > -dist_man_MANS := $(addprefix doc/, usbip.8 usbipd.8) > > +dist_man_MANS := $(addprefix doc/, usbip.8 usbipd.8 usbipa.8) > > diff --git a/tools/usb/usbip/README b/tools/usb/usbip/README > > index 831f49f..d3cae75 100644 > > --- a/tools/usb/usbip/README > > +++ b/tools/usb/usbip/README > > @@ -3,6 +3,7 @@ > > # > > # Copyright (C) 2011 matt mooney <mfm@xxxxxxxxxxxxx> > > # 2005-2008 Takahiro Hirofuchi > > +# Copyright (C) 2015-2016 Nobuo Iwata > <nobuo.iwata@xxxxxxxxxxxxxxx> > > > > > > [Requirements] > > @@ -36,41 +37,70 @@ > > > > > > [Usage] > > - server:# (Physically attach your USB device.) > > +Device-side: a machine has USB device(s). > > +Application-side: a machine runs an application software uses remote > USB device. > > > > - server:# insmod usbip-core.ko > > - server:# insmod usbip-host.ko > > +1) Connect from application-side to device-side. > > > > - server:# usbipd -D > > + dev:# (Physically attach your USB device.) > > + > > + dev:# insmod usbip-core.ko > > + dev:# insmod usbip-host.ko > > + > > + dev:# usbipd -D > > - Start usbip daemon. > > > > - server:# usbip list -l > > - - List driver assignments for USB devices. > > + dev:# usbip list -l > > + - List driver assignments for USB devices and their busid. > > > > - server:# usbip bind --busid 1-2 > > - - Bind usbip-host.ko to the device with busid 1-2. > > - - The USB device 1-2 is now exportable to other hosts! > > - - Use `usbip unbind --busid 1-2' to stop exporting the device. > > + dev:# usbip bind --busid <busid> > > + - Bind usbip-host.ko to the device with <busid>. > > + - The USB device with <busid> is now exportable to other hosts! > > + - Use `usbip unbind --busid <busid>` to stop exporting the > device. > > > > - client:# insmod usbip-core.ko > > - client:# insmod vhci-hcd.ko > > + app:# insmod usbip-core.ko > > + app:# insmod vhci-hcd.ko > > > > - client:# usbip list --remote <host> > > + app:# usbip list --remote <host> > > - List exported USB devices on the <host>. > > > > - client:# usbip attach --remote <host> --busid 1-2 > > + app:# usbip attach --remote <host> --busid <busid> > > - Connect the remote USB device. > > > > - client:# usbip port > > + app:# usbip port > > - Show virtual port status. > > > > - client:# usbip detach --port <port> > > + app:# usbip detach --port <port> > > - Detach the USB device. > > > > +2) Connect from device-side to application-side. > > + > > + app:# insmod usbip-core.ko > > + app:# insmod vhci-hcd.ko > > + > > + app:# usbipa -D > > + - Start usbip daemon. > > + > > + dev:# (Physically attach your USB device.) > > + > > + dev:# insmod usbip-core.ko > > + dev:# insmod usbip-host.ko > > + > > + dev:# usbip list -l > > + - List driver assignments for USB devices and their busid. > > + > > + dev:# usbip connect --remote <host> --busid <busid> > > + - Bind usbip-host.ko to the device with <busid>. > > + - The USB device of <busid> is connected to remote host! > > + > > + dev:# usbip disconnect --remote <host> --busid <busid> > > + - The USB device with <busid> is disconnected from remote host. > > + - Unbind usbip-host.ko from the device. > > + > > > > [Example] > > --------------------------- > > - SERVER SIDE > > + DEVICE SIDE > > --------------------------- > > Physically attach your USB devices to this host. > > > > @@ -131,7 +161,7 @@ Mark the device of busid 3-3.2 as exportable: > > ... > > > > --------------------------- > > - CLIENT SIDE > > + APPLICATION SIDE > > --------------------------- > > First, let's list available remote devices that are marked as > > exportable on the host. > > @@ -170,7 +200,7 @@ Attach a remote USB device: > > deux:# usbip attach --remote 10.0.0.3 --busid 1-1 > > port 0 attached > > > > -Show the devices attached to this client: > > +Show the devices attached to this machine: > > > > deux:# usbip port > > Port 00: <Port in Use> at Full Speed(12Mbps) > > @@ -187,6 +217,19 @@ Detach the imported device: > > port 0 detached > > > > > > +[Security consideration] > > + > > +Daemons accept following requests form network : > > + EXISTING) 'list --remote' and 'attach' > > + NEW) 'connect' and 'disconnect' > > + > > +TCP wrappers allows and/or denies network access. It is enabled > when the daemons are compiled with ./configure --with-tcp-wrappers. > > + > > +When the daemons are running with SSL or Secure WebSocket > tunneling proxy, the proxy can use client authentication with certificate > files. > > + > > +Udev rules can allow only known devices. To identify whether a device > is remote, the local bus-id (KERNEL parameter in the rule) will be found in > the last column of /sys/devices/platform/vhci_hcd/status[.N]. When > device is found, the port number of USB/IP can be found in the first > column of the matched line. The udev script can finish the connection > using detach operation with the port number. > > + > > + > > [Checklist] > > - See 'Debug Tips' on the project wiki. > > - http://usbip.wiki.sourceforge.net/how-to-debug-usbip > > diff --git a/tools/usb/usbip/doc/usbip.8 > b/tools/usb/usbip/doc/usbip.8 > > index a6097be..523bb53 100644 > > --- a/tools/usb/usbip/doc/usbip.8 > > +++ b/tools/usb/usbip/doc/usbip.8 > > @@ -6,27 +6,30 @@ usbip \- manage USB/IP devices > > [\fIoptions\fR] <\fIcommand\fR> <\fIargs\fR> > > > > .SH DESCRIPTION > > -On a USB/IP server, devices can be listed, bound, and unbound using > > -this program. On a USB/IP client, devices exported by USB/IP servers > > -can be listed, attached and detached. > > +On a USB/IP device side computer, > > +lists local devices, makes a device importable, makes not importable, > > +connects a device and disconnects a device. > > + > > +On a USB/IP application side computer, > > +lists devices importable from a remote computer, attaches a remote > device and detaches an attached device. > > > > .SH OPTIONS > > .HP > > -\fB\-\-debug\fR > > +\fB\-d\fR, \fB\-\-debug\fR > > .IP > > Print debugging information. > > .PP > > > > .HP > > -\fB\-\-log\fR > > +\fB\-l\fR, \fB\-\-log\fR > > .IP > > Log to syslog. > > .PP > > > > .HP > > -\fB\-\-tcp-port PORT\fR > > +\fB\-tPORT\fR, \fB\-\-tcp-port PORT\fR > > .IP > > -Connect to PORT on remote host (used for attach and list --remote). > > +TCP port number used by remote usbip daemon. Default is 3240. > > .PP > > > > .SH COMMANDS > > @@ -44,52 +47,137 @@ then exit. > > .PP > > > > .HP > > -\fBattach\fR \-\-remote=<\fIhost\fR> \-\-busid=<\fIbus_id\fR> > > +\fBattach\fR \-\-remote <\fIhost\fR> \-\-busid <\fIbusid\fR> > > .IP > > -Attach a remote USB device. > > +Attach a importable USB device from remote computer. > > .PP > > > > .HP > > -\fBdetach\fR \-\-port=<\fIport\fR> > > +\fBdetach\fR \-\-port <\fIport\fR> > > .IP > > Detach an imported USB device. > > .PP > > > > .HP > > -\fBbind\fR \-\-busid=<\fIbusid\fR> > > +\fBconnect\fR \-\-remote <\fIhost\fR> \-\-busid <\fIbusid\fR> > [\-\-device] > > +.IP > > +Connect a USB device to remote computer. > > +.PP > > + > > +.HP > > +\fBdisconnect\fR \-\-remote <\fIhost\fR> \-\-busid > <\fIbusid\fR> [\-\-device] > > .IP > > -Make a device exportable. > > +Disconnect a USB device from remote computer. It allows to disconnet > from a computer which issued connect operation. > > .PP > > > > .HP > > -\fBunbind\fR \-\-busid=<\fIbusid\fR> > > +\fBbind\fR \-\-busid <\fIbusid\fR> > > .IP > > -Stop exporting a device so it can be used by a local driver. > > +Make a USB device importable from remote computer. > > .PP > > > > .HP > > -\fBlist\fR \-\-remote=<\fIhost\fR> > > +\fBunbind\fR \-\-busid <\fIbusid\fR> > > .IP > > -List USB devices exported by a remote host. > > +Make a USB device not importable so it can be used by a local driver. > > .PP > > > > .HP > > -\fBlist\fR \-\-local > > +\fBlist\fR \-\-remote <\fIhost\fR> > > +.IP > > +List importable USB devices from a remote computer. > > +.PP > > + > > +.HP > > +\fBlist\fR [\-\-parsable] \-\-local > > .IP > > List local USB devices. > > .PP > > > > +.HP > > +\fBlist\fR [\-\-parsable] \-\-device > > +.IP > > +List local USB devices with an alternate driver, e.g. vUDC. > > +.PP > > + > > +.HP > > +\fBport\fR > > +.HP > > +.IP > > +List imported USB devices. > > +.PP > > > > -.SH EXAMPLES > > > > - client:# usbip list --remote=server > > - - List exportable usb devices on the server. > > +.SH ARGUMENTS > > +.HP > > +\fB\-rHOST\fR, \fB\-\-remote HOST\fR > > +.IP > > +Remote host address. > > +.PP > > + > > +.HP > > +\fB\-bBUSID\fR, \fB\-\-busid BUSID\fR > > +.IP > > +Bus ID of a device to be handled. > > +.PP > > + > > +.HP > > +\fB\-pPORT\fR, \fB\-\-port PORT\fR > > +.IP > > +d. > > +Port number of an imported device shown by port command. > > +.PP > > + > > +.HP > > +\fB\-l\fR, \fB\-\-local\fR > > +.IP > > +Target local devices. > > +.PP > > + > > +.HP > > +\fB\-p\fR, \fB\-\-parsable\fR > > +.IP > > +Parsable format. > > +.PP > > + > > +.HP > > +\fB\-d\fR, \fB\-\-device\fR > > +.IP > > +Run with with an alternate driver, e.g. vUDC. > > +.PP > > + > > + > > +.SH EXAMPLES > > > > - client:# usbip attach --remote=server --busid=1-2 > > - - Connect the remote USB device. > > +dev: at a device side computer > > +.br > > +app: at an application side computer > > + > > +Attach a device from a remote computer > > + dev:# usbip list > > + - List local USB devices. > > + dev:# usbip bind --busid 1-2 > > + - Make a USB device importable from a remote computer. > > + app:# usbip list --remote 172.1.2.3 > > + - List importable USB devices on the computer. > > + app:# usbip attach --remote 172.1.2.3 --busid 1-2 > > + - Import a remote USB device. > > + app:# usbip port > > + - List imported USB devices. > > + app:# usbip detach --port 0 > > + - Detach the USB device. > > + dev:# usbip unbind --busid 1-2 > > + - Make a USB device not importable, then release to local. > > + > > +Connect a device to a remote computer > > + dev:# usbip list > > + - List local USB devices. > > + dev:# usbip connect --remote 172.4.5.6 --busid 1-2 > > + - Export a USB device to a remote computer. > > + dev:# usbip disconnect --remote 172.4.5.6 --busid 1-2 > > + - Unxport a USB device from a remote computer. > > > > - client:# usbip detach --port=0 > > - - Detach the usb device. > > > > .SH "SEE ALSO" > > \fBusbipd\fP\fB(8)\fB\fP > > +\fBusbipa\fP\fB(8)\fB\fP > > diff --git a/tools/usb/usbip/doc/usbipa.8 > b/tools/usb/usbip/doc/usbipa.8 > > new file mode 100644 > > index 0000000..0dd7a52 > > --- /dev/null > > +++ b/tools/usb/usbip/doc/usbipa.8 > > @@ -0,0 +1,78 @@ > > +.TH USBIP "8" "March 2015" "usbip" "System Administration Utilities" > > +.SH NAME > > +usbipa \- USB/IP application side daemon > > +.SH SYNOPSIS > > +.B usbipa > > +[\fIoptions\fR] > > + > > +.SH DESCRIPTION > > +.B usbipa > > +runs on an application side computer and make remote USB devices > connected using \fBusbip connect\fR at remote computers accessible on > the application side computer. > > + > > +.SH OPTIONS > > +.HP > > +\fB\-4\fR, \fB\-\-ipv4\fR > > +.IP > > +Bind to IPv4. Default is both. > > +.PP > > + > > +.HP > > +\fB\-6\fR, \fB\-\-ipv6\fR > > +.IP > > +Bind to IPv6. Default is both. > > +.PP > > + > > +.HP > > +\fB\-D\fR, \fB\-\-daemon\fR > > +.IP > > +Run as a daemon process. > > +.PP > > + > > +.HP > > +\fB\-d\fR, \fB\-\-debug\fR > > +.IP > > +Print debugging information. > > +.PP > > + > > +.HP > > +\fB\-PFILE\fR, \fB\-\-pid FILE\fR > > +.IP > > +Write process id to FILE. > > +.br > > +If no FILE specified, use /var/run/usbipd.pid > > +.PP > > + > > +.HP > > +\fB\-tPORT\fR, \fB\-\-tcp\-port PORT\fR > > +.IP > > +Listen on TCP/IP port PORT. Default is 3240. > > +.PP > > + > > +.HP > > +\fB\-h\fR, \fB\-\-help\fR > > +.IP > > +Print the program help message and exit. > > +.PP > > + > > +.HP > > +\fB\-v\fR, \fB\-\-version\fR > > +.IP > > +Show version. > > +.PP > > + > > +.SH LIMITATIONS > > + > > +.B usbipa > > +offers no authentication or authorization for USB/IP. Any > > +USB/IP client can connect and use exported devices. > > + > > +.SH EXAMPLES > > + > > + app:# modprobe vhci-hcd > > + > > + app:# usbipa -D > > + - Start usbip daemon. > > + > > +.SH "SEE ALSO" > > +\fBusbip\fP\fB(8)\fB\fP > > +\fBusbipd\fP\fB(8)\fB\fP > > diff --git a/tools/usb/usbip/doc/usbipd.8 > b/tools/usb/usbip/doc/usbipd.8 > > index ac4635d..0c27182 100644 > > --- a/tools/usb/usbip/doc/usbipd.8 > > +++ b/tools/usb/usbip/doc/usbipd.8 > > @@ -1,20 +1,15 @@ > > .TH USBIP "8" "February 2009" "usbip" "System Administration > Utilities" > > .SH NAME > > -usbipd \- USB/IP server daemon > > +usbipd \- USB/IP device side daemon > > .SH SYNOPSIS > > .B usbipd > > [\fIoptions\fR] > > > > .SH DESCRIPTION > > .B usbipd > > -provides USB/IP clients access to exported USB devices. > > +runs on a divice side computer and provides USB/IP access from > remote computers. > > > > -Devices have to explicitly be exported using > > -.B usbip bind > > -before usbipd makes them available to other hosts. > > - > > -The daemon accepts connections from USB/IP clients > > -on TCP port 3240 by default. > > +To make devices accessible from remote computers, they must be > made importable using \fBusbip bind\fR. > > > > .SH OPTIONS > > .HP > > @@ -49,11 +44,19 @@ Write process id to FILE. > > If no FILE specified, use /var/run/usbipd.pid > > .PP > > > > +.HP > > \fB\-tPORT\fR, \fB\-\-tcp\-port PORT\fR > > .IP > > -Listen on TCP/IP port PORT. > > +Listen on TCP/IP port PORT. Default is 3240. > > .PP > > > > +.HP > > +\fB\-e\fR, \fB\-\-device\fR > > +.IP > > +Run with with an alternate driver, e.g. vUDC. > > +.PP > > + > > +.HP > > \fB\-h\fR, \fB\-\-help\fR > > .IP > > Print the program help message and exit. > > @@ -73,19 +76,22 @@ USB/IP client can connect and use exported > devices. > > > > .SH EXAMPLES > > > > - server:# modprobe usbip > > + dev:# modprobe usbip-host > > > > - server:# usbipd -D > > + dev:# usbipd -D > > - Start usbip daemon. > > > > - server:# usbip list --local > > + dev:# usbip list --local > > - List driver assignments for usb devices. > > > > - server:# usbip bind --busid=1-2 > > + dev:# usbip bind --busid 1-2 > > - Bind usbip-host.ko to the device of busid 1-2. > > - - A usb device 1-2 is now exportable to other hosts! > > - - Use 'usbip unbind --busid=1-2' when you want to shutdown > exporting and use the device locally. > > + - USB device 1-2 is now importable from other computer! > > + > > + dev:# usbip unbind --busid 1-2 > > + - Unind usbip-host.ko from the device of busid 1-2. > > + - USB device 1-2 is not importable from other computer. > > > > .SH "SEE ALSO" > > \fBusbip\fP\fB(8)\fB\fP > > - > > +\fBusbipa\fP\fB(8)\fB\fP > > Best Regards, Nobuo Iwata // -- To unsubscribe from this list: send the line "unsubscribe linux-usb" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
