docs/abi: align userspace documentation with implementation
Subsystems (6)
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
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
@@ -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
PATCH 2/7 docs: landlock: fix ENOMSG condition in create_ruleset kernel-doc
In reply to Iván Ezequiel RodriguezThe 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
@@ -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
PATCH 3/7 docs: gpio: note lineinfo padding must be zero filled
In reply to Iván Ezequiel RodriguezGPIO_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
@@ -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
Re: [PATCH 3/7] docs: gpio: note lineinfo padding must be zero filled
Quoted 23 lines · Iván Ezequiel Rodriguez
GPIO_V2_GET_LINEINFO_IOCTLandGPIO_V2_GET_LINEINFO_WATCH_IOCTLreject non-zero lineinfo.padding with-EINVAL; align the uapi comment with gpio_v2_line_request.padding.Signed-off-by Iván Ezequiel Rodriguez <[email protected]>--- include/uapi/linux/gpio.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)include/uapi/linux/gpio.h +1
-2@@ -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
PATCH 4/7 docs: dma-buf-heaps: fix CMA heap name typo
In reply to Iván Ezequiel RodriguezLine 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
@@ -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
PATCH 5/7 docs: vduse: align documentation with current uapi and driver
In reply to Iván Ezequiel RodriguezUpdate 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
@@ -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
Jonathan Corbet
maintainerRe: [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_IRQioctl name, andVQ_SETUPgroup vs asid usage perinclude/uapi/linux/vduse.h.Signed-off-by Iván Ezequiel Rodriguez <[email protected]>--- Documentation/userspace-api/vduse.rst | 33 +++++++++++++++++---------- 1 file changed, 21 insertions(+), 12 deletions(-)Documentation/userspace-api/vduse.rst +0
-0@@ -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
PATCH 6/7 docs: ioctl: fix stale NVMe registry entry and note N conflict
In reply to Iván Ezequiel RodriguezThe 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
@@ -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
PATCH 7/7 gpio: cdev: return EOPNOTSUPP when HTE is unavailable
In reply to Iván Ezequiel RodriguezGPIO 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
@@ -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
Bartosz Golaszewski
maintainerQuoted 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
-EOPNOTSUPPwhenEVENT_CLOCK_HTEis 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
Jonathan Corbet
maintainerQuoted 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
-EOPNOTSUPPwhenEVENT_CLOCK_HTEis 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 forfutex_waitv
docs: landlock: fix ENOMSG condition increate_rulesetkernel-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