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 | |
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')
-rw-r--r-- | doc/README.gpt | 2 | ||||
-rw-r--r-- | doc/README.uniphier | 2 | ||||
-rw-r--r-- | doc/board/emulation/qemu-x86.rst | 3 | ||||
-rw-r--r-- | doc/board/st/stm32mp1.rst | 2 | ||||
-rw-r--r-- | doc/board/tbs/tbs2910.rst | 2 | ||||
-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 |
9 files changed, 395 insertions, 5 deletions
diff --git a/doc/README.gpt b/doc/README.gpt index cc2a1b7ac7..386ac2e0fc 100644 --- a/doc/README.gpt +++ b/doc/README.gpt @@ -177,7 +177,7 @@ To restore GUID partition table one needs to: "name=u-boot,size=60MiB;name=boot,size=60Mib,bootable;name=rootfs,size=0" It can be used to locate bootable disks with command "part list <interface> <dev> -bootable <varname>", - please check out doc/README.distro for use. + please check out doc/develop/distro.rst for use. 2. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT' diff --git a/doc/README.uniphier b/doc/README.uniphier index badfacd66a..af746f6c31 100644 --- a/doc/README.uniphier +++ b/doc/README.uniphier @@ -336,7 +336,7 @@ Deployment for Distro Boot -------------------------- UniPhier SoC family boot the kernel in a generic manner as described in -doc/README.distro . +doc/develop/distro.rst. To boot the kernel, you need to deploy necesssary components to a file system on one of your block devices (eMMC, NAND, USB drive, etc.). diff --git a/doc/board/emulation/qemu-x86.rst b/doc/board/emulation/qemu-x86.rst index db842f2ece..e7dd4e994d 100644 --- a/doc/board/emulation/qemu-x86.rst +++ b/doc/board/emulation/qemu-x86.rst @@ -57,7 +57,8 @@ to instantiate. Note, the maximum supported CPU number in QEMU is 255. U-Boot uses 'distro_bootcmd' by default when booting on x86 QEMU. This tries to load a boot script, kernel, and ramdisk from several different interfaces. For the default boot order, see 'qemu-x86.h'. For more information, see -'README.distro'. Most Linux distros can be booted by writing a uboot script. +'doc/develop/distro.rst'. Most Linux distros can be booted by writing a uboot +script. For example, Debian (stretch) can be booted by creating a script file named 'boot.txt' with the contents:: diff --git a/doc/board/st/stm32mp1.rst b/doc/board/st/stm32mp1.rst index 9780ac9768..3f70634d28 100644 --- a/doc/board/st/stm32mp1.rst +++ b/doc/board/st/stm32mp1.rst @@ -478,7 +478,7 @@ or: +-------+--------+---------+------------------------+------------------------+ And the 4th partition (Rootfs) is marked bootable with a file extlinux.conf -following the Generic Distribution feature (doc/README.distro for use). +following the Generic Distribution feature (doc/develop/distro.rst for use). The size of fip or ssbl partition must be enough for the associated binary file, 4MB and 2MB are default values. diff --git a/doc/board/tbs/tbs2910.rst b/doc/board/tbs/tbs2910.rst index e97f2b6e61..9d4be61783 100644 --- a/doc/board/tbs/tbs2910.rst +++ b/doc/board/tbs/tbs2910.rst @@ -181,7 +181,7 @@ If that fails it will then try to boot from several interfaces using 'distro_bootcmd': It will first try to boot from the microSD slot, then the SD slot, then the internal eMMC, then the SATA interface and finally the USB interface. For more information on how to configure your distribution to boot, -see 'README.distro'. +see 'doc/develop/distro.rst'. Links: ------ 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 |