Re: [PATCH v6] docs: usbip: Fix major fields and descriptions in protocol

[Shuah Khan <skhan@linuxfoundation.org>]

On 3/30/21 11:00 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 pointed out, which is crucial for stream protocol
>      like TCP
> 
> Major changes:
>    * Document the correct field as described in the codebase.
>    * Document the padding in usbip headers. This is crucial for TCP
>      stream hence these padding should be explicitly point out.
>      In code these padding are implemented by a union of all headers.
>    * Fix two FIXME related to usbip unlink and Document the behavior
>      of unlink in different situation.
>    * Clarify some field with more accurate explanation, like those
>      fields associated with URB. Some constraints are extracted from
>      code.
>    * Delete specific transfer_flag doc in usbip as it should be
>      documented by the URB doc in Documentation/driver-api/usb/URB.rst
>    * Add data captured from wire as example
> 
> Version change:
>      From "PRELIMINARY DRAFT, MAY CONTAIN MISTAKES, 28 Jun 2011"
>      To "Version 1, 31 Mar 2021"
> 
> Co-developed-by: Alexandre Demers <alexandre.f.demers@gmail.com>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> Signed-off-by: Hongren Zheng <i@zenithal.me>
> ---
>   Documentation/usb/usbip_protocol.rst | 344 +++++++++++++++------------
>   1 file changed, 193 insertions(+), 151 deletions(-)
> 
> PATCH v2:
> Some changes suggested by a previous patch in
> https://lore.kernel.org/linux-usb
> /20180128071514.9107-1-alexandre.f.demers@gmail.com/
> is adopted in this patch.
>    * Fix Typo: duplicated 'the' in 'the following 4 field'
>    * Fix incorrect field: in OP_REQ_DEVLIST, the second dev starts with
>      field 'path', not 'busid'
> 
> PATCH v3:
> Suggested by
> https://lore.kernel.org/linux-doc/YE8Oan2BmSuKR4%2Fp@kroah.com/
>    * Remove date and changelog in doc as these are tracked in git history
>    * Remove 'mistake alert' as all data fields are documented properly
>      now. However, docs on possible values for some field shall be added
>      in the future
> 
> PATCH v4:
> Suggested by https://lore.kernel.org/linux-doc
> /40351ed6-2907-3966-e69a-a564173b3682@infradead.org/
>    * Add punctuations for readability
>    * Move patch changelog after the marker line
>    * Remove nickname in signed-off-by line
> 
> PATCH v5:
>    * Instead of co-developed-by, use reviewed-by
>      for Randy Dunlap
> 
> PATCH v6:
>    * Add reference to URB doc in changelog
>    * Add version change in changelog
>    * Add reference to URB doc for transfer_flag and other fields in
>      USBIP_CMD_SUBMIT
>    * Add reference to specific functions for UNLINK behavior
>      and transfer_flag
>    * Fix typo: "clients import", "connection to the server" and
>      "USBIP_RET_UNLINK" to "USBIP_RET_SUBMIT" in UNLINK behavior part
>    * Separate the flow of UNLINK for clarity
>    * Extract the version number in message headers to one separate
>      section for ease of maintainence
> 

Thank you for updating the document.

Reviewed-by: Shuah Khan <skhan@linuxfoundation.org>

Greg, please pick this up.

thanks,
-- Shuah