From 2851cc94f3010d686fca3817f66ec8e9f4b2235b Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sat, 29 Oct 2022 19:47:18 -0600 Subject: [PATCH] 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 --- doc/arch/index.rst | 2 +- doc/arch/sandbox/block_impl.rst | 39 ++++++++++ doc/arch/sandbox/index.rst | 12 +++ doc/arch/{ => sandbox}/sandbox.rst | 9 ++- doc/usage/cmd/host.rst | 116 +++++++++++++++++++++++++++++ doc/usage/index.rst | 1 + 6 files changed, 175 insertions(+), 4 deletions(-) create mode 100644 doc/arch/sandbox/block_impl.rst create mode 100644 doc/arch/sandbox/index.rst rename doc/arch/{ => sandbox}/sandbox.rst (98%) create mode 100644 doc/usage/cmd/host.rst diff --git a/doc/arch/index.rst b/doc/arch/index.rst index 792d9182c3..b3e85f9bf3 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 0000000000..344c74f718 --- /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 + +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 0000000000..1f1f5de4b0 --- /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 + +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 ed66f70f61..34c4e06d9b 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 diff --git a/doc/usage/cmd/host.rst b/doc/usage/cmd/host.rst new file mode 100644 index 0000000000..e14508986c --- /dev/null +++ b/doc/usage/cmd/host.rst @@ -0,0 +1,116 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +host command +============ + +Synopis +------- + +:: + + host bind [-r]