On Fri, Mar 07 2025, Jonathan Corbet wrote:
> Pratyush Yadav <ptyadav@xxxxxxxxx> 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 <ptyadav@xxxxxxxxx>
>> ---
>> 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@xxxxxxxxxx/
[1] https://web.git.kernel.org/pub/scm/linux/kernel/git/pratyush/linux.git/tree/Documentation/kho?h=kho
--
Regards,
Pratyush Yadav
