* [PATCH v1 1/4] tools/usbip: update documentation
@ 2021-11-07 17:15 Lars Gunnarsson
2021-11-19 19:00 ` Shuah Khan
0 siblings, 1 reply; 2+ messages in thread
From: Lars Gunnarsson @ 2021-11-07 17:15 UTC (permalink / raw)
To: Valentina Manea, Shuah Khan, linux-usb
This patch contains usbip protocol documentation updates for
the implementation changes in subsequent patches.
Signed-off-by: Lars Gunnarsson <gunnarsson.lars@gmail.com>
---
v1: New patch added in series.
Documentation/usb/usbip_protocol.rst | 61 ++++++++++++++++++++++++----
1 file changed, 53 insertions(+), 8 deletions(-)
diff --git a/Documentation/usb/usbip_protocol.rst b/Documentation/usb/usbip_protocol.rst
index 0b8541fda4d8..1afe6d297efc 100644
--- a/Documentation/usb/usbip_protocol.rst
+++ b/Documentation/usb/usbip_protocol.rst
@@ -9,6 +9,11 @@ The USB/IP protocol follows a server/client architecture. The server exports the
USB devices and the clients import them. The device driver for the exported
USB device runs on the client machine.
+Initially the server may choose to export any of its available USB devices,
+based on the busid. The device will remain exported until it's unplugged or
+unbound from the usbip driver. It is also possible to persistently export
+devices on a given bus by monitor when they are plugged in.
+
The client may ask for the list of the exported USB devices. To get the list the
client opens a TCP/IP connection to 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
@@ -31,12 +36,7 @@ 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 to 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.
+sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT.
::
@@ -50,6 +50,47 @@ server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively.
| OP_REP_IMPORT |
| <---------------------------------------------- |
| |
+
+The client may also request to poll for devices to become exported on a given
+busid, instead of immediately receive an error. If no device becomes exported
+within the chosen time, the server replies with timeout. The TCP/IP connection
+remains open and subsequent poll requests can be sent.
+
+::
+
+ virtual host controller usb host
+ "client" "server"
+ (imports USB devices) (exports USB devices)
+ | |
+ | OP_REQ_IMPORT |
+ | ----------------------------------------------> |
+ | . |
+ | : |
+ | |
+ | OP_REP_IMPORT |
+ | <---------------------------------------------- |
+ | |
+ | OP_REQ_IMPORT |
+ | ----------------------------------------------> |
+ | . |
+ | : |
+ | |
+ | 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.
+
+::
+
+ virtual host controller usb host
+ "client" "server"
+ (imports USB devices) (exports USB devices)
| |
| USBIP_CMD_SUBMIT(seqnum = n) |
| ----------------------------------------------> |
@@ -132,8 +173,8 @@ byte (MSB) is stored at the lowest address.
Protocol Version
================
-The documented USBIP version is v1.1.1. The binary representation of this
-version in message headers is 0x0111.
+The documented USBIP version is v1.1.2. The binary representation of this
+version in message headers is 0x0112.
This is defined in tools/usb/usbip/configure.ac
@@ -243,6 +284,10 @@ OP_REQ_IMPORT:
| | | | A string closed with zero, the unused bytes |
| | | | shall be filled with zeros. |
+-----------+--------+------------+---------------------------------------------------+
+| 40 | 4 | | poll timeout: instead of returning immediately if |
+| | | | device is not available, wait until usb device |
+| | | | becomes exported or a timeout occurs. |
++-----------+--------+------------+---------------------------------------------------+
OP_REP_IMPORT:
Reply to import (attach) a remote USB device.
--
2.25.1
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH v1 1/4] tools/usbip: update documentation
2021-11-07 17:15 [PATCH v1 1/4] tools/usbip: update documentation Lars Gunnarsson
@ 2021-11-19 19:00 ` Shuah Khan
0 siblings, 0 replies; 2+ messages in thread
From: Shuah Khan @ 2021-11-19 19:00 UTC (permalink / raw)
To: Lars Gunnarsson, Valentina Manea, Shuah Khan, linux-usb, Shuah Khan
On 11/7/21 10:15 AM, Lars Gunnarsson wrote:
> This patch contains usbip protocol documentation updates for
> the implementation changes in subsequent patches.
>
> Signed-off-by: Lars Gunnarsson <gunnarsson.lars@gmail.com>
> ---
> v1: New patch added in series.
>
> Documentation/usb/usbip_protocol.rst | 61 ++++++++++++++++++++++++----
> 1 file changed, 53 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/usb/usbip_protocol.rst b/Documentation/usb/usbip_protocol.rst
> index 0b8541fda4d8..1afe6d297efc 100644
> --- a/Documentation/usb/usbip_protocol.rst
> +++ b/Documentation/usb/usbip_protocol.rst
> @@ -9,6 +9,11 @@ The USB/IP protocol follows a server/client architecture. The server exports the
> USB devices and the clients import them. The device driver for the exported
> USB device runs on the client machine.
>
> +Initially the server may choose to export any of its available USB devices,
> +based on the busid. The device will remain exported until it's unplugged or
> +unbound from the usbip driver. It is also possible to persistently export
> +devices on a given bus by monitor when they are plugged in.
> +
The current description is mixing export and unbound.
Let's rephrase this as follows.
"The server may choose to export any of its available USB devices based on their
busid. These devices will remain exported until they are unplugged or unexported.
Optionally, it is possible to persistently export the devices on a given bus by
monitor when they are plugged in"
I don't see tools/usb/usbip/doc updated to reflect the new commands? Please
include tools/usb/usbip/doc to both usbipd.8 and usbip.8 to describe how this
new feature can be used. Also include details on how to reverse persistent
export. Right now it is a decision made on each boot and there is no need to
be concerned about exporting devices that should no longer be exported. With
this feature, it becomes important to make sure there is clear indication that
devices are being exported in persistent manner.
I would like to see the doc updates - please add them as the second patch in
this series, so it would be easier for people to review.
thanks,
-- Shuah
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2021-11-19 19:00 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-11-07 17:15 [PATCH v1 1/4] tools/usbip: update documentation Lars Gunnarsson
2021-11-19 19:00 ` Shuah Khan
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).