[PATCH v3 2/3] doc: usage: cmd: load: null-block-device

[Simon Glass]

Hi Vincent,

On 2026-06-01T13:12:01, Vincent Jardin <vjardin at free.fr> 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 <sjg at chromium.org>
> Signed-off-by: Vincent Jardin <vjardin at free.fr>
>
> 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 <sjg at chromium.org>

> 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