Skip to contentSkip to conversation

docs/abi: align userspace documentation with implementation

PATCH In review Iván Ezequiel Rodriguez 3 participants 12 messages Aug 31 – Sep 15

Subsystems (6)
lore
Share & tools
lore
#0 lore raw

cover docs/abi: align userspace documentation with implementation

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(-)
Signature · 1 line
2.43.0
#1 lore raw

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

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.

---
 Documentation/userspace-api/futex2.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/userspace-api/futex2.rst +2 -2
index 9693f47a7e62..615616305c57 100644
@@ -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.
 
Signature · 1 line
2.43.0
#2 lore raw

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

In reply to 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.

---
 security/landlock/syscalls.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
security/landlock/syscalls.c +1 -1
index 1d02d57f4c48..400a2f928de3 100644
@@ -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
Signature · 1 line
2.43.0
#3 lore raw

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

In reply to 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.

---
 include/uapi/linux/gpio.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
include/uapi/linux/gpio.h +1 -1
index f7cb8ae87df7..5515b718886e 100644
@@ -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];
Signature · 1 line
2.43.0
maintainer Reviewed-by on v1 3/7
#4 lore raw

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

Quoted 23 lines · 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.

---
 include/uapi/linux/gpio.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
include/uapi/linux/gpio.h +1 -2
index f7cb8ae87df7..5515b718886e 100644
@@ -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];
--
Quoted 3 lines

2.43.0

#5 lore raw

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

In reply to 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.

---
 Documentation/userspace-api/dma-buf-heaps.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/userspace-api/dma-buf-heaps.rst +1 -1
index f56b743cdb36..92099188893e 100644
@@ -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
 =================
Signature · 1 line
2.43.0
#6 lore raw

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

In reply to 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.

---
 Documentation/userspace-api/vduse.rst | 33 +++++++++++++++++----------
 1 file changed, 21 insertions(+), 12 deletions(-)
Documentation/userspace-api/vduse.rst +21 -12
index 81479d47c8b9..d316857ca5bd 100644
@@ -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:
Signature · 1 line
2.43.0
maintainer
#7 lore raw

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

Quoted 16 lines · 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.

---
 Documentation/userspace-api/vduse.rst | 33 +++++++++++++++++----------
 1 file changed, 21 insertions(+), 12 deletions(-)
Documentation/userspace-api/vduse.rst +0 -0
index 81479d47c8b9..d316857ca5bd 100644
@@ -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.

Documentation/userspace-api/vduse.rst to make the device emulation more secure, the emulated vDPA device's · line 17

Quoted 10 lines
Documentation/userspace-api/vduse.rst +4 -5
 
-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.

So that paragraph was somewhat impenetrable before, but I think this change has made it worse. What are "the security implications"? This has the look of a mechanical change that isn't really concerned about what is supposed to be communicated...?

Thanks,

jon

#8 lore raw

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

In reply to 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.

---
 Documentation/userspace-api/ioctl/ioctl-number.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/userspace-api/ioctl/ioctl-number.rst +3 -2
index 2fc53093752d..bb7004e6043d 100644
@@ -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:[email protected]>
 'O'   00-06  mtd/ubi-user.h                                            UBI
 'P'   all    linux/soundcard.h                                         conflict!
Signature · 1 line
2.43.0
#9 lore raw

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

In reply to 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.

---
 drivers/gpio/gpiolib-cdev.c | 2 ++
 1 file changed, 2 insertions(+)
drivers/gpio/gpiolib-cdev.c +2 -0
index 9f3b628d5793..6dc01f7ea838 100644
@@ -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;
 
Signature · 1 line
2.43.0
#10 lore raw
In reply to Iván Ezequiel Rodriguez
Quoted 8 lines · 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.

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

Bartosz

maintainer
#11 lore raw
In reply to Iván Ezequiel Rodriguez
Quoted 10 lines · 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.

Quoted 7 lines

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

I have applied the series...

Quoted 1 line

gpio: cdev: return EOPNOTSUPP when HTE is unavailable

...minus this patch.

Quoted 8 lines
 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(-)

I do have a comment on patch 5 that I'll send separately, though.

Did you write these yourself, or was there an LLM involved? In the latter case, these patches really needed Assisted-by tags as well.

Thanks,

jon