On 11/22/2016 07:48 AM, Nobuo Iwata wrote: > This patch adds export and un-export request/response to > Documentation/usb/usbip_protocol.txt. > > The definition of the structs has been defined in original code of > tools/usb/usbip/usbip_network.h but not described in the document. > > Adding the request and response, words 'server' and 'client' are > ambiguous in several place. To avoid confusion, 'device-side' and > 'application-side' are written together with 'server' and 'client'. > > 'export' was used in the counter side of 'import' request. This patch > organizes usage of 'import' and 'export'. >
I would be very happy if we could avoid device and application side terms like I described in previous email. > Signed-off-by: Nobuo Iwata <nobuo.iw...@fujixerox.co.jp> > --- > Documentation/usb/usbip_protocol.txt | 204 ++++++++++++++++++++++++--- > 1 file changed, 181 insertions(+), 23 deletions(-) > > diff --git a/Documentation/usb/usbip_protocol.txt > b/Documentation/usb/usbip_protocol.txt > index 16b6fe2..d4be5b6 100644 > --- a/Documentation/usb/usbip_protocol.txt > +++ b/Documentation/usb/usbip_protocol.txt > @@ -1,20 +1,26 @@ > PRELIMINARY DRAFT, MAY CONTAIN MISTAKES! > 28 Jun 2011 > +MODIFIED FOR CONNECT AND DISCONNECT OPERARION. > +07 March 2016 > > -The USB/IP protocol follows a server/client architecture. The server exports > the > -USB devices and the clients imports them. The device driver for the exported > -USB device runs on the client machine. > +The USB/IP protocol follows a server/client architecture between two > computers > +one has USB devices and the other runs application using the devices. There > are > +two ways for initiation. > > -The client may ask for the list of the exported USB devices. To get the list > the > -client opens a TCP/IP connection towards the server, and sends an > OP_REQ_DEVLIST > -packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be > sent > -in one or more pieces at the low level transport layer). The server sends > back > -the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the > -TCP/IP connection is closed. > +The first way is to import devices from application-side. In this way, the > +server runs in device-side and the client runs in application-side. In device > +side user makes devices importable with 'bind' operation. > > +The client may ask for the list of the importable USB devices. To get the > list > +the client opens a TCP/IP connection towards the server, and sends an > +OP_REQ_DEVLIST packet on top of the TCP/IP connection (so the actual > +OP_REQ_DEVLIST may be sent in one or more pieces at the low level transport > +layer). The server sends back the OP_REP_DEVLIST packet which lists the > +importable USB devices. Finally the TCP/IP connection is closed. > + > + application-side device-side > virtual host controller usb host > - "client" "server" > - (imports USB devices) (exports USB devices) > + "client" (lists importable devices) "server" > | | > | OP_REQ_DEVLIST | > | ----------------------------------------------> | > @@ -23,18 +29,13 @@ TCP/IP connection is closed. > | <---------------------------------------------- | > | | > > -Once the client knows the list of exported USB devices it may decide to use > one > -of them. First the client opens a TCP/IP connection towards the server and > -sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the > -import was successful the TCP/IP connection remains open and will be used > -to transfer the URB traffic between the client and the server. The client may > -send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and > -USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the > -server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively. > +Once the client knows the list of importable USB devices it may decide to use > +one of them. First the client opens a TCP/IP connection towards the server > and > +sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. > > + application-side device-side > virtual host controller usb host > - "client" "server" > - (imports USB devices) (exports USB devices) > + "client" (imports a USB device) "server" > | | > | OP_REQ_IMPORT | > | ----------------------------------------------> | > @@ -42,6 +43,32 @@ server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK > respectively. > | OP_REP_IMPORT | > | <---------------------------------------------- | > | | > + > +The second way is to export devices from device-side. In this way, the server > +runs in application-side and the client runs in device-side. The client > binds a > +device to export, opens a TCP/IP connection towards the server and sends an > +OP_REQ_EXPORT packet. The server replies with OP_REP_EXPORT. > + > + application-side device-side > + virtual host controller usb host > + "server" (exports a USB device) "client" > + | | > + | OP_REQ_EXPORT | > + | <---------------------------------------------- | > + | | > + | OP_REP_EXPORT | > + | ----------------------------------------------> | > + | | > + > +If the import or export was successful the TCP/IP connection remains open and > +will be used to transfer the URB traffic between the client and the server. > The > +client may send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, > and > +USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the > server > +may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively. > + > + application-side device-side > + virtual host controller usb host > + "client/server" "server/client" > | | > | USBIP_CMD_SUBMIT(seqnum = n) | > | ----------------------------------------------> | > @@ -84,11 +111,27 @@ server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK > respectively. > | <---------------------------------------------- | > | | > > +For the second way, it is able to unexport devices from device-side. First > the > +client opens a TCP/IP connection towards the server and sends an > OP_REQ_UNEXPORT > +packet. Then the server detaches exported device then the connection will be > +closed. The server replies the result with OP_REP_UNEXPORT. > + > + application-side device-side > + virtual host controller usb host > + "server" (un-exports a USB device) "client" > + | | > + | OP_REQ_UNEXPORT | > + | <---------------------------------------------- | > + | | > + | OP_REP_UNEXPORT | > + | ----------------------------------------------> | > + | | > + > The fields are in network (big endian) byte order meaning that the most > significant > byte (MSB) is stored at the lowest address. > > > -OP_REQ_DEVLIST: Retrieve the list of exported USB devices. > +OP_REQ_DEVLIST: Retrieve the list of importable USB devices. > > Offset | Length | Value | Description > > -----------+--------+------------+--------------------------------------------------- > @@ -182,7 +225,6 @@ OP_REQ_IMPORT: Request to import (attach) a remote USB > device. > | | | from the message field > OP_REP_DEVLIST.busid. > | | | A string closed with zero, the unused > bytes > | | | shall be filled with zeros. > ------------+--------+------------+--------------------------------------------------- > > OP_REP_IMPORT: Reply to import (attach) a remote USB device. > > @@ -233,6 +275,122 @@ OP_REP_IMPORT: Reply to import (attach) a remote USB > device. > > -----------+--------+------------+--------------------------------------------------- > 0x13E | 1 | | bNumInterfaces > > +OP_REQ_EXPORT: Request to export (connect) a local USB device to remote. > + > + Offset | Length | Value | Description > +-----------+--------+------------+--------------------------------------------------- > + 0 | 2 | 0x0100 | Binary-coded decimal USBIP version > number: v1.0.0 > +-----------+--------+------------+--------------------------------------------------- > + 2 | 2 | 0x8006 | Command code: export a remote USB device. > +-----------+--------+------------+--------------------------------------------------- > + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 > +-----------+--------+------------+--------------------------------------------------- > + 8 | | | From now on comes the details of the > exporting > + | | | device. > +-----------+--------+------------+--------------------------------------------------- > + | 256 | | path: Path of the device on the host > exporting the > + | | | USB device, string closed with zero > byte, e.g. > + | | | > "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" > + | | | The unused bytes shall be filled with > zero > + | | | bytes. > +-----------+--------+------------+--------------------------------------------------- > + 0x108 | 32 | | busid: Bus ID of the exported device, > string > + | | | closed with zero byte, e.g. "3-2". The > unused > + | | | bytes shall be filled with zero bytes. > +-----------+--------+------------+--------------------------------------------------- > + 0x128 | 4 | | busnum > +-----------+--------+------------+--------------------------------------------------- > + 0x12C | 4 | | devnum > +-----------+--------+------------+--------------------------------------------------- > + 0x130 | 4 | | speed > +-----------+--------+------------+--------------------------------------------------- > + 0x134 | 2 | | idVendor > +-----------+--------+------------+--------------------------------------------------- > + 0x136 | 2 | | idProduct > +-----------+--------+------------+--------------------------------------------------- > + 0x138 | 2 | | bcdDevice > +-----------+--------+------------+--------------------------------------------------- > + 0x139 | 1 | | bDeviceClass > +-----------+--------+------------+--------------------------------------------------- > + 0x13A | 1 | | bDeviceSubClass > +-----------+--------+------------+--------------------------------------------------- > + 0x13B | 1 | | bDeviceProtocol > +-----------+--------+------------+--------------------------------------------------- > + 0x13C | 1 | | bConfigurationValue > +-----------+--------+------------+--------------------------------------------------- > + 0x13D | 1 | | bNumConfigurations > +-----------+--------+------------+--------------------------------------------------- > + 0x13E | 1 | | bNumInterfaces > + Why we need to send so much data? As far as I see from the code busnum, devnum and speed is enough to import a device. > +OP_REP_EXPORT: Reply to export (connect) a local USB device to remote. > + > + Offset | Length | Value | Description > +-----------+--------+------------+--------------------------------------------------- > + 0 | 2 | 0x0100 | Binary-coded decimal USBIP version > number: v1.0.0 > +-----------+--------+------------+--------------------------------------------------- > + 2 | 2 | 0x0006 | Reply code: Reply to import. > +-----------+--------+------------+--------------------------------------------------- > + 4 | 4 | 0x00000000 | Status: 0 for OK > + | | | 1 for error > + > +OP_REQ_UNEXPORT: Request to un-export (disconnect) a local USB device from > remote. > + > + Offset | Length | Value | Description > +-----------+--------+------------+--------------------------------------------------- > + 0 | 2 | 0x0100 | Binary-coded decimal USBIP version > number: v1.0.0 > +-----------+--------+------------+--------------------------------------------------- > + 2 | 2 | 0x8007 | Command code: export a remote USB device. > +-----------+--------+------------+--------------------------------------------------- > + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 > +-----------+--------+------------+--------------------------------------------------- > + 8 | | | From now on comes the details of the > un-exporting > + | | | device. > +-----------+--------+------------+--------------------------------------------------- > + | 256 | | path: Path of the device on the host > exporting the > + | | | USB device, string closed with zero > byte, e.g. > + | | | > "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" > + | | | The unused bytes shall be filled with > zero > + | | | bytes. > +-----------+--------+------------+--------------------------------------------------- > + 0x108 | 32 | | busid: Bus ID of the exported device, > string > + | | | closed with zero byte, e.g. "3-2". The > unused > + | | | bytes shall be filled with zero bytes. > +-----------+--------+------------+--------------------------------------------------- > + 0x128 | 4 | | busnum > +-----------+--------+------------+--------------------------------------------------- > + 0x12C | 4 | | devnum > +-----------+--------+------------+--------------------------------------------------- > + 0x130 | 4 | | speed > +-----------+--------+------------+--------------------------------------------------- > + 0x134 | 2 | | idVendor > +-----------+--------+------------+--------------------------------------------------- > + 0x136 | 2 | | idProduct > +-----------+--------+------------+--------------------------------------------------- > + 0x138 | 2 | | bcdDevice > +-----------+--------+------------+--------------------------------------------------- > + 0x139 | 1 | | bDeviceClass > +-----------+--------+------------+--------------------------------------------------- > + 0x13A | 1 | | bDeviceSubClass > +-----------+--------+------------+--------------------------------------------------- > + 0x13B | 1 | | bDeviceProtocol > +-----------+--------+------------+--------------------------------------------------- > + 0x13C | 1 | | bConfigurationValue > +-----------+--------+------------+--------------------------------------------------- > + 0x13D | 1 | | bNumConfigurations > +-----------+--------+------------+--------------------------------------------------- > + 0x13E | 1 | | bNumInterfaces > + Why we need to send so much data to detach USB device? > +OP_REP_UNEXPORT: Reply to un-export (disconnect) a local USB device from > remote. > + > + Offset | Length | Value | Description > +-----------+--------+------------+--------------------------------------------------- > + 0 | 2 | 0x0100 | Binary-coded decimal USBIP version > number: v1.0.0 > +-----------+--------+------------+--------------------------------------------------- > + 2 | 2 | 0x0007 | Reply code: Reply to import. > +-----------+--------+------------+--------------------------------------------------- > + 4 | 4 | 0x00000000 | Status: 0 for OK > + | | | 1 for error Why this field is called in a different way than it's called in the code (returncode vs status)? Not to mention that you used -1 as error indicator which for sure not equal to 1 when placed in unsigned integer? Best regards, -- Krzysztof Opasiak Samsung R&D Institute Poland Samsung Electronics -- To unsubscribe from this list: send the line "unsubscribe linux-usb" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
