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