From: bot+bpf-ci@kernel.org
To: jarkko@kernel.org,linux-fsdevel@vger.kernel.org
Cc: jarkko@kernel.org,bpf@vger.kernel.org,containers@lists.linux.dev,linux-api@vger.kernel.org,linux-arch@vger.kernel.org,linux-doc@vger.kernel.org,linux-kernel@vger.kernel.org,linux-kselftest@vger.kernel.org,linux-mm@kvack.org,linux-security-module@vger.kernel.org,aleksa@amutable.com,alex@amutable.com,viro@zeniv.linux.org.uk,luto@amacapital.net,arnd@arndb.de,brauner@kernel.org,dhowells@redhat.com,giuseppe@scrivano.org,hughd@google.com,jack@suse.cz,jlayton@kernel.org,corbet@lwn.net,josef@toxicpanda.com,kees@kernel.org,kpsingh@kernel.org,lennart@poettering.net,neal@gompa.dev,oleg@redhat.com,paul@paul-moore.com,ptikhomirov@virtuozzo.com,sergeh@kernel.org,skhan@linuxfoundation.org,zygmunt.krynicki@canonical.com,ast@kernel.org,andrii@kernel.org,daniel@iogearbox.net,martin.lau@kernel.org,eddyz87@gmail.com,yonghong.song@linux.dev,mason@kernel.org,ihor.solodrai@linux.dev
Subject: Re: [RFC PATCH v6 24/26] docs: Document userland uAPI
Date: Sun, 22 Nov 2026 01:56:56 +0000 (UTC) [thread overview]
Message-ID: <99f64593ccffc93d735505cff682eecae40a6671b80ad7485c078ff8f335a214@mail.kernel.org> (raw)
In-Reply-To: <20261122011809.2667684-25-jarkko@kernel.org>
[-- Attachment #1: Type: text/plain, Size: 3452 bytes --]
> 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@kernel.org>
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
next prev parent reply other threads:[~2026-11-22 1:56 UTC|newest]
Thread overview: 41+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-22 1:17 [RFC PATCH v6 00/26] userland: Userland containers Jarkko Sakkinen
2026-11-22 1:17 ` [RFC PATCH v6 01/26] userns: Factor out idmap validation and commit helpers Jarkko Sakkinen
2026-11-22 1:57 ` bot+bpf-ci
2026-11-22 1:17 ` [RFC PATCH v6 02/26] userns: Add userns_set_idmap() system call Jarkko Sakkinen
2026-11-22 2:13 ` bot+bpf-ci
2026-11-22 1:17 ` [RFC PATCH v6 03/26] arch: Wire up " Jarkko Sakkinen
2026-11-22 1:17 ` [RFC PATCH v6 04/26] mount: Add mnt_ns_get_root() Jarkko Sakkinen
2026-11-22 1:17 ` [RFC PATCH v6 05/26] mount: Enforce mount_too_revealing() for foreign mntns Jarkko Sakkinen
2026-11-22 2:13 ` bot+bpf-ci
2026-11-22 1:17 ` [RFC PATCH v6 06/26] mount: Support MOVE_MOUNT_T_MNTNS in move_mount() Jarkko Sakkinen
2026-11-22 2:14 ` bot+bpf-ci
2026-11-22 1:17 ` [RFC PATCH v6 07/26] mount: Support MOVE_MOUNT_CLONE with MOVE_MOUNT_T_MNTNS Jarkko Sakkinen
2026-11-22 1:17 ` [RFC PATCH v6 08/26] userns: Factor out install_user_ns_cred() Jarkko Sakkinen
2026-11-22 1:17 ` [RFC PATCH v6 09/26] nsproxy: Expose create_new_namespaces() Jarkko Sakkinen
2026-11-22 1:17 ` [RFC PATCH v6 10/26] userland: Add core infrastructure Jarkko Sakkinen
2026-11-22 1:17 ` [RFC PATCH v6 11/26] userland: Track init lifecycle via copy_process() and pid_namespace Jarkko Sakkinen
2026-11-22 2:13 ` bot+bpf-ci
2026-11-22 1:17 ` [RFC PATCH v6 12/26] userland: Add userland_open() system call Jarkko Sakkinen
2026-11-22 2:13 ` bot+bpf-ci
2026-11-22 1:17 ` [RFC PATCH v6 13/26] userland: Add USERLAND_GET_NSFD ioctl Jarkko Sakkinen
2026-11-22 2:13 ` bot+bpf-ci
2026-11-22 1:17 ` [RFC PATCH v6 14/26] userland: Add USERLAND_SHARE_NSFD ioctl Jarkko Sakkinen
2026-11-22 1:17 ` [RFC PATCH v6 15/26] exit: Support P_USERLAND in waitid() Jarkko Sakkinen
2026-11-22 2:13 ` bot+bpf-ci
2026-11-22 1:17 ` [RFC PATCH v6 16/26] signal: Support userland fds in pidfd_send_signal() Jarkko Sakkinen
2026-11-22 2:13 ` bot+bpf-ci
2026-11-22 1:18 ` [RFC PATCH v6 17/26] fork: Support CLONE_INTO_USERLAND in clone3() Jarkko Sakkinen
2026-11-22 2:14 ` bot+bpf-ci
2026-11-22 1:18 ` [RFC PATCH v6 18/26] fs: Support FSCONFIG_SET_USERLAND in fsconfig() Jarkko Sakkinen
2026-11-22 2:13 ` bot+bpf-ci
2026-11-22 1:18 ` [RFC PATCH v6 19/26] proc: Implement ->set_userland() fs_context operation Jarkko Sakkinen
2026-11-22 1:18 ` [RFC PATCH v6 20/26] ipc/mqueue: " Jarkko Sakkinen
2026-11-22 1:18 ` [RFC PATCH v6 21/26] security: Add userland LSM hooks Jarkko Sakkinen
2026-11-22 1:18 ` [RFC PATCH v6 22/26] bpf: Register " Jarkko Sakkinen
2026-11-22 1:18 ` [RFC PATCH v6 23/26] arch: Wire up userland_open() system call Jarkko Sakkinen
2026-11-22 1:18 ` [RFC PATCH v6 24/26] docs: Document userland uAPI Jarkko Sakkinen
2026-11-22 1:56 ` bot+bpf-ci [this message]
2026-11-22 1:18 ` [RFC PATCH v6 25/26] selftests/userland: Add userland test suite Jarkko Sakkinen
2026-11-22 2:14 ` bot+bpf-ci
2026-11-22 1:18 ` [RFC PATCH v6 26/26] MAINTAINERS: Add entry for USERLAND Jarkko Sakkinen
2026-11-22 1:58 ` [RFC PATCH v6 00/26] userland: Userland containers Jarkko Sakkinen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=99f64593ccffc93d735505cff682eecae40a6671b80ad7485c078ff8f335a214@mail.kernel.org \
--to=bot+bpf-ci@kernel.org \
--cc=aleksa@amutable.com \
--cc=alex@amutable.com \
--cc=andrii@kernel.org \
--cc=arnd@arndb.de \
--cc=ast@kernel.org \
--cc=bpf@vger.kernel.org \
--cc=brauner@kernel.org \
--cc=containers@lists.linux.dev \
--cc=corbet@lwn.net \
--cc=daniel@iogearbox.net \
--cc=dhowells@redhat.com \
--cc=eddyz87@gmail.com \
--cc=giuseppe@scrivano.org \
--cc=hughd@google.com \
--cc=ihor.solodrai@linux.dev \
--cc=jack@suse.cz \
--cc=jarkko@kernel.org \
--cc=jlayton@kernel.org \
--cc=josef@toxicpanda.com \
--cc=kees@kernel.org \
--cc=kpsingh@kernel.org \
--cc=lennart@poettering.net \
--cc=linux-api@vger.kernel.org \
--cc=linux-arch@vger.kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-kselftest@vger.kernel.org \
--cc=linux-mm@kvack.org \
--cc=linux-security-module@vger.kernel.org \
--cc=luto@amacapital.net \
--cc=martin.lau@kernel.org \
--cc=mason@kernel.org \
--cc=neal@gompa.dev \
--cc=oleg@redhat.com \
--cc=paul@paul-moore.com \
--cc=ptikhomirov@virtuozzo.com \
--cc=sergeh@kernel.org \
--cc=skhan@linuxfoundation.org \
--cc=viro@zeniv.linux.org.uk \
--cc=yonghong.song@linux.dev \
--cc=zygmunt.krynicki@canonical.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®