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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxx>
Reviewed-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Signed-off-by: Hongren Zheng <i@xxxxxxxxxxx>
---
  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@xxxxxxxxx/
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@xxxxxxxxx/
   * 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@xxxxxxxxxxxxx/
   * 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@xxxxxxxxxxxxxxxxxxx>

Greg, please pick this up.

thanks,
-- Shuah



[Index of Archives]     [Linux Media]     [Linux Input]     [Linux Audio Users]     [Yosemite News]     [Linux Kernel]     [Linux SCSI]     [Old Linux USB Devel Archive]

  Powered by Linux