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

On Fri, Mar 07 2025, Jonathan Corbet wrote:

Pratyush Yadav [off-list ref] writes:

quoted

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 <redacted>
---
 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/20250206132754.2596694-10-rppt@kernel.org/ (local)
[1] https://web.git.kernel.org/pub/scm/linux/kernel/git/pratyush/linux.git/tree/Documentation/kho?h=kho

-- 
Regards,
Pratyush Yadav