On 3/15/21 8:25 PM, 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 part.
* Add data captured from wire as example
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 | 320 ++++++++++++++-------------
1 file changed, 171 insertions(+), 149 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
Hi Hongren Zheng,
Thanks for the patch. The document updates are very much needed.
I will review and give you comments.
Please wait for a couple of days before sending another version.
Makes it easier for you an your reviewers.
I started reviewing patch v3 and I will switch to v5 now
and send you comments.
thanks,
-- Shuah
