dm: Add documentation for host command and implementation
Document the 'host' command and also the internals of how it is
implemented.
Signed-off-by: Simon Glass <sjg@chromium.org>
diff --git a/doc/arch/index.rst b/doc/arch/index.rst
index 792d918..b3e85f9 100644
--- a/doc/arch/index.rst
+++ b/doc/arch/index.rst
@@ -11,7 +11,7 @@
m68k
mips
nios2
- sandbox
+ sandbox/index
sh
x86
xtensa
diff --git a/doc/arch/sandbox/block_impl.rst b/doc/arch/sandbox/block_impl.rst
new file mode 100644
index 0000000..344c74f
--- /dev/null
+++ b/doc/arch/sandbox/block_impl.rst
@@ -0,0 +1,39 @@
+.. SPDX-License-Identifier: GPL-2.0+ */
+.. Copyright (c) 2014 The Chromium OS Authors.
+.. sectionauthor:: Simon Glass <sjg@chromium.org>
+
+Sandbox block devices (implementation)
+======================================
+
+(See :ref:`sandbox_blk` for operation)
+
+Sandbox block devices are implemented using the `UCLASS_HOST` uclass. Only one
+driver is provided (`host_sb_drv`) so all devices in the uclass use the same
+driver.
+
+The uclass has a simple API allowing files to be attached and detached.
+Attaching a file results in it appearing as a block device in sandbox. This
+allows filesystems and whole disk images to be accessed from U-Boot. This is
+particularly useful for tests.
+
+Devices are created using `host_create_device()`. This sets up a new
+`UCLASS_HOST`.
+
+The device can then be attached to a file with `host_attach_file()`. This
+creates the child block device (and bootdev device).
+
+The host device's block device must be probed before use, as normal.
+
+To destroy a device, call host_destroy_device(). This removes the device (and
+its children of course), then closes any attached file, then unbinds the device.
+
+There is no arbitrary limit to the number of host devices that can be created.
+
+
+Uclass API
+----------
+
+This is incomplete as it isn't clear how to make Sphinx do the right thing for
+struct host_ops. See `include/sandbox_host.h` for full details.
+
+.. kernel-doc:: include/sandbox_host.h
diff --git a/doc/arch/sandbox/index.rst b/doc/arch/sandbox/index.rst
new file mode 100644
index 0000000..1f1f5de
--- /dev/null
+++ b/doc/arch/sandbox/index.rst
@@ -0,0 +1,12 @@
+.. SPDX-License-Identifier: GPL-2.0+ */
+.. Copyright 2022 Google LLC
+.. sectionauthor:: Simon Glass <sjg@chromium.org>
+
+Sandbox
+=======
+
+.. toctree::
+ :maxdepth: 2
+
+ sandbox
+ block_impl
diff --git a/doc/arch/sandbox.rst b/doc/arch/sandbox/sandbox.rst
similarity index 98%
rename from doc/arch/sandbox.rst
rename to doc/arch/sandbox/sandbox.rst
index ed66f70..34c4e06 100644
--- a/doc/arch/sandbox.rst
+++ b/doc/arch/sandbox/sandbox.rst
@@ -43,7 +43,7 @@
Prerequisites
-------------
-Install the dependencies noted in :doc:`../build/gcc`.
+Install the dependencies noted in :doc:`../../build/gcc`.
Basic Operation
@@ -374,6 +374,7 @@
This is issuing a READ_ID command and getting back 20 (ST Micro) part
0x2015 (the M25P16).
+.. _sandbox_blk:
Block Device Emulation
----------------------
@@ -401,6 +402,8 @@
import make_test_disk
make_test_disk.makeDisk()
+For more technical details, see :doc:`block_impl`.
+
Writing Sandbox Drivers
-----------------------
@@ -600,8 +603,8 @@
U-Boot sandbox can be used to run various tests, mostly in the test/
directory.
-See :doc:`../develop/tests_sandbox` for more information and
-:doc:`../develop/testing` for information about testing generally.
+See :doc:`../../develop/tests_sandbox` for more information and
+:doc:`../../develop/testing` for information about testing generally.
Memory Map
diff --git a/doc/usage/cmd/host.rst b/doc/usage/cmd/host.rst
new file mode 100644
index 0000000..e145089
--- /dev/null
+++ b/doc/usage/cmd/host.rst
@@ -0,0 +1,116 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+host command
+============
+
+Synopis
+-------
+
+::
+
+ host bind [-r] <label> [<filename>]
+ host unbind <label|seq>
+ host info [<label|seq>]
+ host dev [<label|seq>]
+
+Description
+-----------
+
+The host command provides a way to attach disk images on the host to U-Boot
+sandbox. This can be useful for testing U-Boot's filesystem implementations.
+
+Common arguments:
+
+<label|seq>
+ This is used to specify a host device. It can either be a label (a string)
+ or the sequence number of the device. An invalid value causes the command
+ to fail.
+
+
+host bind
+~~~~~~~~~
+
+This creates a new host device and binds a file to it.
+
+Arguments:
+
+label
+ Label to use to identify this binding. This can be any string.
+
+filename:
+ Host filename to bind to
+
+Flags:
+
+-r
+ Mark the device as removable
+
+
+host unbind
+~~~~~~~~~~~
+
+This unbinds a host device that was previously bound. The sequence numbers of
+other devices remain unchanged.
+
+
+host info
+~~~~~~~~~
+
+Provides information about a particular host binding, or all of them.
+
+
+host dev
+~~~~~~~~
+
+Allowing selecting a particular device, or (with no arguments) seeing which one
+is selected.
+
+
+Example
+-------
+
+Initially there are no devices::
+
+ => host info
+ dev blocks label path
+
+Bind a device::
+
+ => host bind -r test2 2MB.ext2.img
+ => host bind fat 1MB.fat32.img
+ => host info
+ dev blocks label path
+ 0 4096 test2 2MB.ext2.img
+ 1 2048 fat 1MB.fat32.img
+
+Select a device by label or sequence number::
+
+ => host dev fat
+ Current host device: 1: fat
+ => host dev 0
+ Current host device: 0: test2
+
+Write a file::
+
+ => ext4write host 0 0 /dump 1e00
+ File System is consistent
+ 7680 bytes written in 3 ms (2.4 MiB/s)
+ => ext4ls host 0
+ <DIR> 4096 .
+ <DIR> 4096 ..
+ <DIR> 16384 lost+found
+ 4096 testing
+ 7680 dump
+
+Unbind a device::
+
+ => host unbind test2
+ => host info
+ dev blocks label path
+ 1 2048 fat 1MB.fat32.img
+
+
+Return value
+------------
+
+The return value $? indicates whether the command succeeded.
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index f3c8fba..f7f03ae 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -52,6 +52,7 @@
cmd/for
cmd/fwu_mdata
cmd/gpio
+ cmd/host
cmd/load
cmd/loadm
cmd/loady