Merge tag 'dm-pull-7nov22' of https://source.denx.de/u-boot/custodians/u-boot-dm

sandbox UCLASS_HOST

8 files changed, 362 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 <[email protected]>
+
+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 <[email protected]>
+
+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
diff --git a/doc/develop/tests_sandbox.rst b/doc/develop/tests_sandbox.rst
index 8e42a32afb9..bfd3bdb9270 100644
--- a/doc/develop/tests_sandbox.rst
+++ b/doc/develop/tests_sandbox.rst
@@ -143,6 +143,75 @@ For example::
    Test dm_test_rtc_reset failed 3 times
 
 
+Isolating a test that breaks another
+------------------------------------
+
+When running unit tests, some may have side effects which cause a subsequent
+test to break. This can sometimes be seen when using 'ut dm' or similar.
+
+You can use the `-I` argument to the `ut` command to isolate this problem.
+First use `ut info` to see how many tests there are, then use a binary search to
+home in on the problem. Note that you might need to restart U-Boot after each
+iteration, so the `-c` argument to U-Boot is useful.
+
+For example, let's stay that dm_test_host() is failing::
+
+   => ut dm
+   ...
+   Test: dm_test_get_stats: core.c
+   Test: dm_test_get_stats: core.c (flat tree)
+   Test: dm_test_host: host.c
+   test/dm/host.c:71, dm_test_host(): 0 == ut_check_delta(mem_start): Expected 0x0 (0), got 0xffffcbb0 (-13392)
+   Test: dm_test_host: host.c (flat tree)
+   Test <NULL> failed 1 times
+   Test: dm_test_host_dup: host.c
+   Test: dm_test_host_dup: host.c (flat tree)
+   ...
+
+You can then tell U-Boot to run the failing test at different points in the
+sequence:
+
+   => ut info
+   Test suites: 21
+   Total tests: 645
+
+::
+
+   $ ./u-boot -T -c "ut dm -I300:dm_test_host"
+   ...
+   Test: dm_test_pinctrl_single: pinmux.c (flat tree)
+   Test: dm_test_host: host.c
+   test/dm/host.c:71, dm_test_host(): 0 == ut_check_delta(mem_start): Expected 0x0 (0), got 0xfffffdb0 (-592)
+   Test: dm_test_host: host.c (flat tree)
+   Test dm_test_host failed 1 times (position 300)
+   Failures: 4
+
+So it happened before position 300. Trying 150 shows it failing, so we try 75::
+
+   $ ./u-boot  -T  -c "ut dm -I75:dm_test_host"
+   ...
+   Test: dm_test_autoprobe: core.c
+   Test: dm_test_autoprobe: core.c (flat tree)
+   Test: dm_test_host: host.c
+   Test: dm_test_host: host.c (flat tree)
+   Failures: 0
+
+That succeeds, so we try 120, etc. until eventually we can figure out that the
+problem first happens at position 82.
+
+   $ ./u-boot  -T  -c "ut dm -I82:dm_test_host"
+   ...
+   Test: dm_test_blk_flags: blk.c
+   Test: dm_test_blk_flags: blk.c (flat tree)
+   Test: dm_test_host: host.c
+   test/dm/host.c:71, dm_test_host(): 0 == ut_check_delta(mem_start): Expected 0x0 (0), got 0xffffc960 (-13984)
+   Test: dm_test_host: host.c (flat tree)
+   Test dm_test_host failed 1 times (position 82)
+   Failures: 1
+
+From this we can deduce that `dm_test_blk_flags()` causes the problem with
+`dm_test_host()`.
+
 Running sandbox_spl tests directly
 ----------------------------------
 
diff --git a/doc/usage/cmd/host.rst b/doc/usage/cmd/host.rst
new file mode 100644
index 00000000000..e14508986ca
--- /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/cmd/ut.rst b/doc/usage/cmd/ut.rst
new file mode 100644
index 00000000000..a3039634f2e
--- /dev/null
+++ b/doc/usage/cmd/ut.rst
@@ -0,0 +1,117 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+ut command
+==========
+
+Synopis
+-------
+
+::
+
+    ut [-r<runs>] [-f] [-I<n>:<one_test>] [<suite> [<test>]]
+
+       <runs>      Number of times to run each test
+       -f          Force 'manual' tests to run as well
+       <n>         Run <one test> after <n> other tests have run
+       <one_test>  Name of the 'one' test to run
+       <suite>     Test suite to run, or `all`
+       <test>      Name of single test to run
+
+Description
+-----------
+
+The ut command runs unit tests written in C.
+
+Typically the command is run on :ref:`arch/sandbox/sandbox:sandbox` since it
+includes a near-complete set of emulators, no code-size limits, many CONFIG
+options enabled and runs easily in CI without needing QEMU. It is also possible
+to run some tests on real boards.
+
+For a list of available test suites, type `ut` by itself.
+
+Each test is normally run once, although those marked with `UT_TESTF_DM` are
+run with livetree and flattree where possible. To run a test more than once,
+use the `-r` flag.
+
+Manual tests are normally skipped by this command. Use `-f` to run them. See
+See :ref:`develop/tests_writing:mixing python and c` for more information on
+manual test.
+
+When running unit tests, some may have side effects which cause a subsequent
+test to break. This can sometimes be seen when using 'ut dm' or similar. To
+fix this, select the 'one' test which breaks. Then tell the 'ut' command to
+run this one test after a certain number of other tests have run. Using a
+binary search method with `-I` you can quickly figure one which test is causing
+the problem.
+
+Generally all tests in the suite are run. To run just a single test from the
+suite, provide the <test> argument.
+
+See :ref:`develop/tests_writing:writing c tests` for more information on how to
+write unit tests.
+
+Example
+-------
+
+List available unit-test suites::
+
+    => ut
+    ut - unit tests
+
+    Usage:
+    ut [-r] [-f] [<suite>] - run unit tests
+    -r<runs>   Number of times to run each test
+    -f         Force 'manual' tests to run as well
+    <suite>    Test suite to run, or all
+
+    Suites:
+    all - execute all enabled tests
+    addrmap - very basic test of addrmap command
+    bloblist - bloblist implementation
+    bootstd - standard boot implementation
+    compression - compressors and bootm decompression
+    dm - driver model
+    env - environment
+    fdt - fdt command
+    loadm - loadm command parameters and loading memory blob
+    lib - library functions
+    log - logging functions
+    mem - memory-related commands
+    overlay - device tree overlays
+    print  - printing things to the console
+    setexpr - setexpr command
+    str - basic test of string functions
+    time - very basic test of time functions
+    unicode - Unicode functions
+
+Run one of the suites::
+
+    => ut bloblist
+    Running 14 bloblist tests
+    Test: bloblist_test_align: bloblist.c
+    Test: bloblist_test_bad_blob: bloblist.c
+    Test: bloblist_test_blob: bloblist.c
+    Test: bloblist_test_blob_ensure: bloblist.c
+    Test: bloblist_test_blob_maxsize: bloblist.c
+    Test: bloblist_test_checksum: bloblist.c
+    Test: bloblist_test_cmd_info: bloblist.c
+    Test: bloblist_test_cmd_list: bloblist.c
+    Test: bloblist_test_grow: bloblist.c
+    Test: bloblist_test_init: bloblist.c
+    Test: bloblist_test_reloc: bloblist.c
+    Test: bloblist_test_resize_fail: bloblist.c
+    Test: bloblist_test_resize_last: bloblist.c
+    Test: bloblist_test_shrink: bloblist.c
+    Failures: 0
+
+Run just a single test in a suite::
+
+    => ut bloblist bloblist_test_grow
+    Test: bloblist_test_grow: bloblist.c
+    Failures: 0
+
+Show information about tests::
+
+    => ut info
+    Test suites: 21
+    Total tests: 642
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index df50746c349..f7f03aeac16 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -52,6 +52,7 @@ Shell commands
    cmd/for
    cmd/fwu_mdata
    cmd/gpio
+   cmd/host
    cmd/load
    cmd/loadm
    cmd/loady
@@ -74,6 +75,7 @@ Shell commands
    cmd/tftpput
    cmd/true
    cmd/ums
+   cmd/ut
    cmd/wdt
    cmd/xxd