From 93e2673982e6005a298ca2bd3450ac130105981e Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sat, 29 Oct 2022 19:47:11 -0600 Subject: test: doc: Add documentation for ut command Before adding more options, document this command. Signed-off-by: Simon Glass --- doc/usage/cmd/ut.rst | 102 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 doc/usage/cmd/ut.rst (limited to 'doc/usage/cmd') diff --git a/doc/usage/cmd/ut.rst b/doc/usage/cmd/ut.rst new file mode 100644 index 00000000000..9f602ea7917 --- /dev/null +++ b/doc/usage/cmd/ut.rst @@ -0,0 +1,102 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +ut command +========== + +Synopis +------- + +:: + + ut [-r] [-f] [ []] + + Number of times to run each test + -f Force 'manual' tests to run as well + Test suite to run, or `all` + 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. + +Generally all tests in the suite are run. To run just a single test from the +suite, provide the 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] [] - run unit tests + -r Number of times to run each test + -f Force 'manual' tests to run as well + 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 -- cgit v1.2.3 From 6580b618306a24b6ae2974318922c40588ab0284 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sat, 29 Oct 2022 19:47:12 -0600 Subject: test: Allow showing basic information about tests Add a 'ut info' command to show the number of suites and tests. This is useful to get a feel for the scale of the tests. Signed-off-by: Simon Glass --- doc/usage/cmd/ut.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'doc/usage/cmd') diff --git a/doc/usage/cmd/ut.rst b/doc/usage/cmd/ut.rst index 9f602ea7917..11c64a17793 100644 --- a/doc/usage/cmd/ut.rst +++ b/doc/usage/cmd/ut.rst @@ -100,3 +100,9 @@ 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 -- cgit v1.2.3 From d1b46595700b063faaec3e33f5754642e68b3d8f Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sat, 29 Oct 2022 19:47:13 -0600 Subject: test: Add a way to detect 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. Add a new argument which allows a particular (failing) test to be run immediately after a certain number of tests have run. This allows the test causing the failure to be determined. Update the documentation also. Signed-off-by: Simon Glass --- doc/usage/cmd/ut.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'doc/usage/cmd') diff --git a/doc/usage/cmd/ut.rst b/doc/usage/cmd/ut.rst index 11c64a17793..a3039634f2e 100644 --- a/doc/usage/cmd/ut.rst +++ b/doc/usage/cmd/ut.rst @@ -8,10 +8,12 @@ Synopis :: - ut [-r] [-f] [ []] + ut [-r] [-f] [-I:] [ []] Number of times to run each test -f Force 'manual' tests to run as well + Run after other tests have run + Name of the 'one' test to run Test suite to run, or `all` Name of single test to run @@ -35,6 +37,13 @@ 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 argument. -- cgit v1.2.3 From 2851cc94f3010d686fca3817f66ec8e9f4b2235b Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sat, 29 Oct 2022 19:47:18 -0600 Subject: 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/usage/cmd/host.rst | 116 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 doc/usage/cmd/host.rst (limited to 'doc/usage/cmd') 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]