diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 2 | ||||
| -rw-r--r-- | doc/README.menu | 124 | ||||
| -rw-r--r-- | doc/develop/index.rst | 25 | ||||
| -rw-r--r-- | doc/develop/menus.rst | 131 | ||||
| -rw-r--r-- | doc/develop/py_testing.rst | 426 | ||||
| -rw-r--r-- | doc/develop/testing.rst | 96 | ||||
| -rw-r--r-- | doc/device-tree-bindings/pinctrl/atmel,at91-pio4-pinctrl.txt | 2 | ||||
| -rw-r--r-- | doc/uImage.FIT/source_file_format.txt | 33 | ||||
| -rw-r--r-- | doc/usage/conitrace.rst | 54 | ||||
| -rw-r--r-- | doc/usage/echo.rst | 65 | ||||
| -rw-r--r-- | doc/usage/exit.rst | 40 | ||||
| -rw-r--r-- | doc/usage/false.rst | 28 | ||||
| -rw-r--r-- | doc/usage/for.rst | 65 | ||||
| -rw-r--r-- | doc/usage/index.rst | 8 | ||||
| -rw-r--r-- | doc/usage/loady.rst | 67 | ||||
| -rw-r--r-- | doc/usage/sbi.rst | 49 | ||||
| -rw-r--r-- | doc/usage/true.rst | 28 |
17 files changed, 1096 insertions, 147 deletions
diff --git a/doc/Makefile b/doc/Makefile index 0e0da5666f8..a686d4728ec 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -106,7 +106,7 @@ cleandocs: $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=doc/media clean dochelp: - @echo ' Linux kernel internal documentation in different formats from ReST:' + @echo ' U-Boot documentation in different formats from ReST:' @echo ' htmldocs - HTML' @echo ' latexdocs - LaTeX' @echo ' pdfdocs - PDF' diff --git a/doc/README.menu b/doc/README.menu deleted file mode 100644 index 0f3d7416055..00000000000 --- a/doc/README.menu +++ /dev/null @@ -1,124 +0,0 @@ -SPDX-License-Identifier: GPL-2.0+ -/* - * Copyright 2010-2011 Calxeda, Inc. - */ - -U-Boot provides a set of interfaces for creating and using simple, text -based menus. Menus are displayed as lists of labeled entries on the -console, and an entry can be selected by entering its label. - -To use the menu code, enable CONFIG_MENU, and include "menu.h" where -the interfaces should be available. - -Menus are composed of items. Each item has a key used to identify it in -the menu, and an opaque pointer to data controlled by the consumer. - -If you want to show a menu, instead starting the shell, define -CONFIG_AUTOBOOT_MENU_SHOW. You have to code the int menu_show(int bootdelay) -function, which handle your menu. This function returns the remaining -bootdelay. - -Interfaces ----------- -#include "menu.h" - -/* - * Consumers of the menu interfaces will use a struct menu * as the - * handle for a menu. struct menu is only fully defined in menu.c, - * preventing consumers of the menu interfaces from accessing its - * contents directly. - */ -struct menu; - -/* - * NOTE: See comments in common/menu.c for more detailed documentation on - * these interfaces. - */ - -/* - * menu_create() - Creates a menu handle with default settings - */ -struct menu *menu_create(char *title, int timeout, int prompt, - void (*item_data_print)(void *), - char *(*item_choice)(void *), - void *item_choice_data); - -/* - * menu_item_add() - Adds or replaces a menu item - */ -int menu_item_add(struct menu *m, char *item_key, void *item_data); - -/* - * menu_default_set() - Sets the default choice for the menu - */ -int menu_default_set(struct menu *m, char *item_key); - -/* - * menu_default_choice() - Set *choice to point to the default item's data - */ -int menu_default_choice(struct menu *m, void **choice); - -/* - * menu_get_choice() - Returns the user's selected menu entry, or the - * default if the menu is set to not prompt or the timeout expires. - */ -int menu_get_choice(struct menu *m, void **choice); - -/* - * menu_destroy() - frees the memory used by a menu and its items. - */ -int menu_destroy(struct menu *m); - -/* - * menu_display_statusline(struct menu *m); - * shows a statusline for every menu_display call. - */ -void menu_display_statusline(struct menu *m); - -Example Code ------------- -This example creates a menu that always prompts, and allows the user -to pick from a list of tools. The item key and data are the same. - -#include "menu.h" - -char *tools[] = { - "Hammer", - "Screwdriver", - "Nail gun", - NULL -}; - -char *pick_a_tool(void) -{ - struct menu *m; - int i; - char *tool = NULL; - - m = menu_create("Tools", 0, 1, NULL); - - for(i = 0; tools[i]; i++) { - if (menu_item_add(m, tools[i], tools[i]) != 1) { - printf("failed to add item!"); - menu_destroy(m); - return NULL; - } - } - - if (menu_get_choice(m, (void **)&tool) != 1) - printf("Problem picking tool!\n"); - - menu_destroy(m); - - return tool; -} - -void caller(void) -{ - char *tool = pick_a_tool(); - - if (tool) { - printf("picked a tool: %s\n", tool); - use_tool(tool); - } -} diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 0a7e204b343..beaa64d8d90 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -3,13 +3,32 @@ Develop U-Boot ============== +Implementation +-------------- .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - coccinelle commands - crash_dumps global_data logging + menus + +Debugging +--------- + +.. toctree:: + :maxdepth: 1 + + crash_dumps trace + +Testing +------- + +.. toctree:: + :maxdepth: 1 + + coccinelle + testing + py_testing diff --git a/doc/develop/menus.rst b/doc/develop/menus.rst new file mode 100644 index 00000000000..dda8f963fb5 --- /dev/null +++ b/doc/develop/menus.rst @@ -0,0 +1,131 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2010-2011 Calxeda, Inc. + +Menus +===== + +U-Boot provides a set of interfaces for creating and using simple, text +based menus. Menus are displayed as lists of labeled entries on the +console, and an entry can be selected by entering its label. + +To use the menu code, enable CONFIG_MENU, and include "menu.h" where +the interfaces should be available. + +Menus are composed of items. Each item has a key used to identify it in +the menu, and an opaque pointer to data controlled by the consumer. + +If you want to show a menu, instead starting the shell, define +CONFIG_AUTOBOOT_MENU_SHOW. You have to code the int menu_show(int bootdelay) +function, which handle your menu. This function returns the remaining +bootdelay. + +Interfaces +---------- + +.. code-block:: c + + #include "menu.h" + + /* + * Consumers of the menu interfaces will use a struct menu * as the + * handle for a menu. struct menu is only fully defined in menu.c, + * preventing consumers of the menu interfaces from accessing its + * contents directly. + */ + struct menu; + + /* + * NOTE: See comments in common/menu.c for more detailed documentation on + * these interfaces. + */ + + /* + * menu_create() - Creates a menu handle with default settings + */ + struct menu *menu_create(char *title, int timeout, int prompt, + void (*item_data_print)(void *), + char *(*item_choice)(void *), + void *item_choice_data); + + /* + * menu_item_add() - Adds or replaces a menu item + */ + int menu_item_add(struct menu *m, char *item_key, void *item_data); + + /* + * menu_default_set() - Sets the default choice for the menu + */ + int menu_default_set(struct menu *m, char *item_key); + + /* + * menu_default_choice() - Set *choice to point to the default item's data + */ + int menu_default_choice(struct menu *m, void **choice); + + /* + * menu_get_choice() - Returns the user's selected menu entry, or the + * default if the menu is set to not prompt or the timeout expires. + */ + int menu_get_choice(struct menu *m, void **choice); + + /* + * menu_destroy() - frees the memory used by a menu and its items. + */ + int menu_destroy(struct menu *m); + + /* + * menu_display_statusline(struct menu *m); + * shows a statusline for every menu_display call. + */ + void menu_display_statusline(struct menu *m); + +Example Code +------------ + +This example creates a menu that always prompts, and allows the user +to pick from a list of tools. The item key and data are the same. + +.. code-block:: c + + #include "menu.h" + + char *tools[] = { + "Hammer", + "Screwdriver", + "Nail gun", + NULL + }; + + char *pick_a_tool(void) + { + struct menu *m; + int i; + char *tool = NULL; + + m = menu_create("Tools", 0, 1, NULL); + + for(i = 0; tools[i]; i++) { + if (menu_item_add(m, tools[i], tools[i]) != 1) { + printf("failed to add item!"); + menu_destroy(m); + return NULL; + } + } + + if (menu_get_choice(m, (void **)&tool) != 1) + printf("Problem picking tool!\n"); + + menu_destroy(m); + + return tool; + } + + void caller(void) + { + char *tool = pick_a_tool(); + + if (tool) { + printf("picked a tool: %s\n", tool); + use_tool(tool); + } + } diff --git a/doc/develop/py_testing.rst b/doc/develop/py_testing.rst new file mode 100644 index 00000000000..f71e837aa96 --- /dev/null +++ b/doc/develop/py_testing.rst @@ -0,0 +1,426 @@ +U-Boot pytest suite +=================== + +Introduction +------------ + +This tool aims to test U-Boot by executing U-Boot shell commands using the +console interface. A single top-level script exists to execute or attach to the +U-Boot console, run the entire script of tests against it, and summarize the +results. Advantages of this approach are: + +- Testing is performed in the same way a user or script would interact with + U-Boot; there can be no disconnect. +- There is no need to write or embed test-related code into U-Boot itself. + It is asserted that writing test-related code in Python is simpler and more + flexible than writing it all in C. +- It is reasonably simple to interact with U-Boot in this way. + +Requirements +------------ + +The test suite is implemented using pytest. Interaction with the U-Boot console +involves executing some binary and interacting with its stdin/stdout. You will +need to implement various "hook" scripts that are called by the test suite at +the appropriate time. + +In order to run the test suite at a minimum we require that both Python 3 and +pip for Python 3 are installed. All of the required python modules are +described in the requirements.txt file in the /test/py/ directory and can be +installed via the command + +.. code-block:: bash + + pip install -r requirements.txt + +In order to execute certain tests on their supported platforms other tools +will be required. The following is an incomplete list: + +* gdisk +* dfu-util +* dtc +* openssl +* sudo OR guestmount +* e2fsprogs +* util-linux +* coreutils +* dosfstools +* efitools +* mount +* mtools +* sbsigntool +* udisks2 + +Please use the appropriate commands for your distribution to match these tools +up with the package that provides them. + +The test script supports either: + +- Executing a sandbox port of U-Boot on the local machine as a sub-process, + and interacting with it over stdin/stdout. +- Executing an external "hook" scripts to flash a U-Boot binary onto a + physical board, attach to the board's console stream, and reset the board. + Further details are described later. + +Using `virtualenv` to provide requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The recommended way to run the test suite, in order to ensure reproducibility +is to use `virtualenv` to set up the necessary environment. This can be done +via the following commands: + + +.. code-block:: console + + $ cd /path/to/u-boot + $ sudo apt-get install python3 python3-virtualenv + $ virtualenv -p /usr/bin/python3 venv + $ . ./venv/bin/activate + $ pip install -r test/py/requirements.txt + +Testing sandbox +--------------- + +To run the test suite on the sandbox port (U-Boot built as a native user-space +application), simply execute: + +.. code-block:: bash + + ./test/py/test.py --bd sandbox --build + +The `--bd` option tells the test suite which board type is being tested. This +lets the test suite know which features the board has, and hence exactly what +can be tested. + +The `--build` option tells U-Boot to compile U-Boot. Alternatively, you may +omit this option and build U-Boot yourself, in whatever way you choose, before +running the test script. + +The test script will attach to U-Boot, execute all valid tests for the board, +then print a summary of the test process. A complete log of the test session +will be written to `${build_dir}/test-log.html`. This is best viewed in a web +browser, but may be read directly as plain text, perhaps with the aid of the +`html2text` utility. + +Testing under a debugger +~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to run sandbox under a debugger, you may pass the command-line +option `--gdbserver COMM`. This causes two things to happens: + +- Instead of running U-Boot directly, it will be run under gdbserver, with + debug communication via the channel `COMM`. You can attach a debugger to the + sandbox process in order to debug it. See `man gdbserver` and the example + below for details of valid values for `COMM`. +- All timeouts in tests are disabled, allowing U-Boot an arbitrary amount of + time to execute commands. This is useful if U-Boot is stopped at a breakpoint + during debugging. + +A usage example is: + +Window 1: + +.. code-block:: bash + + ./test/py/test.py --bd sandbox --gdbserver localhost:1234 + +Window 2: + +.. code-block:: bash + + gdb ./build-sandbox/u-boot -ex 'target remote localhost:1234' + +Alternatively, you could leave off the `-ex` option and type the command +manually into gdb once it starts. + +You can use any debugger you wish, as long as it speaks the gdb remote +protocol, or any graphical wrapper around gdb. + +Some tests deliberately cause the sandbox process to exit, e.g. to test the +reset command, or sandbox's CTRL-C handling. When this happens, you will need +to attach the debugger to the new sandbox instance. If these tests are not +relevant to your debugging session, you can skip them using pytest's -k +command-line option; see the next section. + +Command-line options +-------------------- + +--board-type, --bd, -B + set the type of the board to be tested. For example, `sandbox` or `seaboard`. + +--board-identity`, --id + sets the identity of the board to be tested. This allows differentiation + between multiple instances of the same type of physical board that are + attached to the same host machine. This parameter is not interpreted by th + test script in any way, but rather is simply passed to the hook scripts + described below, and may be used in any site-specific way deemed necessary. + +--build + indicates that the test script should compile U-Boot itself before running + the tests. If using this option, make sure that any environment variables + required by the build process are already set, such as `$CROSS_COMPILE`. + +--buildman + indicates that `--build` should use buildman to build U-Boot. There is no need + to set $CROSS_COMPILE` in this case since buildman handles it. + +--build-dir + sets the directory containing the compiled U-Boot binaries. If omitted, this + is `${source_dir}/build-${board_type}`. + +--result-dir + sets the directory to write results, such as log files, into. + If omitted, the build directory is used. + +--persistent-data-dir + sets the directory used to store persistent test data. This is test data that + may be re-used across test runs, such as file-system images. + +`pytest` also implements a number of its own command-line options. Commonly used +options are mentioned below. Please see `pytest` documentation for complete +details. Execute `py.test --version` for a brief summary. Note that U-Boot's +test.py script passes all command-line arguments directly to `pytest` for +processing. + +-k + selects which tests to run. The default is to run all known tests. This + option takes a single argument which is used to filter test names. Simple + logical operators are supported. For example: + + - `'-k ums'` runs only tests with "ums" in their name. + - `'-k ut_dm'` runs only tests with "ut_dm" in their name. Note that in this + case, "ut_dm" is a parameter to a test rather than the test name. The full + test name is e.g. "test_ut[ut_dm_leak]". + - `'-k not reset'` runs everything except tests with "reset" in their name. + - `'-k ut or hush'` runs only tests with "ut" or "hush" in their name. + - `'-k not (ut or hush)'` runs everything except tests with "ut" or "hush" in + their name. + +-s + prevents pytest from hiding a test's stdout. This allows you to see + U-Boot's console log in real time on pytest's stdout. + +Testing real hardware +--------------------- + +The tools and techniques used to interact with real hardware will vary +radically between different host and target systems, and the whims of the user. +For this reason, the test suite does not attempt to directly interact with real +hardware in any way. Rather, it executes a standardized set of "hook" scripts +via `$PATH`. These scripts implement certain actions on behalf of the test +suite. This keeps the test suite simple and isolated from system variances +unrelated to U-Boot features. + +Hook scripts +~~~~~~~~~~~~ + +Environment variables +''''''''''''''''''''' + +The following environment variables are set when running hook scripts: + +- `UBOOT_BOARD_TYPE` the board type being tested. +- `UBOOT_BOARD_IDENTITY` the board identity being tested, or `na` if none was + specified. +- `UBOOT_SOURCE_DIR` the U-Boot source directory. +- `UBOOT_TEST_PY_DIR` the full path to `test/py/` in the source directory. +- `UBOOT_BUILD_DIR` the U-Boot build directory. +- `UBOOT_RESULT_DIR` the test result directory. +- `UBOOT_PERSISTENT_DATA_DIR` the test persistent data directory. + +u-boot-test-console +''''''''''''''''''' + +This script provides access to the U-Boot console. The script's stdin/stdout +should be connected to the board's console. This process should continue to run +indefinitely, until killed. The test suite will run this script in parallel +with all other hooks. + +This script may be implemented e.g. by executing `cu`, `kermit`, `conmux`, etc. +via exec(). + +If you are able to run U-Boot under a hardware simulator such as QEMU, then +you would likely spawn that simulator from this script. However, note that +`u-boot-test-reset` may be called multiple times per test script run, and must +cause U-Boot to start execution from scratch each time. Hopefully your +simulator includes a virtual reset button! If not, you can launch the +simulator from `u-boot-test-reset` instead, while arranging for this console +process to always communicate with the current simulator instance. + +u-boot-test-flash +''''''''''''''''' + +Prior to running the test suite against a board, some arrangement must be made +so that the board executes the particular U-Boot binary to be tested. Often +this involves writing the U-Boot binary to the board's flash ROM. The test +suite calls this hook script for that purpose. + +This script should perform the entire flashing process synchronously; the +script should only exit once flashing is complete, and a board reset will +cause the newly flashed U-Boot binary to be executed. + +It is conceivable that this script will do nothing. This might be useful in +the following cases: + +- Some other process has already written the desired U-Boot binary into the + board's flash prior to running the test suite. +- The board allows U-Boot to be downloaded directly into RAM, and executed + from there. Use of this feature will reduce wear on the board's flash, so + may be preferable if available, and if cold boot testing of U-Boot is not + required. If this feature is used, the `u-boot-test-reset` script should + perform this download, since the board could conceivably be reset multiple + times in a single test run. + +It is up to the user to determine if those situations exist, and to code this +hook script appropriately. + +This script will typically be implemented by calling out to some SoC- or +board-specific vendor flashing utility. + +u-boot-test-reset +''''''''''''''''' + +Whenever the test suite needs to reset the target board, this script is +executed. This is guaranteed to happen at least once, prior to executing the +first test function. If any test fails, the test infra-structure will execute +this script again to restore U-Boot to an operational state before running the +next test function. + +This script will likely be implemented by communicating with some form of +relay or electronic switch attached to the board's reset signal. + +The semantics of this script require that when it is executed, U-Boot will +start running from scratch. If the U-Boot binary to be tested has been written +to flash, pulsing the board's reset signal is likely all this script needs to +do. However, in some scenarios, this script may perform other actions. For +example, it may call out to some SoC- or board-specific vendor utility in order +to download the U-Boot binary directly into RAM and execute it. This would +avoid the need for `u-boot-test-flash` to actually write U-Boot to flash, thus +saving wear on the flash chip(s). + +Examples +'''''''' + +https://github.com/swarren/uboot-test-hooks contains some working example hook +scripts, and may be useful as a reference when implementing hook scripts for +your platform. These scripts are not considered part of U-Boot itself. + +Board-type-specific configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each board has a different configuration and behaviour. Many of these +differences can be automatically detected by parsing the `.config` file in the +build directory. However, some differences can't yet be handled automatically. + +For each board, an optional Python module `u_boot_board_${board_type}` may exist +to provide board-specific information to the test script. Any global value +defined in these modules is available for use by any test function. The data +contained in these scripts must be purely derived from U-Boot source code. +Hence, these configuration files are part of the U-Boot source tree too. + +Execution environment configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each user's hardware setup may enable testing different subsets of the features +implemented by a particular board's configuration of U-Boot. For example, a +U-Boot configuration may support USB device mode and USB Mass Storage, but this +can only be tested if a USB cable is connected between the board and the host +machine running the test script. + +For each board, optional Python modules `u_boot_boardenv_${board_type}` and +`u_boot_boardenv_${board_type}_${board_identity}` may exist to provide +board-specific and board-identity-specific information to the test script. Any +global value defined in these modules is available for use by any test +function. The data contained in these is specific to a particular user's +hardware configuration. Hence, these configuration files are not part of the +U-Boot source tree, and should be installed outside of the source tree. Users +should set `$PYTHONPATH` prior to running the test script to allow these +modules to be loaded. + +Board module parameter usage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The test scripts rely on the following variables being defined by the board +module: + +- none at present + +U-Boot `.config` feature usage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The test scripts rely on various U-Boot `.config` features, either directly in +order to test those features, or indirectly in order to query information from +the running U-Boot instance in order to test other features. + +One example is that testing of the `md` command requires knowledge of a RAM +address to use for the test. This data is parsed from the output of the +`bdinfo` command, and hence relies on CONFIG_CMD_BDI being enabled. + +For a complete list of dependencies, please search the test scripts for +instances of: + +- `buildconfig.get(...` +- `@pytest.mark.buildconfigspec(...` +- `@pytest.mark.notbuildconfigspec(...` + +Complete invocation example +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Assuming that you have installed the hook scripts into $HOME/ubtest/bin, and +any required environment configuration Python modules into $HOME/ubtest/py, +then you would likely invoke the test script as follows: + +If U-Boot has already been built: + +.. code-block:: bash + + PATH=$HOME/ubtest/bin:$PATH \ + PYTHONPATH=${HOME}/ubtest/py/${HOSTNAME}:${PYTHONPATH} \ + ./test/py/test.py --bd seaboard + +If you want the test script to compile U-Boot for you too, then you likely +need to set `$CROSS_COMPILE` to allow this, and invoke the test script as +follows: + +.. code-block:: bash + + CROSS_COMPILE=arm-none-eabi- \ + PATH=$HOME/ubtest/bin:$PATH \ + PYTHONPATH=${HOME}/ubtest/py/${HOSTNAME}:${PYTHONPATH} \ + ./test/py/test.py --bd seaboard --build + +or, using buildman to handle it: + +.. code-block:: bash + + PATH=$HOME/ubtest/bin:$PATH \ + PYTHONPATH=${HOME}/ubtest/py/${HOSTNAME}:${PYTHONPATH} \ + ./test/py/test.py --bd seaboard --build --buildman + +Writing tests +------------- + +Please refer to the pytest documentation for details of writing pytest tests. +Details specific to the U-Boot test suite are described below. + +A test fixture named `u_boot_console` should be used by each test function. This +provides the means to interact with the U-Boot console, and retrieve board and +environment configuration information. + +The function `u_boot_console.run_command()` executes a shell command on the +U-Boot console, and returns all output from that command. This allows +validation or interpretation of the command output. This function validates +that certain strings are not seen on the U-Boot console. These include shell +error messages and the U-Boot sign-on message (in order to detect unexpected +board resets). See the source of `u_boot_console_base.py` for a complete list of +"bad" strings. Some test scenarios are expected to trigger these strings. Use +`u_boot_console.disable_check()` to temporarily disable checking for specific +strings. See `test_unknown_cmd.py` for an example. + +Board- and board-environment configuration values may be accessed as sub-fields +of the `u_boot_console.config` object, for example +`u_boot_console.config.ram_base`. + +Build configuration values (from `.config`) may be accessed via the dictionary +`u_boot_console.config.buildconfig`, with keys equal to the Kconfig variable +names. diff --git a/doc/develop/testing.rst b/doc/develop/testing.rst new file mode 100644 index 00000000000..4bc9ca3a6ae --- /dev/null +++ b/doc/develop/testing.rst @@ -0,0 +1,96 @@ +Testing in U-Boot +================= + +U-Boot has a large amount of code. This file describes how this code is +tested and what tests you should write when adding a new feature. + + +Running tests +------------- + +To run most tests on sandbox, type this: + + make check + +in the U-Boot directory. Note that only the pytest suite is run using this +command. + +Some tests take ages to run. To run just the quick ones, type this: + + make qcheck + + +Sandbox +------- +U-Boot can be built as a user-space application (e.g. for Linux). This +allows test to be executed without needing target hardware. The 'sandbox' +target provides this feature and it is widely used in tests. + + +Pytest Suite +------------ + +Many tests are available using the pytest suite, in test/py. This can run +either on sandbox or on real hardware. It relies on the U-Boot console to +inject test commands and check the result. It is slower to run than C code, +but provides the ability to unify lots of tests and summarise their results. + +You can run the tests on sandbox with: + + ./test/py/test.py --bd sandbox --build + +This will produce HTML output in build-sandbox/test-log.html + +See test/py/README.md for more information about the pytest suite. + + +tbot +---- + +Tbot provides a way to execute tests on target hardware. It is intended for +trying out both U-Boot and Linux (and potentially other software) on a +number of boards automatically. It can be used to create a continuous test +environment. See http://www.tbot.tools for more information. + + +Ad-hoc tests +------------ + +There are several ad-hoc tests which run outside the pytest environment: + + test/fs - File system test (shell script) + test/image - FIT and legacy image tests (shell script and Python) + test/stdint - A test that stdint.h can be used in U-Boot (shell script) + trace - Test for the tracing feature (shell script) + +TODO: Move these into pytest. + + +When to write tests +------------------- + +If you add code to U-Boot without a test you are taking a risk. Even if you +perform thorough manual testing at the time of submission, it may break when +future changes are made to U-Boot. It may even break when applied to mainline, +if other changes interact with it. A good mindset is that untested code +probably doesn't work and should be deleted. + +You can assume that the Pytest suite will be run before patches are accepted +to mainline, so this provides protection against future breakage. + +On the other hand there is quite a bit of code that is not covered with tests, +or is covered sparingly. So here are some suggestions: + +- If you are adding a new uclass, add a sandbox driver and a test that uses it +- If you are modifying code covered by an existing test, add a new test case + to cover your changes +- If the code you are modifying has not tests, consider writing one. Even a + very basic test is useful, and may be picked up and enhanced by others. It + is much easier to add onto a test - writing a new large test can seem + daunting to most contributors. + + +Future work +----------- + +Converting existing shell scripts into pytest tests. diff --git a/doc/device-tree-bindings/pinctrl/atmel,at91-pio4-pinctrl.txt b/doc/device-tree-bindings/pinctrl/atmel,at91-pio4-pinctrl.txt index a376c6fba5d..9252dc154e9 100644 --- a/doc/device-tree-bindings/pinctrl/atmel,at91-pio4-pinctrl.txt +++ b/doc/device-tree-bindings/pinctrl/atmel,at91-pio4-pinctrl.txt @@ -28,6 +28,8 @@ Optional properties: - GENERIC_PINCONFIG: generic pinconfig options to use, bias-disable, bias-pull-down, bias-pull-up, drive-open-drain, input-schmitt-enable, input-debounce. +- atmel,drive-strength: 0 or 1 for low drive, 2 for medium drive and 3 for +high drive. The default value is low drive. Example: diff --git a/doc/uImage.FIT/source_file_format.txt b/doc/uImage.FIT/source_file_format.txt index 633f227c59c..00ed3ebe935 100644 --- a/doc/uImage.FIT/source_file_format.txt +++ b/doc/uImage.FIT/source_file_format.txt @@ -126,12 +126,10 @@ Root node of the uImage Tree should have the following layout: load addresses supplied within sub-image nodes. May be omitted when no entry or load addresses are used. - Mandatory node: + Mandatory nodes: - images : This node contains a set of sub-nodes, each of them representing single component sub-image (like kernel, ramdisk, etc.). At least one sub-image is required. - - Optional node: - configurations : Contains a set of available configuration nodes and defines a default configuration. @@ -169,8 +167,8 @@ the '/images' node should have the following layout: to "none". Conditionally mandatory property: - - os : OS name, mandatory for types "kernel" and "ramdisk". Valid OS names - are: "openbsd", "netbsd", "freebsd", "4_4bsd", "linux", "svr4", "esix", + - os : OS name, mandatory for types "kernel". Valid OS names are: + "openbsd", "netbsd", "freebsd", "4_4bsd", "linux", "svr4", "esix", "solaris", "irix", "sco", "dell", "ncr", "lynxos", "vxworks", "psos", "qnx", "u-boot", "rtems", "unity", "integrity". - arch : Architecture name, mandatory for types: "standalone", "kernel", @@ -179,10 +177,13 @@ the '/images' node should have the following layout: "sparc64", "m68k", "microblaze", "nios2", "blackfin", "avr32", "st200", "sandbox". - entry : entry point address, address size is determined by - '#address-cells' property of the root node. Mandatory for for types: - "standalone" and "kernel". + '#address-cells' property of the root node. + Mandatory for types: "firmware", and "kernel". - load : load address, address size is determined by '#address-cells' - property of the root node. Mandatory for types: "standalone" and "kernel". + property of the root node. + Mandatory for types: "firmware", and "kernel". + - compatible : compatible method for loading image. + Mandatory for types: "fpga", and images that do not specify a load address. Optional nodes: - hash-1 : Each hash sub-node represents separate hash or checksum @@ -205,9 +206,8 @@ o hash-1 6) '/configurations' node ------------------------- -The 'configurations' node is optional. If present, it allows to create a -convenient, labeled boot configurations, which combine together kernel images -with their ramdisks and fdt blobs. +The 'configurations' node creates convenient, labeled boot configurations, +which combine together kernel images with their ramdisks and fdt blobs. The 'configurations' node has has the following structure: @@ -236,27 +236,22 @@ Each configuration has the following structure: o config-1 |- description = "configuration description" |- kernel = "kernel sub-node unit name" - |- ramdisk = "ramdisk sub-node unit name" |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...] - |- fpga = "fpga sub-node unit-name" |- loadables = "loadables sub-node unit-name" |- compatible = "vendor,board-style device tree compatible string" Mandatory properties: - description : Textual configuration description. - - kernel : Unit name of the corresponding kernel image (image sub-node of a - "kernel" type). + - kernel or firmware: Unit name of the corresponding kernel or firmware + (u-boot, op-tee, etc) image. If both "kernel" and "firmware" are specified, + control is passed to the firmware image. Optional properties: - - ramdisk : Unit name of the corresponding ramdisk image (component image - node of a "ramdisk" type). - fdt : Unit name of the corresponding fdt blob (component image node of a "fdt type"). Additional fdt overlay nodes can be supplied which signify that the resulting device tree blob is generated by the first base fdt blob with all subsequent overlays applied. - - setup : Unit name of the corresponding setup binary (used for booting - an x86 kernel). This contains the setup.bin file built by the kernel. - fpga : Unit name of the corresponding fpga bitstream blob (component image node of a "fpga type"). - loadables : Unit name containing a list of additional binaries to be diff --git a/doc/usage/conitrace.rst b/doc/usage/conitrace.rst new file mode 100644 index 00000000000..d9916c865ee --- /dev/null +++ b/doc/usage/conitrace.rst @@ -0,0 +1,54 @@ +conitrace command +================= + +Synopsis +-------- + +:: + + conitrace + +Description +----------- + +The conitrace command is used to test the correct function of the console input +driver. It is especially valuable for checking the support for special keys like +<F1> or <POS1>. + +To display escape sequences on a single line the output only advances to the +next line after detecting a pause of a few milliseconds. + +The output is hexadecimal. + +Examples +-------- + +Entering keys <B><SHIFT-B><CTRL-B><X> + +:: + + => conitrace + Waiting for your input + To terminate type 'x' + 62 + 42 + 02 + => + +Entering keys <F1><POS1><DEL><BACKSPACE><X> + +:: + + => conitrace + Waiting for your input + To terminate type 'x' + 1b 4f 50 + 1b 5b 48 + 1b 5b 33 7e + 7f + => + +Configuration +------------- + +The conitrace command is only available if CONFIG_CMD_CONITRACE=y. diff --git a/doc/usage/echo.rst b/doc/usage/echo.rst new file mode 100644 index 00000000000..861abdfd1eb --- /dev/null +++ b/doc/usage/echo.rst @@ -0,0 +1,65 @@ +echo command +============ + +Synopsis +-------- + +:: + + echo [-n] [args ...] + +Description +----------- + +The echo command prints its arguments to the console separated by spaces. + +-n + Do not print a line feed after the last argument. + +args + Arguments to be printed. The arguments are evaluated before being passed to + the command. + +Examples +-------- + +Strings are parsed before the arguments are passed to the echo command: + +:: + + => echo "a" 'b' c + a b c + => + +Observe how variables included in strings are handled: + +:: + + => setenv var X; echo "a)" ${var} 'b)' '${var}' c) ${var} + a) X b) ${var} c) X + => + + +-n suppresses the line feed: + +:: + + => echo -n 1 2 3; echo a b c + 1 2 3a b c + => echo -n 1 2 3 + 1 2 3=> + +A more complex example: + +:: + + => for i in a b c; do for j in 1 2 3; do echo -n "${i}${j}, "; done; echo; done; + a1, a2, a3, + b1, b2, b3, + c1, c2, c3, + => + +Return value +------------ + +The return value $? is always set to 0 (true). diff --git a/doc/usage/exit.rst b/doc/usage/exit.rst new file mode 100644 index 00000000000..769223c4775 --- /dev/null +++ b/doc/usage/exit.rst @@ -0,0 +1,40 @@ +exit command +============ + +Synopsis +-------- + +:: + + exit + +Description +----------- + +The exit command terminates a script started via the run or source command. +If scripts are nested, only the innermost script is left. + +:: + + => setenv inner 'echo entry inner; exit; echo inner done' + => setenv outer 'echo entry outer; run inner; echo outer done' + => run outer + entry outer + entry inner + outer done + => + +When executed outside a script a warning is written. Following commands are not +executed. + +:: + + => echo first; exit; echo last + first + exit not allowed from main input shell. + => + +Return value +------------ + +$? is always set to 0 (true). diff --git a/doc/usage/false.rst b/doc/usage/false.rst new file mode 100644 index 00000000000..a17fe860217 --- /dev/null +++ b/doc/usage/false.rst @@ -0,0 +1,28 @@ +false command +============= + +Synopsis +-------- + +:: + + false + +Description +----------- + +The false command sets the return value $? to 1 (false). + +Example +------- + +:: + + => false; echo $? + 1 + => + +Configuration +------------- + +The false command is only available if CONFIG_HUSH_PARSER=y. diff --git a/doc/usage/for.rst b/doc/usage/for.rst new file mode 100644 index 00000000000..f9e504979c3 --- /dev/null +++ b/doc/usage/for.rst @@ -0,0 +1,65 @@ +for command +=========== + +Synopis +------- + +:: + + for <variable> in <items>; do <commands>; done + +Description +----------- + +The for command is used to loop over a list of values and execute a series of +commands for each of these. + +The counter variable of the loop is a shell variable. Please, keep in mind that +an environment variable takes precedence over a shell variable of the same name. + +variable + name of the counter variable + +items + space separated item list + +commands + commands to execute + +Example +------- + +:: + + => setenv c + => for c in 1 2 3; do echo item ${c}; done + item 1 + item 2 + item 3 + => echo ${c} + 3 + => setenv c x + => for c in 1 2 3; do echo item ${c}; done + item x + item x + item x + => + +The first line ensures that there is no environment variable *c*. Hence in the +first loop the shell variable *c* is printed. + +After defining an environment variable of name *c* it takes precedence over the +shell variable and the environment variable is printed. + +Return value +------------ + +The return value $? after the done statement is the return value of the last +statement executed in the loop. + +:: + + => for i in true false; do ${i}; done; echo $? + 1 + => for i in false true; do ${i}; done; echo $? + 0 diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 6def2507663..f75bd082378 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -17,5 +17,13 @@ Shell commands bootefi bootmenu button + conitrace + echo + exit + false + for + loady mbr pstore + sbi + true diff --git a/doc/usage/loady.rst b/doc/usage/loady.rst new file mode 100644 index 00000000000..2819cc72aef --- /dev/null +++ b/doc/usage/loady.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +loady command +============= + +Synopsis +-------- + +:: + + loady [addr [baud]] + +Description +----------- + +The loady command is used to transfer a file to the device via the serial line +using the YMODEM protocol. + +The number of transferred bytes is saved in environment variable filesize. + +addr + load address, defaults to environment variable loadaddr or if loadaddr is + not set to configuration variable CONFIG_SYS_LOAD_ADDR + +baud + baud rate for the ymodem transmission. After the transmission the baud + rate is reset to the original value. + +Example +------- + +In the example below the terminal emulation program picocom was used to +transfer a file to the device. + +After entering the loady command the key sequence <CTRL-A><CTRL-S> is used to +let picocom prompt for the file name. Picocom invokes the program sz for the +file transfer. + +:: + + => loady 80064000 115200 + ## Ready for binary (ymodem) download to 0x80064000 at 115200 bps... + C + *** file: BOOTRISCV64.EFI + $ sz -b -vv BOOTRISCV64.EFI + Sending: BOOTRISCV64.EFI + Bytes Sent: 398976 BPS:7883 + Sending: + Ymodem sectors/kbytes sent: 0/ 0k + Transfer complete + + *** exit status: 0 *** + /1(CAN) packets, 4 retries + ## Total Size = 0x0006165f = 398943 Bytes + => echo ${filesize} + 6165f + => + +Configuration +------------- + +The command is only available if CONFIG_CMD_LOADB=y. + +Return value +------------ + +The return value $? is always 0 (true). diff --git a/doc/usage/sbi.rst b/doc/usage/sbi.rst new file mode 100644 index 00000000000..96d8861057f --- /dev/null +++ b/doc/usage/sbi.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +sbi command +=========== + +Synopsis +-------- + +:: + + sbi + +Description +----------- + +The sbi command is used to display information about the SBI (Supervisor Binary +Interface) implementation on RISC-V systems. + +The output may look like: + +:: + + => sbi + SBI 0.2 + OpenSBI + Extensions: + sbi_set_timer + sbi_console_putchar + sbi_console_getchar + sbi_clear_ipi + sbi_send_ipi + sbi_remote_fence_i + sbi_remote_sfence_vma + sbi_remote_sfence_vma_asid + sbi_shutdown + SBI Base Functionality + Timer Extension + IPI Extension + RFENCE Extension + Hart State Management Extension + +The first line indicates the version of the RISC-V SBI specification. +The second line indicates the implementation. +The further lines enumerate the implemented extensions. + +Configuration +------------- + +To use the sbi command you must specify CONFIG_CMD_SBI=y. diff --git a/doc/usage/true.rst b/doc/usage/true.rst new file mode 100644 index 00000000000..f9ef71b2d1b --- /dev/null +++ b/doc/usage/true.rst @@ -0,0 +1,28 @@ +true command +============ + +Synopsis +-------- + +:: + + true + +Description +----------- + +The true command sets the return value $? to 0 (true). + +Example +------- + +:: + + => true; echo $? + 0 + => + +Configuration +------------- + +The true command is only available if CONFIG_HUSH_PARSER=y. |