Hi, Some comments inline. On 3/15/21 1:40 AM, Hongren Zheng (Zenithal) wrote: > The old document for usbip protocol is misleading and hard to read: > * Some fields in header are incorrect > * Explanation of some fields are unclear or even wrong > * Padding of header (namely all headers have the same length) is > not explicitly point out, which is crucial for stream protocol like > TCP > > These fixes are made through reading usbip kernel drivers and userland > codes. Also I have implemented one usbip server. > > Major changes: > > PATCH v2: > > PATCH v3: > > Co-developed-by: Alexandre Demers <alexandre.f.demers@xxxxxxxxx> > Signed-off-by: Hongren Zheng (Zenithal) <i@xxxxxxxxxxx> > --- > Documentation/usb/usbip_protocol.rst | 288 ++++++++++++++------------- > 1 file changed, 155 insertions(+), 133 deletions(-) > > diff --git a/Documentation/usb/usbip_protocol.rst b/Documentation/usb/usbip_protocol.rst > index 988c832166cd..ed423cdda236 100644 > --- a/Documentation/usb/usbip_protocol.rst > +++ b/Documentation/usb/usbip_protocol.rst > @@ -254,65 +283,75 @@ OP_REP_IMPORT: > | 0x13E | 1 | | bNumInterfaces | > +-----------+--------+------------+---------------------------------------------------+ > > -USBIP_CMD_SUBMIT: > - Submit an URB > +The following four commands have a common basic header called > +'usbip_header_basic', and their headers, called 'usbip_header' (before URB > +payload), have the same length, therefore paddings are needed. > > -+-----------+--------+------------+---------------------------------------------------+ > -| Offset | Length | Value | Description | > -+===========+========+============+===================================================+ > -| 0 | 4 | 0x00000001 | command: Submit an URB | > -+-----------+--------+------------+---------------------------------------------------+ > -| 4 | 4 | | seqnum: the sequence number of the URB to submit | > -+-----------+--------+------------+---------------------------------------------------+ > -| 8 | 4 | | devid | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0xC | 4 | | direction: | > -| | | | | > -| | | | - 0: USBIP_DIR_OUT | > -| | | | - 1: USBIP_DIR_IN | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0x10 | 4 | | ep: endpoint number, possible values are: 0...15 | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0x14 | 4 | | transfer_flags: possible values depend on the | > -| | | | URB transfer type, see below | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0x18 | 4 | | transfer_buffer_length | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0x1C | 4 | | start_frame: specify the selected frame to | > -| | | | transmit an ISO frame, ignored if URB_ISO_ASAP | > -| | | | is specified at transfer_flags | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0x20 | 4 | | number_of_packets: number of ISO packets | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0x24 | 4 | | interval: maximum time for the request on the | > -| | | | server-side host controller | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0x28 | 8 | | setup: data bytes for USB setup, filled with | > -| | | | zeros if not used | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0x30 | | | URB data. For ISO transfers the padding between | > -| | | | each ISO packets is not transmitted. | > -+-----------+--------+------------+---------------------------------------------------+ > +usbip_header_basic: > > ++-----------+--------+---------------------------------------------------+ > +| Offset | Length | Description | > ++===========+========+===================================================+ > +| 0 | 4 | command | > ++-----------+--------+---------------------------------------------------+ > +| 4 | 4 | seqnum: sequential number that identifies requests| > +| | | and corresponding responses; | > +| | | incremented per connection | > ++-----------+--------+---------------------------------------------------+ > +| 8 | 4 | devid: specifies a remote USB device uniquely | > +| | | instead of busnum and devnum; | > +| | | for client (request), this value is | > +| | | ((busnum << 16) | devnum); | > +| | | for server (response), this shall be set to 0 | > ++-----------+--------+---------------------------------------------------+ > +| 0xC | 4 | direction: | > +| | | | > +| | | - 0: USBIP_DIR_OUT | > +| | | - 1: USBIP_DIR_IN | > +| | | | > +| | | only used by client, for server this shall be 0 | > ++-----------+--------+---------------------------------------------------+ > +| 0x10 | 4 | ep: endpoint number | > +| | | only used by client, for server this shall be 0 | This could use a ';' after the '0' above for better readability. > +| | | for UNLINK, this shall be 0 | > ++-----------+--------+---------------------------------------------------+ > > - +-------------------------+------------+---------+-----------+----------+-------------+ > - | Allowed transfer_flags | value | control | interrupt | bulk | isochronous | > - +=========================+============+=========+===========+==========+=============+ > - | URB_SHORT_NOT_OK | 0x00000001 | only in | only in | only in | no | > - +-------------------------+------------+---------+-----------+----------+-------------+ > - | URB_ISO_ASAP | 0x00000002 | no | no | no | yes | > - +-------------------------+------------+---------+-----------+----------+-------------+ > - | URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes | yes | yes | yes | > - +-------------------------+------------+---------+-----------+----------+-------------+ > - | URB_ZERO_PACKET | 0x00000040 | no | no | only out | no | > - +-------------------------+------------+---------+-----------+----------+-------------+ > - | URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes | yes | > - +-------------------------+------------+---------+-----------+----------+-------------+ > - | URB_FREE_BUFFER | 0x00000100 | yes | yes | yes | yes | > - +-------------------------+------------+---------+-----------+----------+-------------+ > - | URB_DIR_MASK | 0x00000200 | yes | yes | yes | yes | > - +-------------------------+------------+---------+-----------+----------+-------------+ > +USBIP_CMD_SUBMIT: > + Submit an URB > > ++-----------+--------+---------------------------------------------------+ > +| Offset | Length | Description | > ++===========+========+===================================================+ > +| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000001 | > ++-----------+--------+---------------------------------------------------+ > +| 0x14 | 4 | transfer_flags: possible values depend on the | > +| | | URB transfer_flags, | > +| | | but with URB_NO_TRANSFER_DMA_MAP masked | > ++-----------+--------+---------------------------------------------------+ > +| 0x18 | 4 | transfer_buffer_length: | > +| | | use URB transfer_buffer_length | > ++-----------+--------+---------------------------------------------------+ > +| 0x1C | 4 | start_frame: use URB start_frame; | > +| | | initial frame for ISO transfer | transfer; > +| | | shall be set to 0 if not ISO transfer | > ++-----------+--------+---------------------------------------------------+ > +| 0x20 | 4 | number_of_packets: number of ISO packets | packets; > +| | | shall be set to 0xffffffff if not ISO transfer | > ++-----------+--------+---------------------------------------------------+ > +| 0x24 | 4 | interval: maximum time for the request on the | > +| | | server-side host controller | > ++-----------+--------+---------------------------------------------------+ > +| 0x28 | 8 | setup: data bytes for USB setup, filled with | > +| | | zeros if not used | > ++-----------+--------+---------------------------------------------------+ > +| 0x30 | n | tranfer_buffer. | > +| | | If direction is USBIP_DIR_OUT then n equals | > +| | | transfer_buffer_length; otherwise n equals 0 | equals 0. > +| | | For ISO transfers the padding between each ISO | > +| | | between each ISO packets is not transmitted. | > ++-----------+--------+---------------------------------------------------+ > +| 0x30+n | m | iso_packet_descriptor | > ++-----------+--------+---------------------------------------------------+ > > USBIP_RET_SUBMIT: > Reply for submitting an URB > @@ -320,92 +359,75 @@ USBIP_RET_SUBMIT: > +-----------+--------+------------+---------------------------------------------------+ > | Offset | Length | Value | Description | > +===========+========+============+===================================================+ > -| 0 | 4 | 0x00000003 | command | > -+-----------+--------+------------+---------------------------------------------------+ > -| 4 | 4 | | seqnum: URB sequence number | > -+-----------+--------+------------+---------------------------------------------------+ > -| 8 | 4 | | devid | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0xC | 4 | | direction: | > -| | | | | > -| | | | - 0: USBIP_DIR_OUT | > -| | | | - 1: USBIP_DIR_IN | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0x10 | 4 | | ep: endpoint number | > +| 0 | 20 | | usbip_header_basic, 'command' shall be 0x00000003 | > +-----------+--------+------------+---------------------------------------------------+ > | 0x14 | 4 | | status: zero for successful URB transaction, | > | | | | otherwise some kind of error happened. | > +-----------+--------+------------+---------------------------------------------------+ > | 0x18 | 4 | n | actual_length: number of URB data bytes | bytes; > +| | | | use URB actual_length | > +-----------+--------+------------+---------------------------------------------------+ > -| 0x1C | 4 | | start_frame: for an ISO frame the actually | > -| | | | selected frame for transmit. | > +| 0x1C | 4 | | start_frame: use URB start_frame; | > +| | | | initial frame for ISO transfer | transfer; > +| | | | shall be set to 0 if not ISO transfer | > +-----------+--------+------------+---------------------------------------------------+ > -| 0x20 | 4 | | number_of_packets | > +| 0x20 | 4 | | number_of_packets: number of ISO packets | packets; > +| | | | shall be set to 0xffffffff if not ISO transfer | > +-----------+--------+------------+---------------------------------------------------+ > | 0x24 | 4 | | error_count | > +-----------+--------+------------+---------------------------------------------------+ > -| 0x28 | 8 | | setup: data bytes for USB setup, filled with | > -| | | | zeros if not used | used; > +| 0x28 | 8 | | padding, shall be set to 0 | > +-----------+--------+------------+---------------------------------------------------+ > -| 0x30 | n | | URB data bytes. For ISO transfers the padding | > +| 0x30 | n | | tranfer_buffer. | transfer_buffer. > +| | | | If direction is USBIP_DIR_OUT then n equals | > +| | | | transfer_buffer_length; otherwise n equals 0 | equals 0. > +| | | | For ISO transfers the padding between each ISO | > | | | | between each ISO packets is not transmitted. | > +-----------+--------+------------+---------------------------------------------------+ > +| 0x30+n | m | | iso_packet_descriptor | > ++-----------+--------+------------+---------------------------------------------------+ > > USBIP_CMD_UNLINK: > Unlink an URB > > -+-----------+--------+------------+---------------------------------------------------+ > -| Offset | Length | Value | Description | > -+===========+========+============+===================================================+ > -| 0 | 4 | 0x00000002 | command: URB unlink command | > -+-----------+--------+------------+---------------------------------------------------+ > -| 4 | 4 | | seqnum: URB sequence number to unlink: | > -| | | | | > -| | | | FIXME: | > -| | | | is this so? | > -+-----------+--------+------------+---------------------------------------------------+ > -| 8 | 4 | | devid | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0xC | 4 | | direction: | > -| | | | | > -| | | | - 0: USBIP_DIR_OUT | > -| | | | - 1: USBIP_DIR_IN | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0x10 | 4 | | ep: endpoint number: zero | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0x14 | 4 | | seqnum: the URB sequence number given previously | > -| | | | at USBIP_CMD_SUBMIT.seqnum field | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0x30 | n | | URB data bytes. For ISO transfers the padding | > -| | | | between each ISO packets is not transmitted. | > -+-----------+--------+------------+---------------------------------------------------+ > ++-----------+--------+---------------------------------------------------+ > +| Offset | Length | Description | > ++===========+========+===================================================+ > +| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000002 | > ++-----------+--------+---------------------------------------------------+ > +| 0x14 | 4 | unlink_seqnum, of the SUBMIT request to unlink | > ++-----------+--------+---------------------------------------------------+ > +| 0x18 | 24 | padding, shall be set to 0 | > ++-----------+--------+---------------------------------------------------+ > > USBIP_RET_UNLINK: > Reply for URB unlink > > -+-----------+--------+------------+---------------------------------------------------+ > -| Offset | Length | Value | Description | > -+===========+========+============+===================================================+ > -| 0 | 4 | 0x00000004 | command: reply for the URB unlink command | > -+-----------+--------+------------+---------------------------------------------------+ > -| 4 | 4 | | seqnum: the unlinked URB sequence number | > -+-----------+--------+------------+---------------------------------------------------+ > -| 8 | 4 | | devid | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0xC | 4 | | direction: | > -| | | | | > -| | | | - 0: USBIP_DIR_OUT | > -| | | | - 1: USBIP_DIR_IN | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0x10 | 4 | | ep: endpoint number | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0x14 | 4 | | status: This is the value contained in the | > -| | | | urb->status in the URB completition handler. | completion > -| | | | | > -| | | | FIXME: | > -| | | | a better explanation needed. | > -+-----------+--------+------------+---------------------------------------------------+ > -| 0x30 | n | | URB data bytes. For ISO transfers the padding | > -| | | | between each ISO packets is not transmitted. | > -+-----------+--------+------------+---------------------------------------------------+ > ++-----------+--------+---------------------------------------------------+ > +| Offset | Length | Description | > ++===========+========+===================================================+ > +| 0 | 20 | usbip_header_basic, 'command' shall be 0x00000004 | > ++-----------+--------+---------------------------------------------------+ > +| 0x14 | 4 | status: This is similar to that status of | to the status of > +| | | USBIP_RET_SUBMIT (share the same memory offset) | offset). > +| | | When UNLINK is successful, status is -ECONNRESET; | > +| | | when USBIP_CMD_UNLINK is after USBIP_RET_SUBMIT | > +| | | status is 0 |> ++-----------+--------+---------------------------------------------------+ > +| 0x18 | 24 | padding, shall be set to 0 | > ++-----------+--------+---------------------------------------------------+ > + > +EXAMPLE > +======= HTH. -- ~Randy