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

[Vincent Jardin]

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>
---

(no changes since v1)

 doc/usage/cmd/load.rst | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/doc/usage/cmd/load.rst b/doc/usage/cmd/load.rst
index bfa45c6f36c..5d7abdd30f3 100644
--- a/doc/usage/cmd/load.rst
+++ b/doc/usage/cmd/load.rst
@@ -63,6 +63,43 @@ Example
     16 bytes read in 1 ms (15.6 KiB/s)
     =>
 
+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.
+
+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``.
+
+ubifs
+    Read files from a UBIFS volume that has already been attached
+    and mounted with the ``ubi part`` + ``ubifsmount`` commands.
+    Built when ``CONFIG_CMD_UBIFS=y``.
+
+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 ``<dev[:part]>`` argument is conventionally written as ``-`` for
+these interfaces, to make it visible at the call site that the field
+is unused. The filesystem layer never looks at it.
+
+Example::
+
+    => load semihosting - ${kernel_addr_r} kernel.itb
+    9437184 bytes read in 412 ms (21.8 MiB/s)
+    =>
+
 Configuration
 -------------
 
-- 
2.43.0