On Thu, Mar 06 2025, Randy Dunlap wrote: > On March 6, 2025 4:57:36 PM PST, Pratyush Yadav <ptyadav@xxxxxxxxx> 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@xxxxxxxxx> >>--- [...] >>+ >>+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
