[RFC,2/5] misc: add documentation for FDBox

Commit Message

Pratyush Yadav March 7, 2025, 12:57 a.m. UTC

With FDBox in place, add documentation that describes what it is and how
it is used, along with its UAPI and in-kernel API.

Since the document refers to KHO, add a reference tag in kho/index.rst.

Signed-off-by: Pratyush Yadav <[e-mail]>
---
 Documentation/filesystems/locking.rst |  21 +++
 Documentation/kho/fdbox.rst           | 224 ++++++++++++++++++++++++++
 Documentation/kho/index.rst           |   3 +
 MAINTAINERS                           |   1 +
 4 files changed, 249 insertions(+)
 create mode 100644 Documentation/kho/fdbox.rst

Comments

Randy Dunlap March 7, 2025, 2:19 a.m. UTC | #1

On March 6, 2025 4:57:36 PM PST, Pratyush Yadav <[e-mail]> wrote:
>With FDBox in place, add documentation that describes what it is and how
>it is used, along with its UAPI and in-kernel API.
>
>Since the document refers to KHO, add a reference tag in kho/index.rst.
>
>Signed-off-by: Pratyush Yadav <[e-mail]>
>---
> Documentation/filesystems/locking.rst |  21 +++
> Documentation/kho/fdbox.rst           | 224 ++++++++++++++++++++++++++
> Documentation/kho/index.rst           |   3 +
> MAINTAINERS                           |   1 +
> 4 files changed, 249 insertions(+)
> create mode 100644 Documentation/kho/fdbox.rst
>
>diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst
>index d20a32b77b60f..5526833faf79a 100644
>--- a/Documentation/filesystems/locking.rst
>+++ b/Documentation/filesystems/locking.rst
>@@ -607,6 +607,27 @@ used. To block changes to file contents via a memory mapping during the
> operation, the filesystem must take mapping->invalidate_lock to coordinate
> with ->page_mkwrite.
> 
>+fdbox_file_ops
>+==============
>+
>+prototypes::
>+
>+	int (*kho_write)(struct fdbox_fd *box_fd, void *fdt);
>+	int (*seal)(struct fdbox *box);
>+	int (*unseal)(struct fdbox *box);
>+
>+
>+locking rules:
>+	all may block
>+
>+==============	==================================================
>+ops		i_rwsem(box_fd->file->f_inode)
>+==============	==================================================
>+kho_write:	exclusive
>+seal:		no
>+unseal:		no
>+==============	==================================================
>+
> dquot_operations
> ================
> 
>diff --git a/Documentation/kho/fdbox.rst b/Documentation/kho/fdbox.rst
>new file mode 100644
>index 0000000000000..44a3f5cdf1efb
>--- /dev/null
>+++ b/Documentation/kho/fdbox.rst
>@@ -0,0 +1,224 @@
>+.. SPDX-License-Identifier: GPL-2.0-or-later
>+
>+===========================
>+File Descriptor Box (FDBox)
>+===========================
>+
>+:Author: Pratyush Yadav
>+
>+Introduction
>+============
>+
>+The File Descriptor Box (FDBox) is a mechanism for userspace to name file
>+descriptors and give them over to the kernel to hold. They can later be
>+retrieved by passing in the same name.
>+
>+The primary purpose of FDBox is to be used with :ref:`kho`. There are many kinds

    many kinds of 

>+anonymous file descriptors in the kernel like memfd, guest_memfd, iommufd, etc.

   etc.,

>+that would be useful to be preserved using KHO. To be able to do that, there
>+needs to be a mechanism to label FDs that allows userspace to set the label
>+before doing KHO and to use the label to map them back after KHO. FDBox achieves
>+that purpose by exposing a miscdevice which exposes ioctls to label and transfer
>+FDs between the kernel and userspace. FDBox is not intended to work with any
>+generic file descriptor. Support for each kind of FDs must be explicitly
>+enabled.
>+
>+FDBox can be enabled by setting the ``CONFIG_FDBOX`` option to ``y``. While the
>+primary purpose of FDBox is to be used with KHO, it does not explicitly require
>+``CONFIG_KEXEC_HANDOVER``, since it can be used without KHO, simply as a way to
>+preserve or transfer FDs when userspace exits.
>+
>+Concepts
>+========
>+
>+Box
>+---
>+
>+The box is a container for FDs. Boxes are identified by their name, which must
>+be unique. Userspace can put FDs in the box using the ``FDBOX_PUT_FD``
>+operation, and take them out of the box using the ``FDBOX_GET_FD`` operation.

Is this ioctl range documented is ioctl-number.rst?
I didn't notice a patch for that.

>+Once all the required FDs are put into the box, it can be sealed to make it
>+ready for shipping. This can be done by the ``FDBOX_SEAL`` operation. The seal
>+operation notifies each FD in the box. If any of the FDs have a dependency on
>+another, this gives them an opportunity to ensure all dependencies are met, or
>+fail the seal if not. Once a box is sealed, no FDs can be added or removed from
>+the box until it is unsealed. Only sealed boxes are transported to a new kernel

What if KHO is not being used?

>+via KHO. The box can be unsealed by the ``FDBOX_UNSEAL`` operation. This is the
>+opposite of seal. It also notifies each FD in the box to ensure all dependencies
>+are met. This can be useful in case some FDs fail to be restored after KHO.
>+
>+Box FD
>+------

I can't tell in my email font, but is each underlinoat least as long as the title above it?

>+
>+The Box FD is a FD that is currently in a box. It is identified by its name,
>+which must be unique in the box it belongs to. The Box FD is created when a FD
>+is put into a box by using the ``FDBOX_PUT_FD`` operation. This operation
>+removes the FD from the calling task. The FD can be restored by passing the
>+unique name to the ``FDBOX_GET_FD`` operation.
>+
>+FDBox control device
>+--------------------
>+
>+This is the ``/dev/fdbox/fdbox`` device. A box can be created using the
>+``FDBOX_CREATE_BOX`` operation on the device. A box can be removed using the
>+``FDBOX_DELETE_BOX`` operation.
>+
>+UAPI
>+====
>+
>+FDBOX_NAME_LEN
>+--------------
>+
>+.. code-block:: c
>+
>+    #define FDBOX_NAME_LEN			256
>+
>+Maximum length of the name of a Box or Box FD.
>+
>+Ioctls on /dev/fdbox/fdbox
>+--------------------------
>+
>+FDBOX_CREATE_BOX
>+~~~~~~~~~~~~~~~~
>+
>+.. code-block:: c
>+
>+    #define FDBOX_CREATE_BOX	_IO(FDBOX_TYPE, FDBOX_BASE + 0)
>+    struct fdbox_create_box {
>+    	__u64 flags;
>+    	__u8 name[FDBOX_NAME_LEN];
>+    };
>+
>+Create a box.
>+
>+After this returns, the box is available at ``/dev/fdbox/<name>``.
>+
>+``name``
>+    The name of the box to be created. Must be unique.
>+
>+``flags``
>+    Flags to the operation. Currently, no flags are defined.
>+
>+Returns:
>+    0 on success, -1 on error, with errno set.
>+
>+FDBOX_DELETE_BOX
>+~~~~~~~~~~~~~~~~
>+
>+.. code-block:: c
>+
>+    #define FDBOX_DELETE_BOX	_IO(FDBOX_TYPE, FDBOX_BASE + 1)
>+    struct fdbox_delete_box {
>+    	__u64 flags;
>+    	__u8 name[FDBOX_NAME_LEN];
>+    };
>+
>+Delete a box.
>+
>+After this returns, the box is no longer available at ``/dev/fdbox/<name>``.
>+
>+``name``
>+    The name of the box to be deleted.
>+
>+``flags``
>+    Flags to the operation. Currently, no flags are defined.
>+
>+Returns:
>+    0 on success, -1 on error, with errno set.
>+
>+Ioctls on /dev/fdbox/<boxname>
>+------------------------------
>+
>+These must be performed on the ``/dev/fdbox/<boxname>`` device.
>+
>+FDBX_PUT_FD
>+~~~~~~~~~~~
>+
>+.. code-block:: c
>+
>+    #define FDBOX_PUT_FD	_IO(FDBOX_TYPE, FDBOX_BASE + 2)
>+    struct fdbox_put_fd {
>+    	__u64 flags;
>+    	__u32 fd;
>+    	__u32 pad;
>+    	__u8 name[FDBOX_NAME_LEN];
>+    };
>+
>+
>+Put FD into the box.
>+
>+After this returns, ``fd`` is removed from the task and can no longer be used by
>+it.
>+
>+``name``
>+    The name of the FD.
>+
>+``fd``
>+    The file descriptor number to be
>+
>+``flags``
>+    Flags to the operation. Currently, no flags are defined.
>+
>+Returns:
>+    0 on success, -1 on error, with errno set.
>+
>+FDBX_GET_FD
>+~~~~~~~~~~~
>+
>+.. code-block:: c
>+
>+    #define FDBOX_GET_FD	_IO(FDBOX_TYPE, FDBOX_BASE + 3)
>+    struct fdbox_get_fd {
>+    	__u64 flags;
>+    	__u8 name[FDBOX_NAME_LEN];
>+    };
>+
>+Get an FD from the box.
>+
>+After this returns, the FD identified by ``name`` is mapped into the task and is
>+available for use.
>+
>+``name``
>+    The name of the FD to get.
>+
>+``flags``
>+    Flags to the operation. Currently, no flags are defined.
>+
>+Returns:
>+    FD number on success, -1 on error with errno set.
>+
>+FDBOX_SEAL
>+~~~~~~~~~~
>+
>+.. code-block:: c
>+
>+    #define FDBOX_SEAL	_IO(FDBOX_TYPE, FDBOX_BASE + 4)
>+
>+Seal the box.
>+
>+Gives the kernel an opportunity to ensure all dependencies are met in the box.
>+After this returns, the box is sealed and FDs can no longer be added or removed
>+from it. A box must be sealed for it to be transported across KHO.
>+
>+Returns:
>+    0 on success, -1 on error with errno set.
>+
>+FDBOX_UNSEAL
>+~~~~~~~~~~~~
>+
>+.. code-block:: c
>+
>+    #define FDBOX_UNSEAL	_IO(FDBOX_TYPE, FDBOX_BASE + 5)
>+
>+Unseal the box.
>+
>+Gives the kernel an opportunity to ensure all dependencies are met in the box,
>+and in case of KHO, no FDs have been lost in transit.
>+
>+Returns:
>+    0 on success, -1 on error with errno set.
>+
>+Kernel functions and structures
>+===============================
>+
>+.. kernel-doc:: include/linux/fdbox.h
>diff --git a/Documentation/kho/index.rst b/Documentation/kho/index.rst
>index 5e7eeeca8520f..051513b956075 100644
>--- a/Documentation/kho/index.rst
>+++ b/Documentation/kho/index.rst
>@@ -1,5 +1,7 @@
> .. SPDX-License-Identifier: GPL-2.0-or-later
> 
>+.. _kho:
>+
> ========================
> Kexec Handover Subsystem
> ========================
>@@ -9,6 +11,7 @@ Kexec Handover Subsystem
> 
>    concepts
>    usage
>+   fdbox
> 
> .. only::  subproject and html
> 
>diff --git a/MAINTAINERS b/MAINTAINERS
>index d329d3e5514c5..135427582e60f 100644
>--- a/MAINTAINERS
>+++ b/MAINTAINERS
>@@ -8866,6 +8866,7 @@ FDBOX
> M:	Pratyush Yadav <[e-mail]>
> L:	[e-mail]
> S:	Maintained
>+F:	Documentation/kho/fdbox.rst
> F:	drivers/misc/fdbox.c
> F:	include/linux/fdbox.h
> F:	include/uapi/linux/fdbox.h


~Randy

Jonathan Corbet March 7, 2025, 2:22 p.m. UTC | #2

Pratyush Yadav <[e-mail]> writes:

> With FDBox in place, add documentation that describes what it is and how
> it is used, along with its UAPI and in-kernel API.
>
> Since the document refers to KHO, add a reference tag in kho/index.rst.
>
> Signed-off-by: Pratyush Yadav <[e-mail]>
> ---
>  Documentation/filesystems/locking.rst |  21 +++
>  Documentation/kho/fdbox.rst           | 224 ++++++++++++++++++++++++++
>  Documentation/kho/index.rst           |   3 +
>  MAINTAINERS                           |   1 +
>  4 files changed, 249 insertions(+)
>  create mode 100644 Documentation/kho/fdbox.rst

Please do not create a new top-level directory under Documentation for
this; your new file belongs in userspace-api/.

From a quick perusal of your documentation:

- You never say what "KHO" is

- Your boxes live in a single global namespace?

- What sort of access control applies to one of these boxes?  What keeps
  me from mucking around inside somebody else's box?

Thanks,

jon

Pratyush Yadav March 7, 2025, 2:51 p.m. UTC | #3

On Fri, Mar 07 2025, Jonathan Corbet wrote:

> Pratyush Yadav <[e-mail]> writes:
>
>> With FDBox in place, add documentation that describes what it is and how
>> it is used, along with its UAPI and in-kernel API.
>>
>> Since the document refers to KHO, add a reference tag in kho/index.rst.
>>
>> Signed-off-by: Pratyush Yadav <[e-mail]>
>> ---
>>  Documentation/filesystems/locking.rst |  21 +++
>>  Documentation/kho/fdbox.rst           | 224 ++++++++++++++++++++++++++
>>  Documentation/kho/index.rst           |   3 +
>>  MAINTAINERS                           |   1 +
>>  4 files changed, 249 insertions(+)
>>  create mode 100644 Documentation/kho/fdbox.rst
>
> Please do not create a new top-level directory under Documentation for
> this; your new file belongs in userspace-api/.

I did not. The top-level directory comes from the KHO patches [0] (not
merged yet). This series is based on top of those. You can find the full
tree here [1].

Since this is closely tied to KHO I found it a good fit for putting it
on KHO's directory. I don't have strong opinions about this so don't
mind moving it elsewhere if you think that is better.

>
> From a quick perusal of your documentation:
>
> - You never say what "KHO" is

fdbox.rst has a reference to Documentation/kho/index.rst which does
explain what Kexec Handover (KHO) means. Due to the ref to the top-level
heading, the rendered text looks like:

>     The primary purpose of FDBox is to be used with Kexec Handover Subsystem.
                    This is a link to kho/index.rst   ^^^^^^^^^^^^^^^^^^^^^^^^

IMO that is enough explanation, and there would be little benefit in
duplicating the explanation for KHO. Do you still think a one or two
line explanation is warranted here?

>
> - Your boxes live in a single global namespace?

Yes. Should they not? FWIW, the boxes are in a global namespace, but
each box has a namespace of its own for naming FDs. All FD names in a
single box should be unique but the same FD name can be used in two
different boxes.

>
> - What sort of access control applies to one of these boxes?  What keeps
>   me from mucking around inside somebody else's box?

For now, none. You need CAP_SYS_ADMIN to be able to muck around with a
box. The current idea is that we only let root use it and if more a fine
grained permission model needed it can be done in userspace, or we can
extend our permission model later.

[0] https://lore.kernel.org/lkml/[e-mail]/
[1] https://web.git.kernel.org/pub/scm/linux/kernel/git/pratyush/linux.git/tree/Documentation/kho?h=kho

Pratyush Yadav March 7, 2025, 3:03 p.m. UTC | #4

On Thu, Mar 06 2025, Randy Dunlap wrote:

> On March 6, 2025 4:57:36 PM PST, Pratyush Yadav <[e-mail]> wrote:
>>With FDBox in place, add documentation that describes what it is and how
>>it is used, along with its UAPI and in-kernel API.
>>
>>Since the document refers to KHO, add a reference tag in kho/index.rst.
>>
>>Signed-off-by: Pratyush Yadav <[e-mail]>
>>---
[...]
>>+
>>+The File Descriptor Box (FDBox) is a mechanism for userspace to name file
>>+descriptors and give them over to the kernel to hold. They can later be
>>+retrieved by passing in the same name.
>>+
>>+The primary purpose of FDBox is to be used with :ref:`kho`. There are many kinds
>
>     many kinds of 
>
>>+anonymous file descriptors in the kernel like memfd, guest_memfd, iommufd, etc.
>
>    etc.,

Thanks, will fix these.

[...]
>>+
>>+Box
>>+---
>>+
>>+The box is a container for FDs. Boxes are identified by their name, which must
>>+be unique. Userspace can put FDs in the box using the ``FDBOX_PUT_FD``
>>+operation, and take them out of the box using the ``FDBOX_GET_FD`` operation.
>
> Is this ioctl range documented is ioctl-number.rst?
> I didn't notice a patch for that.

My bad, missed that.

>
>>+Once all the required FDs are put into the box, it can be sealed to make it
>>+ready for shipping. This can be done by the ``FDBOX_SEAL`` operation. The seal
>>+operation notifies each FD in the box. If any of the FDs have a dependency on
>>+another, this gives them an opportunity to ensure all dependencies are met, or
>>+fail the seal if not. Once a box is sealed, no FDs can be added or removed from
>>+the box until it is unsealed. Only sealed boxes are transported to a new kernel
>
> What if KHO is not being used?

Then the FDs are lost on shutdown.

>
>>+via KHO. The box can be unsealed by the ``FDBOX_UNSEAL`` operation. This is the
>>+opposite of seal. It also notifies each FD in the box to ensure all dependencies
>>+are met. This can be useful in case some FDs fail to be restored after KHO.
>>+
>>+Box FD
>>+------
>
> I can't tell in my email font, but is each underlinoat least as long as the title above it?

They are. I went and double-checked as well. Maybe just something with
your email font.

[...]

Jonathan Corbet March 7, 2025, 3:25 p.m. UTC | #5

Pratyush Yadav <[e-mail]> writes:

> On Fri, Mar 07 2025, Jonathan Corbet wrote:
>
>> Pratyush Yadav <[e-mail]> writes:
>>
>>> With FDBox in place, add documentation that describes what it is and how
>>> it is used, along with its UAPI and in-kernel API.
>>>
>>> Since the document refers to KHO, add a reference tag in kho/index.rst.
>>>
>>> Signed-off-by: Pratyush Yadav <[e-mail]>
>>> ---
>>>  Documentation/filesystems/locking.rst |  21 +++
>>>  Documentation/kho/fdbox.rst           | 224 ++++++++++++++++++++++++++
>>>  Documentation/kho/index.rst           |   3 +
>>>  MAINTAINERS                           |   1 +
>>>  4 files changed, 249 insertions(+)
>>>  create mode 100644 Documentation/kho/fdbox.rst
>>
>> Please do not create a new top-level directory under Documentation for
>> this; your new file belongs in userspace-api/.
>
> I did not. The top-level directory comes from the KHO patches [0] (not
> merged yet). This series is based on top of those. You can find the full
> tree here [1].
>
> Since this is closely tied to KHO I found it a good fit for putting it
> on KHO's directory. I don't have strong opinions about this so don't
> mind moving it elsewhere if you think that is better.

I've not seen the KHO stuff, but I suspect I'll grumble about that too.
Our documentation should be organized for its audience, not for its
authors.  So yes, I think that your documentation of the user-space
interface should definitely go in the userspace-api book.

Thanks,

jon

(Who now realizes he has been arguing this point of view for over ten
years ... eventually it will get across... :)

Pratyush Yadav March 7, 2025, 11:28 p.m. UTC | #6

On Fri, Mar 07 2025, Jonathan Corbet wrote:

> Pratyush Yadav <[e-mail]> writes:
>
>> On Fri, Mar 07 2025, Jonathan Corbet wrote:
>>
>>> Pratyush Yadav <[e-mail]> writes:
>>>
>>>> With FDBox in place, add documentation that describes what it is and how
>>>> it is used, along with its UAPI and in-kernel API.
>>>>
>>>> Since the document refers to KHO, add a reference tag in kho/index.rst.
>>>>
>>>> Signed-off-by: Pratyush Yadav <[e-mail]>
>>>> ---
>>>>  Documentation/filesystems/locking.rst |  21 +++
>>>>  Documentation/kho/fdbox.rst           | 224 ++++++++++++++++++++++++++
>>>>  Documentation/kho/index.rst           |   3 +
>>>>  MAINTAINERS                           |   1 +
>>>>  4 files changed, 249 insertions(+)
>>>>  create mode 100644 Documentation/kho/fdbox.rst
>>>
>>> Please do not create a new top-level directory under Documentation for
>>> this; your new file belongs in userspace-api/.
>>
>> I did not. The top-level directory comes from the KHO patches [0] (not
>> merged yet). This series is based on top of those. You can find the full
>> tree here [1].
>>
>> Since this is closely tied to KHO I found it a good fit for putting it
>> on KHO's directory. I don't have strong opinions about this so don't
>> mind moving it elsewhere if you think that is better.
>
> I've not seen the KHO stuff, but I suspect I'll grumble about that too.
> Our documentation should be organized for its audience, not for its
> authors.  So yes, I think that your documentation of the user-space
> interface should definitely go in the userspace-api book.

Okay, fair enough. I'll move it there.

>
> Thanks,
>
> jon
>
> (Who now realizes he has been arguing this point of view for over ten
> years ... eventually it will get across... :)

Patch

diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst
index d20a32b77b60f..5526833faf79a 100644
--- a/Documentation/filesystems/locking.rst
+++ b/Documentation/filesystems/locking.rst
@@ -607,6 +607,27 @@  used. To block changes to file contents via a memory mapping during the
 operation, the filesystem must take mapping->invalidate_lock to coordinate
 with ->page_mkwrite.
 
+fdbox_file_ops
+==============
+
+prototypes::
+
+	int (*kho_write)(struct fdbox_fd *box_fd, void *fdt);
+	int (*seal)(struct fdbox *box);
+	int (*unseal)(struct fdbox *box);
+
+
+locking rules:
+	all may block
+
+==============	==================================================
+ops		i_rwsem(box_fd->file->f_inode)
+==============	==================================================
+kho_write:	exclusive
+seal:		no
+unseal:		no
+==============	==================================================
+
 dquot_operations
 ================
 
diff --git a/Documentation/kho/fdbox.rst b/Documentation/kho/fdbox.rst
new file mode 100644
index 0000000000000..44a3f5cdf1efb
--- /dev/null
+++ b/Documentation/kho/fdbox.rst
@@ -0,0 +1,224 @@ 
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+===========================
+File Descriptor Box (FDBox)
+===========================
+
+:Author: Pratyush Yadav
+
+Introduction
+============
+
+The File Descriptor Box (FDBox) is a mechanism for userspace to name file
+descriptors and give them over to the kernel to hold. They can later be
+retrieved by passing in the same name.
+
+The primary purpose of FDBox is to be used with :ref:`kho`. There are many kinds
+anonymous file descriptors in the kernel like memfd, guest_memfd, iommufd, etc.
+that would be useful to be preserved using KHO. To be able to do that, there
+needs to be a mechanism to label FDs that allows userspace to set the label
+before doing KHO and to use the label to map them back after KHO. FDBox achieves
+that purpose by exposing a miscdevice which exposes ioctls to label and transfer
+FDs between the kernel and userspace. FDBox is not intended to work with any
+generic file descriptor. Support for each kind of FDs must be explicitly
+enabled.
+
+FDBox can be enabled by setting the ``CONFIG_FDBOX`` option to ``y``. While the
+primary purpose of FDBox is to be used with KHO, it does not explicitly require
+``CONFIG_KEXEC_HANDOVER``, since it can be used without KHO, simply as a way to
+preserve or transfer FDs when userspace exits.
+
+Concepts
+========
+
+Box
+---
+
+The box is a container for FDs. Boxes are identified by their name, which must
+be unique. Userspace can put FDs in the box using the ``FDBOX_PUT_FD``
+operation, and take them out of the box using the ``FDBOX_GET_FD`` operation.
+Once all the required FDs are put into the box, it can be sealed to make it
+ready for shipping. This can be done by the ``FDBOX_SEAL`` operation. The seal
+operation notifies each FD in the box. If any of the FDs have a dependency on
+another, this gives them an opportunity to ensure all dependencies are met, or
+fail the seal if not. Once a box is sealed, no FDs can be added or removed from
+the box until it is unsealed. Only sealed boxes are transported to a new kernel
+via KHO. The box can be unsealed by the ``FDBOX_UNSEAL`` operation. This is the
+opposite of seal. It also notifies each FD in the box to ensure all dependencies
+are met. This can be useful in case some FDs fail to be restored after KHO.
+
+Box FD
+------
+
+The Box FD is a FD that is currently in a box. It is identified by its name,
+which must be unique in the box it belongs to. The Box FD is created when a FD
+is put into a box by using the ``FDBOX_PUT_FD`` operation. This operation
+removes the FD from the calling task. The FD can be restored by passing the
+unique name to the ``FDBOX_GET_FD`` operation.
+
+FDBox control device
+--------------------
+
+This is the ``/dev/fdbox/fdbox`` device. A box can be created using the
+``FDBOX_CREATE_BOX`` operation on the device. A box can be removed using the
+``FDBOX_DELETE_BOX`` operation.
+
+UAPI
+====
+
+FDBOX_NAME_LEN
+--------------
+
+.. code-block:: c
+
+    #define FDBOX_NAME_LEN			256
+
+Maximum length of the name of a Box or Box FD.
+
+Ioctls on /dev/fdbox/fdbox
+--------------------------
+
+FDBOX_CREATE_BOX
+~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+    #define FDBOX_CREATE_BOX	_IO(FDBOX_TYPE, FDBOX_BASE + 0)
+    struct fdbox_create_box {
+    	__u64 flags;
+    	__u8 name[FDBOX_NAME_LEN];
+    };
+
+Create a box.
+
+After this returns, the box is available at ``/dev/fdbox/<name>``.
+
+``name``
+    The name of the box to be created. Must be unique.
+
+``flags``
+    Flags to the operation. Currently, no flags are defined.
+
+Returns:
+    0 on success, -1 on error, with errno set.
+
+FDBOX_DELETE_BOX
+~~~~~~~~~~~~~~~~
+
+.. code-block:: c
+
+    #define FDBOX_DELETE_BOX	_IO(FDBOX_TYPE, FDBOX_BASE + 1)
+    struct fdbox_delete_box {
+    	__u64 flags;
+    	__u8 name[FDBOX_NAME_LEN];
+    };
+
+Delete a box.
+
+After this returns, the box is no longer available at ``/dev/fdbox/<name>``.
+
+``name``
+    The name of the box to be deleted.
+
+``flags``
+    Flags to the operation. Currently, no flags are defined.
+
+Returns:
+    0 on success, -1 on error, with errno set.
+
+Ioctls on /dev/fdbox/<boxname>
+------------------------------
+
+These must be performed on the ``/dev/fdbox/<boxname>`` device.
+
+FDBX_PUT_FD
+~~~~~~~~~~~
+
+.. code-block:: c
+
+    #define FDBOX_PUT_FD	_IO(FDBOX_TYPE, FDBOX_BASE + 2)
+    struct fdbox_put_fd {
+    	__u64 flags;
+    	__u32 fd;
+    	__u32 pad;
+    	__u8 name[FDBOX_NAME_LEN];
+    };
+
+
+Put FD into the box.
+
+After this returns, ``fd`` is removed from the task and can no longer be used by
+it.
+
+``name``
+    The name of the FD.
+
+``fd``
+    The file descriptor number to be
+
+``flags``
+    Flags to the operation. Currently, no flags are defined.
+
+Returns:
+    0 on success, -1 on error, with errno set.
+
+FDBX_GET_FD
+~~~~~~~~~~~
+
+.. code-block:: c
+
+    #define FDBOX_GET_FD	_IO(FDBOX_TYPE, FDBOX_BASE + 3)
+    struct fdbox_get_fd {
+    	__u64 flags;
+    	__u8 name[FDBOX_NAME_LEN];
+    };
+
+Get an FD from the box.
+
+After this returns, the FD identified by ``name`` is mapped into the task and is
+available for use.
+
+``name``
+    The name of the FD to get.
+
+``flags``
+    Flags to the operation. Currently, no flags are defined.
+
+Returns:
+    FD number on success, -1 on error with errno set.
+
+FDBOX_SEAL
+~~~~~~~~~~
+
+.. code-block:: c
+
+    #define FDBOX_SEAL	_IO(FDBOX_TYPE, FDBOX_BASE + 4)
+
+Seal the box.
+
+Gives the kernel an opportunity to ensure all dependencies are met in the box.
+After this returns, the box is sealed and FDs can no longer be added or removed
+from it. A box must be sealed for it to be transported across KHO.
+
+Returns:
+    0 on success, -1 on error with errno set.
+
+FDBOX_UNSEAL
+~~~~~~~~~~~~
+
+.. code-block:: c
+
+    #define FDBOX_UNSEAL	_IO(FDBOX_TYPE, FDBOX_BASE + 5)
+
+Unseal the box.
+
+Gives the kernel an opportunity to ensure all dependencies are met in the box,
+and in case of KHO, no FDs have been lost in transit.
+
+Returns:
+    0 on success, -1 on error with errno set.
+
+Kernel functions and structures
+===============================
+
+.. kernel-doc:: include/linux/fdbox.h
diff --git a/Documentation/kho/index.rst b/Documentation/kho/index.rst
index 5e7eeeca8520f..051513b956075 100644
--- a/Documentation/kho/index.rst
+++ b/Documentation/kho/index.rst
@@ -1,5 +1,7 @@ 
 .. SPDX-License-Identifier: GPL-2.0-or-later
 
+.. _kho:
+
 ========================
 Kexec Handover Subsystem
 ========================
@@ -9,6 +11,7 @@  Kexec Handover Subsystem
 
    concepts
    usage
+   fdbox
 
 .. only::  subproject and html
 
diff --git a/MAINTAINERS b/MAINTAINERS
index d329d3e5514c5..135427582e60f 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8866,6 +8866,7 @@  FDBOX
 M:	Pratyush Yadav <[e-mail]>
 L:	[e-mail]
 S:	Maintained
+F:	Documentation/kho/fdbox.rst
 F:	drivers/misc/fdbox.c
 F:	include/linux/fdbox.h
 F:	include/uapi/linux/fdbox.h