mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: Jarkko Sakkinen <jarkko@kernel.org>
To: linux-fsdevel@vger.kernel.org
Cc: Jarkko Sakkinen <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 Sarai <aleksa@amutable.com>,
	Alexander Mikhalitsyn <alex@amutable.com>,
	Alexander Viro <viro@zeniv.linux.org.uk>,
	Andy Lutomirski <luto@amacapital.net>,
	Arnd Bergmann <arnd@arndb.de>,
	Christian Brauner <brauner@kernel.org>,
	David Howells <dhowells@redhat.com>,
	Eric Biggers <ebiggers@kernel.org>,
	Giuseppe Scrivano <giuseppe@scrivano.org>,
	Hugh Dickins <hughd@google.com>, Jan Kara <jack@suse.cz>,
	Jeff Layton <jlayton@kernel.org>,
	Jonathan Corbet <corbet@lwn.net>,
	Josef Bacik <josef@toxicpanda.com>, Kees Cook <kees@kernel.org>,
	KP Singh <kpsingh@kernel.org>,
	Lennart Poettering <lennart@poettering.net>,
	Neal Gompa <neal@gompa.dev>, Oleg Nesterov <oleg@redhat.com>,
	Paul Moore <paul@paul-moore.com>,
	Pavel Tikhomirov <ptikhomirov@virtuozzo.com>,
	Serge Hallyn <sergeh@kernel.org>,
	Shuah Khan <skhan@linuxfoundation.org>,
	Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
Subject: [RFC PATCH v7 24/26] docs: Document userland uAPI
Date: Sun, 22 Nov 2026 21:35:37 +0200	[thread overview]
Message-ID: <20261122193539.3334213-25-jarkko@kernel.org> (raw)
In-Reply-To: <20261122193539.3334213-1-jarkko@kernel.org>

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 including the kernel-doc
sections, type definitions, ioctl descriptions, and system call
reference from include/linux/userland.h, include/uapi/linux/userland.h,
include/uapi/linux/nsfs.h, kernel/userland.c, kernel/user_namespace.c,
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>
---
 Documentation/userspace-api/index.rst         |  1 +
 .../userspace-api/ioctl/ioctl-number.rst      |  1 +
 Documentation/userspace-api/userland.rst      | 77 +++++++++++++++++++
 3 files changed, 79 insertions(+)
 create mode 100644 Documentation/userspace-api/userland.rst

diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst
index a68b1bea57a8..ac665b8fea72 100644
--- a/Documentation/userspace-api/index.rst
+++ b/Documentation/userspace-api/index.rst
@@ -17,6 +17,7 @@ System calls
    :maxdepth: 1
 
    unshare
+   userland
    futex2
    ebpf/index
    ioctl/index
diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst
index dbe462040999..4cf194e7b648 100644
--- a/Documentation/userspace-api/ioctl/ioctl-number.rst
+++ b/Documentation/userspace-api/ioctl/ioctl-number.rst
@@ -385,6 +385,7 @@ Code  Seq#    Include File                                             Comments
 0xB8  01-02  uapi/misc/mrvl_cn10k_dpi.h                                Marvell CN10K DPI driver
 0xB8  all    uapi/linux/mshv.h                                         Microsoft Hyper-V /dev/mshv driver
                                                                        <mailto:linux-hyperv@vger.kernel.org>
+0xB9  00-0F  uapi/linux/userland.h                                     userland uAPI
 0xBA  00-0F  uapi/linux/liveupdate.h                                   Pasha Tatashin
                                                                        <mailto:pasha.tatashin@soleen.com>
 0xC0  00-0F  linux/usb/iowarrior.h
diff --git a/Documentation/userspace-api/userland.rst b/Documentation/userspace-api/userland.rst
new file mode 100644
index 000000000000..e32ea3501472
--- /dev/null
+++ b/Documentation/userspace-api/userland.rst
@@ -0,0 +1,77 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============
+userland uAPI
+=============
+
+Overview
+========
+
+.. kernel-doc:: kernel/userland.c
+   :doc: Overview
+
+Lifecycle
+=========
+
+.. kernel-doc:: include/linux/userland.h
+   :identifiers: userland_state
+
+Flags
+=====
+
+.. kernel-doc:: include/uapi/linux/userland.h
+   :identifiers: userland_flags
+
+Ioctls
+======
+
+.. kernel-doc:: include/uapi/linux/userland.h
+   :doc: USERLAND_GET_NSFD
+
+.. kernel-doc:: include/uapi/linux/userland.h
+   :doc: USERLAND_SHARE_NSFD
+
+System calls
+============
+
+.. kernel-doc:: kernel/userland.c
+   :identifiers: sys_userland_open
+
+Process creation
+================
+
+.. kernel-doc:: kernel/userland.c
+   :doc: CLONE_INTO_USERLAND
+
+Process waiting
+===============
+
+.. kernel-doc:: kernel/userland.c
+   :doc: P_USERLAND
+
+Signal delivery
+===============
+
+.. kernel-doc:: kernel/userland.c
+   :doc: pidfd_send_signal
+
+Filesystem configuration
+========================
+
+.. kernel-doc:: fs/fsopen.c
+   :doc: FSCONFIG_SET_USERLAND
+
+Mount tree installation
+=======================
+
+.. kernel-doc:: fs/namespace.c
+   :doc: MOVE_MOUNT_T_MNTNS
+
+User namespace ID mapping
+=========================
+
+.. kernel-doc:: include/uapi/linux/nsfs.h
+   :identifiers: userns_idmap_extent userns_flags userns_idmap
+
+.. kernel-doc:: kernel/user_namespace.c
+   :identifiers: sys_userns_set_idmap
-- 
2.47.3


  parent reply	other threads:[~2026-11-22 19:37 UTC|newest]

Thread overview: 34+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-22 19:35 [RFC PATCH v7 00/26] userland: Userland containers Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 01/26] userns: Factor out idmap validation and commit helpers Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 02/26] userns: Add userns_set_idmap() system call Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 03/26] arch: Wire up " Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 04/26] mount: Add mnt_ns_get_root() Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 05/26] mount: Enforce mount_too_revealing() for foreign mntns Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 06/26] mount: Support MOVE_MOUNT_T_MNTNS in move_mount() Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 07/26] mount: Support MOVE_MOUNT_CLONE with MOVE_MOUNT_T_MNTNS Jarkko Sakkinen
2026-11-22 20:28   ` bot+bpf-ci
2026-11-22 19:35 ` [RFC PATCH v7 08/26] userns: Factor out install_user_ns_cred() Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 09/26] nsproxy: Expose create_new_namespaces() Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 10/26] userland: Add core infrastructure Jarkko Sakkinen
2026-11-22 20:28   ` bot+bpf-ci
2026-11-22 19:35 ` [RFC PATCH v7 11/26] userland: Track init lifecycle via copy_process() and pid_namespace Jarkko Sakkinen
2026-11-22 20:09   ` bot+bpf-ci
2026-11-22 19:35 ` [RFC PATCH v7 12/26] userland: Add userland_open() system call Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 13/26] userland: Add USERLAND_GET_NSFD ioctl Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 14/26] userland: Add USERLAND_SHARE_NSFD ioctl Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 15/26] exit: Support P_USERLAND in waitid() Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 16/26] signal: Support userland fds in pidfd_send_signal() Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 17/26] fork: Support CLONE_INTO_USERLAND in clone3() Jarkko Sakkinen
2026-11-22 20:28   ` bot+bpf-ci
2026-11-22 19:35 ` [RFC PATCH v7 18/26] fs: Support FSCONFIG_SET_USERLAND in fsconfig() Jarkko Sakkinen
2026-11-22 20:28   ` bot+bpf-ci
2026-11-22 19:35 ` [RFC PATCH v7 19/26] proc: Implement ->set_userland() fs_context operation Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 20/26] ipc/mqueue: " Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 21/26] security: Add userland LSM hooks Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 22/26] bpf: Register " Jarkko Sakkinen
2026-11-22 19:35 ` [RFC PATCH v7 23/26] arch: Wire up userland_open() system call Jarkko Sakkinen
2026-11-22 19:35 ` Jarkko Sakkinen [this message]
2026-11-22 20:09   ` [RFC PATCH v7 24/26] docs: Document userland uAPI bot+bpf-ci
2026-11-22 19:35 ` [RFC PATCH v7 25/26] selftests/userland: Add userland test suite Jarkko Sakkinen
2026-11-22 20:28   ` bot+bpf-ci
2026-11-22 19:35 ` [RFC PATCH v7 26/26] MAINTAINERS: Add entry for USERLAND 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=20261122193539.3334213-25-jarkko@kernel.org \
    --to=jarkko@kernel.org \
    --cc=aleksa@amutable.com \
    --cc=alex@amutable.com \
    --cc=arnd@arndb.de \
    --cc=bpf@vger.kernel.org \
    --cc=brauner@kernel.org \
    --cc=containers@lists.linux.dev \
    --cc=corbet@lwn.net \
    --cc=dhowells@redhat.com \
    --cc=ebiggers@kernel.org \
    --cc=giuseppe@scrivano.org \
    --cc=hughd@google.com \
    --cc=jack@suse.cz \
    --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=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=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®