diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/arch/sandbox/sandbox.rst | 6 | ||||
| -rw-r--r-- | doc/board/armltd/vexpress64.rst | 16 | ||||
| -rw-r--r-- | doc/board/index.rst | 1 | ||||
| -rw-r--r-- | doc/board/xiaomi/index.rst | 9 | ||||
| -rw-r--r-- | doc/board/xiaomi/mocha.rst | 112 | ||||
| -rw-r--r-- | doc/develop/py_testing.rst | 16 | ||||
| -rw-r--r-- | doc/develop/tests_writing.rst | 64 | ||||
| -rw-r--r-- | doc/device-tree-bindings/pinctrl/adi,adsp-pinctrl.yaml | 73 | ||||
| -rw-r--r-- | doc/usage/cmd/meminfo.rst | 71 | ||||
| -rw-r--r-- | doc/usage/cmd/mv.rst | 61 | ||||
| -rw-r--r-- | doc/usage/cmd/ut.rst | 145 | ||||
| -rw-r--r-- | doc/usage/cmd/wget.rst | 82 | ||||
| -rw-r--r-- | doc/usage/environment.rst | 12 | ||||
| -rw-r--r-- | doc/usage/index.rst | 1 |
14 files changed, 577 insertions, 92 deletions
diff --git a/doc/arch/sandbox/sandbox.rst b/doc/arch/sandbox/sandbox.rst index a8b0d7f0395..7e641306da2 100644 --- a/doc/arch/sandbox/sandbox.rst +++ b/doc/arch/sandbox/sandbox.rst @@ -658,10 +658,10 @@ that are mapped into that memory: ======== ======================== =============================== Addr Config Usage ======== ======================== =============================== - 100 CONFIG_SYS_FDT_LOAD_ADDR Device tree - b000 CONFIG_BLOBLIST_ADDR Blob list - 10000 CFG_MALLOC_F_ADDR Early memory allocation + 100 CONFIG_BLOBLIST_ADDR Blob list + 1000 CONFIG_SYS_FDT_LOAD_ADDR Device tree f0000 CONFIG_PRE_CON_BUF_ADDR Pre-console buffer + f4000 CFG_MALLOC_F_ADDR Early memory allocation 100000 TCG Event log TCG Event Log 200000 CONFIG_TRACE_EARLY_ADDR Early trace buffer (if enabled). Also used 400000 CONFIG_TEXT_BASE Load buffer for U-Boot (sandbox_spl only) diff --git a/doc/board/armltd/vexpress64.rst b/doc/board/armltd/vexpress64.rst index a7f771d2667..a732fac899d 100644 --- a/doc/board/armltd/vexpress64.rst +++ b/doc/board/armltd/vexpress64.rst @@ -43,6 +43,22 @@ Juno is an Arm development board with the following features: More details can be found in the board documentation [3]_. +Bloblist Support +---------------- + +The ``vexpress_fvp_bloblist_defconfig`` configures U-Boot to be compiled for +Vexpress64 with Bloblist as the primary method for information handoff between +boot stages. U-Boot offers three methods to set up a bloblist: using a +predefined bloblist at a specified address, dynamically allocating memory for a +bloblist, or utilizing a standard passage-provided bloblist with automatic size +detection. + +By default, ``vexpress_fvp_bloblist_defconfig`` uses the standard passage method mandatorily +(CONFIG_BLOBLIST_PASSAGE_MANDATORY) because TF-A provides a Transfer List in non-secure +memory that U-Boot can utilise. This Bloblist, which is referred to as a Transfer List in +TF-A, contains all necessary data for the handoff process, including DT and ACPI +tables. + References ---------- diff --git a/doc/board/index.rst b/doc/board/index.rst index b055046e649..84c135e02c1 100644 --- a/doc/board/index.rst +++ b/doc/board/index.rst @@ -69,4 +69,5 @@ Board-specific doc variscite/index wexler/index xen/index + xiaomi/index xilinx/index diff --git a/doc/board/xiaomi/index.rst b/doc/board/xiaomi/index.rst new file mode 100644 index 00000000000..109ab4a251f --- /dev/null +++ b/doc/board/xiaomi/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Xiaomi +====== + +.. toctree:: + :maxdepth: 2 + + mocha diff --git a/doc/board/xiaomi/mocha.rst b/doc/board/xiaomi/mocha.rst new file mode 100644 index 00000000000..be3e333127b --- /dev/null +++ b/doc/board/xiaomi/mocha.rst @@ -0,0 +1,112 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for the Xiaomi Mi Pad tablet +=================================== + +``DISCLAMER!`` Moving your Xiaomi Mi Pad to use U-Boot assumes replacement +of the vendor bootloader. Vendor Android firmwares will no longer be able +to run on the device. This replacement IS reversible. + +Quick Start +----------- + +- Build U-Boot +- Boot U-Boot +- Process and flash U-Boot +- Boot Linux +- Self Upgrading +- Chainload configuration + +Build U-Boot +------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=arm-none-eabi- + $ make mocha_defconfig + $ make + +After the build succeeds, you will obtain the final ``u-boot-dtb-tegra.bin`` +image, ready for booting or further processing. + +Boot U-Boot +----------- +Existing tegrarcm loader can be used to pre-load U-Boot you have build +into RAM and basically perform a tethered cold-boot. + +.. code-block:: bash + + $ tegrarcm --bct mocha.bct --bootloader u-boot-dtb-tegra.bin --loadaddr 0x80108000 + +U-Boot will try to load Linux kernel and if fails, it will turn the +tablet off. While pre-loading U-Boot, hold the ``volume down`` button +which will trigger the bootmenu. + +Process and flash U-Boot +------------------------ + +``DISCLAMER!`` All questions related to the re-crypt work should be asked +in re-crypt repo issues. NOT HERE! + +re-crypt is a tool that processes the ``u-boot-dtb-tegra.bin`` binary into +form usable by device. This process is required only on the first +installation or to recover the device in case of a failed update. + +.. code-block:: bash + + $ git clone https://gitlab.com/grate-driver/re-crypt.git + $ cd re-crypt # place your u-boot-dtb-tegra.bin here + $ ./re-crypt.py --dev mocha + +The script will produce ``bct.img`` and ``ebt.img`` ready to flash. + +Permanent installation can be performed by pre-loading just built U-Boot +into RAM via tegrarcm. While pre-loading U-Boot, hold the ``volume down`` +button which will trigger the bootmenu. There, select ``fastboot`` using +the volume and power buttons. + +After, on host PC, do: + +.. code-block:: bash + + $ fastboot flash 0.1 bct.img + $ fastboot flash 0.2 ebt.img + $ fastboot reboot + +Device will reboot. + +Boot Linux +---------- + +To boot Linux, U-Boot will look for an ``extlinux.conf`` on MicroSD and then on +eMMC. Additionally, if the ``volume down`` button is pressed while booting, the +device will enter bootmenu. Bootmenu contains entries to mount MicroSD and eMMC +as mass storage, fastboot, reboot, reboot RCM, poweroff, enter U-Boot console +and update bootloader (check the next chapter). + +Flashing ``bct.img`` and ``ebt.img`` eliminates vendor restrictions on eMMC and +allows the user to use/partition it in any way the user desires. + +Self Upgrading +-------------- + +Place your ``u-boot-dtb-tegra.bin`` on the first partition of the MicroSD card +and insert it into the tablet. Enter bootmenu, choose update the bootloader +option with the Power button and U-Boot should update itself. Once the process +is completed, U-Boot will ask to press any button to reboot. + +Chainload configuration +----------------------- + +To build U-Boot without SPL suitable for chainloading adjust mocha_defconfig: + +.. code-block:: + + CONFIG_TEXT_BASE=0x80A00000 + CONFIG_SKIP_LOWLEVEL_INIT=y + # CONFIG_OF_BOARD_SETUP is not set + CONFIG_TEGRA_SUPPORT_NON_SECURE=y + +After the build succeeds, you will obtain the final ``u-boot-dtb.bin`` +file, ready for booting using vendor bootloader's fastboot or which can be +further processed into a flashable image. diff --git a/doc/develop/py_testing.rst b/doc/develop/py_testing.rst index b50473039be..40a85380343 100644 --- a/doc/develop/py_testing.rst +++ b/doc/develop/py_testing.rst @@ -125,7 +125,7 @@ browser, but may be read directly as plain text, perhaps with the aid of the If sandbox crashes (e.g. with a segfault) you will see message like this:: - test/py/u_boot_spawn.py:171: in expect + test/py/spawn.py:171: in expect c = os.read(self.fd, 1024).decode(errors='replace') E ValueError: U-Boot exited with signal 11 (Signals.SIGSEGV) @@ -506,24 +506,24 @@ 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 +A test fixture named `ubman` 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 +The function `ubman.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 +board resets). See the source of `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 +`ubman.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`. +of the `ubman.config` object, for example +`ubman.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 +`ubman.config.buildconfig`, with keys equal to the Kconfig variable names. diff --git a/doc/develop/tests_writing.rst b/doc/develop/tests_writing.rst index 54efb7e1b04..7ea17081def 100644 --- a/doc/develop/tests_writing.rst +++ b/doc/develop/tests_writing.rst @@ -116,19 +116,19 @@ below are approximate, as measured on an AMD 2950X system. Here is is the test in Python:: @pytest.mark.buildconfigspec('cmd_memory') - def test_md(u_boot_console): + def test_md(ubman): """Test that md reads memory as expected, and that memory can be modified using the mw command.""" - ram_base = u_boot_utils.find_ram_base(u_boot_console) + ram_base = utils.find_ram_base(ubman) addr = '%08x' % ram_base val = 'a5f09876' expected_response = addr + ': ' + val - u_boot_console.run_command('mw ' + addr + ' 0 10') - response = u_boot_console.run_command('md ' + addr + ' 10') + ubman.run_command('mw ' + addr + ' 0 10') + response = ubman.run_command('md ' + addr + ' 10') assert(not (expected_response in response)) - u_boot_console.run_command('mw ' + addr + ' ' + val) - response = u_boot_console.run_command('md ' + addr + ' 10') + ubman.run_command('mw ' + addr + ' ' + val) + response = ubman.run_command('md ' + addr + ' 10') assert(expected_response in response) This runs a few commands and checks the output. Note that it runs a command, @@ -261,7 +261,7 @@ with the suite. For example, to add a new mem_search test:: /* Test 'ms' command with 32-bit values */ static int mem_test_ms_new_thing(struct unit_test_state *uts) { - /* test code here*/ + /* test code here */ return 0; } @@ -291,32 +291,20 @@ suite. For example:: /* Declare a new wibble test */ #define WIBBLE_TEST(_name, _flags) UNIT_TEST(_name, _flags, wibble_test) - /* Tetss go here */ - - /* At the bottom of the file: */ - - int do_ut_wibble(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[]) - { - struct unit_test *tests = UNIT_TEST_SUITE_START(wibble_test); - const int n_ents = UNIT_TEST_SUITE_COUNT(wibble_test); - - return cmd_ut_category("cmd_wibble", "wibble_test_", tests, n_ents, argc, argv); - } + /* Tests go here */ Then add new tests to it as above. Register this new suite in test/cmd_ut.c by adding to cmd_ut_sub[]:: - /* Within cmd_ut_sub[]... */ - - U_BOOT_CMD_MKENT(wibble, CONFIG_SYS_MAXARGS, 1, do_ut_wibble, "", ""), + /* with the other SUITE_DECL() declarations */ + SUITE_DECL(wibble); -and adding new help to ut_help_text[]:: + /* Within suites[]... */ + SUITE(wibble, "my test of wibbles"); - "ut wibble - Test the wibble feature\n" - -If your feature is conditional on a particular Kconfig, then you can use #ifdef -to control that. +If your feature is conditional on a particular Kconfig, you do not need to add +an #ifdef since the suite will automatically be compiled out in that case. Finally, add the test to the build by adding to the Makefile in the same directory:: @@ -326,17 +314,35 @@ directory:: Note that CMDLINE is never enabled in SPL, so this test will only be present in U-Boot proper. See below for how to do SPL tests. -As before, you can add an extra Kconfig check if needed:: +You can add an extra Kconfig check if needed:: ifneq ($(CONFIG_$(XPL_)WIBBLE),) obj-$(CONFIG_$(XPL_)CMDLINE) += wibble.o endif +Each suite can have an optional init and uninit function. These are run before +and after any suite tests, respectively:: + + #define WIBBLE_TEST_INIT(_name, _flags) UNIT_TEST_INIT(_name, _flags, wibble_test) + #define WIBBLE_TEST_UNINIT(_name, _flags) UNIT_TEST_UNINIT(_name, _flags, wibble_test) -Example commit: 919e7a8fb64 ("test: Add a simple test for bloblist") [1] + static int wibble_test_init(struct unit_test_state *uts) + { + /* init code here */ + + return 0; + } + WIBBLE_TEST_INIT(wibble_test_init, 0); -[1] https://gitlab.denx.de/u-boot/u-boot/-/commit/919e7a8fb64 + static int wibble_test_uninit(struct unit_test_state *uts) + { + /* uninit code here */ + + return 0; + } + WIBBLE_TEST_INIT(wibble_test_uninit, 0); +Both functions are included in the totals for each suite. Making the test run from pytest ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/device-tree-bindings/pinctrl/adi,adsp-pinctrl.yaml b/doc/device-tree-bindings/pinctrl/adi,adsp-pinctrl.yaml new file mode 100644 index 00000000000..418ebd5ce41 --- /dev/null +++ b/doc/device-tree-bindings/pinctrl/adi,adsp-pinctrl.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: (GPL-2.0+ OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/adi,adsp-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Pinctrl Driver for Analog Devices SC5xx Processors + +maintainers: + - Vasileios Bimpikas <vasileios.bimpikas@analog.com> + - Utsav Agarwal <utsav.agarwal@analog.com> + - Arturs Artamonovs <arturs.artamonovs@analog.com> + +description: | + This driver provides an interface for performing pin configuration + Analog Devices SoCs using the ADSP PORT hardware for pin + configuration according to the HRM. Currently this is only the + SC5xx series. + +properties: + compatible: + const: adi,adsp-pinctrl + + reg: + maxItems: 1 + + adi,npins: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Total number of pins available to this SoC's pin controller, + found in the HRM. + +patternProperties: + '_pins$': + type: object + + properties: + adi,pins: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: + For n pins, 2n values must be provided as a sequence of pin + name as identified with the ADI_ADSP_PIN() macro and a pin + function constant, both defined in + include/dt-bindings/pinctrl/adi-adsp.h. + + required: + - adi,pins + + additionalProperties: false + +required: + - compatible + - reg + - adi,npins + +additionalProperties: false + +examples: + - | + #include <dt-bindings/pinctrl/adi-adsp.h> + + soc { + pinctrl0: pinctrl@0x31004000 { + compatible = "adi,adsp-pinctrl"; + reg = <0x31004000 0x500>; + adi,npins = <135>; + uart0_default: uart0_pins { + adi,pins = <ADI_ADSP_PIN('A', 6) ADI_ADSP_PINFUNC_ALT1>, + <ADI_ADSP_PIN('A', 7) ADI_ADSP_PINFUNC_ALT1>; + }; + }; + + }; diff --git a/doc/usage/cmd/meminfo.rst b/doc/usage/cmd/meminfo.rst index 6c94493cccc..e10bdc6832c 100644 --- a/doc/usage/cmd/meminfo.rst +++ b/doc/usage/cmd/meminfo.rst @@ -18,7 +18,8 @@ Description The meminfo command shows the amount of memory. If ``CONFIG_CMD_MEMINFO_MAP`` is enabled, then it also shows the layout of memory used by U-Boot and the region -which is free for use by images. +which is free for use by images. In architectures that support it, it also prints +the mapped pages and their permissions. The latter is architecture specific. The layout of memory is set up before relocation, within the init sequence in ``board_init_f()``, specifically the various ``reserve_...()`` functions. This @@ -26,8 +27,9 @@ The layout of memory is set up before relocation, within the init sequence in ending with the stack. This results in the maximum possible amount of memory being left free for image-loading. -The meminfo command writes the DRAM size, then the rest of its outputs in 5 -columns: +The meminfo command writes the DRAM size. If the architecture also supports it, +page table entries will be shown next. Finally the rest of the outputs are +printed in 5 columns: Region Name of the region @@ -99,28 +101,61 @@ free Free memory, which is available for loading images. The base address of this is ``gd->ram_base`` which is generally set by ``CFG_SYS_SDRAM_BASE``. +Aarch64 specific flags +---------------------- + +More information on the output can be found +Chapter D8 - The AArch64 Virtual Memory System Architecture at +https://developer.arm.com/documentation/ddi0487/latest/ + +In short, for a stage 1 translation regime the following apply: + +* RWX: Pages mapped with Read, Write and Execute permissions +* RO: Pages mapped with Read-Only permissions +* PXN: PXN (Privileged Execute Never) applies to execution at EL1 and above +* UXN: UXN (Unprivileged Execute Never) applies to EL0 + Example ------- This example shows output with both ``CONFIG_CMD_MEMINFO`` and -``CONFIG_CMD_MEMINFO_MAP`` enabled:: - - => meminfo - DRAM: 256 MiB +``CONFIG_CMD_MEMINFO_MAP`` enabled for aarch64 qemu:: + + DRAM: 8 GiB + Walking pagetable at 000000023ffe0000, va_bits: 40. Using 4 levels + [0x0000023ffe1000] | Table | | | + [0x0000023ffe2000] | Table | | | + [0x00000000000000 - 0x00000008000000] | Block | RWX | Normal | Inner-shareable + [0x00000008000000 - 0x00000040000000] | Block | PXN UXN | Device-nGnRnE | Non-shareable + [0x00000040000000 - 0x00000200000000] | Block | RWX | Normal | Inner-shareable + [0x0000023ffea000] | Table | | | + [0x00000200000000 - 0x0000023f600000] | Block | RWX | Normal | Inner-shareable + [0x0000023ffeb000] | Table | | | + [0x0000023f600000 - 0x0000023f68c000] | Pages | RWX | Normal | Inner-shareable + [0x0000023f68c000 - 0x0000023f74f000] | Pages | RO | Normal | Inner-shareable + [0x0000023f74f000 - 0x0000023f794000] | Pages | PXN UXN RO | Normal | Inner-shareable + [0x0000023f794000 - 0x0000023f79d000] | Pages | PXN UXN | Normal | Inner-shareable + [0x0000023f79d000 - 0x0000023f800000] | Pages | RWX | Normal | Inner-shareable + [0x0000023f800000 - 0x00000240000000] | Block | RWX | Normal | Inner-shareable + [0x00000240000000 - 0x00004000000000] | Block | RWX | Normal | Inner-shareable + [0x0000023ffe3000] | Table | | | + [0x00004010000000 - 0x00004020000000] | Block | PXN UXN | Device-nGnRnE | Non-shareable + [0x0000023ffe4000] | Table | | | + [0x00008000000000 - 0x00010000000000] | Block | PXN UXN | Device-nGnRnE | Non-shareable Region Base Size End Gap ------------------------------------------------ - video f000000 1000000 10000000 - code ec3a000 3c5d28 efffd28 2d8 - malloc 8c38000 6002000 ec3a000 0 - board_info 8c37f90 68 8c37ff8 8 - global_data 8c37d80 208 8c37f88 8 - devicetree 8c33000 4d7d 8c37d7d 3 - bootstage 8c32c20 3c8 8c32fe8 18 - bloblist 8c32000 400 8c32400 820 - stack 7c31ff0 1000000 8c31ff0 10 - free 0 7c31ff0 7c31ff0 0 - + video 23f7e0000 800000 23ffe0000 + code 23f68a000 156000 23f7e0000 0 + malloc 23e64a000 1040000 23f68a000 0 + board_info 23e649f80 78 23e649ff8 8 + global_data 23e649df0 188 23e649f78 8 + devicetree 23e549df0 100000 23e649df0 0 + bloblist 23e547000 2000 23e549000 df0 + stack 23d546ff0 1000000 23e546ff0 10 + lmb 23d546ff0 0 23d546ff0 0 + lmb 23d543000 3ff0 23d546ff0 0 + free 40000000 23d543000 27d543000 ffffffffc0000000 Return value ------------ diff --git a/doc/usage/cmd/mv.rst b/doc/usage/cmd/mv.rst new file mode 100644 index 00000000000..99864371038 --- /dev/null +++ b/doc/usage/cmd/mv.rst @@ -0,0 +1,61 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: mv (command) + +mv command +========== + +Synopsis +-------- + +:: + + mv <interface> [<dev[:part]>] <old_path> <new_path> + +Description +----------- + +The mv command renames/moves a file or directory within a filesystem. + +interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + +dev + device number + +part + partition number, defaults to 0 (whole device) + +old_path + existing path to file/directory + +new_path + new path/name for the rename/move + + +Example +------- + + # Rename file 'foo' in directory 'dir' to 'bar' + mv mmc 0:0 dir/foo dir/bar + + # Move file 'f' from directory 'foo' to existing directory 'bar' renaming + # 'f' to 'g' + mv mmc 0:0 foo/f bar/g + + # Move directory 'abc' in directory 'dir1' into existing directory 'dir2' + mv mmc 0:0 dir1/abc dir2 + +Configuration +------------- + +The mv command is only available if CONFIG_CMD_FS_GENERIC=y. + +Return value +------------ + +The return value $? is set to 0 (true) if the file was successfully +renamed/moved. + +If an error occurs, the return value $? is set to 1 (false). diff --git a/doc/usage/cmd/ut.rst b/doc/usage/cmd/ut.rst index e794922c806..1acf3126680 100644 --- a/doc/usage/cmd/ut.rst +++ b/doc/usage/cmd/ut.rst @@ -11,34 +11,44 @@ Synopsis :: - ut [-r<runs>] [-fs] [-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 + ut [-r<runs>] [-f] [-I<n>:<one_test>] [-r<n>] [<suite> | 'all' [<test>]] + ut [-s] info Description ----------- The ut command runs unit tests written in C. +suite + Specifies the suite to run, This can be a single suite, or a comma-separated + list + +test + Speciifes a particular test to run, within a suite, or all suites + +-f + Forces running of a manual test. + +-r <n> + Specifies the number of types to run each test + +-I <n>:<one_test> + Test to run after <n> other tests have run. This is used to find which test + causes another test to fail. If the one test fails, testing stops + immediately. + 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 info -s`. - Each test is normally run once, although those marked with `UTF_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. +:ref:`develop/tests_writing:mixing python and c` for more information on manual +tests. 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 @@ -50,9 +60,22 @@ the problem. Generally all tests in the suite are run. To run just a single test from the suite, provide the <test> argument. +To specify a list of suites to run, <suites> can also be a comma-separated list. + See :ref:`develop/tests_writing:writing c tests` for more information on how to write unit tests. +ut all +~~~~~~ + +Instead of a suite name 'all' may be used to run all tests. + +ut info +~~~~~~~ + +This provides information about the total number of suites and tests. Use the +`-s` flag to show a detailed list of suites. + Example ------- @@ -97,26 +120,84 @@ List available unit-test suites:: 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 + => ut common + Running 14 common tests + Test: cli_ch_test: cread.c + Test: cread_test: cread.c + Test: dm_test_cyclic_running: cyclic.c + Test: print_display_buffer: print.c + Test: print_do_hex_dump: print.c + Test: print_efi_ut: print.c + Test: print_guid: print.c + Test: print_hexdump_line: print.c + Test: print_printf: print.c + Test: snprint: print.c + Test: test_autoboot: test_autoboot.c + Enter password "a" in 1 seconds to stop autoboot + Enter password "a" in 1 seconds to stop autoboot + Enter password "a" in 1 seconds to stop autoboot + Enter password "a" in 1 seconds to stop autoboot + Enter password "a" in 1 seconds to stop autoboot + Enter password "a" in 1 seconds to stop autoboot + Autoboot password unlock not successful + Test: test_event_base: event.c + Test: test_event_probe: event.c + Test: test_event_probe: event.c (flat tree) + Test: test_event_simple: event.c + Tests run: 14, 2611 ms, average 186 ms, skipped: 2, failures: 0 Run just a single test in a suite:: - => ut bloblist bloblist_test_grow - Test: bloblist_test_grow: bloblist.c - Failures: 0 + => ut fdt_overlay change_int_property + Test: fdt_overlay_init: cmd_ut_fdt_overlay.c + Test: change_int_property: cmd_ut_fdt_overlay.c + Tests run: 2, 0 ms, average 0 ms, failures: 0 + +Run a selection of three suites:: + + => ut bloblist,mem,fdt_overlay + Running 14 bloblist tests + Test: align: bloblist.c + Test: bad_blob: bloblist.c + Test: blob: bloblist.c + Test: blob_ensure: bloblist.c + Test: blob_maxsize: bloblist.c + Test: checksum: bloblist.c + Test: cmd_info: bloblist.c + Test: cmd_list: bloblist.c + Test: grow: bloblist.c + Test: init: bloblist.c + Test: reloc: bloblist.c + Test: resize_fail: bloblist.c + Test: resize_last: bloblist.c + Test: shrink: bloblist.c + Tests run: 14, 1 ms, average: 0 ms, failures: 0 + Running 13 mem tests + Test: cp_b: mem_copy.c + Test: cp_l: mem_copy.c + Test: cp_q: mem_copy.c + Test: cp_w: mem_copy.c + Test: ms_b: mem_search.c + Test: ms_cont: mem_search.c + Test: ms_cont_end: mem_search.c + Test: ms_l: mem_search.c + Test: ms_limit: mem_search.c + Test: ms_mult: mem_search.c + Test: ms_quiet: mem_search.c + Test: ms_s: mem_search.c + Test: ms_w: mem_search.c + Tests run: 13, 13 ms, average: 1 ms, failures: 0 + Running 10 fdt_overlay tests + Test: fdt_overlay_init: cmd_ut_fdt_overlay.c + Test: add_node_by_path: cmd_ut_fdt_overlay.c + Test: add_node_by_phandle: cmd_ut_fdt_overlay.c + Test: add_str_property: cmd_ut_fdt_overlay.c + Test: add_subnode_property: cmd_ut_fdt_overlay.c + Test: change_int_property: cmd_ut_fdt_overlay.c + Test: change_str_property: cmd_ut_fdt_overlay.c + Test: local_phandle: cmd_ut_fdt_overlay.c + Test: local_phandles: cmd_ut_fdt_overlay.c + Test: stacked: cmd_ut_fdt_overlay.c + Tests run: 10, 12 ms, average: 1 ms, failures: 0 + Suites run: 3, total tests run: 37, 26 ms, average: 0 ms, failures: 0 + Average test time: 0 ms, worst case 'mem' took 1 ms diff --git a/doc/usage/cmd/wget.rst b/doc/usage/cmd/wget.rst index 48bedf1e845..cc82e495a29 100644 --- a/doc/usage/cmd/wget.rst +++ b/doc/usage/cmd/wget.rst @@ -12,7 +12,9 @@ Synopsis :: wget [address] [host:]path - wget [address] url # lwIP only + wget [address] url # lwIP only + wget cacert none|optional|required # lwIP only + wget cacert <address> <size> # lwIP only Description @@ -54,6 +56,32 @@ address url HTTP or HTTPS URL, that is: http[s]://<host>[:<port>]/<path>. +The cacert (stands for 'Certification Authority certificates') subcommand is +used to provide root certificates for the purpose of HTTPS authentication. It +also allows to enable or disable authentication. + +wget cacert <address> <size> + +address + memory address of the root certificates in X509 DER format + +size + the size of the root certificates + +wget cacert none|optional|required + +none + certificate verification is disabled. HTTPS is used without any server + authentication (unsafe) +optional + certificate verification is enabled provided root certificates have been + provided via wget cacert <addr> <size> or wget cacert builtin. Otherwise + HTTPS is used without any server authentication (unsafe). +required + certificate verification is mandatory. If no root certificates have been + configured, HTTPS transfers will fail. + + Examples -------- @@ -97,11 +125,61 @@ In the example the following steps are executed: 1694892032 bytes transferred in 492181 ms (3.3 MiB/s) Bytes transferred = 1694892032 (65060000 hex) +Here is an example showing how to configure built-in root certificates as +well as providing some at run time. In this example it is assumed that +CONFIG_WGET_BUILTIN_CACERT_PATH=DigiCertTLSRSA4096RootG5.crt downloaded from +https://cacerts.digicert.com/DigiCertTLSRSA4096RootG5.crt. + +:: + + # Make sure IP is configured + => dhcp + # When built-in certificates are configured, authentication is mandatory + # (i.e., "wget cacert required"). Use a test server... + => wget https://digicert-tls-rsa4096-root-g5.chain-demos.digicert.com/ + 1864 bytes transferred in 1 ms (1.8 MiB/s) + Bytes transferred = 1864 (748 hex) + # Another server not signed against Digicert will fail + => wget https://www.google.com/ + Certificate verification failed + + HTTP client error 4 + # Disable authentication to allow the command to proceed anyways + => wget cacert none + => wget https://www.google.com/ + WARNING: no CA certificates, HTTPS connections not authenticated + 16683 bytes transferred in 15 ms (1.1 MiB/s) + Bytes transferred = 16683 (412b hex) + # Force verification but unregister the CA certificates + => wget cacert required + => wget cacert 0 0 + # Unsurprisingly, download fails + => wget https://digicert-tls-rsa4096-root-g5.chain-demos.digicert.com/ + Error: cacert authentication mode is 'required' but no CA certificates given + # Get the same certificates as above from the network + => wget cacert none + => wget https://cacerts.digicert.com/DigiCertTLSRSA4096RootG5.crt + WARNING: no CA certificates, HTTPS connections not authenticated + 1386 bytes transferred in 1 ms (1.3 MiB/s) + Bytes transferred = 1386 (56a hex) + # Register them and force authentication + => wget cacert $fileaddr $filesize + => wget cacert required + # Authentication is operational again + => wget https://digicert-tls-rsa4096-root-g5.chain-demos.digicert.com/ + 1864 bytes transferred in 1 ms (1.8 MiB/s) + Bytes transferred = 1864 (748 hex) + # The builtin certificates can be restored at any time + => wget cacert builtin + Configuration ------------- The command is only available if CONFIG_CMD_WGET=y. -To enable lwIP support set CONFIG_NET_LWIP=y. +To enable lwIP support set CONFIG_NET_LWIP=y. In this case, root certificates +support can be enabled via CONFIG_WGET_BUILTIN_CACERT=y +CONFIG_WGET_BUILTIN_CACERT_PATH=<some path> (for built-in certificates) and/or +CONFIG_WGET_CACERT=y (for the wget cacert command). TCP Selective Acknowledgments in the legacy network stack can be enabled via CONFIG_PROT_TCP_SACK=y. This will improve the download speed. Selective diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst index 30fc16794fc..7e2f2863d06 100644 --- a/doc/usage/environment.rst +++ b/doc/usage/environment.rst @@ -87,6 +87,18 @@ settings. For example:: #include <env/ti/mmc.env> +Quotes are not suppressed, for example:: + + fdtfile=CONFIG_DEFAULT_DEVICE_TREE.dtb + # produces: fdtfile="sun7i-a20-pcduino3.dtb" + +For this particular issue you can use ``DEFAULT_DEVICE_TREE`` instead:: + + fdtfile=DEFAULT_DEVICE_TREE.dtb + # produces: fdtfile=sun7i-a20-pcduino3.dtb + +There is no general way to remove quotes. + If CONFIG_ENV_SOURCE_FILE is empty and the default filename is not present, then the old-style C environment is used instead. See below. diff --git a/doc/usage/index.rst b/doc/usage/index.rst index bf2335dc8f0..fc058476f39 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -93,6 +93,7 @@ Shell commands cmd/msr cmd/mtest cmd/mtrr + cmd/mv cmd/optee cmd/panic cmd/part |