Re: [RFC PATCH v6 24/26] docs: Document userland uAPI
From: bot+bpf-ci
Date: Sat Nov 21 2026 - 20:57:06 EST
> docs: Document userland uAPI
TL;DR: Documentation only: the new userland uAPI doc never defines the
INIT/RUNNING/DEAD states or their transitions, so readers can't tell when
USERLAND_SHARE_NSFD is allowed. Commit message also misattributes ioctl docs
to nsfs.h.
> docs: Document userland uAPI
>
> Userspace orchestrators need a clear specification of what a userland
> is, its build and live state transitions, USERLAND_GET_NSFD,
> USERLAND_SHARE_NSFD, waitid(P_USERLAND), pidfd_send_signal(), mount-tree
> construction, user namespace ID mapping, credential rules, and process
> creation semantics.
>
> Add Documentation/userspace-api/userland.rst to include the kernel-doc
> sections, ioctl descriptions, and system call reference from
> kernel/userland.c, kernel/user_namespace.c,
> include/uapi/linux/userland.h, include/uapi/linux/nsfs.h, fs/fsopen.c,
> and fs/namespace.c, and register the userland ioctl magic in
> ioctl-number.rst.
>
> Signed-off-by: Jarkko Sakkinen <jarkko@xxxxxxxxxx>
The message says the ioctl descriptions come from the listed files,
including include/uapi/linux/nsfs.h. Is that accurate?
The only nsfs.h content included by userland.rst is:
.. kernel-doc:: include/uapi/linux/nsfs.h
:identifiers: userns_idmap_extent userns_flags userns_idmap
which documents the structures and enum used by userns_set_idmap(). The
ioctl descriptions (USERLAND_GET_NSFD, USERLAND_SHARE_NSFD) come from
include/uapi/linux/userland.h.
This isn't a bug, but the body paragraphs and the Signed-off-by tag are
also not separated by blank lines in the message as rendered.
> diff --git a/Documentation/userspace-api/userland.rst b/Documentation/userspace-api/userland.rst
> new file mode 100644
> index 000000000000..47d5c39ccb1c
> --- /dev/null
> +++ b/Documentation/userspace-api/userland.rst
> @@ -0,0 +1,73 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=============
> +userland uAPI
> +=============
> +
> +Overview
> +========
> +
> +A userland is an anonymous-inode control object opened by ``userland_open()`` (not
> +an ``nsfs`` namespace) that binds a detached namespace set, an initially empty
> +mount namespace, an owning user namespace, and an init process lifecycle across
> +build (``USERLAND_INIT``) and live (``USERLAND_RUNNING`` / ``USERLAND_DEAD``) phases.
Where are USERLAND_INIT, USERLAND_RUNNING and USERLAND_DEAD defined for
the reader?
These states are not in any uapi header and are only used inside
kernel/userland.c, and no section of this document defines them or the
transitions between them. Yet the included sections rely on them:
USERLAND_SHARE_NSFD works only while userland_fd is in USERLAND_INIT
P_USERLAND waits until USERLAND_DEAD
USERLAND_GET_NSFD for CLONE_NEWPID needs the init to be running
What moves a userland from USERLAND_INIT to USERLAND_RUNNING, and from
USERLAND_RUNNING to USERLAND_DEAD? The commit message promises a
specification of the build and live state transitions and of credential
rules, but the document only has this one-paragraph overview plus the
included kernel-doc, so a userspace reader cannot tell when
USERLAND_SHARE_NSFD is still allowed.
[ ... ]
---
AI reviewed your patch. Please fix the bug or email reply why it's not a bug.
See: https://github.com/kernel-patches/vmtest/blob/master/ci/claude/README.md
CI run summary: https://github.com/kernel-patches/bpf/actions/runs/44972669664