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

[Pratyush Yadav <ptyadav@amazon.de>]

On Thu, Mar 06 2025, Randy Dunlap wrote:

> On March 6, 2025 4:57:36 PM PST, Pratyush Yadav <ptyadav@amazon.de> 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 <ptyadav@amazon.de>
>>---
[...]
>>+
>>+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.

[...]

-- 
Regards,
Pratyush Yadav