diff options
author | Tom Rini <trini@konsulko.com> | 2023-01-20 22:23:20 +0300 |
---|---|---|
committer | Tom Rini <trini@konsulko.com> | 2023-01-20 22:23:20 +0300 |
commit | dd31cd58b02729807934cb699b164b1f8736620f (patch) | |
tree | 58d933861545e5950932f2911109610b98397a8e /doc/usage | |
parent | 0b9b01517f0b1398ec27dbb47faf3645b719e02c (diff) | |
parent | e10fffe8b56f4430e0e242977bfa67ab589b8235 (diff) | |
download | u-boot-dd31cd58b02729807934cb699b164b1f8736620f.tar.xz |
Merge tag 'efi-2023-04-rc1-2' of https://source.denx.de/u-boot/custodians/u-boot-efi
Pull request for efi-2023-04-rc1-2
Documentation
* man-pages for source, blkcache, bdinfo
* fix references to distro documentation
UEFI:
* allow clear screen by scrolling
* ensure that file ubootefi.var is created
* fix CapsuleMax variable reporting
Others:
* reduce verbosity of fat_read_file()
Diffstat (limited to 'doc/usage')
-rw-r--r-- | doc/usage/cmd/bdinfo.rst | 119 | ||||
-rw-r--r-- | doc/usage/cmd/blkcache.rst | 74 | ||||
-rw-r--r-- | doc/usage/cmd/source.rst | 193 | ||||
-rw-r--r-- | doc/usage/index.rst | 3 |
4 files changed, 389 insertions, 0 deletions
diff --git a/doc/usage/cmd/bdinfo.rst b/doc/usage/cmd/bdinfo.rst new file mode 100644 index 0000000000..6b3cde2ccb --- /dev/null +++ b/doc/usage/cmd/bdinfo.rst @@ -0,0 +1,119 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2023, Heinrich Schuchardt <heinrich.schuchardt@canonical.com> + +bdinfo command +============== + +Synopsis +-------- + +:: + + bdinfo + +Description +----------- + +The *bdinfo* command prints information about the board. + +Example +======= + +:: + + => bdinfo + boot_params = 0x0000000000000000 + DRAM bank = 0x0000000000000000 + -> start = 0x0000000040000000 + -> size = 0x0000000100000000 + flashstart = 0x0000000000000000 + flashsize = 0x0000000004000000 + flashoffset = 0x00000000000e87f8 + baudrate = 115200 bps + relocaddr = 0x000000013fefb000 + reloc off = 0x000000013fefb000 + Build = 64-bit + current eth = virtio-net#32 + ethaddr = 52:52:52:52:52:52 + IP addr = 10.0.2.15 + fdt_blob = 0x000000013edbadb0 + new_fdt = 0x000000013edbadb0 + fdt_size = 0x0000000000100000 + lmb_dump_all: + memory.cnt = 0x1 + memory[0] [0x40000000-0x13fffffff], 0x100000000 bytes flags: 0 + reserved.cnt = 0x2 + reserved[0] [0x13ddb3000-0x13fffffff], 0x0224d000 bytes flags: 0 + reserved[1] [0x13edb6930-0x13fffffff], 0x012496d0 bytes flags: 0 + devicetree = board + arch_number = 0x0000000000000000 + TLB addr = 0x000000013fff0000 + irq_sp = 0x000000013edbada0 + sp start = 0x000000013edbada0 + Early malloc usage: 3a8 / 2000 + => + +boot_params + address of the memory area for boot parameters + +DRAM bank + index, start address and end address of a memory bank + +baudrate + baud rate of the serial console + +relocaddr + address to which U-Boot has relocated itself + +reloc off + relocation offset, difference between *relocaddr* and the text base + +Build + bitness of the system + +current eth + name of the active network device + +IP addr + network address, value of the environment variable *ipaddr* + +fdt_blob + address of U-Boot's own device tree, NULL if none + +new_fdt + location of the relocated device tree + +fdt_size + space reserved for relocated device space + +lmb_dump_all + available memory and memory reservations + +devicetree + source of the device-tree + +arch_number + unique id for the board + +TLB addr + address of the translation lookaside buffer + +irq_sp + address of the IRQ stack pointer + +sp start + initial stack pointer address + +Early malloc usage + amount of memory used in the early malloc memory and its maximum size + as defined by CONFIGSYS_MALLOC_F_LEN + +Configuration +------------- + +The bdinfo command is available if CONFIG_CMD_BDI=y. + +Return code +----------- + +The return code $? is 0 (true). diff --git a/doc/usage/cmd/blkcache.rst b/doc/usage/cmd/blkcache.rst new file mode 100644 index 0000000000..d3b2254cfa --- /dev/null +++ b/doc/usage/cmd/blkcache.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2023, Heinrich Schuchardt <heinrich.schuchardt@canonical.com> + +blkcache command +================ + +Synopsis +-------- + +:: + + blkcache show + blkcache configure <blocks> <entries> + +Description +----------- + +The *blkcache* command is used to control the size of the block cache and to +display statistics. + +The block cache buffers data read from block devices. This speeds up the access +to file-systems. + +show + show and reset statistics + +configure + set the maximum number of cache entries and the maximum number of blocks per + entry + +blocks + maximum number of blocks per cache entry. The block size is device specific. + The initial value is 8. + +entries + maximum number of entries in the cche. The initial value is 32. + +Example +------- + +.. code-block:: + + => blkcache show + hits: 296 + misses: 149 + entries: 7 + max blocks/entry: 8 + max cache entries: 32 + => blkcache show + hits: 0 + misses: 0 + entries: 7 + max blocks/entry: 8 + max cache entries: 32 + => blkcache configure 16 64 + changed to max of 64 entries of 16 blocks each + => blkcache show + hits: 0 + misses: 0 + entries: 0 + max blocks/entry: 16 + max cache entries: 64 + => + +Configuration +------------- + +The blkcache command is only available if CONFIG_CMD_BLOCK_CACHE=y. + +Return code +----------- + +If the command succeeds, the return code $? is set 0 (true). In case of an +error the return code is set to 1 (false). diff --git a/doc/usage/cmd/source.rst b/doc/usage/cmd/source.rst new file mode 100644 index 0000000000..61a4505909 --- /dev/null +++ b/doc/usage/cmd/source.rst @@ -0,0 +1,193 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2022, Heinrich Schuchardt <xypron.glpk@gmx.de> + +source command +============== + +Synopsis +-------- + +:: + + source [<addr>][:[<image>]|#[<config>]] + +Description +----------- + +The *source* command is used to execute a script file from memory. + +Two formats for script files exist: + +* legacy U-Boot image format +* Flat Image Tree (FIT) + +The benefit of the FIT images is that they can be signed and verifed as +decribed in :download:`signature.txt <../../uImage.FIT/signature.txt>`. + +Both formats can be created with the mkimage tool. + +addr + location of the script file in memory, defaults to CONFIG_SYS_LOAD_ADDR. + +image + name of an image in a FIT file + +config + name of a configuration in a FIT file. A hash sign following white space + starts a comment. Hence, if no *addr* is specified, the hash sign has to be + escaped with a backslash or the argument must be quoted. + +If both *image* and *config* are omitted, the default configuration is used, or +if no configuration is defined, the default image. + +Examples +-------- + +FIT image +''''''''' + +For creating a FIT image an image tree source file (\*.its) is needed. Here is +an example (source.its). + +.. code-block:: + + /dts-v1/; + + / { + description = "FIT image to test the source command"; + #address-cells = <1>; + + images { + default = "script-1"; + + script-1 { + data = "echo 1"; + type = "script"; + compression = "none"; + }; + + script-2 { + data = "echo 2"; + type = "script"; + compression = "none"; + }; + }; + + configurations { + default = "conf-2"; + + conf-1 { + script = "script-1"; + }; + + conf-2 { + script = "script-2"; + }; + }; + }; + +The FIT image file (boot.itb) is created with: + +.. code-block:: bash + + mkimage -f source.its boot.itb + +In U-Boot the script can be loaded and execute like this + +.. code-block:: + + => load host 0:1 $loadaddr boot.itb + 1552 bytes read in 0 ms + => source $loadaddr#conf-1 + ## Executing script at 00000000 + 1 + => source $loadaddr#conf-2 + ## Executing script at 00000000 + 2 + => source $loadaddr:script-1 + ## Executing script at 00000000 + 1 + => source $loadaddr:script-2 + ## Executing script at 00000000 + 2 + => source $loadaddr + ## Executing script at 00000000 + 2 + => source \#conf-1 + ## Executing script at 00000000 + 1 + => source '#conf-1' + ## Executing script at 00000000 + 1 + => source ':script-1' + ## Executing script at 00000000 + 1 + => source + ## Executing script at 00000000 + 2 + => + +Instead of specifying command line instructions directly in the *data* property +of the image tree source file another file can be included. Here is a minimal +example which encapsulates the file boot.txt: + +.. code-block:: + + /dts-v1/; + / { + description = ""; + images { + script { + data = /incbin/("./boot.txt"); + type = "script"; + }; + }; + }; + +Legacy U-Boot image +''''''''''''''''''' + +A script file using the legacy U-Boot image file format can be created based on +a text file. Let's use this example text file (boot.txt): + +.. code-block:: bash + + echo Hello from a script + echo ------------------- + +The boot scripts (boot.scr) is created with: + +.. code-block:: bash + + mkimage -T script -n 'Test script' -d boot.txt boot.scr + +The script can be execute in U-boot like this: + +.. code-block:: + + => load host 0:1 $loadaddr boot.scr + 122 bytes read in 0 ms + => source $loadaddr + ## Executing script at 00000000 + Hello from a script + ------------------- + => source + ## Executing script at 00000000 + Hello from a script + ------------------- + => + +Configuration +------------- + +The source command is only available if CONFIG_CMD_SOURCE=y. +The FIT image file format requires CONFIG_FIT=y.# +The legacy U-Boot image file format requires CONFIG_LEGACY_IMAGE_FORMAT=y. +On hardened systems support for the legacy U-Boot image format should be +disabled as these images cannot be signed and verified. + +Return value +------------ + +If the scripts is executed successfully, the return value $? is 0 (true). +Otherwise it is 1 (false). diff --git a/doc/usage/index.rst b/doc/usage/index.rst index cf3666a77d..7d4a1cbc10 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -23,6 +23,8 @@ Shell commands cmd/addrmap cmd/askenv cmd/base + cmd/bdinfo + cmd/blkcache cmd/bootd cmd/bootdev cmd/bootefi @@ -75,6 +77,7 @@ Shell commands cmd/setexpr cmd/size cmd/sound + cmd/source cmd/temperature cmd/tftpput cmd/true |