[RFC PATCH 01/24] pidfd: add spawn builder uapi

[Li Chen <me@linux.beauty>]

Define PIDFD_EMPTY, the fsconfig-style configuration command and path
key, and versioned run arguments for pidfd spawn builders. Add the
initial ordered file-action records.

Store userspace pointers in full-width aligned containers on every ABI.
Keep flags and reserved fields zero so later kernels can extend the
structures without changing their initial layout.

Suggested-by: Christian Brauner <brauner@kernel.org>
Assisted-by: Codex:gpt-5.6-sol
Signed-off-by: Li Chen <me@linux.beauty>
---
 MAINTAINERS                            |  2 ++
 include/uapi/linux/pidfd.h             |  1 +
 include/uapi/linux/pidfd_spawn.h       | 49 ++++++++++++++++++++++++++
 tools/include/uapi/linux/pidfd_spawn.h | 49 ++++++++++++++++++++++++++
 4 files changed, 101 insertions(+)
 create mode 100644 include/uapi/linux/pidfd_spawn.h
 create mode 100644 tools/include/uapi/linux/pidfd_spawn.h

diff --git a/MAINTAINERS b/MAINTAINERS
index 8729cea57c3dd..b63bc1ee0171f 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -21287,7 +21287,9 @@ M:	Christian Brauner <christian@brauner.io>
 L:	linux-kernel@vger.kernel.org
 S:	Maintained
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/brauner/linux.git
+F:	include/uapi/linux/pidfd_spawn.h
 F:	samples/pidfd/
+F:	tools/include/uapi/linux/pidfd_spawn.h
 F:	tools/testing/selftests/clone3/
 F:	tools/testing/selftests/pidfd/
 K:	(?i)pidfd
diff --git a/include/uapi/linux/pidfd.h b/include/uapi/linux/pidfd.h
index 0919246a1611c..cad5b722e9f0e 100644
--- a/include/uapi/linux/pidfd.h
+++ b/include/uapi/linux/pidfd.h
@@ -10,6 +10,7 @@
 /* Flags for pidfd_open().  */
 #define PIDFD_NONBLOCK	O_NONBLOCK
 #define PIDFD_THREAD	O_EXCL
+#define PIDFD_EMPTY	(1U << 27)
 #ifdef __KERNEL__
 #include <linux/sched.h>
 #define PIDFD_STALE CLONE_PIDFD
diff --git a/include/uapi/linux/pidfd_spawn.h b/include/uapi/linux/pidfd_spawn.h
new file mode 100644
index 0000000000000..46d61e72435cc
--- /dev/null
+++ b/include/uapi/linux/pidfd_spawn.h
@@ -0,0 +1,49 @@
+/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
+
+#ifndef _UAPI_LINUX_PIDFD_SPAWN_H
+#define _UAPI_LINUX_PIDFD_SPAWN_H
+
+#include <linux/types.h>
+
+#define PIDFD_SPAWN_RUN_SIZE_VER0	64
+#define PIDFD_SPAWN_ACTION_SIZE_VER0	32
+
+/* Commands for pidfd_config(). */
+#define PIDFD_CONFIG_SET_STRING	0
+
+/* String keys for pidfd_config(). */
+#define PIDFD_CONFIG_KEY_PATH	"path"
+
+struct pidfd_spawn_run_args {
+	__u32 flags;
+	__u32 nr_actions;
+	/* The next four fields are full-width userspace virtual addresses. */
+	__aligned_u64 path;
+	__aligned_u64 argv;
+	__aligned_u64 envp;
+	__aligned_u64 actions;
+	__u32 action_size;
+	__u32 reserved0;
+	__u64 reserved[2];
+};
+
+enum pidfd_spawn_action_type {
+	PIDFD_SPAWN_ACTION_DUP2 = 0,
+	PIDFD_SPAWN_ACTION_CLOSE_RANGE = 1,
+	PIDFD_SPAWN_ACTION_FCHDIR = 2,
+};
+
+struct pidfd_spawn_action {
+	__u32 type;
+	__u32 flags;
+	/*
+	 * DUP2 uses fd as the source and newfd as the destination.
+	 * CLOSE_RANGE uses fd as the first and newfd as the last descriptor.
+	 * FCHDIR uses fd as the directory descriptor and requires newfd to be 0.
+	 */
+	__u32 fd;
+	__u32 newfd;
+	__u64 reserved[2];
+};
+
+#endif /* _UAPI_LINUX_PIDFD_SPAWN_H */
diff --git a/tools/include/uapi/linux/pidfd_spawn.h b/tools/include/uapi/linux/pidfd_spawn.h
new file mode 100644
index 0000000000000..46d61e72435cc
--- /dev/null
+++ b/tools/include/uapi/linux/pidfd_spawn.h
@@ -0,0 +1,49 @@
+/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
+
+#ifndef _UAPI_LINUX_PIDFD_SPAWN_H
+#define _UAPI_LINUX_PIDFD_SPAWN_H
+
+#include <linux/types.h>
+
+#define PIDFD_SPAWN_RUN_SIZE_VER0	64
+#define PIDFD_SPAWN_ACTION_SIZE_VER0	32
+
+/* Commands for pidfd_config(). */
+#define PIDFD_CONFIG_SET_STRING	0
+
+/* String keys for pidfd_config(). */
+#define PIDFD_CONFIG_KEY_PATH	"path"
+
+struct pidfd_spawn_run_args {
+	__u32 flags;
+	__u32 nr_actions;
+	/* The next four fields are full-width userspace virtual addresses. */
+	__aligned_u64 path;
+	__aligned_u64 argv;
+	__aligned_u64 envp;
+	__aligned_u64 actions;
+	__u32 action_size;
+	__u32 reserved0;
+	__u64 reserved[2];
+};
+
+enum pidfd_spawn_action_type {
+	PIDFD_SPAWN_ACTION_DUP2 = 0,
+	PIDFD_SPAWN_ACTION_CLOSE_RANGE = 1,
+	PIDFD_SPAWN_ACTION_FCHDIR = 2,
+};
+
+struct pidfd_spawn_action {
+	__u32 type;
+	__u32 flags;
+	/*
+	 * DUP2 uses fd as the source and newfd as the destination.
+	 * CLOSE_RANGE uses fd as the first and newfd as the last descriptor.
+	 * FCHDIR uses fd as the directory descriptor and requires newfd to be 0.
+	 */
+	__u32 fd;
+	__u32 newfd;
+	__u64 reserved[2];
+};
+
+#endif /* _UAPI_LINUX_PIDFD_SPAWN_H */
-- 
2.52.0