[PATCH] docs: driver-api: usb: Document USBDEVFS_BULK return value and short reads

[PATCH] docs: driver-api: usb: Document USBDEVFS_BULK return value and short reads

[Malaya Kumar Rout]

Remove a longstanding FIXME comment in the USBDEVFS_BULK documentation
by properly documenting the return value behavior. The ioctl returns the
actual number of bytes transferred on success, which naturally handles
short reads (where fewer bytes are read than requested) by returning a
value less than the requested length.

This information was verified by examining the implementation in
drivers/usb/core/devio.c:do_proc_bulk(), which returns the actual
transfer length on success.

Signed-off-by: Malaya Kumar Rout <malayarout91@gmail.com>
---
 Documentation/driver-api/usb/usb.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst
index 7f2f41e80c1c..a01d72af479b 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -539,6 +539,12 @@ USBDEVFS_BULK
     kernels support requests up to about 128KBytes. *FIXME say how read
     length is returned, and how short reads are handled.*.
 
+    kernels support requests up to about 128KBytes. On success, the
+    ioctl returns the number of bytes actually transferred. Short reads
+    are supported; if fewer bytes are received than requested, only the
+    actual number of bytes received are copied to the buffer and that
+    count is returned. On error, a negative error code is returned.
+
 USBDEVFS_CLEAR_HALT
     Clears endpoint halt (stall) and resets the endpoint toggle. This is
     only meaningful for bulk or interrupt endpoints. The ioctl parameter
-- 
2.53.0

Re: [PATCH] docs: driver-api: usb: Document USBDEVFS_BULK return value and short reads

[Brigham Campbell]

On Thu, 05 Mar 2026 23:37:50 +0530, Malaya Kumar Rout <malayarout91@gmail.com> wrote:
> Remove a longstanding FIXME comment in the USBDEVFS_BULK documentation
> by properly documenting the return value behavior. The ioctl returns the
> actual number of bytes transferred on success, which naturally handles
> short reads (where fewer bytes are read than requested) by returning a
> value less than the requested length.
> 
> This information was verified by examining the implementation in
> drivers/usb/core/devio.c:do_proc_bulk(), which returns the actual
> transfer length on success.

Good effort, Malaya! As far as I can tell, you've done a good job
formatting this patch and sending it out to the right people. You've
done a lot right with this patch. However, these changes aren't quite
suitable for inclusion upstream.

> ---
>  Documentation/driver-api/usb/usb.rst | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst
> index 7f2f41e80c1c..a01d72af479b 100644
> --- a/Documentation/driver-api/usb/usb.rst
> +++ b/Documentation/driver-api/usb/usb.rst
> @@ -539,6 +539,12 @@ USBDEVFS_BULK
>      kernels support requests up to about 128KBytes. *FIXME say how read
>      length is returned, and how short reads are handled.*.

You prepared this patch with intent to address this FIXME, but you
didn't remove the FIXME.

>  
> +    kernels support requests up to about 128KBytes. On success, the

This line directly duplicates information already in the previous
paragraph.

> +    ioctl returns the number of bytes actually transferred. Short reads
> +    are supported; if fewer bytes are received than requested, only the
> +    actual number of bytes received are copied to the buffer and that
> +    count is returned. On error, a negative error code is returned.

The FIXME says that documentation should "say how read length is
returned". Is it returned by overwriting the `len` member of the struct
that is passed in? Or is it returned via the integer return value of the
ioctl call itself? Your patch doesn't communicate _how_ read length is
returned.

> +
>  USBDEVFS_CLEAR_HALT
>      Clears endpoint halt (stall) and resets the endpoint toggle. This is
>      only meaningful for bulk or interrupt endpoints. The ioctl parameter

These small documentation fixes are a great way to get started with
kernel development, but they're also difficult to get right. This is
just a suggestion, but you may find more success checking out
`docs-next` and looking for documentation compilation warnings that need
to be addressed. Fix whatever issue is causing the warning and it will
go away. Those types of changes are easier for maintainers to verify for
correctness.

- Brigham

-- 
Brigham Campbell <me@brighamcampbell.com>