diff options
Diffstat (limited to 'doc/usage')
| -rw-r--r-- | doc/usage/cmd/host.rst | 116 | ||||
| -rw-r--r-- | doc/usage/cmd/ut.rst | 117 | ||||
| -rw-r--r-- | doc/usage/index.rst | 2 |
3 files changed, 235 insertions, 0 deletions
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 |