summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorTom Rini <trini@konsulko.com>2023-01-20 22:23:20 +0300
committerTom Rini <trini@konsulko.com>2023-01-20 22:23:20 +0300
commitdd31cd58b02729807934cb699b164b1f8736620f (patch)
tree58d933861545e5950932f2911109610b98397a8e /doc
parent0b9b01517f0b1398ec27dbb47faf3645b719e02c (diff)
parente10fffe8b56f4430e0e242977bfa67ab589b8235 (diff)
downloadu-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.gpt2
-rw-r--r--doc/README.uniphier2
-rw-r--r--doc/board/emulation/qemu-x86.rst3
-rw-r--r--doc/board/st/stm32mp1.rst2
-rw-r--r--doc/board/tbs/tbs2910.rst2
-rw-r--r--doc/usage/cmd/bdinfo.rst119
-rw-r--r--doc/usage/cmd/blkcache.rst74
-rw-r--r--doc/usage/cmd/source.rst193
-rw-r--r--doc/usage/index.rst3
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