Hi Vincent, On 2026-06-01T13:12:01, Vincent Jardin <[email protected]> wrote: > doc: usage: cmd: load: null-block-device > > Document the dispatch path added by the former commit > > fs: dispatch null_dev_desc_ok filesystems before lookup > > Add a null-block-device interfaces section that: > > * lists the three fstypes that can benefit of it (semihosting, ubifs, > sandbox) and the CONFIG option that builds each > * explains the '-' convention for the unused <dev[:part]> field > > Suggested-by: Simon Glass <[email protected]> > Signed-off-by: Vincent Jardin <[email protected]> > > doc/usage/cmd/load.rst | 37 +++++++++++++++++++++++++++++++++++++ > 1 file changed, 37 insertions(+)
Thanks for doing the docs. A few grammar/doc-level nits below. Reviewed-by: Simon Glass <[email protected]> > diff --git a/doc/usage/cmd/load.rst b/doc/usage/cmd/load.rst > @@ -63,6 +63,43 @@ Example > +Null-block-device interfaces > +---------------------------- > + > +A few `<interface> values do not name their block device. Their > +filesystem implementations call directly a back-end (JTAG > +debugger, UBI volume, host running U-Boot under sandbox, ...) > +and ignore the <dev[:part]> argument. The fstype info table marks > +these with the internal null_dev_desc_ok flag; the dispatcher in > +fs_set_blk_dev() routes them by name before any block-device > +lookup is attempted, so load <iface> - <addr> <filename> works. This is user-facing documentation but is leaning heavily on implementation detail. The user does not need to know the flag name null_dev_desc_ok or fs_set_blk_dev(). Please reword along the lines of "some interfaces have no underlying block device; for these, the dev[:part] field is ignored and may be given as '-'", and drop the references to the internal flag and function. The implementation rationale already lives in patch 1. Also: "call directly a back-end" reads oddly - how about "directly call a back-end". > diff --git a/doc/usage/cmd/load.rst b/doc/usage/cmd/load.rst > @@ -63,6 +63,43 @@ Example > +semihosting > + Read files from the host filesystem of an attached JTAG debugger > + via using the ARM semihosting protocol. Useful with OpenOCD. > + Built when CONFIG_SEMIHOSTING=y. "via using" - pick one, 'using' is enough. > diff --git a/doc/usage/cmd/load.rst b/doc/usage/cmd/load.rst > @@ -63,6 +63,43 @@ Example > +sandbox > + Read files from the host filesystem the sandbox binary is > + running under. Built on a sandbox build (the sandbox fstype > + is registered with name sandbox and null_dev_desc_ok = > + true). The parenthetical exposes table internals again - I suggest dropping it. "Available on sandbox builds" is enough. Regards, Simon
