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>

4 files changed, 58 insertions, 4 deletions

diff --git a/doc/arch/index.rst b/doc/arch/index.rst
index 792d9182c31..b3e85f9bf34 100644
--- a/doc/arch/index.rst
+++ b/doc/arch/index.rst
@@ -11,7 +11,7 @@ Architecture-specific doc
    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 00000000000..344c74f718b
--- /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 00000000000..1f1f5de4b03
--- /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
index ed66f70f619..34c4e06d9b8 100644
--- a/doc/arch/sandbox.rst
+++ b/doc/arch/sandbox/sandbox.rst
@@ -43,7 +43,7 @@ Note that standalone/API support is not available at present.
 Prerequisites
 -------------
 
-Install the dependencies noted in :doc:`../build/gcc`.
+Install the dependencies noted in :doc:`../../build/gcc`.
 
 
 Basic Operation
@@ -374,6 +374,7 @@ also use low-level SPI commands::
 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 @@ or utilize the device described in test/py/make_test_disk.py::
    import make_test_disk
    make_test_disk.makeDisk()
 
+For more technical details, see :doc:`block_impl`.
+
 Writing Sandbox Drivers
 -----------------------
 
@@ -600,8 +603,8 @@ Testing
 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