[PATCH 0/7] docs/abi: align userspace documentation with implementation

[PATCH 0/7] docs/abi: align userspace documentation with implementation

[Iván Ezequiel Rodriguez]

Documentation and ABI alignment fixes found on v7.3-rc1 by comparing
userspace-api docs, kernel-doc blocks, and uapi headers against the
current implementation.

Patches 1-6 are documentation only. Patch 7 makes GPIO v2 return
-EOPNOTSUPP when EVENT_CLOCK_HTE is requested but no HTE provider is
available, matching the documented behaviour.

No functional ABI changes are intended beyond the GPIO errno correction.

Iván Ezequiel Rodriguez (7):
  docs: futex2: fix documented errno names for futex_waitv
  docs: landlock: fix ENOMSG condition in create_ruleset kernel-doc
  docs: gpio: note lineinfo padding must be zero filled
  docs: dma-buf-heaps: fix CMA heap name typo
  docs: vduse: align documentation with current uapi and driver
  docs: ioctl: fix stale NVMe registry entry and note N conflict
  gpio: cdev: return EOPNOTSUPP when HTE is unavailable

 Documentation/userspace-api/dma-buf-heaps.rst |  2 +-
 Documentation/userspace-api/futex2.rst        |  4 +--
 .../userspace-api/ioctl/ioctl-number.rst      |  5 +--
 Documentation/userspace-api/vduse.rst         | 33 ++++++++++++-------
 drivers/gpio/gpiolib-cdev.c                   |  2 ++
 include/uapi/linux/gpio.h                     |  2 +-
 security/landlock/syscalls.c                  |  2 +-
 7 files changed, 31 insertions(+), 19 deletions(-)

-- 
2.43.0

[PATCH 1/7] docs: futex2: fix documented errno names for futex_waitv

[Iván Ezequiel Rodriguez]

The documentation cited -EAGAIN and -ETIMEOUT, but futex_waitv()
returns -EWOULDBLOCK on value mismatch and -ETIMEDOUT when the
timeout expires, per kernel/futex/waitwake.c.

Signed-off-by: Iván Ezequiel Rodriguez <ivanrwcm25@gmail.com>
---
 Documentation/userspace-api/futex2.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/userspace-api/futex2.rst b/Documentation/userspace-api/futex2.rst
index 9693f47a7e62..615616305c57 100644
--- a/Documentation/userspace-api/futex2.rst
+++ b/Documentation/userspace-api/futex2.rst
@@ -51,10 +51,10 @@ future extension.
 
 For each entry in ``waiters`` array, the current value at ``uaddr`` is compared
 to ``val``. If it's different, the syscall undo all the work done so far and
-return ``-EAGAIN``. If all tests and verifications succeeds, syscall waits until
+return ``-EWOULDBLOCK``. If all tests and verifications succeeds, syscall waits until
 one of the following happens:
 
-- The timeout expires, returning ``-ETIMEOUT``.
+- The timeout expires, returning ``-ETIMEDOUT``.
 - A signal was sent to the sleeping task, returning ``-ERESTARTSYS``.
 - Some futex at the list was woken, returning the index of some waked futex.
 
-- 
2.43.0

[PATCH 2/7] docs: landlock: fix ENOMSG condition in create_ruleset kernel-doc

[Iván Ezequiel Rodriguez]

The kernel-doc stated ENOMSG applies when handled_access_fs is empty,
but landlock_create_ruleset() returns ENOMSG only when handled_access_fs,
handled_access_net, and scoped are all zero.

Signed-off-by: Iván Ezequiel Rodriguez <ivanrwcm25@gmail.com>
---
 security/landlock/syscalls.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/security/landlock/syscalls.c b/security/landlock/syscalls.c
index 1d02d57f4c48..400a2f928de3 100644
--- a/security/landlock/syscalls.c
+++ b/security/landlock/syscalls.c
@@ -204,7 +204,7 @@ const int landlock_abi_version = 11;
  *   scoped;
  * - %E2BIG: @attr or @size inconsistencies;
  * - %EFAULT: @attr or @size inconsistencies;
- * - %ENOMSG: empty &landlock_ruleset_attr.handled_access_fs.
+ * - %ENOMSG: empty handled_access_fs, handled_access_net, and scoped fields.
  *
  * .. kernel-doc:: include/uapi/linux/landlock.h
  *     :identifiers: landlock_create_ruleset_flags
-- 
2.43.0

[PATCH 3/7] docs: gpio: note lineinfo padding must be zero filled

[Iván Ezequiel Rodriguez]

GPIO_V2_GET_LINEINFO_IOCTL and GPIO_V2_GET_LINEINFO_WATCH_IOCTL reject
non-zero lineinfo.padding with -EINVAL; align the uapi comment with
gpio_v2_line_request.padding.

Signed-off-by: Iván Ezequiel Rodriguez <ivanrwcm25@gmail.com>
---
 include/uapi/linux/gpio.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/uapi/linux/gpio.h b/include/uapi/linux/gpio.h
index f7cb8ae87df7..5515b718886e 100644
--- a/include/uapi/linux/gpio.h
+++ b/include/uapi/linux/gpio.h
@@ -218,7 +218,7 @@ struct gpio_v2_line_request {
  * gpio_v2_line_flag, such as %GPIO_V2_LINE_FLAG_ACTIVE_LOW,
  * %GPIO_V2_LINE_FLAG_OUTPUT etc, added together
  * @attrs: the configuration attributes associated with the line
- * @padding: reserved for future use
+ * @padding: reserved for future use, must be zero filled
  */
 struct gpio_v2_line_info {
 	char name[GPIO_MAX_NAME_SIZE];
-- 
2.43.0

Re: [PATCH 3/7] docs: gpio: note lineinfo padding must be zero filled

[Bartosz Golaszewski]

On Mon, 31 Aug 2026 16:31:21 +0200, "Iván Ezequiel Rodriguez"
<ivanrwcm25@gmail.com> said:
> GPIO_V2_GET_LINEINFO_IOCTL and GPIO_V2_GET_LINEINFO_WATCH_IOCTL reject
> non-zero lineinfo.padding with -EINVAL; align the uapi comment with
> gpio_v2_line_request.padding.
>
> Signed-off-by: Iván Ezequiel Rodriguez <ivanrwcm25@gmail.com>
> ---
>  include/uapi/linux/gpio.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/include/uapi/linux/gpio.h b/include/uapi/linux/gpio.h
> index f7cb8ae87df7..5515b718886e 100644
> --- a/include/uapi/linux/gpio.h
> +++ b/include/uapi/linux/gpio.h
> @@ -218,7 +218,7 @@ struct gpio_v2_line_request {
>   * gpio_v2_line_flag, such as %GPIO_V2_LINE_FLAG_ACTIVE_LOW,
>   * %GPIO_V2_LINE_FLAG_OUTPUT etc, added together
>   * @attrs: the configuration attributes associated with the line
> - * @padding: reserved for future use
> + * @padding: reserved for future use, must be zero filled
>   */
>  struct gpio_v2_line_info {
>  	char name[GPIO_MAX_NAME_SIZE];
> --
> 2.43.0
>
>

Reviewed-by: Bartosz Golaszewski <bartosz.golaszewski@oss.qualcomm.com>

[PATCH 4/7] docs: dma-buf-heaps: fix CMA heap name typo

[Iván Ezequiel Rodriguez]

Line 39 used default-cma-region with hyphens; the registered heap name
is default_cma_region, already named correctly at line 26.

Signed-off-by: Iván Ezequiel Rodriguez <ivanrwcm25@gmail.com>
---
 Documentation/userspace-api/dma-buf-heaps.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/userspace-api/dma-buf-heaps.rst b/Documentation/userspace-api/dma-buf-heaps.rst
index f56b743cdb36..92099188893e 100644
--- a/Documentation/userspace-api/dma-buf-heaps.rst
+++ b/Documentation/userspace-api/dma-buf-heaps.rst
@@ -36,7 +36,7 @@ following heaps:
  - A heap will be created for each reusable region in the device tree
    with the ``shared-dma-pool`` compatible, using the full device tree
    node name as its name. The buffer semantics are identical to
-   ``default-cma-region``.
+   ``default_cma_region``.
 
 Naming Convention
 =================
-- 
2.43.0

[PATCH 5/7] docs: vduse: align documentation with current uapi and driver

[Iván Ezequiel Rodriguez]

Update supported device IDs (block, net, fs), all six read/write message
types, the VDUSE_VQ_INJECT_IRQ ioctl name, and VQ_SETUP group vs asid
usage per include/uapi/linux/vduse.h.

Signed-off-by: Iván Ezequiel Rodriguez <ivanrwcm25@gmail.com>
---
 Documentation/userspace-api/vduse.rst | 33 +++++++++++++++++----------
 1 file changed, 21 insertions(+), 12 deletions(-)

diff --git a/Documentation/userspace-api/vduse.rst b/Documentation/userspace-api/vduse.rst
index 81479d47c8b9..d316857ca5bd 100644
--- a/Documentation/userspace-api/vduse.rst
+++ b/Documentation/userspace-api/vduse.rst
@@ -11,11 +11,10 @@ to make the device emulation more secure, the emulated vDPA device's
 control path is handled in the kernel and only the data path is
 implemented in the userspace.
 
-Note that only virtio block device is supported by VDUSE framework now,
-which can reduce security risks when the userspace process that implements
-the data path is run by an unprivileged user. The support for other device
-types can be added after the security issue of corresponding device driver
-is clarified or fixed in the future.
+Note that virtio block, network, and filesystem device types are supported
+by the VDUSE framework. Other device types may be added after the security
+implications of the corresponding device driver are clarified or fixed in
+the future.
 
 Create/Destroy VDUSE devices
 ----------------------------
@@ -135,7 +134,8 @@ module as follows:
 		return 0;
 	}
 
-There are now three types of messages introduced by VDUSE framework:
+The following control message types may be delivered via read(2) on
+/dev/vduse/$NAME:
 
 - VDUSE_GET_VQ_STATE: Get the state for virtqueue, userspace should return
   avail index for split virtqueue or the device/driver ring wrap counters and
@@ -151,6 +151,15 @@ There are now three types of messages introduced by VDUSE framework:
   IOVA range, userspace should firstly remove the old mapping, then setup the new
   mapping via the VDUSE_IOTLB_GET_FD ioctl.
 
+- VDUSE_SET_VQ_GROUP_ASID: Notify userspace to change the address space of a
+  virtqueue group (API version 1).
+
+- VDUSE_SET_VQ_READY: Notify userspace that a virtqueue should become ready or
+  not ready (when VDUSE_F_QUEUE_READY is negotiated).
+
+- VDUSE_SUSPEND: Notify userspace that the device is being suspended (when
+  VDUSE_F_SUSPEND is negotiated).
+
 After DRIVER_OK status bit is set via the VDUSE_SET_STATUS message, userspace is
 able to start the dataplane processing as follows:
 
@@ -227,7 +236,7 @@ able to start the dataplane processing as follows:
    described by the descriptors in the descriptor table should be also mapped into
    userspace via the VDUSE_IOTLB_GET_FD ioctl before accessing.
 
-5. Inject an interrupt for specific virtqueue with the VDUSE_INJECT_VQ_IRQ ioctl
+5. Inject an interrupt for specific virtqueue with the VDUSE_VQ_INJECT_IRQ ioctl
    after the used ring is filled.
 
 Enabling ASID (API version 1)
@@ -238,11 +247,11 @@ version 1. Set it up with ioctl(VDUSE_SET_API_VERSION) on `/dev/vduse/control`
 and pass `VDUSE_API_VERSION_1` before creating a new VDUSE instance with
 ioctl(VDUSE_CREATE_DEV).
 
-Afterwards, you can use the member asid of ioctl(VDUSE_VQ_SETUP) argument to
-select the address space of the IOTLB you are querying.  The driver could
-change the address space of any virtqueue group by using the
-VDUSE_SET_VQ_GROUP_ASID VDUSE message type, and the VDUSE instance needs to
-reply with VDUSE_REQ_RESULT_OK if it was possible to change it.
+Afterwards, ioctl(VDUSE_VQ_SETUP) takes a virtqueue group index in
+struct vduse_vq_config::group.  The driver can change the address space
+of any virtqueue group by using the VDUSE_SET_VQ_GROUP_ASID message type,
+and the VDUSE instance needs to reply with VDUSE_REQ_RESULT_OK if it was
+possible to change it.
 
 Similarly, you can use ioctl(VDUSE_IOTLB_GET_FD2) to obtain the file descriptor
 describing an IOVA region of a specific ASID. Example usage:
-- 
2.43.0

[PATCH 6/7] docs: ioctl: fix stale NVMe registry entry and note N conflict

[Iván Ezequiel Rodriguez]

The NVMe row pointed at drivers/block/nvme.c, which no longer exists,
and ioctl numbers 0x80-0x83 overlap between ntsync.h and nvme_ioctl.h
without a conflict! marker.

Signed-off-by: Iván Ezequiel Rodriguez <ivanrwcm25@gmail.com>
---
 Documentation/userspace-api/ioctl/ioctl-number.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst
index 2fc53093752d..bb7004e6043d 100644
--- a/Documentation/userspace-api/ioctl/ioctl-number.rst
+++ b/Documentation/userspace-api/ioctl/ioctl-number.rst
@@ -181,8 +181,9 @@ Code  Seq#    Include File                                             Comments
 'M'   01-03  drivers/scsi/megaraid/megaraid_sas.h
 'M'   00-0F  drivers/video/fsl-diu-fb.h                                conflict!
 'N'   00-1F  drivers/usb/scanner.h
-'N'   40-7F  drivers/block/nvme.c
-'N'   80-8F  uapi/linux/ntsync.h                                       NT synchronization primitives
+'N'   40-7F  uapi/linux/nvme_ioctl.h
+'N'   80-83  uapi/linux/ntsync.h and uapi/linux/nvme_ioctl.h           conflict!
+'N'   84-8F  uapi/linux/ntsync.h                                       NT synchronization primitives
                                                                        <mailto:wine-devel@winehq.org>
 'O'   00-06  mtd/ubi-user.h                                            UBI
 'P'   all    linux/soundcard.h                                         conflict!
-- 
2.43.0

[PATCH 7/7] gpio: cdev: return EOPNOTSUPP when HTE is unavailable

[Iván Ezequiel Rodriguez]

GPIO v2 documentation promises -EOPNOTSUPP when
GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE is requested without HTE hardware;
map -ENODEV from hte_ts_get() in the HTE-only edge setup path.

Signed-off-by: Iván Ezequiel Rodriguez <ivanrwcm25@gmail.com>
---
 drivers/gpio/gpiolib-cdev.c | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/drivers/gpio/gpiolib-cdev.c b/drivers/gpio/gpiolib-cdev.c
index 9f3b628d5793..6dc01f7ea838 100644
--- a/drivers/gpio/gpiolib-cdev.c
+++ b/drivers/gpio/gpiolib-cdev.c
@@ -715,6 +715,8 @@ static int hte_edge_setup(struct line *line, u64 eflags)
 			   line->desc);
 
 	ret = hte_ts_get(NULL, hdesc, 0);
+	if (ret == -ENODEV)
+		return -EOPNOTSUPP;
 	if (ret)
 		return ret;
 
-- 
2.43.0

Re: [PATCH 0/7] docs/abi: align userspace documentation with implementation

[Bartosz Golaszewski]

On Mon, 31 Aug 2026 16:31:18 +0200, "Iván Ezequiel Rodriguez"
<ivanrwcm25@gmail.com> said:
> Documentation and ABI alignment fixes found on v7.3-rc1 by comparing
> userspace-api docs, kernel-doc blocks, and uapi headers against the
> current implementation.
>
> Patches 1-6 are documentation only. Patch 7 makes GPIO v2 return
> -EOPNOTSUPP when EVENT_CLOCK_HTE is requested but no HTE provider is
> available, matching the documented behaviour.
>

I suppose the separate series you sent after is the one I should be looking at?

Bartosz