diff options
Diffstat (limited to 'doc/usage')
132 files changed, 16153 insertions, 0 deletions
diff --git a/doc/usage/blkmap.rst b/doc/usage/blkmap.rst new file mode 100644 index 00000000000..7337ea507a1 --- /dev/null +++ b/doc/usage/blkmap.rst @@ -0,0 +1,111 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. +.. Copyright (c) 2023 Addiva Elektronik +.. Author: Tobias Waldekranz <tobias@waldekranz.com> + +Block Maps (blkmap) +=================== + +Block maps are a way of looking at various sources of data through the +lens of a regular block device. It lets you treat devices that are not +block devices, like RAM, as if they were. It also lets you export a +slice of an existing block device, which does not have to correspond +to a partition boundary, as a new block device. + +This is primarily useful because U-Boot's filesystem drivers only +operate on block devices, so a block map lets you access filesystems +wherever they might be located. + +The implementation is loosely modeled on Linux's "Device Mapper" +subsystem, see `kernel documentation`_ for more information. + +.. _kernel documentation: https://www.kernel.org/doc/html/latest/admin-guide/device-mapper/index.html + + +Example: Netbooting an Ext4 Image +--------------------------------- + +Say that our system is using an Ext4 filesystem as its rootfs, where +the kernel is stored in ``/boot``. This image is then typically stored +in an eMMC partition. In this configuration, we can use something like +``load mmc 0 ${kernel_addr_r} /boot/Image`` to load the kernel image +into the expected location, and then boot the system. No problems. + +Now imagine that during development, or as a recovery mechanism, we +want to boot the same type of image by downloading it over the +network. Getting the image to the target is easy enough: + +:: + + dhcp ${ramdisk_addr_r} rootfs.ext4 + +But now we are faced with a predicament: how to we extract the kernel +image? Block maps to the rescue! + +We start by creating a new device: + +:: + + blkmap create netboot + +Before setting up the mapping, we figure out the size of the +downloaded file, in blocks: + +:: + + setexpr fileblks ${filesize} + 0x1ff + setexpr fileblks ${filesize} / 0x200 + +Then we can add a mapping to the start of our device, backed by the +memory at `${loadaddr}`: + +:: + + blkmap map netboot 0 ${fileblks} mem ${fileaddr} + +Now we can access the filesystem via the virtual device: + +:: + + blkmap get netboot dev devnum + load blkmap ${devnum} ${kernel_addr_r} /boot/Image + + +Example: Accessing a filesystem inside an FIT image +--------------------------------------------------- + +In this example, an FIT image is stored in an eMMC partition. We would +like to read the file ``/etc/version``, stored inside a Squashfs image +in the FIT. Since the Squashfs image is not stored on a partition +boundary, there is no way of accessing it via ``load mmc ...``. + +What we can to instead is to first figure out the offset and size of +the filesystem: + +:: + + mmc dev 0 + mmc read ${loadaddr} 0 0x100 + + fdt addr ${loadaddr} + fdt get value squashaddr /images/ramdisk data-position + fdt get value squashsize /images/ramdisk data-size + + setexpr squashblk ${squashaddr} / 0x200 + setexpr squashsize ${squashsize} + 0x1ff + setexpr squashsize ${squashsize} / 0x200 + +Then we can create a block map that maps to that slice of the full +partition: + +:: + + blkmap create sq + blkmap map sq 0 ${squashsize} linear mmc 0 ${squashblk} + +Now we can access the filesystem: + +:: + + blkmap get sq dev devnum + load blkmap ${devnum} ${loadaddr} /etc/version diff --git a/doc/usage/cmd/acpi.rst b/doc/usage/cmd/acpi.rst new file mode 100644 index 00000000000..9f30972fe53 --- /dev/null +++ b/doc/usage/cmd/acpi.rst @@ -0,0 +1,263 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: acpi (command) + +acpi command +============ + +Synopsis +-------- + +:: + + acpi list + acpi items [-d] + acpi dump <name> + acpi set <address> + +Description +----------- + +The *acpi* command is used to dump the ACPI tables generated by U-Boot for +passing to the operating systems. It allows manually setting the address to take +a look at existing ACPI tables. + +ACPI tables can be generated by various output functions and even devices can +output material to include in the Differentiated System Description Table (DSDT) +and SSDT tables (Secondary System Description Table). U-Boot keeps track of +which device or table-writer produced each piece of the ACPI tables. + +The ACPI tables are stored contiguously in memory. + + +acpi list +~~~~~~~~~ + +List the ACPI tables that have been generated. Each table has a 4-character +table name (e.g. SSDT, FACS) and has a format defined by the +`ACPI specification`_. + +U-Boot does not currently support decoding the tables. Unlike devicetree, ACPI +tables have no regular schema and also some include bytecode, so decoding the +tables requires a lot of code. + +The table shows the following information: + +Name + Table name, e.g. `MCFG` + +Base + Base address of table in memory + +Size + Size of table in bytes + +Detail + More information depending on the table type + + Revision + Table revision number (two decimal digits) + + OEM ID + ID for the Original Equipment Manufacturer. Typically this is "U-BOOT". + + OEM Table ID + Table ID for the Original Equipment Manufacturer. Typically this is + "U-BOOTBL" (U-Boot bootloader) + + OEM Revision + Revision string for the Original Equipment Manufacturer. Typically this + is the U-Boot release number, e.g. 20220101 (meaning v2022.01 since the + final 01 is not used). For DSDT, this is set by the source code in + the parameters of DefinitionBlock(). + + ACPI compiler-vendor ID + This is normally `INTL` for Intel + + ACPI compiler revision + This is the compiler revision. It is set to the version string for the + DSDT table but other tables just use the value 0 or 1, since U-Boot does + not actually use the compiler in these cases. It generates the code + itself. + +acpi items +~~~~~~~~~~ + +List the ACPI data that was generated, broken down by item. An item is either +an ACPI table generated by a writer function, or the part of a table that was +generated by a particular device. + +The `-d` flag also shows a binary dump of the table. + +The table shows the following information about each item: + +Seq + Sequence number in hex + +Type + Type of item + + ===== ============================================================ + Type Meaning + ===== ============================================================ + dsdt Fragment of a DSDT table, as generated by a device + ssdt Fragment of a SSDT table, as generated by a device + other A whole table of a particular type. as generated by a writer + ===== ============================================================ + +Base + Base address of table in memory + +Size + Size of table in bytes + +Device / Writer + Name of device (for ssdt/dsdt) that wrong this fragment of the table, or + name of the registered writer function (otherwise) that wrote the table. + +acpi dump +~~~~~~~~~ + +Dump a paticular ACPI table in binary format. This can be used to read the table +if you have the specification handy. + + +Example +------- + +:: + + => acpi list + Name Base Size Detail + ---- -------- ----- ------ + RSDP 79925000 24 v02 U-BOOT + RSDT 79925030 48 v01 U-BOOT U-BOOTBL 20220101 INTL 0 + XSDT 799250e0 6c v01 U-BOOT U-BOOTBL 20220101 INTL 0 + FACP 79929570 f4 v04 U-BOOT U-BOOTBL 20220101 INTL 1 + DSDT 79925280 32ea v02 U-BOOT U-BOOTBL 20110725 INTL 20180105 + FACS 79925240 40 + MCFG 79929670 2c v01 U-BOOT U-BOOTBL 20220101 INTL 0 + SPCR 799296a0 50 v02 U-BOOT U-BOOTBL 20220101 INTL 0 + TPM2 799296f0 4c v04 U-BOOT U-BOOTBL 20220101 INTL 0 + APIC 79929740 6c v02 U-BOOT U-BOOTBL 20220101 INTL 0 + SSDT 799297b0 1523 v02 U-BOOT U-BOOTBL 20220101 INTL 1 + NHLT 7992ace0 e60 v05 coral coral 3 INTL 0 + DBG2 7992db40 61 v00 U-BOOT U-BOOTBL 20220101 INTL 0 + HPET 7992dbb0 38 v01 U-BOOT U-BOOTBL 20220101 INTL 0 + => acpi items + Seq Type Base Size Device/Writer + --- ----- -------- ---- ------------- + 0 other 79925000 240 0base + 1 other 79925240 40 1facs + 2 dsdt 799252a4 58 board + 3 dsdt 799252fc 10 lpc + 4 other 79925280 32f0 3dsdt + 5 other 79928570 1000 4gnvs + 6 other 79929570 100 5fact + 7 other 79929670 30 5mcfg + 8 other 799296a0 50 5spcr + 9 other 799296f0 50 5tpm2 + a other 79929740 70 5x86 + b ssdt 799297d4 fe maxim-codec + c ssdt 799298d2 28 i2c2@16,0 + d ssdt 799298fa 270 da-codec + e ssdt 79929b6a 28 i2c2@16,1 + f ssdt 79929b92 28 i2c2@16,2 + 10 ssdt 79929bba 83 tpm@50 + 11 ssdt 79929c3d 28 i2c2@16,3 + 12 ssdt 79929c65 282 elan-touchscreen@10 + 13 ssdt 79929ee7 285 raydium-touchscreen@39 + 14 ssdt 7992a16c 28 i2c2@17,0 + 15 ssdt 7992a194 d8 elan-touchpad@15 + 16 ssdt 7992a26c 163 synaptics-touchpad@2c + 17 ssdt 7992a3cf 28 i2c2@17,1 + 18 ssdt 7992a3f7 111 wacom-digitizer@9 + 19 ssdt 7992a508 8f sdmmc@1b,0 + 1a ssdt 7992a597 4b wifi + 1b ssdt 7992a5e2 1a0 cpu@0 + 1c ssdt 7992a782 1a0 cpu@1 + 1d ssdt 7992a922 1a0 cpu@2 + 1e ssdt 7992aac2 211 cpu@3 + 1f other 799297b0 1530 6ssdt + 20 other 7992ace0 2f10 8dev + => acpi dump mcfg + MCFG @ 79929670 + 00000000: 4d 43 46 47 2c 00 00 00 01 41 55 2d 42 4f 4f 54 MCFG,....AU-BOOT + 00000010: 55 2d 42 4f 4f 54 42 4c 01 01 22 20 49 4e 54 4c U-BOOTBL.." INTL + 00000020: 00 00 00 00 00 00 00 00 00 00 00 00 ............ + => acpi items -d + Seq Type Base Size Device/Writer + --- ----- -------- ---- ------------- + 0 other 79925000 240 0base + 00000000: 52 53 44 20 50 54 52 20 9e 55 2d 42 4f 4f 54 02 RSD PTR .U-BOOT. + 00000010: 30 50 92 79 24 00 00 00 e0 50 92 79 00 00 00 00 0P.y$....P.y.... + 00000020: a1 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000030: 52 53 44 54 48 00 00 00 01 8b 55 2d 42 4f 4f 54 RSDTH.....U-BOOT + 00000040: 55 2d 42 4f 4f 54 42 4c 01 01 22 20 49 4e 54 4c U-BOOTBL.." INTL + 00000050: 00 00 00 00 70 95 92 79 70 96 92 79 a0 96 92 79 ....p..yp..y...y + 00000060: f0 96 92 79 40 97 92 79 b0 97 92 79 e0 ac 92 79 ...y@..y...y...y + 00000070: 40 db 92 79 b0 db 92 79 00 00 00 00 00 00 00 00 @..y...y........ + 00000080: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000090: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 000000a0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 000000b0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 000000c0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 000000d0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 000000e0: 58 53 44 54 6c 00 00 00 01 61 55 2d 42 4f 4f 54 XSDTl....aU-BOOT + 000000f0: 55 2d 42 4f 4f 54 42 4c 01 01 22 20 49 4e 54 4c U-BOOTBL.." INTL + 00000100: 00 00 00 00 70 95 92 79 00 00 00 00 70 96 92 79 ....p..y....p..y + 00000110: 00 00 00 00 a0 96 92 79 00 00 00 00 f0 96 92 79 .......y.......y + 00000120: 00 00 00 00 40 97 92 79 00 00 00 00 b0 97 92 79 ....@..y.......y + 00000130: 00 00 00 00 e0 ac 92 79 00 00 00 00 40 db 92 79 .......y....@..y + 00000140: 00 00 00 00 b0 db 92 79 00 00 00 00 00 00 00 00 .......y........ + 00000150: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000160: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + ... + + 1 other 79925240 40 1facs + 00000000: 46 41 43 53 40 00 00 00 00 00 00 00 00 00 00 00 FACS@........... + 00000010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000020: 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + + 2 dsdt 799252a4 58 board + 00000000: 10 87 05 00 5c 00 08 4f 49 50 47 12 8c 04 00 03 ....\..OIPG..... + 00000010: 12 8b 01 00 04 01 01 0e ff ff ff ff ff ff ff ff ................ + 00000020: 0d 49 4e 54 33 34 35 32 3a 30 31 00 12 85 01 00 .INT3452:01..... + 00000030: 04 0a 03 01 0a 23 0d 49 4e 54 33 34 35 32 3a 30 .....#.INT3452:0 + 00000040: 31 00 12 85 01 00 04 0a 04 01 0a 0a 0d 49 4e 54 1............INT + 00000050: 33 34 35 32 3a 30 30 00 3452:00. + + 3 dsdt 799252fc 10 lpc + 00000000: 10 8f 00 00 5c 00 08 4e 56 53 41 0c 10 50 93 79 ....\..NVSA..P.y + + 4 other 79925280 32f0 3dsdt + 00000000: 44 53 44 54 ea 32 00 00 02 eb 55 2d 42 4f 4f 54 DSDT.2....U-BOOT + 00000010: 55 2d 42 4f 4f 54 42 4c 25 07 11 20 49 4e 54 4c U-BOOTBL%.. INTL + +This shows searching for tables in a known area of memory, then setting the +pointer:: + + => acpi list + No ACPI tables present + => ms.s bff00000 80000 "RSD PTR" + bff75000: 52 53 44 20 50 54 52 20 cf 42 4f 43 48 53 20 00 RSD PTR .BOCHS . + 1 match + => acpi set bff75000 + Setting ACPI pointer to bff75000 + => acpi list + Name Base Size Detail + ---- -------- ----- ------ + RSDP bff75000 0 v00 BOCHS + RSDT bff76a63 38 v01 BOCHS BXPC 1 BXPC 1 + FACP bff768ff 74 v01 BOCHS BXPC 1 BXPC 1 + DSDT bff75080 187f v01 BOCHS BXPC 1 BXPC 1 + FACS bff75040 40 + APIC bff76973 90 v01 BOCHS BXPC 1 BXPC 1 + HPET bff76a03 38 v01 BOCHS BXPC 1 BXPC 1 + WAET bff76a3b 28 v01 BOCHS BXPC 1 BXPC 1 + SSDT bff95040 c5 v02 COREv4 COREBOOT 2a CORE 20221020 + + +.. _`ACPI specification`: https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf diff --git a/doc/usage/cmd/addrmap.rst b/doc/usage/cmd/addrmap.rst new file mode 100644 index 00000000000..6d0dbceefea --- /dev/null +++ b/doc/usage/cmd/addrmap.rst @@ -0,0 +1,44 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: addrmap (command) + +addrmap command +=============== + +Synopsis +-------- + +:: + + addrmap + +Description +----------- + +The addrmap command is used to display non-identity virtual-physical memory +mappings for 32-bit CPUs. + +The output may look like: + +:: + + => addrmap + vaddr paddr size + ================ ================ ================ + e0000000 fe0000000 00100000 + 00000000 00000000 04000000 + 04000000 04000000 04000000 + 80000000 c00000000 10000000 + 90000000 c10000000 10000000 + a0000000 fe1000000 00010000 + +The first column indicates the virtual address. +The second column indicates the physical address. +The third column indicates the mapped size. + +Configuration +------------- + +To use the addrmap command you must specify CONFIG_CMD_ADDRMAP=y. +It is automatically turned on when CONFIG_ADDR_MAP is set. diff --git a/doc/usage/cmd/armffa.rst b/doc/usage/cmd/armffa.rst new file mode 100644 index 00000000000..4f41e3393fd --- /dev/null +++ b/doc/usage/cmd/armffa.rst @@ -0,0 +1,97 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2022-2023 Arm Limited and/or its affiliates <open-source-office@arm.com> + +.. index:: + single: armffa (command) + +armffa command +============== + +Synopsis +-------- + +:: + + armffa [sub-command] [arguments] + + sub-commands: + + getpart [partition UUID] + + lists the partition(s) info + + ping [partition ID] + + sends a data pattern to the specified partition + + devlist + + displays information about the FF-A device/driver + +Description +----------- + +armffa is a command showcasing how to use the FF-A bus and how to invoke its operations. + +This provides a guidance to the client developers on how to call the FF-A bus interfaces. + +The command also allows to gather secure partitions information and ping these partitions. + +The command is also helpful in testing the communication with secure partitions. + +Example +------- + +The following examples are run on Corstone-1000 platform. + +* ping + +:: + + corstone1000# armffa ping 0x8003 + SP response: + [LSB] + fffffffe + 0 + 0 + 0 + 0 + +* ping (failure case) + +:: + + corstone1000# armffa ping 0 + Sending direct request error (-22) + +* getpart + +:: + + corstone1000# armffa getpart 33d532ed-e699-0942-c09c-a798d9cd722d + Partition: id = 8003 , exec_ctxt 1 , properties 3 + +* getpart (failure case) + +:: + + corstone1000# armffa getpart 33d532ed-e699-0942-c09c-a798d9cd7221 + INVALID_PARAMETERS: Unrecognized UUID + Failure in querying partitions count (error code: -22) + +* devlist + +:: + + corstone1000# armffa devlist + device name arm_ffa, dev 00000000fdf41c30, driver name arm_ffa, ops 00000000fffc0e98 + +Configuration +------------- + +The command is available if CONFIG_CMD_ARMFFA=y and CONFIG_ARM_FFA_TRANSPORT=y. + +Return value +------------ + +The return value $? is 0 (true) on success, 1 (false) on failure. diff --git a/doc/usage/cmd/askenv.rst b/doc/usage/cmd/askenv.rst new file mode 100644 index 00000000000..e2b3c5379ae --- /dev/null +++ b/doc/usage/cmd/askenv.rst @@ -0,0 +1,92 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: askenv (command) + +askenv command +============== + +Synopsis +-------- + +:: + + askenv name [message] [size] + +Description +----------- + +Display message and get environment variable name of max size characters +from stdin. + +See also *env ask* in :doc:`env`. + +name + name of the environment variable + +message + message is displayed while the command waits for the value to be + entered from stdin.if no message is specified,a default message + "Please enter name:" will be displayed. + +size + maximum number of characters that will be stored in environment + variable name.this is in decimal number format (unlike in + other commands where size values are in hexa-decimal). Default + value of size is 1023 (CONFIG_SYS_CBSIZE - 1). + +Example +------- + +Value of a environment variable env1 without message and size parameters: + +:: + + => askenv env1;echo $? + Please enter 'env1': val1 + 0 + => printenv env1 + env1=val1 + +Value of a environment variable env2 with message and size parameters: + +:: + + => askenv env2 Please type-in a value for env2: 10;echo $? + Please type-in a value for env2: 1234567890123 + 0 + => printenv env2 + env2=1234567890 + +Value of a environment variable env3 with size parameter only: + +:: + + => askenv env3 10;echo $? + Please enter 'env3': val3 + 0 + => printenv env3 + env3=val3 + +Return Value of askenv command, when used without any other arguments: + +:: + + => askenv;echo $? + askenv - get environment variables from stdin + + Usage: + askenv name [message] [size] + - display 'message' and get environment variable 'name' from stdin (max 'size' chars) + 1 + +Configuration +------------- + +The askenv command is only available if CMD_ASKENV=y + +Return value +------------ + +The return value $? is set to 0 (true). +If no other arguments are specified (along with askenv), it is set to 1 (false). diff --git a/doc/usage/cmd/base.rst b/doc/usage/cmd/base.rst new file mode 100644 index 00000000000..0d030a1d1e0 --- /dev/null +++ b/doc/usage/cmd/base.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: base (command) + +base command +============ + +Synopsis +-------- + +:: + + base [address] + +Description +----------- + +The *base* command sets or displays the address offset used by the memory +commands *cmp, cp, md, mdc, mm, ms, mw, mwc*. + +All other commands ignore the address defined by *base*. + +address + new base address as hexadecimal number. If no value is provided, the current + value is displayed. diff --git a/doc/usage/cmd/bdinfo.rst b/doc/usage/cmd/bdinfo.rst new file mode 100644 index 00000000000..a21fbc83ccf --- /dev/null +++ b/doc/usage/cmd/bdinfo.rst @@ -0,0 +1,122 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2023, Heinrich Schuchardt <heinrich.schuchardt@canonical.com> + +.. index:: + single: bdinfo (command) + +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 CONFIG_SYS_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/bind.rst b/doc/usage/cmd/bind.rst new file mode 100644 index 00000000000..23457783666 --- /dev/null +++ b/doc/usage/cmd/bind.rst @@ -0,0 +1,106 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: bind (command) + +bind command +============ + +Synopsis +-------- + +:: + + bind <node path> <driver> + bind <class> <index> <driver> + +Description +----------- + +The bind command is used to bind a device to a driver. This makes the +device available in U-Boot. + +While binding to a *node path* typically provides a working device +binding by parent node and driver may lead to a device that is only +partially initialized. + +node path + path of the device's device-tree node + +class + device class name + +index + index of the parent device in the device class + +driver + device driver name + +Example +------- + +Given a system with a real time clock device with device path */pl031@9010000* +and using driver rtc-pl031 unbinding and binding of the device is demonstrated +using the two alternative bind syntaxes. + +.. code-block:: + + => dm tree + Class Index Probed Driver Name + ----------------------------------------------------------- + root 0 [ + ] root_driver root_driver + ... + rtc 0 [ ] rtc-pl031 |-- pl031@9010000 + ... + => fdt addr $fdtcontroladdr + Working FDT set to 7ed7fdb0 + => fdt print + / { + interrupt-parent = <0x00008003>; + model = "linux,dummy-virt"; + #size-cells = <0x00000002>; + #address-cells = <0x00000002>; + compatible = "linux,dummy-virt"; + ... + pl031@9010000 { + clock-names = "apb_pclk"; + clocks = <0x00008000>; + interrupts = <0x00000000 0x00000002 0x00000004>; + reg = <0x00000000 0x09010000 0x00000000 0x00001000>; + compatible = "arm,pl031", "arm,primecell"; + }; + ... + } + => unbind /pl031@9010000 + => date + Cannot find RTC: err=-19 + => dm tree + Class Index Probed Driver Name + ----------------------------------------------------------- + root 0 [ + ] root_driver root_driver + ... + => bind /pl031@9010000 rtc-pl031 + => dm tree + Class Index Probed Driver Name + ----------------------------------------------------------- + root 0 [ + ] root_driver root_driver + ... + rtc 0 [ ] rtc-pl031 |-- pl031@9010000 + => date + Date: 2023-06-22 (Thursday) Time: 15:14:51 + => unbind rtc 0 rtc-pl031 + => bind root 0 rtc-pl031 + => date + Date: 1980-08-19 (Tuesday) Time: 14:45:30 + +Obviously the device is not initialized correctly by the last bind command. + +Configuration +------------- + +The bind command is only available if CONFIG_CMD_BIND=y. + +Return code +----------- + +The return code $? is 0 (true) on success and 1 (false) on failure. diff --git a/doc/usage/cmd/blkcache.rst b/doc/usage/cmd/blkcache.rst new file mode 100644 index 00000000000..0329261ba9a --- /dev/null +++ b/doc/usage/cmd/blkcache.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2023, Heinrich Schuchardt <heinrich.schuchardt@canonical.com> + +.. index:: + single: blkcache (command) + +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/bootd.rst b/doc/usage/cmd/bootd.rst new file mode 100644 index 00000000000..619cfb601a0 --- /dev/null +++ b/doc/usage/cmd/bootd.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: bootd (command) + +bootd command +============= + +Synopsis +-------- + +:: + + bootd + +Description +----------- + +The bootd command executes the command stored in the environment variable +*bootcmd*, i.e. it does the same thing as *run bootcmd*. + +Example +------- + +:: + + => setenv bootcmd 'echo Hello World' + => bootd + Hello World + => setenv bootcmd true + => bootd; echo $? + 0 + => setenv bootcmd false + => bootd; echo $? + 1 + +Return value +------------ + +The return value $? of the bootd command is the return value of the command in +the environment variable *bootcmd*. diff --git a/doc/usage/cmd/bootdev.rst b/doc/usage/cmd/bootdev.rst new file mode 100644 index 00000000000..98a0f43c580 --- /dev/null +++ b/doc/usage/cmd/bootdev.rst @@ -0,0 +1,178 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: bootdev (command) + +bootdev command +=============== + +Synopsis +-------- + +:: + + bootdev list [-p] - list all available bootdevs (-p to probe) + bootdev hunt [-l|<spec>] - use hunt drivers to find bootdevs + bootdev select <bm> - select a bootdev by name + bootdev info [-p] - show information about a bootdev + +Description +----------- + +The `bootdev` command is used to manage bootdevs. It can list available +bootdevs, select one and obtain information about it. + +See :doc:`/develop/bootstd/index` for more information about bootdevs in general. + + +bootdev list +~~~~~~~~~~~~ + +This lists available bootdevs + +Scanning with `-p` causes the bootdevs to be probed. This happens automatically +when they are used. + +The list looks something like this: + +=== ====== ====== ======== ========================= +Seq Probed Status Uclass Name +=== ====== ====== ======== ========================= + 0 [ + ] OK mmc mmc@7e202000.bootdev + 1 [ ] OK mmc sdhci@7e300000.bootdev + 2 [ ] OK ethernet smsc95xx_eth.bootdev +=== ====== ====== ======== ========================= + + +The fields are as follows: + +Seq: + Sequence number in the scan, used to reference the bootflow later + +Probed: + Shows a plus (+) if the device is probed, empty if not. + +Status: + Shows the status of the device. Typically this is `OK` meaning that there is + no error. If you use -p and an error occurs when probing, then this shows + the error number. You can look up Linux error codes to find the meaning of + the number. + +Uclass: + Name of the media device's Uclass. This indicates the type of the parent + device (e.g. MMC, Ethernet). + +Name: + Name of the bootdev. This is generated from the media device appended + with `.bootdev` + + +bootdev hunt +~~~~~~~~~~~~ + +This hunts for new bootdevs, or shows a list of hunters. + +Use `-l` to list the available bootdev hunters. + +To run hunters, specify the name of the hunter to run, e.g. "mmc". If no +name is provided, all hunters are run. + + +bootdev select +~~~~~~~~~~~~~~ + +Use this to select a particular bootdev. You can select it by the sequence +number or name, as shown in `bootdev list`. + +Once a bootdev is selected, you can use `bootdev info` to look at it or +`bootflow scan` to scan it. + +If no bootdev name or number is provided, then any existing bootdev is +unselected. + + +bootdev info +~~~~~~~~~~~~ + +This shows information on the current bootdev, with the format looking like +this: + +========= ======================= +Name `mmc@7e202000.bootdev` +Sequence 0 +Status Probed +Uclass mmc +Bootflows 1 (1 valid) +========= ======================= + +Most of the information is the same as `bootdev list` above. The new fields +are: + +Device + Name of the bootdev + +Status + Shows `Probed` if the device is probed, `OK` if not. If `-p` is used and the + device fails to probe, an error code is shown. + +Bootflows + Indicates the number of bootflows attached to the bootdev. This is 0 + unless you have used 'bootflow scan' on the bootflow, or on all bootflows. + + +Example +------- + +This example shows listing available bootdev and getting information about +one of them:: + + U-Boot> bootdev list + Seq Probed Status Uclass Name + --- ------ ------ -------- ------------------ + 0 [ + ] OK mmc mmc@7e202000.bootdev + 1 [ ] OK mmc sdhci@7e300000.bootdev + 2 [ ] OK ethernet smsc95xx_eth.bootdev + --- ------ ------ -------- ------------------ + (3 devices) + U-Boot> bootdev sel 0 + U-Boot> bootflow scan + U-Boot> bootdev info + Name: mmc@7e202000.bootdev + Sequence: 0 + Status: Probed + Uclass: mmc + Bootflows: 1 (1 valid) + +This shows using one of the available hunters, then listing them:: + + => bootdev hunt usb + Hunting with: usb + Bus usb@1: scanning bus usb@1 for devices... + 3 USB Device(s) found + => bootdev hunt -l + Prio Used Uclass Hunter + ---- ---- --------------- --------------- + 6 ethernet eth_bootdev + 1 simple_bus (none) + 5 ide ide_bootdev + 2 mmc mmc_bootdev + 4 nvme nvme_bootdev + 4 scsi scsi_bootdev + 4 spi_flash sf_bootdev + 5 * usb usb_bootdev + 4 virtio virtio_bootdev + (total hunters: 9) + => usb stor + Device 0: Vendor: sandbox Rev: 1.0 Prod: flash + Type: Hard Disk + Capacity: 4.0 MB = 0.0 GB (8192 x 512) + Device 1: Vendor: sandbox Rev: 1.0 Prod: flash + Type: Hard Disk + Capacity: 0.0 MB = 0.0 GB (1 x 512) + => + + +Return value +------------ + +The return value $? is always 0 (true). diff --git a/doc/usage/cmd/bootefi.rst b/doc/usage/cmd/bootefi.rst new file mode 100644 index 00000000000..3efe9e9df57 --- /dev/null +++ b/doc/usage/cmd/bootefi.rst @@ -0,0 +1,154 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2020, Heinrich Schuchardt <xypron.glpk@gmx.de> + +.. index:: + single: bootefi (command) + +bootefi command +=============== + +Synopsis +-------- + +:: + + bootefi <image_addr>[:<image_size>] [<fdt_addr>] + bootefi bootmgr [<fdt_addr>] + bootefi hello [<fdt_addr>] + bootefi selftest [<fdt_addr>] + +Description +----------- + +The *bootefi* command is used to launch a UEFI binary which can be either of + +* UEFI application +* UEFI boot services driver +* UEFI run-time services driver + +An operating system requires a hardware description which can either be +presented as ACPI table (CONFIG\_GENERATE\_ACPI\_TABLE=y) or as device-tree. +The load address of the device-tree may be provided as parameter *fdt\_addr*. If +this address is not specified, the bootefi command will try to fall back in +sequence to: + +* the device-tree specified by environment variable *fdt\_addr* +* the device-tree specified by environment variable *fdtcontroladdr* + +The load address of the binary is specified by parameter *image_address*. A +command sequence to run a UEFI application might look like + +:: + + load mmc 0:2 $fdt_addr_r dtb + load mmc 0:1 $kernel_addr_r /EFI/grub/grubaa64.efi + bootefi $kernel_addr_r $fdt_addr_r + +The last UEFI binary loaded defines the image file path in the loaded image +protocol. + +The value of the environment variable *bootargs* is converted from UTF-8 to +UTF-16 and passed as load options in the loaded image protocol to the UEFI +binary. + +image_addr + Address of the UEFI binary. + +fdt_addr + Address of the device-tree or '-'. If no address is specifiy, the + environment variable $fdt_addr is used as first fallback, the address of + U-Boot's internal device-tree $fdtcontroladdr as second fallback. + When using ACPI no device-tree shall be specified. + +image_size + Size of the UEFI binary file. This argument is only needed if *image_addr* + does not match the address of the last loaded UEFI binary. In this case + a memory device path will be used as image file path in the loaded image + protocol. + +Note + UEFI binaries that are contained in FIT images are launched via the + *bootm* command. + +UEFI boot manager +''''''''''''''''' + +The UEFI boot manager is invoked by the *bootefi bootmgr* sub-command. +Here boot options are defined by UEFI variables with a name consisting of the +letters *Boot* followed by a four digit hexadecimal number, e.g. *Boot0001* or +*BootA03E*. The boot variable defines a label, the device path of the binary to +execute as well as the load options passed in the loaded image protocol. + +If the UEFI variable *BootNext* is defined, it specifies the number of the boot +option to execute next. If no binary can be loaded via *BootNext* the variable +*BootOrder* specifies in which sequence boot options shalled be tried. + +The values of these variables can be managed using the U-Boot command +*efidebug*. + +UEFI hello world application +'''''''''''''''''''''''''''' + +U-Boot can be compiled with a hello world application that can be launched using +the *bootefi hello* sub-command. A session might look like + +:: + + => setenv bootargs 'Greetings to the world' + => bootefi hello + Booting /MemoryMapped(0x0,0x10001000,0x1000) + Hello, world! + Running on UEFI 2.8 + Have SMBIOS table + Have device tree + Load options: Greetings to the world + +UEFI selftest +''''''''''''' + +U-Boot can be compiled with UEFI unit tests. These unit tests are invoked using +the *bootefi selftest* sub-command. + +Which unit test is executed is controlled by the environment variable +*efi\_selftest*. If this variable is not set, all unit tests that are not marked +as 'on request' are executed. + +To show a list of the available unit tests the value *list* can be used + +:: + + => setenv efi_selftest list + => bootefi selftest + + Available tests: + 'block image transfer' - on request + 'block device' + 'configuration tables' + ... + +A single test is selected for execution by setting the *efi\_selftest* +environment variable to match one of the listed identifiers + +:: + + => setenv efi_selftest 'block image transfer' + => bootefi selftest + +Some of the tests execute the ExitBootServices() UEFI boot service and will not +return to the command line but require a board reset. + +Configuration +------------- + +To use the *bootefi* command you must specify CONFIG\_CMD\_BOOTEFI=y. +The *bootefi bootmgr* sub-command requries CMD\_BOOTEFI\_BOOTMGR=y. +The *bootefi hello* sub-command requries CMD\_BOOTEFI\_HELLO=y. +The *bootefi selftest* sub-command depends on CMD\_BOOTEFI\_SELFTEST=y. + +See also +-------- + +* *bootm* for launching UEFI binaries packed in FIT images +* :doc:`booti<booti>`, *bootm*, *bootz* for launching a Linux kernel without + using the UEFI sub-system +* *efidebug* for setting UEFI boot variables and boot options diff --git a/doc/usage/cmd/bootelf.rst b/doc/usage/cmd/bootelf.rst new file mode 100644 index 00000000000..705524c594a --- /dev/null +++ b/doc/usage/cmd/bootelf.rst @@ -0,0 +1,61 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later +.. Copyright 2024, Maxim Moskalets <maximmosk4@gmail.com> + +.. index:: + single: bootelf (command) + +bootelf command +=============== + +Synopsis +-------- + +:: + + bootelf [-p|-s] [-d <fdt_addr>] [<image_addr> [<arg>]...] + +Description +----------- + +The *bootelf* command is used to launch a ELF binary at *image_addr*. If +*image_addr* is not specified, the bootelf command will try to find image in +*image_load_addr* variable (*CONFIG\_SYS\_LOAD\_ADDR* by default). + +Args after *image_addr* will be passed to application in common *argc*, *argv* +format. + +A command sequence to run a ELF image using FDT might look like + +:: + + load mmc 0:1 ${loadaddr} /kernel.elf + load mmc 0:1 ${fdt_addr_r} /soc-board.dtb + bootelf -d ${fdt_addr_r} ${loadaddr} ${loadaddr} + +image_addr + Address of the ELF binary. + +fdt_addr + Address of the device-tree. This argument in only needed if bootable + application uses FDT that requires additional setup (like /memory node). + +arg + Any text arguments for bootable application. This is usually the address + of the device-tree. + +Flags: + +-p + Load ELF image via program headers. + +-s + Load ELF image via section headers. + +-d + Setup FDT by address. + +Configuration +------------- + +The bootelf command is only available if CONFIG_CMD_ELF=y. FDT setup by flag -d +need CONFIG_CMD_ELF_FDT_SETUP=y. diff --git a/doc/usage/cmd/bootflow.rst b/doc/usage/cmd/bootflow.rst new file mode 100644 index 00000000000..5d41fe37a7a --- /dev/null +++ b/doc/usage/cmd/bootflow.rst @@ -0,0 +1,748 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: bootflow (command) + +bootflow command +================ + +Synopsis +-------- + +:: + + bootflow scan [-abelGH] [bootdev] + bootflow list [-e] + bootflow select [<num|name>] + bootflow info [-ds] + bootflow read + bootflow boot + bootflow cmdline [set|get|clear|delete|auto] <param> [<value>] + bootfloe menu [-t] + +Description +----------- + +The `bootflow` command is used to manage bootflows. It can scan bootdevs to +locate bootflows, list them and boot them. + +See :doc:`/develop/bootstd/index` for more information. + +Note that `CONFIG_BOOTSTD_FULL` (which enables `CONFIG_CMD_BOOTFLOW_FULL) must +be enabled to obtain full functionality with this command. Otherwise, it only +supports `bootflow scan` which scans and boots the first available bootflow. + +bootflow scan +~~~~~~~~~~~~~ + +Scans for available bootflows, optionally booting the first valid one it finds. +This operates in two modes: + +- If no bootdev is selected (see `bootdev select`) it scans bootflows one + by one, extracting all the bootdevs from each +- If a bootdev is selected, it just scans that one bootflow + +Flags are: + +-a + Collect all bootflows, even those that cannot be loaded. Normally if a file + is not where it is expected, then the bootflow fails and so is dropped + during the scan. With this option you can see why each bootflow would be + dropped. + +-b + Boot each valid bootflow as it is scanned. Typically only the first bootflow + matters, since by then the system boots in the OS and U-Boot is no-longer + running. `bootflow scan -b` is a quick way to boot the first available OS. + A valid bootflow is one that made it all the way to the `loaded` state. + Note that if `-m` is provided as well, booting is delayed until the user + selects a bootflow. + +-e + Used with -l to also show errors for each bootflow. The shows detailed error + information for each bootflow that failed to make it to the `loaded` state. + +-l + List bootflows while scanning. This is helpful when you want to see what + is happening during scanning. Use it with the `-b` flag to see which + bootdev and bootflows are being tried. + +-G + Skip global bootmeths when scanning. By default these are tried first, but + this flag disables them. + +-H + Don't use bootdev hunters. By default these are used before each boot + priority or label is tried, to see if more bootdevs can be discovered, but + this flag disables that process. + +-m + Show a menu of available bootflows for the user to select. When used with + -b it then boots the one that was selected, if any. + +The optional argument specifies a particular bootdev to scan. This can either be +the name of a bootdev or its sequence number (both shown with `bootdev list`). +Alternatively a convenience label can be used, like `mmc0`, which is the type of +device and an optional sequence number. Specifically, the label is the uclass of +the bootdev's parent followed by the sequence number of that parent. Sequence +numbers are typically set by aliases, so if you have 'mmc0' in your devicetree +alias section, then `mmc0` refers to the bootdev attached to that device. + + +bootflow list +~~~~~~~~~~~~~ + +Lists the previously scanned bootflows. You must use `bootflow scan` before this +to see anything. + +If you scanned with -a and have bootflows with errors, -e can be used to show +those errors. + +The list looks something like this: + +=== ====== ====== ======== ==== =============================== ================ +Seq Method State Uclass Part Name Filename +=== ====== ====== ======== ==== =============================== ================ + 0 distro ready mmc 2 mmc\@7e202000.bootdev.part_2 /boot/extlinux/extlinux.conf + 1 pxe ready ethernet 0 smsc95xx_eth.bootdev.0 rpi.pxe/extlinux/extlinux.conf +=== ====== ====== ======== ==== =============================== ================ + +The fields are as follows: + +Seq: + Sequence number in the scan, used to reference the bootflow later + +Method: + The boot method (bootmeth) used to find the bootflow. Several methods are + included in U-Boot. + +State: + Current state of the bootflow, indicating how far the bootdev got in + obtaining a valid one. See :ref:`BootflowStates` for a list of states. + +Uclass: + Name of the media device's Uclass. This indicates the type of the parent + device (e.g. MMC, Ethernet). + +Part: + Partition number being accesseed, numbered from 1. Normally a device will + have a partition table with a small number of partitions. For devices + without partition tables (e.g. network) this field is 0. + +Name: + Name of the bootflow. This is generated from the bootdev appended with + the partition information + +Filename: + Name of the bootflow file. This indicates where the file is on the + filesystem or network device. + + +bootflow select +~~~~~~~~~~~~~~~ + +Use this to select a particular bootflow. You can select it by the sequence +number or name, as shown in `bootflow list`. + +Once a bootflow is selected, you can use `bootflow info` and `bootflow boot`. + +If no bootflow name or number is provided, then any existing bootflow is +unselected. + + +bootflow info +~~~~~~~~~~~~~ + +This shows information on the current bootflow, with the format looking like +this: + +========= =============================== +Name mmc\@7e202000.bootdev.part_2 +Device mmc\@7e202000.bootdev +Block dev mmc\@7e202000.blk +Type distro +Method: extlinux +State ready +Partition 2 +Subdir (none) +Filename /extlinux/extlinux.conf +Buffer 3db7ad48 +Size 232 (562 bytes) +FDT: <NULL> +Error 0 +========= =============================== + +Most of the information is the same as `bootflow list` above. The new fields +are: + +Device + Name of the bootdev + +Block dev + Name of the block device, if any. Network devices don't have a block device. + +Subdir + Subdirectory used for retrieving files. For network bootdevs this is the + directory of the 'bootfile' parameter passed from DHCP. All file retrievals + when booting are relative to this. + +Buffer + Buffer containing the bootflow file. You can use the :doc:`md` to look at + it, or dump it with `bootflow info -d`. + +Size + Size of the bootflow file + +FDT: + Filename of the device tree, if supported. The EFI bootmeth uses this to + remember the filename to load. If `<NULL>` then there is none. + +Error + Error number returned from scanning for the bootflow. This is 0 if the + bootflow is in the 'loaded' state, or a negative error value on error. You + can look up Linux error codes to find the meaning of the number. + +Use the `-d` flag to dump out the contents of the bootfile file. + +The `-s` flag shows any x86 setup block, instead of the above. + + +bootflow read +~~~~~~~~~~~~~ + +This reads any files related to the bootflow. Some bootflows with large files +avoid doing this when the bootflow is scanned, since it uses a lot of memory +and takes extra time. The files are then automatically read when `bootflow boot` +is used. + +This command reads these files immediately. Typically this fills in the bootflow +`buf` property, which can be used to examine the bootflow. + +Note that reading the files does not result in any extra parsing, nor loading of +images in the files. This is purely used to read in the data ready for +booting, or examination. + + +bootflow boot +~~~~~~~~~~~~~ + +This boots the current bootflow, reading any required files first. + + +bootflow cmdline +~~~~~~~~~~~~~~~~ + +Some bootmeths can obtain the OS command line since it is stored with the OS. +In that case, you can use `bootflow cmdline` to adjust this. The command line +is assumed to be in the format used by Linux, i.e. a space-separated set of +parameters with optional values, e.g. "noinitrd console=/dev/tty0". + +To change or add a parameter, use:: + + bootflow cmdline set <param> <value> + +To clear a parameter value to empty you can use "" for the value, or use:: + + bootflow cmdline clear <param> + +To delete a parameter entirely, use:: + + bootflow cmdline delete <param> + +Automatic parameters are available in a very few cases. You can use these to +add parmeters where the value is known by U-Boot. For example:: + + bootflow cmdline auto earlycon + bootflow cmdline auto console + +can be used to set the early console (or console) to a suitable value so that +output appears on the serial port. This is only supported by the 16550 serial +driver so far. + +bootflow menu +~~~~~~~~~~~~~ + +This shows a menu with available bootflows. The user can select a particular +bootflow, which then becomes the current one. + +The `-t` flag requests a text menu. Otherwise, if a display is available, a +graphical menu is shown. + + +Example +------- + +Here is an example of scanning for bootflows, then listing them:: + + U-Boot> bootflow scan -l + Scanning for bootflows in all bootdevs + Seq Type State Uclass Part Name Filename + --- ----------- ------ -------- ---- ------------------------ ---------------- + Scanning bootdev 'mmc@7e202000.bootdev': + 0 distro ready mmc 2 mmc@7e202000.bootdev.p /extlinux/extlinux.conf + Scanning bootdev 'sdhci@7e300000.bootdev': + Card did not respond to voltage select! : -110 + Scanning bootdev 'smsc95xx_eth.bootdev': + Waiting for Ethernet connection... done. + BOOTP broadcast 1 + DHCP client bound to address 192.168.4.30 (4 ms) + Using smsc95xx_eth device + TFTP from server 192.168.4.1; our IP address is 192.168.4.30 + Filename 'rpi.pxe/'. + Load address: 0x200000 + Loading: * + TFTP error: 'Is a directory' (0) + Starting again + + missing environment variable: pxeuuid + Retrieving file: rpi.pxe/pxelinux.cfg/01-b8-27-eb-a6-61-e1 + Waiting for Ethernet connection... done. + Using smsc95xx_eth device + TFTP from server 192.168.4.1; our IP address is 192.168.4.30 + Filename 'rpi.pxe/pxelinux.cfg/01-b8-27-eb-a6-61-e1'. + Load address: 0x2500000 + Loading: ################################################## 566 Bytes + 45.9 KiB/s + done + Bytes transferred = 566 (236 hex) + 1 distro ready ethernet 0 smsc95xx_eth.bootdev.0 rpi.pxe/extlinux/extlinux.conf + No more bootdevs + --- ----------- ------ -------- ---- ------------------------ ---------------- + (2 bootflows, 2 valid) + U-Boot> bootflow l + Showing all bootflows + Seq Type State Uclass Part Name Filename + --- ----------- ------ -------- ---- ------------------------ ---------------- + 0 distro ready mmc 2 mmc@7e202000.bootdev.p /extlinux/extlinux.conf + 1 pxe ready ethernet 0 smsc95xx_eth.bootdev.0 rpi.pxe/extlinux/extlinux.conf + --- ----------- ------ -------- ---- ------------------------ ---------------- + (2 bootflows, 2 valid) + + +The second one is then selected by name (we could instead use `bootflow sel 0`), +displayed and booted:: + + U-Boot> bootflow info + No bootflow selected + U-Boot> bootflow sel mmc@7e202000.bootdev.part_2 + U-Boot> bootflow info + Name: mmc@7e202000.bootdev.part_2 + Device: mmc@7e202000.bootdev + Block dev: mmc@7e202000.blk + Method: distro + State: ready + Partition: 2 + Subdir: (none) + Filename: extlinux/extlinux.conf + Buffer: 3db7ae88 + Size: 232 (562 bytes) + OS: Fedora-Workstation-armhfp-31-1.9 (5.3.7-301.fc31.armv7hl) + Cmdline: (none) + Logo: (none) + FDT: <NULL> + Error: 0 + U-Boot> bootflow boot + ** Booting bootflow 'smsc95xx_eth.bootdev.0' + Ignoring unknown command: ui + Ignoring malformed menu command: autoboot + Ignoring malformed menu command: hidden + Ignoring unknown command: totaltimeout + 1: Fedora-Workstation-armhfp-31-1.9 (5.3.7-301.fc31.armv7hl) + Retrieving file: rpi.pxe/initramfs-5.3.7-301.fc31.armv7hl.img + get 2700000 rpi.pxe/initramfs-5.3.7-301.fc31.armv7hl.img + Waiting for Ethernet connection... done. + Using smsc95xx_eth device + TFTP from server 192.168.4.1; our IP address is 192.168.4.30 + Filename 'rpi.pxe/initramfs-5.3.7-301.fc31.armv7hl.img'. + Load address: 0x2700000 + Loading: ###################################T ############### 57.7 MiB + 1.9 MiB/s + done + Bytes transferred = 60498594 (39b22a2 hex) + Retrieving file: rpi.pxe//vmlinuz-5.3.7-301.fc31.armv7hl + get 80000 rpi.pxe//vmlinuz-5.3.7-301.fc31.armv7hl + Waiting for Ethernet connection... done. + Using smsc95xx_eth device + TFTP from server 192.168.4.1; our IP address is 192.168.4.30 + Filename 'rpi.pxe//vmlinuz-5.3.7-301.fc31.armv7hl'. + Load address: 0x80000 + Loading: ################################################## 7.2 MiB + 2.3 MiB/s + done + Bytes transferred = 7508480 (729200 hex) + append: ro root=UUID=9732b35b-4cd5-458b-9b91-80f7047e0b8a rhgb quiet LANG=en_US.UTF-8 cma=192MB cma=256MB + Retrieving file: rpi.pxe//dtb-5.3.7-301.fc31.armv7hl/bcm2837-rpi-3-b.dtb + get 2600000 rpi.pxe//dtb-5.3.7-301.fc31.armv7hl/bcm2837-rpi-3-b.dtb + Waiting for Ethernet connection... done. + Using smsc95xx_eth device + TFTP from server 192.168.4.1; our IP address is 192.168.4.30 + Filename 'rpi.pxe//dtb-5.3.7-301.fc31.armv7hl/bcm2837-rpi-3-b.dtb'. + Load address: 0x2600000 + Loading: ################################################## 13.8 KiB + 764.6 KiB/s + done + Bytes transferred = 14102 (3716 hex) + Kernel image @ 0x080000 [ 0x000000 - 0x729200 ] + ## Flattened Device Tree blob at 02600000 + Booting using the fdt blob at 0x2600000 + Using Device Tree in place at 02600000, end 02606715 + + Starting kernel ... + + [ OK ] Started Show Plymouth Boot Screen. + [ OK ] Started Forward Password R…s to Plymouth Directory Watch. + [ OK ] Reached target Local Encrypted Volumes. + [ OK ] Reached target Paths. + .... + + +Here we scan for bootflows and boot the first one found:: + + U-Boot> bootflow scan -bl + Scanning for bootflows in all bootdevs + Seq Method State Uclass Part Name Filename + --- ----------- ------ -------- ---- ---------------------- ---------------- + Scanning bootdev 'mmc@7e202000.bootdev': + 0 distro ready mmc 2 mmc@7e202000.bootdev.p /extlinux/extlinux.conf + ** Booting bootflow 'mmc@7e202000.bootdev.part_2' + Ignoring unknown command: ui + Ignoring malformed menu command: autoboot + Ignoring malformed menu command: hidden + Ignoring unknown command: totaltimeout + 1: Fedora-KDE-armhfp-31-1.9 (5.3.7-301.fc31.armv7hl) + Retrieving file: /initramfs-5.3.7-301.fc31.armv7hl.img + getfile 2700000 /initramfs-5.3.7-301.fc31.armv7hl.img + Retrieving file: /vmlinuz-5.3.7-301.fc31.armv7hl + getfile 80000 /vmlinuz-5.3.7-301.fc31.armv7hl + append: ro root=UUID=b8781f09-e2dd-4cb8-979b-7df5eeaaabea rhgb LANG=en_US.UTF-8 cma=192MB console=tty0 console=ttyS1,115200 + Retrieving file: /dtb-5.3.7-301.fc31.armv7hl/bcm2837-rpi-3-b.dtb + getfile 2600000 /dtb-5.3.7-301.fc31.armv7hl/bcm2837-rpi-3-b.dtb + Kernel image @ 0x080000 [ 0x000000 - 0x729200 ] + ## Flattened Device Tree blob at 02600000 + Booting using the fdt blob at 0x2600000 + Using Device Tree in place at 02600000, end 02606715 + + Starting kernel ... + + [ 0.000000] Booting Linux on physical CPU 0x0 + + +Here is am example using the -e flag to see all errors:: + + U-Boot> bootflow scan -a + Card did not respond to voltage select! : -110 + Waiting for Ethernet connection... done. + BOOTP broadcast 1 + DHCP client bound to address 192.168.4.30 (4 ms) + Using smsc95xx_eth device + TFTP from server 192.168.4.1; our IP address is 192.168.4.30 + Filename 'rpi.pxe/'. + Load address: 0x200000 + Loading: * + TFTP error: 'Is a directory' (0) + Starting again + + missing environment variable: pxeuuid + Retrieving file: rpi.pxe/pxelinux.cfg/01-b8-27-eb-a6-61-e1 + Waiting for Ethernet connection... done. + Using smsc95xx_eth device + TFTP from server 192.168.4.1; our IP address is 192.168.4.30 + Filename 'rpi.pxe/pxelinux.cfg/01-b8-27-eb-a6-61-e1'. + Load address: 0x2500000 + Loading: ################################################## 566 Bytes + 49.8 KiB/s + done + Bytes transferred = 566 (236 hex) + U-Boot> bootflow l -e + Showing all bootflows + Seq Type State Uclass Part Name Filename + --- ----------- ------ -------- ---- --------------------- ---------------- + 0 distro fs mmc 1 mmc@7e202000.bootdev.p /extlinux/extlinux.conf + ** File not found, err=-2 + 1 distro ready mmc 2 mmc@7e202000.bootdev.p /extlinux/extlinux.conf + 2 distro fs mmc 3 mmc@7e202000.bootdev.p /extlinux/extlinux.conf + ** File not found, err=-1 + 3 distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + 4 distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + 5 distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + 6 distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + 7 distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + 8 distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + 9 distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + a distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + b distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + c distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + d distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + e distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + f distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + 10 distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + 11 distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + 12 distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + 13 distro media mmc 0 mmc@7e202000.bootdev.p <NULL> + ** No partition found, err=-2 + 14 distro ready ethernet 0 smsc95xx_eth.bootdev.0 rpi.pxe/extlinux/extlinux.conf + --- ----------- ------ -------- ---- --------------------- ---------------- + (21 bootflows, 2 valid) + U-Boot> + +Here is an example of booting ChromeOS, adjusting the console beforehand. Note that +the cmdline is word-wrapped here and some parts of the command line are elided:: + + => bootfl list + Showing all bootflows + Seq Method State Uclass Part Name Filename + --- ----------- ------ -------- ---- ------------------------ ---------------- + 0 cros ready nvme 0 5.10.153-20434-g98da1eb2c <NULL> + 1 efi ready nvme c nvme#0.blk#1.bootdev.part efi/boot/bootia32.efi + 2 efi ready usb_mass_ 2 usb_mass_storage.lun0.boo efi/boot/bootia32.efi + --- ----------- ------ -------- ---- ------------------------ ---------------- + (3 bootflows, 3 valid) + => bootfl sel 0 + => bootfl inf + Name: 5.10.153-20434-g98da1eb2cf9d (chrome-bot@chromeos-release-builder-us-central1-b-x32-12-xijx) #1 SMP PREEMPT Tue Jan 24 19:38:23 PST 2023 + Device: nvme#0.blk#1.bootdev + Block dev: nvme#0.blk#1 + Method: cros + State: ready + Partition: 0 + Subdir: (none) + Filename: <NULL> + Buffer: 737a1400 + Size: c47000 (12873728 bytes) + OS: ChromeOS + Cmdline: console= loglevel=7 init=/sbin/init cros_secure drm.trace=0x106 + root=/dev/dm-0 rootwait ro dm_verity.error_behavior=3 + dm_verity.max_bios=-1 dm_verity.dev_wait=1 + dm="1 vroot none ro 1,0 6348800 + verity payload=PARTUUID=799c935b-ae62-d143-8493-816fa936eef7/PARTNROFF=1 + hashtree=PARTUUID=799c935b-ae62-d143-8493-816fa936eef7/PARTNROFF=1 + hashstart=6348800 alg=sha256 + root_hexdigest=78cc462cd45aecbcd49ca476587b4dee59aa1b00ba5ece58e2c29ec9acd914ab + salt=8dec4dc80a75dd834a9b3175c674405e15b16a253fdfe05c79394ae5fd76f66a" + noinitrd vt.global_cursor_default=0 + kern_guid=799c935b-ae62-d143-8493-816fa936eef7 add_efi_memmap + noresume i915.modeset=1 ramoops.ecc=1 tpm_tis.force=0 + intel_pmc_core.warn_on_s0ix_failures=1 i915.enable_guc=3 i915.enable_dc=4 + xdomain=0 swiotlb=65536 intel_iommu=on i915.enable_psr=1 + usb-storage.quirks=13fe:6500:u + X86 setup: 742e3400 + Logo: (none) + FDT: <NULL> + Error: 0 + => bootflow cmdline auto earlycon + => bootflow cmd auto console + => print bootargs + bootargs=console=ttyS0,115200n8 loglevel=7 ... + usb-storage.quirks=13fe:6500:u earlycon=uart8250,mmio32,0xfe03e000,115200n8 + => bootflow cmd del console + => print bootargs + bootargs=loglevel=7 ... earlycon=uart8250,mmio32,0xfe03e000,115200n8 + => bootfl boot + ** Booting bootflow '5.10.153-20434-g98da1eb2cf9d (chrome-bot@chromeos-release-builder-us-central1-b-x32-12-xijx) #1 SMP PREEMPT Tue Jan 24 19:38:23 PST 2023' with cros + Kernel command line: "loglevel=7 ... earlycon=uart8250,mmio32,0xfe03e000,115200n8" + + Starting kernel ... + + [ 0.000000] Linux version 5.10.153-20434-g98da1eb2cf9d (chrome-bot@chromeos-release-builder-us-central1-b-x32-12-xijx) (Chromium OS 15.0_pre465103_p20220825-r4 clang version 15.0.0 (/var/tmp/portage/sys-devel/llvm-15.0_pre465103_p20220825-r4/work/llvm-15.0_pre465103_p20220825/clang db1978b67431ca3462ad8935bf662c15750b8252), LLD 15.0.0) #1 SMP PREEMPT Tue Jan 24 19:38:23 PST 2023 + [ 0.000000] Command line: loglevel=7 ... usb-storage.quirks=13fe:6500:u earlycon=uart8250,mmio32,0xfe03e000,115200n8 + [ 0.000000] x86/split lock detection: warning about user-space split_locks + +This shows looking at x86 setup information:: + + => bootfl sel 0 + => bootfl i -s + Setup located at 77b56010: + + ACPI RSDP addr : 0 + E820: 2 entries + Addr Size Type + 0 1000 RAM + fffff000 1000 Reserved + Setup sectors : 1e + Root flags : 1 + Sys size : 63420 + RAM size : 0 + Video mode : ffff + Root dev : 0 + Boot flag : 0 + Jump : 66eb + Header : 53726448 + Kernel V2 + Version : 20d + Real mode switch : 0 + Start sys seg : 1000 + Kernel version : 38cc + @00003acc: + Type of loader : ff + unknown + Load flags : 1 + : loaded-high + Setup move size : 8000 + Code32 start : 100000 + Ramdisk image : 0 + Ramdisk size : 0 + Bootsect kludge : 0 + Heap end ptr : 5160 + Ext loader ver : 0 + Ext loader type : 0 + Command line ptr : 735000 + Initrd addr max : 7fffffff + Kernel alignment : 200000 + Relocatable kernel : 1 + Min alignment : 15 + : 200000 + Xload flags : 3 + : 64-bit-entry can-load-above-4gb + Cmdline size : 7ff + Hardware subarch : 0 + HW subarch data : 0 + Payload offset : 26e + Payload length : 612045 + Setup data : 0 + Pref address : 1000000 + Init size : 1383000 + Handover offset : 0 + +This shows reading a bootflow to examine the kernel:: + + => bootfl i 0 + Name: + Device: emmc@1c,0.bootdev + Block dev: emmc@1c,0.blk + Method: cros + State: ready + Partition: 2 + Subdir: (none) + Filename: <NULL> + Buffer: 0 + Size: 63ee00 (6548992 bytes) + OS: ChromeOS + Cmdline: console= loglevel=7 init=/sbin/init cros_secure oops=panic panic=-1 root=PARTUUID=35c775e7-3735-d745-93e5-d9e0238f7ed0/PARTNROFF=1 rootwait rw dm_verity.error_behavior=3 dm_verity.max_bios=-1 dm_verity.dev_wait=0 dm="1 vroot none rw 1,0 3788800 verity payload=ROOT_DEV hashtree=HASH_DEV hashstart=3788800 alg=sha1 root_hexdigest=55052b629d3ac889f25a9583ea12cdcd3ea15ff8 salt=a2d4d9e574069f4fed5e3961b99054b7a4905414b60a25d89974a7334021165c" noinitrd vt.global_cursor_default=0 kern_guid=35c775e7-3735-d745-93e5-d9e0238f7ed0 add_efi_memmap boot=local noresume noswap i915.modeset=1 tpm_tis.force=1 tpm_tis.interrupts=0 nmi_watchdog=panic,lapic disablevmx=off + X86 setup: 77b56010 + Logo: (none) + FDT: <NULL> + Error: 0 + +Note that `Buffer` is 0 so it has not be read yet. Using `bootflow read`:: + + => bootfl read + => bootfl info + Name: + Device: emmc@1c,0.bootdev + Block dev: emmc@1c,0.blk + Method: cros + State: ready + Partition: 2 + Subdir: (none) + Filename: <NULL> + Buffer: 77b7e400 + Size: 63ee00 (6548992 bytes) + OS: ChromeOS + Cmdline: console= loglevel=7 init=/sbin/init cros_secure oops=panic panic=-1 root=PARTUUID=35c775e7-3735-d745-93e5-d9e0238f7ed0/PARTNROFF=1 rootwait rw dm_verity.error_behavior=3 dm_verity.max_bios=-1 dm_verity.dev_wait=0 dm="1 vroot none rw 1,0 3788800 verity payload=ROOT_DEV hashtree=HASH_DEV hashstart=3788800 alg=sha1 root_hexdigest=55052b629d3ac889f25a9583ea12cdcd3ea15ff8 salt=a2d4d9e574069f4fed5e3961b99054b7a4905414b60a25d89974a7334021165c" noinitrd vt.global_cursor_default=0 kern_guid=35c775e7-3735-d745-93e5-d9e0238f7ed0 add_efi_memmap boot=local noresume noswap i915.modeset=1 tpm_tis.force=1 tpm_tis.interrupts=0 nmi_watchdog=panic,lapic disablevmx=off + X86 setup: 781b4400 + Logo: (none) + FDT: <NULL> + Error: 0 + +Now the buffer can be accessed:: + + => md 77b7e400 + 77b7e400: 1186f6fc 40000002 b8fa0c75 00000018 .......@u....... + 77b7e410: c08ed88e a68dd08e 000001e8 000000e8 ................ + 77b7e420: ed815d00 00000021 62c280b8 89e80100 .]..!......b.... + 77b7e430: 22f7e8c4 c0850061 22ec850f eb890061 ..."a......"a... + 77b7e440: 0230868b 01480000 21d0f7c3 00fb81c3 ..0...H....!.... + 77b7e450: 7d010000 0000bb05 c3810100 00d4f000 ...}............ + 77b7e460: 8130858d 85890061 00618132 3095010f ..0.a...2.a....0 + 77b7e470: 0f006181 c883e020 e0220f20 e000bb8d .a.. ... ."..... + 77b7e480: c0310062 001800b9 8dabf300 62e000bb b.1............b + 77b7e490: 07878d00 89000010 00bb8d07 8d0062f0 .............b.. + 77b7e4a0: 00100787 0004b900 07890000 00100005 ................ + 77b7e4b0: 08c78300 8df37549 630000bb 0183b800 ....Iu.....c.... + 77b7e4c0: 00b90000 89000008 00000507 c7830020 ............ ... + 77b7e4d0: f3754908 e000838d 220f0062 0080b9d8 .Iu.....b..".... + 77b7e4e0: 320fc000 08e8ba0f c031300f b8d0000f ...2.....01..... + 77b7e4f0: 00000020 6ad8000f 00858d10 50000002 ......j.......P + +This shows using a text menu to boot an OS:: + + => bootflow scan + => bootfl list + => bootfl menu -t + U-Boot : Boot Menu + + UP and DOWN to choose, ENTER to select + + > 0 mmc1 mmc1.bootdev.whole + 1 mmc1 Fedora-Workstation-armhfp-31-1.9 (5.3.7-301.fc31.armv7hl) + 2 mmc1 mmc1.bootdev.part_1 + 3 mmc4 mmc4.bootdev.whole + 4 mmc4 Armbian + 5 mmc4 mmc4.bootdev.part_1 + 6 mmc5 mmc5.bootdev.whole + 7 mmc5 ChromeOS + 8 mmc5 ChromeOS + U-Boot : Boot Menu + + UP and DOWN to choose, ENTER to select + + 0 mmc1 mmc1.bootdev.whole + > 1 mmc1 Fedora-Workstation-armhfp-31-1.9 (5.3.7-301.fc31.armv7hl) + 2 mmc1 mmc1.bootdev.part_1 + 3 mmc4 mmc4.bootdev.whole + 4 mmc4 Armbian + 5 mmc4 mmc4.bootdev.part_1 + 6 mmc5 mmc5.bootdev.whole + 7 mmc5 ChromeOS + 8 mmc5 ChromeOS + U-Boot : Boot Menu + + Selected: Fedora-Workstation-armhfp-31-1.9 (5.3.7-301.fc31.armv7hl) + => bootfl boot + ** Booting bootflow 'mmc1.bootdev.part_1' with extlinux + Ignoring unknown command: ui + Ignoring malformed menu command: autoboot + Ignoring malformed menu command: hidden + Ignoring unknown command: totaltimeout + Fedora-Workstation-armhfp-31-1.9 Boot Options. + 1: Fedora-Workstation-armhfp-31-1.9 (5.3.7-301.fc31.armv7hl) + Enter choice: 1 + 1: Fedora-Workstation-armhfp-31-1.9 (5.3.7-301.fc31.armv7hl) + Retrieving file: /vmlinuz-5.3.7-301.fc31.armv7hl + Retrieving file: /initramfs-5.3.7-301.fc31.armv7hl.img + append: ro root=UUID=9732b35b-4cd5-458b-9b91-80f7047e0b8a rhgb quiet LANG=en_US.UTF-8 cma=192MB cma=256MB + Retrieving file: /dtb-5.3.7-301.fc31.armv7hl/sandbox.dtb + ... + + +Return value +------------ + +On success `bootflow boot` normally boots into the Operating System and does not +return to U-Boot. If something about the U-Boot processing fails, then the +return value $? is 1. If the boot succeeds but for some reason the Operating +System returns, then $? is 0, indicating success. + +For `bootflow menu` the return value is $? is 0 (true) if an option was choses, +else 1. + +For other subcommands, the return value $? is always 0 (true). + + +.. BootflowStates_: diff --git a/doc/usage/cmd/booti.rst b/doc/usage/cmd/booti.rst new file mode 100644 index 00000000000..313efb83cc6 --- /dev/null +++ b/doc/usage/cmd/booti.rst @@ -0,0 +1,117 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: booti (command) + +booti command +============= + +Synopsis +-------- + +:: + + booti [<addr> [<initrd>[:<size>]] [<fdt>]] + +Description +----------- + +The booti command is used to boot a Linux kernel in flat or compressed +'Image' format. Which compressed formats are supported is configurable. + +addr + address of kernel image, defaults to CONFIG_SYS_LOAD_ADDR. + +initrd + address of the initial RAM disk. Use '-' to boot a kernel with a device + tree but without an initial RAM disk. + +size + size of the initial RAM disk. This parameter must be specified for raw + initial RAM disks. + +fdt + address of the device tree. + +To support compressed Image files the following environment variables must be +set: + +kernel_comp_addr_r + start of memory area used for decompression + +kernel_comp_size + size of the compressed file. The value has to be at least the size of + loaded image for decompression to succeed. For the booti command the + maximum decompressed size is 10 times this value. + +Example +------- + +This is the boot log of an Odroid C2 board: + +:: + + => load mmc 0:1 $fdt_addr_r dtb-5.10.0-3-arm64 + 27530 bytes read in 7 ms (3.7 MiB/s) + => load mmc 0:1 $kernel_addr_r vmlinuz-5.10.0-3-arm64 + 26990448 bytes read in 1175 ms (21.9 MiB/s) + => load mmc 0:1 $ramdisk_addr_r initrd.img-5.10.0-3-arm64 + 27421776 bytes read in 1209 ms (21.6 MiB/s) + => booti $kernel_addr_r $ramdisk_addr_r:$filesize $fdt_addr_r + Moving Image from 0x8080000 to 0x8200000, end=9c60000 + ## Flattened Device Tree blob at 08008000 + Booting using the fdt blob at 0x8008000 + Loading Ramdisk to 7a52a000, end 7bf50c50 ... OK + Loading Device Tree to 000000007a520000, end 000000007a529b89 ... OK + + Starting kernel ... + +The kernel can be compressed with gzip: + +.. code-block:: bash + + cd /boot + gzip -k vmlinuz-5.10.0-3-arm64 + +Here is the boot log for the compressed kernel: + +:: + + => setenv kernel_comp_addr_r 0x50000000 + => setenv kernel_comp_size 0x04000000 + => load mmc 0:1 $fdt_addr_r dtb-5.10.0-3-arm64 + 27530 bytes read in 6 ms (4.4 MiB/s) + => load mmc 0:1 $kernel_addr_r vmlinuz-5.10.0-3-arm64.gz + 9267730 bytes read in 402 ms (22 MiB/s) + => load mmc 0:1 $ramdisk_addr_r initrd.img-5.10.0-3-arm64 + 27421776 bytes read in 1181 ms (22.1 MiB/s) + => booti $kernel_addr_r $ramdisk_addr_r:$filesize $fdt_addr_r + Uncompressing Kernel Image + Moving Image from 0x8080000 to 0x8200000, end=9c60000 + ## Flattened Device Tree blob at 08008000 + Booting using the fdt blob at 0x8008000 + Loading Ramdisk to 7a52a000, end 7bf50c50 ... OK + Loading Device Tree to 000000007a520000, end 000000007a529b89 ... OK + + Starting kernel ... + +Configuration +------------- + +The booti command is only available if CONFIG_CMD_BOOTI=y. + +Which compression types are supported depends on: + +* CONFIG_BZIP2 +* CONFIG_GZIP +* CONFIG_LZ4 +* CONFIG_LZMA +* CONFIG_LZO +* CONFIG_ZSTD + +Return value +------------ + +Normally this command does not return. If an error occurs, the return value $? +is set to 1 (false). If the operating system returns to U-Boot, the system is +reset. diff --git a/doc/usage/cmd/bootm.rst b/doc/usage/cmd/bootm.rst new file mode 100644 index 00000000000..e409ebc193b --- /dev/null +++ b/doc/usage/cmd/bootm.rst @@ -0,0 +1,303 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: bootm (command) + +bootm command +============= + +Synopsis +-------- + +:: + + bootm [fit_addr]#<conf>[#extra-conf] + bootm [[fit_addr]:<os_subimg>] [[<fit_addr2>]:<rd_subimg2>] [[<fit_addr3>]:<fdt_subimg>] + + bootm <addr1> [[<addr2> [<addr3>]] # Legacy boot + +Description +----------- + +The *bootm* command is used to boot an Operating System. It has a large number +of options depending on what needs to be booted. + +Note that the second form supports the first and/or second arguments to be +omitted by using a hyphen '-' instead. + +fit_addr / fit_addr2 / fit_addr3 + address of FIT to boot, defaults to CONFIG_SYS_LOAD_ADDR. See notes below. + +conf + configuration unit to boot (must be preceded by hash '#') + +extra-conf + extra configuration to boot. This is supported only for additional + devicetree overlays to apply on the base device tree supplied by the first + configuration unit. + +os_subimg + OS sub-image to boot (must be preceded by colon ':') + +rd_subimg + ramdisk sub-image to boot. Use a hyphen '-' if there is no ramdisk but an + FDT is needed. + +fdt_subimg + FDT sub-image to boot + +See below for legacy boot. Booting using :doc:`../fit/index` is recommended. + +Note on current image address +----------------------------- + +When bootm is called without arguments, the image at current image address is +booted. The current image address is the address set most recently by a load +command, etc, and is by default equal to CONFIG_SYS_LOAD_ADDR. For example, +consider the following commands:: + + tftp 200000 /tftpboot/kernel + bootm + # Last command is equivalent to: + # bootm 200000 + +As shown above, with FIT the address portion of any argument +can be omitted. If <addr3> is omitted, then it is assumed that image at +<addr2> should be used. Similarly, when <addr2> is omitted, it is assumed that +image at <addr1> should be used. If <addr1> is omitted, it is assumed that the +current image address is to be used. For example, consider the following +commands:: + + tftp 200000 /tftpboot/uImage + bootm :kernel-1 + # Last command is equivalent to: + # bootm 200000:kernel-1 + + tftp 200000 /tftpboot/uImage + bootm 400000:kernel-1 :ramdisk-1 + # Last command is equivalent to: + # bootm 400000:kernel-1 400000:ramdisk-1 + + tftp 200000 /tftpboot/uImage + bootm :kernel-1 400000:ramdisk-1 :fdt-1 + # Last command is equivalent to: + # bootm 200000:kernel-1 400000:ramdisk-1 400000:fdt-1 + + +Legacy boot +----------- + +U-Boot supports a legacy image format, enabled by `CONFIG_LEGACY_IMAGE_FORMAT`. +This is not recommended as it is quite limited and insecure. Use +:doc:`../fit/index` instead. It is documented here for old boards which still +use it. + +Arguments are: + +addr1 + address of legacy image to boot. If the image includes a second component + (ramdisk) it is used as well, unless the second parameter is hyphen '-'. + +addr2 + address of legacy image to use as ramdisk + +addr3 + address of legacy image to use as FDT + + +Example syntax +-------------- + +This section provides various examples of possible usage:: + + 1. bootm /* boot image at the current address, equivalent to 2,3,8 */ + +This is equivalent to cases 2, 3 or 8, depending on the type of image at +the current image address. + +Boot method: see cases 2,3,8 + +Legacy uImage syntax +~~~~~~~~~~~~~~~~~~~~ + +:: + + 2. bootm <addr1> /* single image at <addr1> */ + +Boot kernel image located at <addr1>. + +Boot method: non-FDT + +:: + + 3. bootm <addr1> /* multi-image at <addr1> */ + +First and second components of the image at <addr1> are assumed to be a +kernel and a ramdisk, respectively. The kernel is booted with initrd loaded +with the ramdisk from the image. + +Boot method: depends on the number of components at <addr1>, and on whether +U-Boot is compiled with OF support, which it should be. + + ==================== ======================== ======================== + Configuration 2 components 3 components + (kernel, initrd) (kernel, initrd, fdt) + ==================== ======================== ======================== + #ifdef CONFIG_OF_* non-FDT FDT + #ifndef CONFIG_OF_* non-FDT non-FDT + ==================== ======================== ======================== + +:: + + 4. bootm <addr1> - /* multi-image at <addr1> */ + +Similar to case 3, but the kernel is booted without initrd. Second +component of the multi-image is irrelevant (it can be a dummy, 1-byte file). + +Boot method: see case 3 + +:: + + 5. bootm <addr1> <addr2> /* single image at <addr1> */ + +Boot kernel image located at <addr1> with initrd loaded with ramdisk +from the image at <addr2>. + +Boot method: non-FDT + +:: + + 6. bootm <addr1> <addr2> <addr3> /* single image at <addr1> */ + +<addr1> is the address of a kernel image, <addr2> is the address of a +ramdisk image, and <addr3> is the address of a FDT binary blob. Kernel is +booted with initrd loaded with ramdisk from the image at <addr2>. + +Boot method: FDT + +:: + + 7. bootm <addr1> - <addr3> /* single image at <addr1> */ + +<addr1> is the address of a kernel image and <addr3> is the address of +a FDT binary blob. Kernel is booted without initrd. + +Boot method: FDT + +FIT syntax +~~~~~~~~~~ + +:: + + 8. bootm <addr1> + +Image at <addr1> is assumed to contain a default configuration, which +is booted. + +Boot method: FDT or non-FDT, depending on whether the default configuration +defines FDT + +:: + + 9. bootm [<addr1>]:<subimg1> + +Similar to case 2: boot kernel stored in <subimg1> from the image at +address <addr1>. + +Boot method: non-FDT + +:: + + 10. bootm [<addr1>]#<conf>[#<extra-conf[#...]] + +Boot configuration <conf> from the image at <addr1>. + +Boot method: FDT or non-FDT, depending on whether the configuration given +defines FDT + +:: + + 11. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> + +Equivalent to case 5: boot kernel stored in <subimg1> from the image +at <addr1> with initrd loaded with ramdisk <subimg2> from the image at +<addr2>. + +Boot method: non-FDT + +:: + + 12. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> [<addr3>]:<subimg3> + +Equivalent to case 6: boot kernel stored in <subimg1> from the image +at <addr1> with initrd loaded with ramdisk <subimg2> from the image at +<addr2>, and pass FDT blob <subimg3> from the image at <addr3>. + +Boot method: FDT + +:: + + 13. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> <addr3> + +Similar to case 12, the difference being that <addr3> is the address +of FDT binary blob that is to be passed to the kernel. + +Boot method: FDT + +:: + + 14. bootm [<addr1>]:<subimg1> - [<addr3>]:<subimg3> + +Equivalent to case 7: boot kernel stored in <subimg1> from the image +at <addr1>, without initrd, and pass FDT blob <subimg3> from the image at +<addr3>. + +Boot method: FDT + + 15. bootm [<addr1>]:<subimg1> - <addr3> + +Similar to case 14, the difference being that <addr3> is the address +of the FDT binary blob that is to be passed to the kernel. + +Boot method: FDT + + + +Example +------- + +boot kernel "kernel-1" stored in a new uImage located at 200000:: + + bootm 200000:kernel-1 + +boot configuration "cfg-1" from a new uImage located at 200000:: + + bootm 200000#cfg-1 + +boot configuration "cfg-1" with extra "cfg-2" from a new uImage located +at 200000:: + + bootm 200000#cfg-1#cfg-2 + +boot "kernel-1" from a new uImage at 200000 with initrd "ramdisk-2" found in +some other new uImage stored at address 800000:: + + bootm 200000:kernel-1 800000:ramdisk-2 + +boot "kernel-2" from a new uImage at 200000, with initrd "ramdisk-1" and FDT +"fdt-1", both stored in some other new uImage located at 800000:: + + bootm 200000:kernel-1 800000:ramdisk-1 800000:fdt-1 + +boot kernel "kernel-2" with initrd "ramdisk-2", both stored in a new uImage +at address 200000, with a raw FDT blob stored at address 600000:: + + bootm 200000:kernel-2 200000:ramdisk-2 600000 + +boot kernel "kernel-2" from new uImage at 200000 with FDT "fdt-1" from the +same new uImage:: + + bootm 200000:kernel-2 - 200000:fdt-1 + +.. sectionauthor:: Bartlomiej Sieka <tur@semihalf.com> +.. sectionauthor:: Simon Glass <sjg@chromium.org> diff --git a/doc/usage/cmd/bootmenu.rst b/doc/usage/cmd/bootmenu.rst new file mode 100644 index 00000000000..294cc02b17a --- /dev/null +++ b/doc/usage/cmd/bootmenu.rst @@ -0,0 +1,167 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. (C) Copyright 2011-2012 Pali Rohár <pali@kernel.org> + +.. index:: + single: bootmenu (command) + +bootmenu command +================ + +Synopsis +-------- +:: + + bootmenu [delay] + +Description +----------- + +The "bootmenu" command uses U-Boot menu interfaces and provides +a simple mechanism for creating menus with different boot items. +The cursor keys "Up" and "Down" are used for navigation through +the items. Current active menu item is highlighted and can be +selected using the "Enter" key. The selection of the highlighted +menu entry invokes an U-Boot command (or a list of commands) +associated with this menu entry. + +The "bootmenu" command interprets ANSI escape sequences, so +an ANSI terminal is required for proper menu rendering and item +selection. + +The assembling of the menu is done via a set of environment variables +"bootmenu_<num>" and "bootmenu_delay", i.e.:: + + bootmenu_delay=<delay> + bootmenu_<num>="<title>=<commands>" + +<delay> + is the autoboot delay in seconds, after which the first + menu entry will be selected automatically + +<num> + is the boot menu entry number, starting from zero + +<title> + is the text of the menu entry shown on the console + or on the boot screen + +<commands> + are commands which will be executed when a menu + entry is selected + +Title and commands are separated by the first appearance of a '=' +character in the value of the environment variable. + +The first (optional) argument of the "bootmenu" command is a delay specifier +and it overrides the delay value defined by "bootmenu_delay" environment +variable. If the environment variable "bootmenu_delay" is not set or if +the argument of the "bootmenu" command is not specified, the default delay +will be CONFIG_BOOTDELAY. If delay is 0, no menu entries will be shown on +the console (or on the screen) and the command of the first menu entry will +be called immediately. If delay is less then 0, bootmenu will be shown and +autoboot will be disabled. + +Bootmenu always adds menu entry "U-Boot console" at the end of all menu +entries specified by environment variables. When selecting this entry +the bootmenu terminates and the usual U-Boot command prompt is presented +to the user. + +Example environment:: + + setenv bootmenu_0 Boot 1. kernel=bootm 0x82000000 # Set first menu entry + setenv bootmenu_1 Boot 2. kernel=bootm 0x83000000 # Set second menu entry + setenv bootmenu_2 Reset board=reset # Set third menu entry + setenv bootmenu_3 U-Boot boot order=boot # Set fourth menu entry + bootmenu 20 # Run bootmenu with autoboot delay 20s + + +The above example will be rendered as below:: + + *** U-Boot Boot Menu *** + + Boot 1. kernel + Boot 2. kernel + Reset board + U-Boot boot order + U-Boot console + + Hit any key to stop autoboot: 20 + Press UP/DOWN to move, ENTER to select + +The selected menu entry will be highlighted - it will have inverted +background and text colors. + +UEFI boot variable enumeration +'''''''''''''''''''''''''''''' +If enabled, the bootmenu command will automatically generate and add +UEFI-related boot menu entries for the following items. + + * possible bootable media with default file names + * user-defined UEFI boot options + +The bootmenu automatically enumerates the possible bootable +media devices supporting EFI_SIMPLE_FILE_SYSTEM_PROTOCOL. +This auto generated entry is named as "<interface> <devnum>:<part>" format. +(e.g. "usb 0:1") + +The bootmenu displays the UEFI-related menu entries in order of "BootOrder". +When the user selects the UEFI boot menu entry, the bootmenu sets +the selected boot variable index to "BootNext" without non-volatile attribute, +then call the uefi boot manager with the command "bootefi bootmgr". + +Example bootmenu is as below:: + + *** U-Boot Boot Menu *** + + mmc 0:1 + mmc 0:2 + debian + nvme 0:1 + ubuntu + nvme 0:2 + usb 0:2 + U-Boot console + +Default behavior when user exits from the bootmenu +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +User can exit from bootmenu by selecting the last entry +"U-Boot console"/"Quit" or ESC key. + +When the CONFIG_BOOTMENU_DISABLE_UBOOT_CONSOLE is disabled, +user exits from the bootmenu and returns to the U-Boot console. + +When the CONFIG_BOOTMENU_DISABLE_UBOOT_CONSOLE is enabled, user can not +enter the U-Boot console. When the user exits from the bootmenu, +the bootmenu invokes the following default behavior. + + * if CONFIG_CMD_BOOTEFI_BOOTMGR is enabled, execute "bootefi bootmgr" command + * "bootefi bootmgr" fails or is not enabled, then execute "run bootcmd" command. + +Configuration +------------- + +The "bootmenu" command is enabled by:: + + CONFIG_CMD_BOOTMENU=y + +To run the bootmenu at startup add these additional settings:: + + CONFIG_AUTOBOOT_KEYED=y + CONFIG_BOOTDELAY=30 + CONFIG_AUTOBOOT_MENU_SHOW=y + +UEFI boot variable enumeration is enabled by:: + + CONFIG_CMD_BOOTEFI_BOOTMGR=y + +To improve the product security, entering U-Boot console from bootmenu +can be disabled by:: + + CONFIG_BOOTMENU_DISABLE_UBOOT_CONSOLE=y + +To scan the discoverable devices connected to the buses such as +USB and PCIe prior to bootmenu showing up, CONFIG_PREBOOT can be +used to run the command before showing the bootmenu, i.e.:: + + CONFIG_USE_PREBOOT=y + CONFIG_PREBOOT="pci enum; usb start; scsi scan; nvme scan; virtio scan" diff --git a/doc/usage/cmd/bootmeth.rst b/doc/usage/cmd/bootmeth.rst new file mode 100644 index 00000000000..c3d2ec1574b --- /dev/null +++ b/doc/usage/cmd/bootmeth.rst @@ -0,0 +1,114 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: bootmeth (command) + +bootmeth command +================ + +Synopsis +-------- + +:: + + bootmeth list [-a] - list selected bootmeths (-a for all) + bootmeth order "[<bm> ...]" - select the order of bootmeths\n" + + +Description +----------- + +The `bootmeth` command is used to manage bootmeths. It can list them and change +the order in which they are used. + +See :doc:`/develop/bootstd/index` for more information. + + +.. _bootmeth_order: + +bootmeth order +~~~~~~~~~~~~~~ + +Selects which bootmeths to use and the order in which they are invoked. When +scanning bootdevs, each bootmeth is tried in turn to see if it can find a valid +bootflow. You can use this command to adjust the order or even to omit some +boomeths. + +The argument is a quoted list of bootmeths to use, by name. If global bootmeths +are included, they must be at the end, otherwise the scanning mechanism will not +work correctly. + + +bootmeth list +~~~~~~~~~~~~~ + +This lists the selected bootmeths, or all of them, if the `-a` flag is used. +The format looks like this: + +===== === ================== ================================= +Order Seq Name Description +===== === ================== ================================= + 0 0 extlinux Extlinux boot from a block device + 1 1 efi EFI boot from an .efi file + 2 2 pxe PXE boot from a network device + 3 3 sandbox Sandbox boot for testing + glob 4 efi_mgr EFI bootmgr flow +===== === ================== ================================= + +The fields are as follows: + +Order: + The order in which these bootmeths are invoked for each bootdev. If this + shows as a hyphen, then the bootmeth is not in the current ordering. If it + shows as 'glob', then this is a global bootmeth and should be at the end. + +Seq: + The sequence number of the bootmeth, i.e. the normal ordering if none is set + +Name: + Name of the bootmeth + +Description: + A friendly description for the bootmeth + + +Example +------- + +This shows listing bootmeths. All are present and in the normal order:: + + => bootmeth list + Order Seq Name Description + ----- --- ------------------ ------------------ + 0 0 distro Extlinux boot from a block device + 1 1 efi EFI boot from an .efi file + 2 2 pxe PXE boot from a network device + 3 3 sandbox Sandbox boot for testing + 4 4 efi_mgr EFI bootmgr flow + ----- --- ------------------ ------------------ + (5 bootmeths) + +Now the order is changed, to include only two of them:: + + => bootmeth order "sandbox distro" + => bootmeth list + Order Seq Name Description + ----- --- ------------------ ------------------ + 0 3 sandbox Sandbox boot for testing + 1 0 distro Extlinux boot from a block device + ----- --- ------------------ ------------------ + (2 bootmeths) + +The -a flag shows all bootmeths so you can clearly see which ones are used and +which are not:: + + => bootmeth list -a + Order Seq Name Description + ----- --- ------------------ ------------------ + 1 0 distro Extlinux boot from a block device + - 1 efi EFI boot from an .efi file + - 2 pxe PXE boot from a network device + 0 3 sandbox Sandbox boot for testing + - 4 efi_mgr EFI bootmgr flow + ----- --- ------------------ ------------------ + (5 bootmeths) diff --git a/doc/usage/cmd/bootz.rst b/doc/usage/cmd/bootz.rst new file mode 100644 index 00000000000..b85875adde3 --- /dev/null +++ b/doc/usage/cmd/bootz.rst @@ -0,0 +1,69 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: bootz (command) + +bootz command +============= + +Synopsis +-------- + +:: + + bootz [<addr> [<initrd>[:<size>]] [<fdt>]] + +Description +----------- + +The bootz command is used to boot a Linux kernel in 'zImage' format. + +addr + address of kernel image, defaults to the value of the environment + variable $loadaddr. + +initrd + address of the initial RAM disk. Use '-' to boot a kernel with a device + tree but without an initial RAM disk. + +size + size of the initial RAM disk. This parameter must be specified for raw + initial RAM disks. + +fdt + address of the device tree. + +Example +------- + +This is the boot log of an OrangePi PC board: + +:: + + => load mmc 0:2 $fdt_addr_r dtb + 23093 bytes read in 7 ms (3.1 MiB/s) + => load mmc 0:2 $kernel_addr_r vmlinuz + 5079552 bytes read in 215 ms (22.5 MiB/s) + => load mmc 0:2 $ramdisk_addr_r initrd.img + 23854965 bytes read in 995 ms (22.9 MiB/s) + => bootz $kernel_addr_r $ramdisk_addr_r:$filesize $fdt_addr_r + Kernel image @ 0x42000000 [ 0x000000 - 0x4d8200 ] + ## Flattened Device Tree blob at 43000000 + Booting using the fdt blob at 0x43000000 + EHCI failed to shut down host controller. + Loading Ramdisk to 48940000, end 49ffff75 ... OK + Loading Device Tree to 48937000, end 4893fa34 ... OK + + Starting kernel ... + +Configuration +------------- + +The bootz command is only available if CONFIG_CMD_BOOTZ=y. + +Return value +------------ + +Normally this command does not return. If an error occurs, the return value $? +is set to 1 (false). If the operating system returns to U-Boot, the system is +reset. diff --git a/doc/usage/cmd/button.rst b/doc/usage/cmd/button.rst new file mode 100644 index 00000000000..6c6794f31b8 --- /dev/null +++ b/doc/usage/cmd/button.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: button (command) + +button command +============== + +Synopsis +-------- + +:: + + button list + button <name> + +Description +----------- + +The button command is used to retrieve the status of a button. To show the +status of a button with name 'button1' you would issue the command + +:: + + button button1 + +The status of the button is both written to the console as *ON* or *OFF* and +set in the return value variable *$?* as 0 (true) or 1 (false). To retrieve +the status of a button with name *button1* and to write it to environment +variable *status1* you would execute the commands + +:: + + button button1 + setenv status1 $? + +A list of all available buttons and their status can be displayed using + +:: + + button list + +If a button device has not been probed yet, its status will be shown as +*<inactive>* in the list. + +Configuration +------------- + +To use the button command you must specify CONFIG_CMD_BUTTON=y and enable a +button driver. The available buttons are defined in the device-tree. + +Return value +------------ + +The variable *$?* takes the following values + ++---+-----------------------------+ +| 0 | ON, the button is pressed | ++---+-----------------------------+ +| 1 | OFF, the button is released | ++---+-----------------------------+ +| 0 | button list was shown | ++---+-----------------------------+ +| 1 | button not found | ++---+-----------------------------+ +| 1 | invalid arguments | ++---+-----------------------------+ diff --git a/doc/usage/cmd/cat.rst b/doc/usage/cmd/cat.rst new file mode 100644 index 00000000000..b22dc6184a2 --- /dev/null +++ b/doc/usage/cmd/cat.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: cat (command) + +cat command +=========== + +Synopsis +-------- + +:: + + cat <interface> <dev[:part]> <file> + +Description +----------- + +The cat command prints the file content to standard out. + +interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + +dev + device number + +part + partition number, defaults to 1 + +file + path to file + +Example +------- + +Here is the output for a example text file: + +:: + + => cat mmc 0:1 hello + hello world + => + +Configuration +------------- + +The cat command is only available if CONFIG_CMD_CAT=y. + +Return value +------------ + +The return value $? is set to 0 (true) if the file is readable, otherwise it returns a non-zero error code. diff --git a/doc/usage/cmd/cbsysinfo.rst b/doc/usage/cmd/cbsysinfo.rst new file mode 100644 index 00000000000..80d8ba1b662 --- /dev/null +++ b/doc/usage/cmd/cbsysinfo.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +cbsysinfo +========= + +Synopsis +-------- + +:: + + cbsysinfo + + +Description +----------- + +This displays information obtained from the coreboot sysinfo table. It is only +useful when booting U-Boot from coreboot. + +Example +------- + +:: + + => cbsysinfo diff --git a/doc/usage/cmd/cedit.rst b/doc/usage/cmd/cedit.rst new file mode 100644 index 00000000000..5670805a00e --- /dev/null +++ b/doc/usage/cmd/cedit.rst @@ -0,0 +1,151 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: cedit (command) + +cedit command +============= + +Synopsis +-------- + +:: + + cedit load <interface> <dev[:part]> <filename> + cedit run + cedit write_fdt <dev[:part]> <filename> + cedit read_fdt <dev[:part]> <filename> + cedit write_env [-v] + cedit read_env [-v] + cedit write_cmos [-v] [dev] + +Description +----------- + +The *cedit* command is used to load a configuration-editor description and allow +the user to interact with it. + +It makes use of the expo subsystem. + +The description is in the form of a devicetree file, as documented at +:ref:`expo_format`. + +See :doc:`../../develop/cedit` for information about the configuration editor. + +cedit load +~~~~~~~~~~ + +Loads a configuration-editor description from a file. It creates a new cedit +structure ready for use. Initially no settings are read, so default values are +used for each object. + +cedit run +~~~~~~~~~ + +Runs the default configuration-editor event loop. This is very simple, just +accepting character input and moving through the objects under user control. +The implementation is at `cedit_run()`. + +cedit write_fdt +~~~~~~~~~~~~~~~ + +Writes the current user settings to a devicetree file. For each menu item the +selected ID and its text string are written. + +cedit read_fdt +~~~~~~~~~~~~~~ + +Reads the user settings from a devicetree file and updates the cedit with those +settings. + +cedit read_env +~~~~~~~~~~~~~~ + +Reads the settings from the environment variables. For each menu item `<name>`, +cedit looks for a variable called `c.<name>` with the ID of the selected menu +item. + +The `-v` flag enables verbose mode, where each variable is printed after it is +read. + +cedit write_env +~~~~~~~~~~~~~~~ + +Writes the settings to environment variables. For each menu item the selected +ID and its text string are written, similar to: + + setenv c.<name> <selected_id> + setenv c.<name>-str <selected_id's text string> + +The `-v` flag enables verbose mode, where each variable is printed before it is +set. + +cedit write_cmos +~~~~~~~~~~~~~~~~ + +Writes the settings to locations in the CMOS RAM. The locations used are +specified by the schema. See `expo_format_`. + +The `-v` flag enables verbose mode, which shows which CMOS locations were +updated. + +Normally the first RTC device is used to hold the data. You can specify a +different device by name using the `dev` parameter. + + +Example +------- + +:: + + => cedit load hostfs - fred.dtb + => cedit run + => cedit write_fdt hostfs - settings.dtb + +That results in:: + + / { + cedit-values { + cpu-speed = <0x00000006>; + cpu-speed-str = "2 GHz"; + power-loss = <0x0000000a>; + power-loss-str = "Always Off"; + }; + } + + => cedit read_fdt hostfs - settings.dtb + +This shows settings being stored in the environment:: + + => cedit write_env -v + c.cpu-speed=7 + c.cpu-speed-str=2.5 GHz + c.power-loss=12 + c.power-loss-str=Memory + => print + ... + c.cpu-speed=6 + c.cpu-speed-str=2 GHz + c.power-loss=10 + c.power-loss-str=Always Off + ... + + => cedit read_env -v + c.cpu-speed=7 + c.power-loss=12 + +This shows writing to CMOS RAM. Notice that the bytes at 80 and 84 change:: + + => rtc read 80 8 + 00000080: 00 00 00 00 00 2f 2a 08 ...../*. + => cedit write_cmos -v + Write 2 bytes from offset 80 to 84 + => rtc read 80 8 + 00000080: 01 00 00 00 08 2f 2a 08 ...../*. + => cedit read_cmos -v + Read 2 bytes from offset 80 to 84 + +Here is an example with the device specified:: + + => cedit write_cmos rtc@43 + => diff --git a/doc/usage/cmd/cli.rst b/doc/usage/cmd/cli.rst new file mode 100644 index 00000000000..23e5ee7a902 --- /dev/null +++ b/doc/usage/cmd/cli.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: cli (command) + +cli command +=========== + +Synopsis +-------- + +:: + + cli get + cli set cli_flavor + +Description +----------- + +The cli command permits getting and changing the current parser at runtime. + +cli get +~~~~~~~ + +It shows the current value of the parser used by the CLI. + +cli set +~~~~~~~ + +It permits setting the value of the parser used by the CLI. + +Possible values are old and modern. +Note that, to use a specific parser its code should have been compiled, that +is to say you need to enable the corresponding CONFIG_HUSH*. +Otherwise, an error message is printed. + +Examples +-------- + +Get the current parser:: + + => cli get + old + +Change the current parser:: + + => cli get + old + => cli set modern + => cli get + modern + => cli set old + => cli get + old + +Trying to set the current parser to an unknown value:: + + => cli set foo + Bad value for parser name: foo + cli - cli + + Usage: + cli get - print current cli + set - set the current cli, possible values are: old, modern + +Trying to set the current parser to a correct value but its code was not +compiled:: + + => cli get + modern + => cli set old + Want to set current parser to old, but its code was not compiled! + +Return value +------------ + +The return value $? indicates whether the command succeeded. diff --git a/doc/usage/cmd/cls.rst b/doc/usage/cmd/cls.rst new file mode 100644 index 00000000000..828276742b9 --- /dev/null +++ b/doc/usage/cmd/cls.rst @@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: cls (command) + +cls command +=========== + +Synopsis +-------- + +:: + + cls + +Description +----------- + +The cls command clears the screen. + +Configuration +------------- + +The cls command is only available if CONFIG_CMD_CLS=y. + +Return value +------------ + +The return value $? is 0 (true) on success and 1 (false) on failure. diff --git a/doc/usage/cmd/cmp.rst b/doc/usage/cmd/cmp.rst new file mode 100644 index 00000000000..a3830747364 --- /dev/null +++ b/doc/usage/cmd/cmp.rst @@ -0,0 +1,108 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: cmp (command) + +cmp command +=========== + +Synopsis +-------- + +:: + + cmp [.b, .w, .l, .q] addr1 addr2 count + +Description +----------- + +The cmp command is used to compare two memory areas. By default it works on +four byte (32-bit) values. By appending .b, .w, .l, .q the size of the +values is controlled: + +cmp.b + compare 1 byte (8-bit) values + +cmp.w + compare 2 byte (16-bit) values + +cmp.l + compare 4 byte (32-bit) values + +cmp.q + compare 8 byte (64-bit) values + +The parameters are used as follows: + +addr1 + Address of the first memory area. + +addr2 + Address of the second memory area. + +count + Number of bytes to compare (as hexadecimal number). + +Example +------- + +In the example below the strings "Hello world\n" and "Hello World\n" are written +to memory and then compared. + +:: + + => mm.b 0x1000000 + 01000000: 00 ? 48 + 01000001: 00 ? 65 + 01000002: 00 ? 6c + 01000003: 00 ? 6c + 01000004: 00 ? 6f + 01000005: 00 ? 20 + 01000006: 00 ? 77 + 01000007: 00 ? 6f + 01000008: 00 ? 72 + 01000009: 00 ? 6c + 0100000a: 00 ? 64 + 0100000b: 00 ? 0d + 0100000c: 00 ? => <INTERRUPT> + => mm.b 0x101000 + 00101000: 00 ? 48 + 00101001: 00 ? 65 + 00101002: 00 ? 6c + 00101003: 00 ? 6c + 00101004: 00 ? 6f + 00101005: 00 ? 20 + 00101006: 00 ? 57 + 00101007: 00 ? 6f + 00101008: 00 ? 72 + 00101009: 00 ? 6c + 0010100a: 00 ? 64 + 0010100b: 00 ? 0d + 0010100c: 00 ? => <INTERRUPT> + => cmp 0x1000000 0x101000 0xc + word at 0x01000004 (0x6f77206f) != word at 0x00101004 (0x6f57206f) + Total of 1 word(s) were the same + => cmp.b 0x1000000 0x101000 0xc + byte at 0x01000006 (0x77) != byte at 0x00101006 (0x57) + Total of 6 byte(s) were the same + => cmp.w 0x1000000 0x101000 0xc + halfword at 0x01000006 (0x6f77) != halfword at 0x00101006 (0x6f57) + Total of 3 halfword(s) were the same + => cmp.l 0x1000000 0x101000 0xc + word at 0x01000004 (0x6f77206f) != word at 0x00101004 (0x6f57206f) + Total of 1 word(s) were the same + => cmp.q 0x1000000 0x101000 0xc + double word at 0x01000000 (0x6f77206f6c6c6548) != double word at 0x00101000 (0x6f57206f6c6c6548) + Total of 0 double word(s) were the same + +Configuration +------------- + +The cmp command is only available if CONFIG_CMD_MEMORY=y. The cmp.q command is +only available on 64-bit targets. + +Return value +------------ + +The return value $? is true (0) if the compared memory areas are equal. +The reutrn value is false (1) if the compared memory areas differ. diff --git a/doc/usage/cmd/coninfo.rst b/doc/usage/cmd/coninfo.rst new file mode 100644 index 00000000000..a66cf90a27b --- /dev/null +++ b/doc/usage/cmd/coninfo.rst @@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: coninfo (command) + +coninfo command +=============== + +Synopsis +-------- + +:: + + coninfo + +Description +----------- + +The coninfo command provides a list of available console input and output +devices and their assignment as stdin, stdout, stderr console devices. + +If CONFIG_SYS_CONSOLE_IS_IN_ENV=y, the assignment is controlled by the +environment variables stdin, stdout, stderr which contain a comma separated +list of device names. + +Example +------- + +.. code-block:: console + + => coninfo + List of available devices + |-- pl011@9000000 (IO) + | |-- stdin + | |-- stdout + | |-- stderr + |-- serial (IO) + |-- usbkbd (I) + => setenv stdin pl011@9000000,usbkbd + => coninfo + List of available devices + |-- pl011@9000000 (IO) + | |-- stdin + | |-- stdout + | |-- stderr + |-- serial (IO) + |-- usbkbd (I) + | |-- stdin + +Configuration +------------- + +The coninfo command is only available if CONFIG_CMD_CONSOLE=y. + +Return value +------------ + +The return value $? is always 0 (true). diff --git a/doc/usage/cmd/conitrace.rst b/doc/usage/cmd/conitrace.rst new file mode 100644 index 00000000000..38ec66ad529 --- /dev/null +++ b/doc/usage/cmd/conitrace.rst @@ -0,0 +1,57 @@ +.. index:: + single: conitrace (command) + +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/cmd/cp.rst b/doc/usage/cmd/cp.rst new file mode 100644 index 00000000000..434dfedfc2b --- /dev/null +++ b/doc/usage/cmd/cp.rst @@ -0,0 +1,87 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: cp (command) + +cp command +========== + +Synopsis +-------- + +:: + + cp source target count + cp.b source target count + cp.w source target count + cp.l source target count + cp.q source target count + +Description +----------- + +The cp command is used to copy *count* chunks of memory from the *source* +address to the *target* address. If the *target* address points to NOR flash, +the flash is programmed. When the *target* address points at ordinary memory, +memmove() is used, so the two regions may overlap. + +The number bytes in one chunk is defined by the suffix defaulting to 4 bytes: + +====== ========== +suffix chunk size +====== ========== +.b 1 byte +.w 2 bytes +.l 4 bytes +.q 8 bytes +<none> 4 bytes +====== ========== + +source + source address, hexadecimal + +target + target address, hexadecimal + +count + number of words to be copied, hexadecimal + +Examples +-------- + +The example device has a NOR flash where the lower part of the flash is +protected. We first copy to RAM, then to unprotected flash. Last we try to +write to protectd flash. + +:: + + => mtd list + List of MTD devices: + * nor0 + - device: flash@0 + - parent: root_driver + - driver: cfi_flash + - path: /flash@0 + - type: NOR flash + - block size: 0x20000 bytes + - min I/O: 0x1 bytes + - 0x000000000000-0x000002000000 : "nor0" + => cp.b 4020000 5000000 200000 + => cp.b 4020000 1e00000 20000 + Copy to Flash... done + => cp.b 4020000 0 20000 + Copy to Flash... Can't write to protected Flash sectors + => + +Configuration +------------- + +The cp command is available if CONFIG_CMD_MEMORY=y. Support for 64 bit words +(cp.q) is only available on 64-bit targets. Copying to flash depends on +CONFIG_MTD_NOR_FLASH=y. + +Return value +------------ + +The return value $? is set to 0 (true) if the command was successfully, +1 (false) otherwise. diff --git a/doc/usage/cmd/cyclic.rst b/doc/usage/cmd/cyclic.rst new file mode 100644 index 00000000000..ac1e4c663bf --- /dev/null +++ b/doc/usage/cmd/cyclic.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: cyclic (command) + +cyclic command +============== + +Synopsis +-------- + +:: + + cyclic list + +Description +----------- + +The cyclic list command provides a list of the currently registered +cyclic functions. + +This shows the following information: + +Function + Function name + +cpu-time + Total time spent in this cyclic function. + +Frequency + Frequency of execution of this function, e.g. 100 times/s for a + pediod of 10ms. + + +See :doc:`../../develop/cyclic` for more information on cyclic functions. + +Example +------- + +:: + + => cyclic list + function: cyclic_demo, cpu-time: 52906 us, frequency: 99.20 times/s + +Configuration +------------- + +The cyclic command is only available if CONFIG_CMD_CYCLIC=y. diff --git a/doc/usage/cmd/dm.rst b/doc/usage/cmd/dm.rst new file mode 100644 index 00000000000..7651507937a --- /dev/null +++ b/doc/usage/cmd/dm.rst @@ -0,0 +1,519 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: dm (command) + +dm command +========== + +Synopsis +-------- + +:: + + dm compat + dm devres + dm drivers + dm static + dm tree [-s][-e] [uclass name] + dm uclass [-e] [udevice name] + +Description +----------- + +The *dm* command allows viewing information about driver model, including the +tree of devices and list of available uclasses. + + +dm compat +~~~~~~~~~ + +This shows the compatible strings associated with each driver. Often there +is only one, but multiple strings are shown on their own line. These strings +can be looked up in the device tree files for each board, to see which driver is +used for each node. + +dm devres +~~~~~~~~~ + +This shows a list of a `devres` (device resource) records for a device. Some +drivers use the devres API to allocate memory, so that it can be freed +automatically (without any code needed in the driver's remove() method) when the +device is removed. + +This feature is controlled by CONFIG_DEVRES so no useful output is obtained if +this option is disabled. + +dm drivers +~~~~~~~~~~ + +This shows all the available drivers, their uclass and a list of devices that +use that driver, each on its own line. Drivers with no devices are shown with +`<none>` as the driver name. + + +dm mem +~~~~~~ + +This subcommand is really just for debugging and exploration. It can be enabled +with the `CONFIG_DM_STATS` option. + +All output is in hex except that in brackets which is decimal. + +The output consists of a header shows the size of the main device model +structures (struct udevice, struct driver, struct uclass and struct uc_driver) +and the count and memory used by each (number of devices, memory used by +devices, memory used by device names, number of uclasses, memory used by +uclasses). + +After that is a table of information about each type of data that can be +attached to a device, showing the number that have non-null data for that type, +the total size of all that data, the amount of memory used in total, the +amount that would be used if this type uses tags instead and the amount that +would be thus saved. + +The `driver_data` line shows the number of devices which have non-NULL driver +data. + +The `tags` line shows the number of tags and the memory used by those. + +At the bottom is an indication of the total memory usage obtained by undertaking +various changes, none of which is currently implemented in U-Boot: + +With tags + Using tags instead of all attached types + +Singly linked + Using a singly linked list + +driver index + Using a driver index instead of a pointer + +uclass index + Using a uclass index instead of a pointer + +Drop device name + Using empty device names + + +dm static +~~~~~~~~~ + +This shows devices bound by platform data, i.e. not from the device tree. There +are normally none of these, but some boards may use static devices for space +reasons. + + +dm tree +~~~~~~~ + +This shows the full tree of devices including the following fields: + +uclass + Shows the name of the uclass for the device + +Index + Shows the index number of the device, within the uclass. This shows the + ordering within the uclass, but not the sequence number. + +Probed + Shows `+` if the device is active + +Driver + Shows the name of the driver that this device uses + +Name + Shows the device name as well as the tree structure, since child devices are + shown attached to their parent. + +If -s is given, the top-level devices (those which are children of the root +device) are shown sorted in order of uclass ID, so it is easier to find a +particular device type. + +If -e is given, forward-matching against existing devices is +made and only the matched devices are shown. + +If a device name is given, forward-matching against existing devices is +made and only the matched devices are shown. + +dm uclass +~~~~~~~~~ + +This shows each uclass along with a list of devices in that uclass. The uclass +ID is shown (e.g. uclass 7) and its name. + +For each device, the format is:: + + n name @ a, seq s + +where `n` is the index within the uclass, `a` is the address of the device in +memory and `s` is the sequence number of the device. + +If -e is given, forward-matching against existing uclasses is +made and only the matched uclasses are shown. + +If no uclass name is given, all the uclasses are shown. + + +Examples +-------- + +dm compat +~~~~~~~~~ + +This example shows an abridged version of the sandbox output:: + + => dm compat + Driver Compatible + -------------------------------- + act8846_reg + sandbox_adder sandbox,adder + axi_sandbox_bus sandbox,axi + blk_partition + bootcount-rtc u-boot,bootcount-rtc + ... + rockchip_rk805 rockchip,rk805 + rockchip,rk808 + rockchip,rk809 + rockchip,rk816 + rockchip,rk817 + rockchip,rk818 + root_driver + rtc-rv8803 microcrystal,rv8803 + epson,rx8803 + epson,rx8900 + ... + wdt_gpio linux,wdt-gpio + wdt_sandbox sandbox,wdt + + +dm devres +~~~~~~~~~ + +This example shows an abridged version of the sandbox test output (running +U-Boot with the -T flag):: + + => dm devres + - root_driver + - demo_shape_drv + - demo_simple_drv + - demo_shape_drv + ... + - h-test + - devres-test + 00000000130194e0 (100 byte) devm_kmalloc_release BIND + - another-test + ... + - syscon@3 + - a-mux-controller + 0000000013025e60 (96 byte) devm_kmalloc_release PROBE + 0000000013025f00 (24 byte) devm_kmalloc_release PROBE + 0000000013026010 (24 byte) devm_kmalloc_release PROBE + 0000000013026070 (24 byte) devm_kmalloc_release PROBE + 00000000130260d0 (24 byte) devm_kmalloc_release PROBE + - syscon@3 + - a-mux-controller + 0000000013026150 (96 byte) devm_kmalloc_release PROBE + 00000000130261f0 (24 byte) devm_kmalloc_release PROBE + 0000000013026300 (24 byte) devm_kmalloc_release PROBE + 0000000013026360 (24 byte) devm_kmalloc_release PROBE + 00000000130263c0 (24 byte) devm_kmalloc_release PROBE + - emul-mux-controller + 0000000013025fa0 (32 byte) devm_kmalloc_release PROBE + - testfdtm0 + - testfdtm1 + ... + - pinmux_spi0_pins + - pinmux_uart0_pins + - pinctrl-single-bits + 0000000013229180 (320 byte) devm_kmalloc_release PROBE + 0000000013229300 (40 byte) devm_kmalloc_release PROBE + 0000000013229370 (160 byte) devm_kmalloc_release PROBE + 000000001322c190 (40 byte) devm_kmalloc_release PROBE + 000000001322c200 (32 byte) devm_kmalloc_release PROBE + - pinmux_i2c0_pins + ... + - reg@0 + - reg@1 + + +dm drivers +~~~~~~~~~~ + +This example shows an abridged version of the sandbox output:: + + => dm drivers + Driver uid uclass Devices + ---------------------------------------------------------- + act8846_reg 087 regulator <none> + sandbox_adder 021 axi adder + adder + axi_sandbox_bus 021 axi axi@0 + ... + da7219 061 misc <none> + demo_shape_drv 001 demo demo_shape_drv + demo_shape_drv + demo_shape_drv + demo_simple_drv 001 demo demo_simple_drv + demo_simple_drv + testfdt_drv 003 testfdt a-test + b-test + d-test + e-test + f-test + g-test + another-test + chosen-test + testbus_drv 005 testbus some-bus + mmio-bus@0 + mmio-bus@1 + dsa-port 039 ethernet lan0 + lan1 + dsa_sandbox 035 dsa dsa-test + eep_sandbox 121 w1_eeprom <none> + ... + pfuze100_regulator 087 regulator <none> + phy_sandbox 077 phy bind-test-child1 + gen_phy@0 + gen_phy@1 + gen_phy@2 + pinconfig 078 pinconfig gpios + gpio0 + gpio1 + gpio2 + gpio3 + i2c + groups + pins + i2s + spi + cs + pinmux_pwm_pins + pinmux_spi0_pins + pinmux_uart0_pins + pinmux_i2c0_pins + pinmux_lcd_pins + pmc_sandbox 017 power-mgr pci@1e,0 + act8846 pmic 080 pmic <none> + max77686_pmic 080 pmic <none> + mc34708_pmic 080 pmic pmic@41 + ... + wdt_gpio 122 watchdog gpio-wdt + wdt_sandbox 122 watchdog wdt@0 + => + + +dm mem +~~~~~~ + +This example shows the sandbox output:: + + > dm mem + Struct sizes: udevice b0, driver 80, uclass 30, uc_driver 78 + Memory: device fe:aea0, device names a16, uclass 5e:11a0 + + Attached type Count Size Cur Tags Save + --------------- ----- ----- ----- ----- ----- + plat 45 a8f aea0 a7c4 6dc (1756) + parent_plat 1a 3b8 aea0 a718 788 (1928) + uclass_plat 3d 6b4 aea0 a7a4 6fc (1788) + priv 8a 68f3 aea0 a8d8 5c8 (1480) + parent_priv 8 38a0 aea0 a6d0 7d0 (2000) + uclass_priv 4e 14a6 aea0 a7e8 6b8 (1720) + driver_data f 0 aea0 a6ec 7b4 (1972) + uclass 6 20 + Attached total 191 cb54 3164 (12644) + tags 0 0 + + Total size: 18b94 (101268) + + With tags: 15a30 (88624) + - singly-linked: 14260 (82528) + - driver index: 13b6e (80750) + - uclass index: 1347c (78972) + Drop device name (not SRAM): a16 (2582) + => + + +dm static +~~~~~~~~~ + +This example shows the sandbox output:: + + => dm static + Driver Address + --------------------------------- + demo_shape_drv 0000562edab8dca0 + demo_simple_drv 0000562edab8dca0 + demo_shape_drv 0000562edab8dc90 + demo_simple_drv 0000562edab8dc80 + demo_shape_drv 0000562edab8dc80 + test_drv 0000562edaae8840 + test_drv 0000562edaae8848 + test_drv 0000562edaae8850 + sandbox_gpio 0000000000000000 + mod_exp_sw 0000000000000000 + sandbox_test_proc 0000562edabb5330 + qfw_sandbox 0000000000000000 + sandbox_timer 0000000000000000 + sandbox_serial 0000562edaa8ed00 + sysreset_sandbox 0000000000000000 + + +dm tree +------- + +This example shows the abridged sandbox output:: + + => dm tree + Class Index Probed Driver Name + ----------------------------------------------------------- + root 0 [ + ] root_driver root_driver + demo 0 [ ] demo_shape_drv |-- demo_shape_drv + demo 1 [ ] demo_simple_drv |-- demo_simple_drv + demo 2 [ ] demo_shape_drv |-- demo_shape_drv + demo 3 [ ] demo_simple_drv |-- demo_simple_drv + demo 4 [ ] demo_shape_drv |-- demo_shape_drv + test 0 [ ] test_drv |-- test_drv + test 1 [ ] test_drv |-- test_drv + test 2 [ ] test_drv |-- test_drv + .. + sysreset 0 [ ] sysreset_sandbox |-- sysreset_sandbox + bootstd 0 [ ] bootstd_drv |-- bootstd + bootmeth 0 [ ] bootmeth_extlinux | |-- extlinux + bootmeth 1 [ ] bootmeth_efi | `-- efi + reboot-mod 0 [ ] reboot-mode-gpio |-- reboot-mode0 + reboot-mod 1 [ ] reboot-mode-rtc |-- reboot-mode@14 + ... + ethernet 7 [ + ] dsa-port | `-- lan1 + pinctrl 0 [ + ] sandbox_pinctrl_gpio |-- pinctrl-gpio + gpio 1 [ + ] sandbox_gpio | |-- base-gpios + nop 0 [ + ] gpio_hog | | |-- hog_input_active_low + nop 1 [ + ] gpio_hog | | |-- hog_input_active_high + nop 2 [ + ] gpio_hog | | |-- hog_output_low + nop 3 [ + ] gpio_hog | | `-- hog_output_high + gpio 2 [ ] sandbox_gpio | |-- extra-gpios + gpio 3 [ ] sandbox_gpio | `-- pinmux-gpios + i2c 0 [ + ] sandbox_i2c |-- i2c@0 + i2c_eeprom 0 [ ] i2c_eeprom | |-- eeprom@2c + i2c_eeprom 1 [ ] i2c_eeprom_partition | | `-- bootcount@10 + rtc 0 [ ] sandbox_rtc | |-- rtc@43 + rtc 1 [ + ] sandbox_rtc | |-- rtc@61 + i2c_emul_p 0 [ + ] sandbox_i2c_emul_par | |-- emul + i2c_emul 0 [ ] sandbox_i2c_eeprom_e | | |-- emul-eeprom + i2c_emul 1 [ ] sandbox_i2c_rtc_emul | | |-- emul0 + i2c_emul 2 [ + ] sandbox_i2c_rtc_emul | | |-- emull + i2c_emul 3 [ ] sandbox_i2c_pmic_emu | | |-- pmic-emul0 + i2c_emul 4 [ ] sandbox_i2c_pmic_emu | | `-- pmic-emul1 + pmic 0 [ ] sandbox_pmic | |-- sandbox_pmic + regulator 0 [ ] sandbox_buck | | |-- buck1 + regulator 1 [ ] sandbox_buck | | |-- buck2 + regulator 2 [ ] sandbox_ldo | | |-- ldo1 + regulator 3 [ ] sandbox_ldo | | |-- ldo2 + regulator 4 [ ] sandbox_buck | | `-- no_match_by_nodename + pmic 1 [ ] mc34708_pmic | `-- pmic@41 + bootcount 0 [ + ] bootcount-rtc |-- bootcount@0 + bootcount 1 [ ] bootcount-i2c-eeprom |-- bootcount + ... + clk 4 [ ] fixed_clock |-- osc + firmware 0 [ ] sandbox_firmware |-- sandbox-firmware + scmi_agent 0 [ ] sandbox-scmi_agent `-- scmi + clk 5 [ ] scmi_clk |-- protocol@14 + reset 2 [ ] scmi_reset_domain |-- protocol@16 + nop 8 [ ] scmi_voltage_domain `-- regulators + regulator 5 [ ] scmi_regulator |-- reg@0 + regulator 6 [ ] scmi_regulator `-- reg@1 + => dm tree pinc + pinctrl 0 [ + ] sandbox_pinctrl_gpio pinctrl-gpio + gpio 1 [ + ] sandbox_gpio |-- base-gpios + nop 0 [ + ] gpio_hog | |-- hog_input_active_low + nop 1 [ + ] gpio_hog | |-- hog_input_active_high + nop 2 [ + ] gpio_hog | |-- hog_output_low + nop 3 [ + ] gpio_hog | `-- hog_output_high + gpio 2 [ ] sandbox_gpio |-- extra-gpios + gpio 3 [ ] sandbox_gpio `-- pinmux-gpios + => + + +dm uclass +~~~~~~~~~ + +This example shows the abridged sandbox output:: + + => dm uclass + uclass 0: root + 0 * root_driver @ 03015460, seq 0 + + uclass 1: demo + 0 demo_shape_drv @ 03015560, seq 0 + 1 demo_simple_drv @ 03015620, seq 1 + 2 demo_shape_drv @ 030156e0, seq 2 + 3 demo_simple_drv @ 030157a0, seq 3 + 4 demo_shape_drv @ 03015860, seq 4 + + uclass 2: test + 0 test_drv @ 03015980, seq 0 + 1 test_drv @ 03015a60, seq 1 + 2 test_drv @ 03015b40, seq 2 + ... + uclass 20: audio-codec + 0 audio-codec @ 030168e0, seq 0 + + uclass 21: axi + 0 adder @ 0301db60, seq 1 + 1 adder @ 0301dc40, seq 2 + 2 axi@0 @ 030217d0, seq 0 + + uclass 22: blk + 0 mmc2.blk @ 0301ca00, seq 0 + 1 mmc1.blk @ 0301cee0, seq 1 + 2 mmc0.blk @ 0301d380, seq 2 + + uclass 23: bootcount + 0 * bootcount@0 @ 0301b3f0, seq 0 + 1 bootcount @ 0301b4b0, seq 1 + 2 bootcount_4@0 @ 0301b570, seq 2 + 3 bootcount_2@0 @ 0301b630, seq 3 + + uclass 24: bootdev + 0 mmc2.bootdev @ 0301cbb0, seq 0 + 1 mmc1.bootdev @ 0301d050, seq 1 + 2 mmc0.bootdev @ 0301d4f0, seq 2 + + ... + uclass 78: pinconfig + 0 gpios @ 03022410, seq 0 + 1 gpio0 @ 030224d0, seq 1 + 2 gpio1 @ 03022590, seq 2 + 3 gpio2 @ 03022650, seq 3 + 4 gpio3 @ 03022710, seq 4 + 5 i2c @ 030227d0, seq 5 + 6 groups @ 03022890, seq 6 + 7 pins @ 03022950, seq 7 + 8 i2s @ 03022a10, seq 8 + 9 spi @ 03022ad0, seq 9 + 10 cs @ 03022b90, seq 10 + 11 pinmux_pwm_pins @ 03022e10, seq 11 + 12 pinmux_spi0_pins @ 03022ed0, seq 12 + 13 pinmux_uart0_pins @ 03022f90, seq 13 + 14 * pinmux_i2c0_pins @ 03023130, seq 14 + 15 * pinmux_lcd_pins @ 030231f0, seq 15 + + ... + uclass 119: virtio + 0 sandbox_virtio1 @ 030220d0, seq 0 + 1 sandbox_virtio2 @ 03022190, seq 1 + + uclass 120: w1 + uclass 121: w1_eeprom + uclass 122: watchdog + 0 * gpio-wdt @ 0301c070, seq 0 + 1 * wdt@0 @ 03021710, seq 1 + + => dm uclass blk + uclass 22: blk + 0 mmc2.blk @ 0301ca00, seq 0 + 1 mmc1.blk @ 0301cee0, seq 1 + 2 mmc0.blk @ 0301d380, seq 2 + + => diff --git a/doc/usage/cmd/ebtupdate.rst b/doc/usage/cmd/ebtupdate.rst new file mode 100644 index 00000000000..22415ee07b4 --- /dev/null +++ b/doc/usage/cmd/ebtupdate.rst @@ -0,0 +1,72 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: ebtupdate (command) + +ebtupdate command +================= + +Synopsis +-------- + +:: + + ebtupdate [<bct> [<ebt>] [<size>]] + +Description +----------- + +The "ebtupdate" command is used to self-update bootloader on Tegra 2 and Tegra 3 +production devices which were processed using re-cryption. + +The "ebtupdate" performs encryption of new bootloader and decryption, patching +and re-encryption of BCT "in situ". After BCT and bootloader can be written in +their respective places. + +bct + address of BCT block pre-loaded into RAM. + +ebt + address of the bootloader pre-loaded into RAM. + +size + size of the pre-loaded bootloader. + +Example +------- + +This is the boot log of a LG Optimus Vu: + +:: + + => mmc dev 0 1 + switch to partitions #1, OK + mmc0(part 1) is current device + => mmc read $kernel_addr_r 0 $boot_block_size + MMC read: dev # 0, block # 0, count 4096 ... 4096 blocks read: OK + => load mmc 0:1 $ramdisk_addr_r $bootloader_file + 684783 bytes read in 44 ms (14.8 MiB/s) + => size mmc 0:1 $bootloader_file + => ebtupdate $kernel_addr_r $ramdisk_addr_r $filesize + => mmc dev 0 1 + switch to partitions #1, OK + mmc0(part 1) is current device + => mmc write $kernel_addr_r 0 $boot_block_size + MMC write: dev # 0, block # 0, count 4096 ... 4096 blocks written: OK + => mmc dev 0 2 + switch to partitions #2, OK + mmc0(part 2) is current device + => mmc write $ramdisk_addr_r 0 $boot_block_size + MMC write: dev # 0, block # 0, count 4096 ... 4096 blocks written: OK + +Configuration +------------- + +The ebtupdate command is only available if CONFIG_CMD_EBTUPDATE=y and +only on Tegra 2 and Tegra 3 configurations. + +Return value +------------ + +The return value $? is set to 0 (true) if everything went successfully. If an +error occurs, the return value $? is set to 1 (false). diff --git a/doc/usage/cmd/echo.rst b/doc/usage/cmd/echo.rst new file mode 100644 index 00000000000..ebc9ff5f843 --- /dev/null +++ b/doc/usage/cmd/echo.rst @@ -0,0 +1,68 @@ +.. index:: + single: echo (command) + +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/cmd/efi.rst b/doc/usage/cmd/efi.rst new file mode 100644 index 00000000000..b19d36188a9 --- /dev/null +++ b/doc/usage/cmd/efi.rst @@ -0,0 +1,222 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2020, Heinrich Schuchardt <xypron.glpk@gmx.de> + +.. index:: + single: efi (command) + +efi command +=========== + +Synopsis +-------- + +:: + + efi mem [all] + efi tables + +Description +----------- + +The *efi* command provides information about the EFI environment U-Boot is +running in, when it is started from EFI. + +When running as an EFI app, this command queries EFI boot services for the +information. When running as an EFI payload, EFI boot services have been +stopped, so it uses the information collected by the boot stub before that +happened. + +efi mem +~~~~~~~ + +This shows the EFI memory map, sorted in order of physical address. + +This is normally a very large table. To help reduce the amount of detritus, +boot-time memory is normally merged with conventional memory. Use the 'all' +argument to show everything. + +The fields are as follows: + +# + Entry number (sequentially from 0) + +Type + Memory type. EFI has a large number of memory types. The type is shown in + the format <n>:<name> where in is the format number in hex and <name> is the + name. + +Physical + Physical address + +Virtual + Virtual address + +Size + Size of memory area in bytes + +Attributes + Shows a code for memory attributes. The key for this is shown below the + table. + +efi tables +~~~~~~~~~~ + +This shows a list of the EFI tables provided in the system table. These use +GUIDs so it is not possible in general to show the name of a table. But some +effort is made to provide a useful table, where the GUID is known by U-Boot. + + +Example +------- + +:: + + => efi mem + EFI table at 0, memory map 000000001ad38b60, size 1260, key a79, version 1, descr. size 0x30 + # Type Physical Virtual Size Attributes + 0 7:conv 0000000000 0000000000 00000a0000 f + <gap> 00000a0000 0000060000 + 1 7:conv 0000100000 0000000000 0000700000 f + 2 a:acpi_nvs 0000800000 0000000000 0000008000 f + 3 7:conv 0000808000 0000000000 0000008000 f + 4 a:acpi_nvs 0000810000 0000000000 00000f0000 f + 5 7:conv 0000900000 0000000000 001efef000 f + 6 6:rt_data 001f8ef000 0000000000 0000100000 rf + 7 5:rt_code 001f9ef000 0000000000 0000100000 rf + 8 0:reserved 001faef000 0000000000 0000080000 f + 9 9:acpi_reclaim 001fb6f000 0000000000 0000010000 f + 10 a:acpi_nvs 001fb7f000 0000000000 0000080000 f + 11 7:conv 001fbff000 0000000000 0000359000 f + 12 6:rt_data 001ff58000 0000000000 0000020000 rf + 13 a:acpi_nvs 001ff78000 0000000000 0000088000 f + <gap> 0020000000 0090000000 + 14 0:reserved 00b0000000 0000000000 0010000000 1 + + Attributes key: + f: uncached, write-coalescing, write-through, write-back + rf: uncached, write-coalescing, write-through, write-back, needs runtime mapping + 1: uncached + *Some areas are merged (use 'all' to see) + + + => efi mem all + EFI table at 0, memory map 000000001ad38bb0, size 1260, key a79, version 1, descr. size 0x30 + # Type Physical Virtual Size Attributes + 0 3:bs_code 0000000000 0000000000 0000001000 f + 1 7:conv 0000001000 0000000000 000009f000 f + <gap> 00000a0000 0000060000 + 2 7:conv 0000100000 0000000000 0000700000 f + 3 a:acpi_nvs 0000800000 0000000000 0000008000 f + 4 7:conv 0000808000 0000000000 0000008000 f + 5 a:acpi_nvs 0000810000 0000000000 00000f0000 f + 6 4:bs_data 0000900000 0000000000 0000c00000 f + 7 7:conv 0001500000 0000000000 000aa36000 f + 8 2:loader_data 000bf36000 0000000000 0010000000 f + 9 4:bs_data 001bf36000 0000000000 0000020000 f + 10 7:conv 001bf56000 0000000000 00021e1000 f + 11 1:loader_code 001e137000 0000000000 00000c4000 f + 12 7:conv 001e1fb000 0000000000 000009b000 f + 13 1:loader_code 001e296000 0000000000 00000e2000 f + 14 7:conv 001e378000 0000000000 000005b000 f + 15 4:bs_data 001e3d3000 0000000000 000001e000 f + 16 7:conv 001e3f1000 0000000000 0000016000 f + 17 4:bs_data 001e407000 0000000000 0000016000 f + 18 2:loader_data 001e41d000 0000000000 0000002000 f + 19 4:bs_data 001e41f000 0000000000 0000828000 f + 20 3:bs_code 001ec47000 0000000000 0000045000 f + 21 4:bs_data 001ec8c000 0000000000 0000001000 f + 22 3:bs_code 001ec8d000 0000000000 000000e000 f + 23 4:bs_data 001ec9b000 0000000000 0000001000 f + 24 3:bs_code 001ec9c000 0000000000 000002c000 f + 25 4:bs_data 001ecc8000 0000000000 0000001000 f + 26 3:bs_code 001ecc9000 0000000000 000000c000 f + 27 4:bs_data 001ecd5000 0000000000 0000006000 f + 28 3:bs_code 001ecdb000 0000000000 0000014000 f + 29 4:bs_data 001ecef000 0000000000 0000001000 f + 30 3:bs_code 001ecf0000 0000000000 000005b000 f + 31 4:bs_data 001ed4b000 0000000000 000000b000 f + 32 3:bs_code 001ed56000 0000000000 0000024000 f + 33 4:bs_data 001ed7a000 0000000000 0000006000 f + 34 3:bs_code 001ed80000 0000000000 0000010000 f + 35 4:bs_data 001ed90000 0000000000 0000002000 f + 36 3:bs_code 001ed92000 0000000000 0000025000 f + 37 4:bs_data 001edb7000 0000000000 0000003000 f + 38 3:bs_code 001edba000 0000000000 0000011000 f + 39 4:bs_data 001edcb000 0000000000 0000008000 f + 40 3:bs_code 001edd3000 0000000000 000002d000 f + 41 4:bs_data 001ee00000 0000000000 0000201000 f + 42 3:bs_code 001f001000 0000000000 0000024000 f + 43 4:bs_data 001f025000 0000000000 0000002000 f + 44 3:bs_code 001f027000 0000000000 0000009000 f + 45 4:bs_data 001f030000 0000000000 0000005000 f + 46 3:bs_code 001f035000 0000000000 000002f000 f + 47 4:bs_data 001f064000 0000000000 0000001000 f + 48 3:bs_code 001f065000 0000000000 0000005000 f + 49 4:bs_data 001f06a000 0000000000 0000005000 f + 50 3:bs_code 001f06f000 0000000000 0000007000 f + 51 4:bs_data 001f076000 0000000000 0000007000 f + 52 3:bs_code 001f07d000 0000000000 000000d000 f + 53 4:bs_data 001f08a000 0000000000 0000001000 f + 54 3:bs_code 001f08b000 0000000000 0000006000 f + 55 4:bs_data 001f091000 0000000000 0000004000 f + 56 3:bs_code 001f095000 0000000000 000000d000 f + 57 4:bs_data 001f0a2000 0000000000 0000003000 f + 58 3:bs_code 001f0a5000 0000000000 0000026000 f + 59 4:bs_data 001f0cb000 0000000000 0000005000 f + 60 3:bs_code 001f0d0000 0000000000 0000019000 f + 61 4:bs_data 001f0e9000 0000000000 0000004000 f + 62 3:bs_code 001f0ed000 0000000000 0000024000 f + 63 4:bs_data 001f111000 0000000000 0000008000 f + 64 3:bs_code 001f119000 0000000000 000000b000 f + 65 4:bs_data 001f124000 0000000000 0000001000 f + 66 3:bs_code 001f125000 0000000000 0000002000 f + 67 4:bs_data 001f127000 0000000000 0000002000 f + 68 3:bs_code 001f129000 0000000000 0000009000 f + 69 4:bs_data 001f132000 0000000000 0000003000 f + 70 3:bs_code 001f135000 0000000000 0000005000 f + 71 4:bs_data 001f13a000 0000000000 0000003000 f + 72 3:bs_code 001f13d000 0000000000 0000005000 f + 73 4:bs_data 001f142000 0000000000 0000003000 f + 74 3:bs_code 001f145000 0000000000 0000011000 f + 75 4:bs_data 001f156000 0000000000 000000b000 f + 76 3:bs_code 001f161000 0000000000 0000009000 f + 77 4:bs_data 001f16a000 0000000000 0000400000 f + 78 3:bs_code 001f56a000 0000000000 0000006000 f + 79 4:bs_data 001f570000 0000000000 0000001000 f + 80 3:bs_code 001f571000 0000000000 0000001000 f + 81 4:bs_data 001f572000 0000000000 0000002000 f + 82 3:bs_code 001f574000 0000000000 0000017000 f + 83 4:bs_data 001f58b000 0000000000 0000364000 f + 84 6:rt_data 001f8ef000 0000000000 0000100000 rf + 85 5:rt_code 001f9ef000 0000000000 0000100000 rf + 86 0:reserved 001faef000 0000000000 0000080000 f + 87 9:acpi_reclaim 001fb6f000 0000000000 0000010000 f + 88 a:acpi_nvs 001fb7f000 0000000000 0000080000 f + 89 4:bs_data 001fbff000 0000000000 0000201000 f + 90 7:conv 001fe00000 0000000000 00000e8000 f + 91 4:bs_data 001fee8000 0000000000 0000020000 f + 92 3:bs_code 001ff08000 0000000000 0000026000 f + 93 4:bs_data 001ff2e000 0000000000 0000009000 f + 94 3:bs_code 001ff37000 0000000000 0000021000 f + 95 6:rt_data 001ff58000 0000000000 0000020000 rf + 96 a:acpi_nvs 001ff78000 0000000000 0000088000 f + <gap> 0020000000 0090000000 + 97 0:reserved 00b0000000 0000000000 0010000000 1 + + Attributes key: + f: uncached, write-coalescing, write-through, write-back + rf: uncached, write-coalescing, write-through, write-back, needs runtime mapping + 1: uncached + + + => efi tables + 000000001f8edf98 ee4e5898-3914-4259-9d6e-dc7bd79403cf EFI_LZMA_COMPRESSED + 000000001ff2ace0 05ad34ba-6f02-4214-952e-4da0398e2bb9 EFI_DXE_SERVICES + 000000001f8ea018 7739f24c-93d7-11d4-9a3a-0090273fc14d EFI_HOB_LIST + 000000001ff2bac0 4c19049f-4137-4dd3-9c10-8b97a83ffdfa EFI_MEMORY_TYPE + 000000001ff2cb10 49152e77-1ada-4764-b7a2-7afefed95e8b (unknown) + 000000001f9ac018 060cc026-4c0d-4dda-8f41-595fef00a502 EFI_MEM_STATUS_CODE_REC + 000000001f9ab000 eb9d2d31-2d88-11d3-9a16-0090273fc14d SMBIOS table + 000000001fb7e000 eb9d2d30-2d88-11d3-9a16-0090273fc14d EFI_GUID_EFI_ACPI1 + 000000001fb7e014 8868e871-e4f1-11d3-bc22-0080c73c8881 ACPI table + 000000001e654018 dcfa911d-26eb-469f-a220-38b7dc461220 (unknown) diff --git a/doc/usage/cmd/eficonfig.rst b/doc/usage/cmd/eficonfig.rst new file mode 100644 index 00000000000..83a3ebf4f0b --- /dev/null +++ b/doc/usage/cmd/eficonfig.rst @@ -0,0 +1,106 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. (C) Copyright 2022, Masahisa Kojima <masahisa.kojima@linaro.org> + +.. index:: + single: eficonfig (command) + +eficonfig command +================= + +Synopsis +-------- +:: + + eficonfig + +Description +----------- + +The "eficonfig" command uses the U-Boot menu interface to provide a +menu-driven UEFI variable maintenance feature. These are the top level menu +entries: + +Add Boot Option + Add a new UEFI Boot Option. + The user can edit description, file path, and optional_data. + The new boot opiton is appended to the boot order in the *BootOrder* + variable. The user may want to update the boot order using the + *Change Boot Order* menu entry. + +Edit Boot Option + Edit an existing UEFI Boot Option. + The User can edit description, file path, and optional_data. + +Change Boot Order + Change the boot order updating the UEFI BootOrder variable. + +Delete Boot Option + Delete a UEFI Boot Option + +Secure Boot Configuration + Edit the UEFI Secure Boot Configuration + +How to boot the system with a newly added UEFI Boot Option +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The "eficonfig" command is used to set the UEFI boot options which are stored +in the UEFI variable Boot#### where #### is a hexadecimal number. + +The command *bootefi bootmgr* can be used to boot by trying in sequence all +boot options selected by the variable *BootOrder*. + +If the bootmenu is enabled, CONFIG_BOOTMENU_DISABLE_UBOOT_CONSOLE is enabled, +and "eficonfig" is configured as preboot command, the newly added Boot Options +are enumerated in the bootmenu when the user exits from the eficonfig menu. +The user may select the entry in the bootmenu to boot the system, or follow +the U-Boot configuration the system already has. + +Auto boot with the UEFI Boot Option +''''''''''''''''''''''''''''''''''' + +To do auto boot according to the UEFI BootOrder variable, +add "bootefi bootmgr" entry as a default or first bootmenu entry:: + + CONFIG_PREBOOT="setenv bootmenu_0 UEFI Boot Manager=bootefi bootmgr; setenv bootmenu_1 UEFI Maintenance Menu=eficonfig" + +UEFI Secure Boot Configuration +'''''''''''''''''''''''''''''' + +The user can enroll the variables PK, KEK, db and dbx by selecting a file. +The "eficonfig" command only accepts signed EFI Signature List(s) with an +authenticated header, typically a ".auth" file. + +To clear the PK, KEK, db and dbx, the user needs to enroll a null value +signed by PK or KEK. + +Configuration +------------- + +The "eficonfig" command is enabled by:: + + CONFIG_CMD_EFICONFIG=y + +If CONFIG_BOOTMENU_DISABLE_UBOOT_CONSOLE is enabled, the user can not enter +U-Boot console. In this case, the bootmenu can be used to invoke "eficonfig":: + + CONFIG_USE_PREBOOT=y + CONFIG_PREBOOT="setenv bootmenu_0 UEFI Maintenance Menu=eficonfig" + +The only way U-Boot can currently store EFI variables on a tamper +resistant medium is via OP-TEE. The Kconfig option that enables that is:: + + CONFIG_EFI_MM_COMM_TEE=y. + +It enables storing EFI variables on the RPMB partition of an eMMC device. + +The UEFI Secure Boot Configuration menu entry is only available if the following +options are enabled:: + + CONFIG_EFI_SECURE_BOOT=y + CONFIG_EFI_MM_COMM_TEE=y + +See also +-------- + +* :doc:`bootmenu<bootmenu>` provides a simple mechanism for creating menus with + different boot items diff --git a/doc/usage/cmd/env.rst b/doc/usage/cmd/env.rst new file mode 100644 index 00000000000..9629f97ffc4 --- /dev/null +++ b/doc/usage/cmd/env.rst @@ -0,0 +1,389 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later: + +.. index:: + single: env (command) + +env command +=========== + +Synopsis +-------- + +:: + + env ask name [message] [size] + env callbacks + env default [-f] (-a | var [...]) + env delete [-f] var [...] + env edit name + env erase + env exists name + env export [-t | -b | -c] [-s size] addr [var ...] + env flags + env grep [-e] [-n | -v | -b] string [...] + env import [-d] [-t [-r] | -b | -c] addr [size] [var ...] + env info [-d] [-p] [-q] + env load + env print [-a | name ...] + env print -e [-guid guid] [-n] [name ...] + env run var [...] + env save + env select [target] + env set [-f] name [value] + env set -e [-nv][-bs][-rt][-at][-a][-i addr:size][-v] name [value] + +Description +----------- + +The *env* commands is used to handle the U-Boot (:doc:`../environment`) or +the UEFI variables. + +The next commands are kept as alias and for compatibility: + ++ :doc:`askenv <askenv>` = *env ask* ++ *editenv* = *env edit* ++ *grepenv* = *env grep* ++ :doc:`printenv <printenv>` = *env print* ++ *run* = *env run* ++ *setenv* = *env set* + +Ask +~~~ + +The *env ask* command asks for the new value of an environment variable +(alias :doc:`askenv`). + + name + name of the environment variable. + + message + message to be displayed while the command waits for the value to be + entered from stdin. If no message is specified, a default message + "Please enter name:" will be displayed. + + size + maximum number of characters that will be stored in the environment + variable name. This is in decimal number format (unlike in + other commands where size values are hexa-decimal). The default + value of size is 1023 (CONFIG_SYS_CBSIZE - 1). + +Callbacks +~~~~~~~~~ + +The *env callbacks* command prints callbacks and their associated variables. + +Default +~~~~~~~ + +The *env default* command resets the selected variables in the U-Boot +environment to their default values. + + var + list of variable name. + \-a + all U-Boot environment. + \-f + forcibly, overwrite read-only/write-once variables. + +Delete +~~~~~~ + +The *env delete* command deletes the selected variables from the U-Boot +environment. + + var + name of the variable to delete. + \-f + forcibly, overwrite read-only/write-once variables. + +Edit +~~~~ + +The *env edit* command edits an environment variable. + + name + name of the variable. + +Erase +~~~~~ + +The *env erase* command erases the U-Boot environment. + +Exists +~~~~~~ + +The *env exists* command tests for existence of variable. + + name + name of the variable. + +Export +~~~~~~ + +The *env export* command exports the U-Boot environment in memory; on success, +the variable $filesize will be set. + + addr + memory address where environment gets stored. + var + list of variable names that get included into the export. + Without arguments, the whole environment gets exported. + \-b + export as binary format (name=value pairs separated by + list end marked by double "\0\0"). + \-t + export as text format; if size is given, data will be + padded with '\0' bytes; if not, one terminating '\0' + will be added. + \-c + Export as checksum protected environment format as used by + 'env save' command. + \-s size + size of output buffer. + +Flags +~~~~~ + +The *env flags* command prints variables that have non-default flags. + +Grep +~~~~ + +The *env grep* command searches environment, list environment name=value pairs +matching the requested 'string'. + + string + string to search in U-Boot environment. + \-e + enable regular expressions. + \-n + search string in variable names. + \-v + search string in vairable values. + \-b + search both names and values (default). + +Import +~~~~~~ + +The *env import* command imports environment from memory. + + addr + memory address to read from. + size + length of input data; if missing, proper '\0' termination is mandatory + if var is set and size should be missing (i.e. '\0' termination), + set size to '-'. + var + List of the names of the only variables that get imported from + the environment at address 'addr'. Without arguments, the whole + environment gets imported. + \-d + delete existing environment before importing if no var is passed; + if vars are passed, if one var is in the current environment but not + in the environment at addr, delete var from current environment; + otherwise overwrite / append to existing definitions. + \-t + assume text format; either "size" must be given or the text data must + be '\0' terminated. + \-r + handle CRLF like LF, that means exported variables with a content which + ends with \r won't get imported. Used to import text files created with + editors which are using CRLF for line endings. + Only effective in addition to -t. + \-b + assume binary format ('\0' separated, "\0\0" terminated). + \-c + assume checksum protected environment format. + +Info +~~~~ + +The *env info* command displays (without argument) or evaluates the U-Boot +environment information. + + \-d + evaluate if the default environment is used. + \-p + evaluate if environment can be persisted. + \-q + quiet output, use only for command result, by example with + 'test' command. + +Load +~~~~ + +The *env load* command loads the U-Boot environment from persistent storage. + +Print +~~~~~ + +The *env print* command prints the selected variables in U-Boot environment or +in UEFI variables. + + name + list of variable name. + \-a + all U-Boot environment, when 'name' is absent. + \-e + print UEFI variables, all by default if 'name' is not provided. + \-guid guid + print only the UEFI variables matching this GUID (any by default) + with guid format = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx". + \-n + suppress dumping variable's value for UEFI. + +Run +~~~ + +The *env run* command runs commands in an environment variable. + + var + name of the variable. + +Save +~~~~ + +The *env save* command saves the U-Boot environment in persistent storage. + +Select +~~~~~~ + +The *env select* command selects an U-Boot environment target, it is useful to +overid the default location when several U-Boot environment backend are +availables. + + target + name of the U-Boot environment backend to select: EEPROM, EXT4, FAT, + Flash, MMC, NAND, nowhere, NVRAM, OneNAND, Remote, SATA, SPIFlash, UBI. + + +Set +~~~ + +The *env set* command sets or delete (when 'value' or '-i' are absent) +U-Boot variable in environment or UEFI variables (when -e is specified). + + name + variable name to modify. + value + when present, set the environment variable 'name' to 'value' + when absent, delete the environment variable 'name'. + \-f + forcibly, overwrite read-only/write-once U-Boot variables. + \-e + update UEFI variables. + \-nv + set non-volatile attribute (UEFI). + \-bs + set boot-service attribute (UEFI). + \-rt + set runtime attribute (UEFI). + \-at + set time-based authentication attribute (UEFI). + \-a + append-write (UEFI). + \-i addr:size + use <addr,size> as variable's value (UEFI). + \-v + verbose message (UEFI). + +Example +------- + +Print the U-Boot environment variables:: + + => env print -a + => env print bootcmd stdout + +Update environment variable in memory:: + + => env set bootcmd "run distro_bootcmd" + => env set stdout "serial,vidconsole" + +Delete environment variable in memory:: + + => env delete bootcmd + => env set bootcmd + +Reset environment variable to default value, in memory:: + + => env default bootcmd + => env default -a + +Save current environment in persistent storage:: + + => env save + +Restore the default environment in persistent storage:: + + => env erase + +Create a text snapshot/backup of the current settings in RAM +(${filesize} can be use to save the snapshot in file):: + + => env export -t ${backup_addr} + +Re-import this snapshot, deleting all other settings:: + + => env import -d -t ${backup_addr} + +Save environment if default enviromnent is used and persistent storage is +selected:: + + => if env info -p -d -q; then env save; fi + +Configuration +------------- + +The env command is always available but some sub-commands depend on +configuration options: + +ask + CONFIG_CMD_ASKENV + +callback + CONFIG_CMD_ENV_CALLBACK + +edit + CONFIG_CMD_EDITENV + +exists + CONFIG_CMD_ENV_EXISTS + +erase + CONFIG_CMD_ERASEENV + +export + CONFIG_CMD_EXPORTENV + +flags + CONFIG_CMD_ENV_FLAGS + +grep + CONFIG_CMD_GREPENV, CONFIG_REGEX for '-e' option + +import + CONFIG_CMD_IMPORTENV + +info + CONFIG_CMD_NVEDIT_INFO + +load + CONFIG_CMD_NVEDIT_LOAD + +print + CONFIG_CMD_NVEDIT_EFI for UEFI variables support ('-e' option), + additionally CONFIG_HEXDUMP to display content of UEFI variables + +run + CONFIG_CMD_RUN + +save + CONFIG_CMD_SAVEENV + +select + CONFIG_CMD_NVEDIT_SELECT + +set + CONFIG_CMD_NVEDIT_EFI for UEFI variables support ('-e' option) diff --git a/doc/usage/cmd/event.rst b/doc/usage/cmd/event.rst new file mode 100644 index 00000000000..5c5e3043733 --- /dev/null +++ b/doc/usage/cmd/event.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: event (command) + +event command +============= + +Synopsis +-------- + +:: + + event list + +Description +----------- + +The event command provides spy list. + +This shows the following information: + +Seq + Sequence number of the spy, numbered from 0 + +Type + Type of the spy, both as a number and a label. If `CONFIG_EVENT_DEBUG` is + not enabled, the label just shows `(unknown)`. + +Function + Address of the function to call + +ID + ID string for this event, if `CONFIG_EVENT_DEBUG` is enabled. Otherwise this + just shows `?`. + + +See :doc:`../../develop/event` for more information on events. + +Example +------- + +:: + + => event list + Seq Type Function ID + 0 7 misc_init_f 55a070517c68 ? + +Configuration +------------- + +The event command is only available if CONFIG_CMD_EVENT=y. diff --git a/doc/usage/cmd/exception.rst b/doc/usage/cmd/exception.rst new file mode 100644 index 00000000000..9cb492d6049 --- /dev/null +++ b/doc/usage/cmd/exception.rst @@ -0,0 +1,69 @@ +.. index:: + single: exception (command) + +exception command +================= + +Synopsis +-------- + +:: + + exception <type> + +Description +----------- + +The exception command is used to test the handling of exceptions like undefined +instructions, segmentation faults or alignment faults. + +type + type of exception to be generated. The available types are architecture + dependent. Use 'help exception' to determine which are available. + + **ARM:** + + breakpoint + prefetch abort + + unaligned + data abort + + undefined + undefined instruction + + **RISC-V:** + + ebreak + breakpoint exception + + unaligned + load address misaligned + + undefined + undefined instruction + + **Sandbox:** + + sigsegv + illegal memory access + + undefined + undefined instruction + + **x86:** + + undefined + undefined instruction + +Examples +-------- + +:: + + => exception undefined + + Illegal instruction + pc = 0x56076dd1a0f9, pc_reloc = 0x540f9 + + resetting ... diff --git a/doc/usage/cmd/exit.rst b/doc/usage/cmd/exit.rst new file mode 100644 index 00000000000..2f250bf4bde --- /dev/null +++ b/doc/usage/cmd/exit.rst @@ -0,0 +1,45 @@ +.. index:: + single: exit (command) + +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 default set to 0 (true). In case zero or positive integer parameter +is passed to the command, the return value is the parameter value. In case +negative integer parameter is passed to the command, the return value is 0. diff --git a/doc/usage/cmd/extension.rst b/doc/usage/cmd/extension.rst new file mode 100644 index 00000000000..4c261e74951 --- /dev/null +++ b/doc/usage/cmd/extension.rst @@ -0,0 +1,114 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2021, Kory Maincent <kory.maincent@bootlin.com> + +.. index:: + single: extension (command) + +extension command +================= + +Synopsis +-------- + +:: + + extension scan + extension list + extension apply <extension number|all> + +Description +----------- + +The "extension" command proposes a generic U-Boot mechanism to detect +extension boards connected to the HW platform, and apply the appropriate +Device Tree overlays depending on the detected extension boards. + +The "extension" command comes with three sub-commands: + + - "extension scan" makes the generic code call the board-specific + extension_board_scan() function to retrieve the list of detected + extension boards. + + - "extension list" allows to list the detected extension boards. + + - "extension apply <number>|all" allows to apply the Device Tree + overlay(s) corresponding to one, or all, extension boards + +The latter requires two environment variables to exist: + + - extension_overlay_addr: the RAM address where to load the Device + Tree overlays + + - extension_overlay_cmd: the U-Boot command to load one overlay. + Indeed, the location and mechanism to load DT overlays is very setup + specific. + +In order to enable this mechanism, board-specific code must implement +the extension_board_scan() function that fills in a linked list of +"struct extension", each describing one extension board. In addition, +the board-specific code must select the SUPPORT_EXTENSION_SCAN Kconfig +boolean. + +Usage example +------------- + +1. Make sure your devicetree is loaded and set as the working fdt tree. + +:: + + => run loadfdt + => fdt addr $fdtaddr + +2. Prepare the environment variables + +:: + + => setenv extension_overlay_addr 0x88080000 + => setenv extension_overlay_cmd 'load mmc 0:1 ${extension_overlay_addr} /boot/${extension_overlay_name}' + +3. Detect the plugged extension board + +:: + + => extension scan + +4. List the plugged extension board information and the devicetree + overlay name + +:: + + => extension list + +5. Apply the appropriate devicetree overlay + +For apply the selected overlay: + +:: + + => extension apply 0 + +For apply all the overlays: + +:: + + => extension apply all + +Simple extension_board_scan function example +-------------------------------------------- + +.. code-block:: c + + int extension_board_scan(struct list_head *extension_list) + { + struct extension *extension; + + extension = calloc(1, sizeof(struct extension)); + snprintf(extension->overlay, sizeof(extension->overlay), "overlay.dtbo"); + snprintf(extension->name, sizeof(extension->name), "extension board"); + snprintf(extension->owner, sizeof(extension->owner), "sandbox"); + snprintf(extension->version, sizeof(extension->version), "1.1"); + snprintf(extension->other, sizeof(extension->other), "Extension board information"); + list_add_tail(&extension->list, extension_list); + + return 1; + } diff --git a/doc/usage/cmd/false.rst b/doc/usage/cmd/false.rst new file mode 100644 index 00000000000..510377e22cd --- /dev/null +++ b/doc/usage/cmd/false.rst @@ -0,0 +1,31 @@ +.. index:: + single: false (command) + +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/cmd/fatinfo.rst b/doc/usage/cmd/fatinfo.rst new file mode 100644 index 00000000000..2e05ab8bece --- /dev/null +++ b/doc/usage/cmd/fatinfo.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: fatinfo (command) + +fatinfo command +=============== + +Synopsis +-------- + +:: + + fatinfo <interface> <dev[:part]> + +Description +----------- + +The fatinfo command displays information about a FAT partition. + +interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + +dev + device number + +part + partition number, defaults to 1 + +Example +------- + +Here is the output for a partition on a 32 GB SD-Card: + +:: + + => fatinfo mmc 0:1 + Interface: MMC + Device 0: Vendor: Man 00001b Snr 97560602 Rev: 13.8 Prod: EB1QT0 + Type: Removable Hard Disk + Capacity: 30528.0 MB = 29.8 GB (62521344 x 512) + Filesystem: FAT32 "MYDISK " + => + +Configuration +------------- + +The fatinfo command is only available if CONFIG_CMD_FAT=y. + +Return value +------------ + +The return value $? is set to 0 (true) if the partition is a FAT partition. +Otherwise it is set to 1 (false). diff --git a/doc/usage/cmd/fatload.rst b/doc/usage/cmd/fatload.rst new file mode 100644 index 00000000000..6c048b7bdac --- /dev/null +++ b/doc/usage/cmd/fatload.rst @@ -0,0 +1,83 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: fatload (command) + +fatload command +=============== + +Synopsis +-------- + +:: + + fatload <interface> [<dev[:part]> [<addr> [<filename> [bytes [pos]]]]] + +Description +----------- + +The fatload command is used to read a file from a FAT filesystem into memory. +You can always use the :doc:`load command <load>` instead. + +The number of transferred bytes is saved in the environment variable filesize. +The load address is saved in the environment variable fileaddr. + +interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + +dev + device number + +part + partition number, defaults to 0 (whole device) + +addr + load address, defaults to environment variable loadaddr or if loadaddr is + not set to configuration variable CONFIG_SYS_LOAD_ADDR + +filename + path to file, defaults to environment variable bootfile + +bytes + maximum number of bytes to load + +pos + number of bytes to skip + +addr, bytes, pos are hexadecimal numbers. + +If either 'pos' or 'bytes' are not aligned according to the minimum alignment +requirement for DMA transfer (ARCH_DMA_MINALIGN) additional buffering will be +used, a misaligned buffer warning will be printed, and performance will suffer +for the load. + +Example +------- + +:: + + => fatload mmc 0:1 ${kernel_addr_r} snp.efi + 149280 bytes read in 11 ms (12.9 MiB/s) + => + => fatload mmc 0:1 ${kernel_addr_r} snp.efi 1000000 + 149280 bytes read in 9 ms (15.8 MiB/s) + => + => fatload mmc 0:1 ${kernel_addr_r} snp.efi 1000000 100 + 149024 bytes read in 10 ms (14.2 MiB/s) + => + => fatload mmc 0:1 ${kernel_addr_r} snp.efi 10 + 16 bytes read in 1 ms (15.6 KiB/s) + => + +Configuration +------------- + +The fatload command is only available if CONFIG_CMD_FAT=y. + +Return value +------------ + +The return value $? is set to 0 (true) if the file was successfully loaded +even if the number of bytes is less then the specified length. + +If an error occurs, the return value $? is set to 1 (false). diff --git a/doc/usage/cmd/fdt.rst b/doc/usage/cmd/fdt.rst new file mode 100644 index 00000000000..71a9fc627e5 --- /dev/null +++ b/doc/usage/cmd/fdt.rst @@ -0,0 +1,73 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: fdt (command) + +fdt command +=========== + +Synopsis +-------- + +:: + + fdt addr [-cq] [addr [len]] + +Description +----------- + +The fdt command provides access to flat device tree blobs in memory. It has +many subcommands, some of which are not documented here. + +Flags: + +-c + Select the control FDT (otherwise the working FDT is used). +-q + Don't display errors + +The control FDT is the one used by U-Boot itself to control various features, +including driver model. This should only be changed if you really know what you +are doing, since once U-Boot starts it maintains pointers into the FDT from the +various driver model data structures. + +The working FDT is the one passed to the Operating System when booting. This +can be freely modified, so far as U-Boot is concerned, since it does not affect +U-Boot's operation. + +fdt addr +~~~~~~~~ + +With no arguments, this shows the address of the current working or control +FDT. + +If the `addr` argument is provided, then this sets the address of the working or +control FDT to the provided address. + +If the `len` argument is provided, then the device tree is expanded to that +size. This can be used to make space for more nodes and properties. It is +assumed that there is enough space in memory for this expansion. + +Example +------- + +Get the control address and copy that FDT to free memory:: + + => fdt addr -c + Control fdt: 0aff9fd0 + => cp.b 0aff9fd0 10000 10000 + => md 10000 4 + 00010000: edfe0dd0 5b3d0000 78000000 7c270000 ......=[...x..'| + +The second word shows the size of the FDT. Now set the working FDT to that +address and expand it to 0xf000 in size:: + + => fdt addr 10000 f000 + Working FDT set to 10000 + => md 10000 4 + 00010000: edfe0dd0 00f00000 78000000 7c270000 ...........x..'| + +Return value +------------ + +The return value $? indicates whether the command succeeded. diff --git a/doc/usage/cmd/font.rst b/doc/usage/cmd/font.rst new file mode 100644 index 00000000000..a8782546333 --- /dev/null +++ b/doc/usage/cmd/font.rst @@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: font (command) + +font command +============ + +Synopsis +-------- + +:: + + font list + font select <name> [<size>] + font size <size> + +Description +----------- + +The *font* command allows selection of the font to use on the video console. +This is available when the TrueType console is in use. + +font list +~~~~~~~~~ + +This lists the available fonts, using the name of the font file in the build. + +font select +~~~~~~~~~~~ + +This selects a new font and optionally changes the size. + +font size +~~~~~~~~~ + +This changes the font size only. + +Examples +-------- + +:: + + => font list + nimbus_sans_l_regular + cantoraone_regular + => font size 40 + => font select cantoraone_regular 20 + => + +Configuration +------------- + +The command is only available if CONFIG_CONSOLE_TRUETYPE=y. + +Return value +------------ + +The return value $? is 0 (true) if the command completes. +The return value is 1 (false) if the command fails. diff --git a/doc/usage/cmd/for.rst b/doc/usage/cmd/for.rst new file mode 100644 index 00000000000..729bd4db43c --- /dev/null +++ b/doc/usage/cmd/for.rst @@ -0,0 +1,68 @@ +.. index:: + single: for (command) + +for command +=========== + +Synopsis +-------- + +:: + + 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/cmd/fwu_mdata.rst b/doc/usage/cmd/fwu_mdata.rst new file mode 100644 index 00000000000..f1bf08fde1d --- /dev/null +++ b/doc/usage/cmd/fwu_mdata.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: fwu_mdata_read (command) + +fwu_mdata_read command +====================== + +Synopsis +-------- + +:: + + fwu_mdata_read + +Description +----------- + +The fwu_mdata_read command is used to read the FWU metadata +structure. The command prints out information about the current active +bank, the previous active bank, image GUIDs, image acceptance etc. + +The output may look like: + +:: + + => fwu_mdata_read + FWU Metadata + crc32: 0xec4fb997 + version: 0x1 + active_index: 0x0 + previous_active_index: 0x1 + Image Info + + Image Type Guid: 19D5DF83-11B0-457B-BE2C-7559C13142A5 + Location Guid: 49272BEB-8DD8-46DF-8D75-356C65EFF417 + Image Guid: D57428CC-BB9A-42E0-AA36-3F5A132059C7 + Image Acceptance: yes + Image Guid: 2BE37D6D-8281-4938-BD7B-9A5BBF80869F + Image Acceptance: yes + +Configuration +------------- + +To use the fwu_mdata_read command, CONFIG_CMD_FWU_METADATA needs to be +enabled. diff --git a/doc/usage/cmd/gpio.rst b/doc/usage/cmd/gpio.rst new file mode 100644 index 00000000000..4b0dc2716e5 --- /dev/null +++ b/doc/usage/cmd/gpio.rst @@ -0,0 +1,135 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: gpio (command) + +gpio command +============ + +Synopsis +-------- + +:: + + gpio <input|set|clear|toggle> <pin> + gpio read <name> <pin> + gpio status [-a] [<bank>|<pin>] + +The gpio command is used to access General Purpose Inputs/Outputs. + +gpio input +---------- + +Switch the GPIO *pin* to input mode. + +gpio set +-------- + +Switch the GPIO *pin* to output mode and set the signal to 1. + +gpio clear +---------- + +Switch the GPIO *pin* to output mode and set the signal to 0. + +gpio toggle +----------- + +Switch the GPIO *pin* to output mode and reverse the signal state. + +gpio read +--------- + +Read the signal state of the GPIO *pin* and save it in environment variable +*name*. + +gpio status +----------- + +Display the status of one or multiple GPIOs. By default only claimed GPIOs +are displayed. +gpio status command output fields are:: + + <name>: <function>: <value> [x] <label> + +*function* can take the following values: + +output + pin configured in gpio output, *value* indicates the pin's level + +input + pin configured in gpio input, *value* indicates the pin's level + +func + pin configured in alternate function, followed by *label* + which shows pinmuxing label. + +unused + pin not configured + +*[x]* or *[ ]* indicate respectively if the gpio is used or not. + +*label* shows the gpio label. + +Parameters +---------- + +-a + Display GPIOs irrespective of being claimed. + +bank + Name of a bank of GPIOs to be displayed. + +pin + Name of a single GPIO to be displayed or manipulated. + +Examples +-------- + +Switch the status of a GPIO:: + + => gpio set a5 + gpio: pin a5 (gpio 133) value is 1 + => gpio clear a5 + gpio: pin a5 (gpio 133) value is 0 + => gpio toggle a5 + gpio: pin a5 (gpio 133) value is 1 + => gpio read myvar a5 + gpio: pin a5 (gpio 133) value is 1 + => echo $myvar + 1 + => gpio toggle a5 + gpio: pin a5 (gpio 133) value is 0 + => gpio read myvar a5 + gpio: pin a5 (gpio 133) value is 0 + => echo $myvar + 0 + +Show the GPIO status:: + + => gpio status + Bank GPIOA: + GPIOA1: func rgmii-0 + GPIOA2: func rgmii-0 + GPIOA7: func rgmii-0 + GPIOA10: output: 0 [x] hdmi-transmitter@39.reset-gpios + GPIOA13: output: 1 [x] red.gpios + + Bank GPIOB: + GPIOB0: func rgmii-0 + GPIOB1: func rgmii-0 + GPIOB2: func uart4-0 + GPIOB7: input: 0 [x] mmc@58005000.cd-gpios + GPIOB11: func rgmii-0 + +Configuration +------------- + +The *gpio* command is only available if CONFIG_CMD_GPIO=y. +The *gpio read* command is only available if CONFIG_CMD_GPIO_READ=y. + +Return value +------------ + +If the command succeds the return value $? is set to 0. If an error occurs, the +return value $? is set to 1. diff --git a/doc/usage/cmd/gpt.rst b/doc/usage/cmd/gpt.rst new file mode 100644 index 00000000000..8534f78cbac --- /dev/null +++ b/doc/usage/cmd/gpt.rst @@ -0,0 +1,230 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: gpt (command) + +gpt command +=========== + +Synopsis +-------- + +:: + + gpt enumerate <interface> <dev> + gpt guid <interface> <dev> [<varname>] + gpt read <interface> <dev> [<varname>] + gpt rename <interface> <dev> <part> <name> + gpt repair <interface> <dev> + gpt set-bootable <interface> <dev> <partition list> + gpt setenv <interface> <dev> <partition name> + gpt swap <interface> <dev> <name1> <name2> + gpt transpose <interface> <dev> <part1> <part2> + gpt verify <interface> <dev> [<partition string>] + gpt write <interface> <dev> <partition string> + +Description +----------- + +The gpt command lets users read, create, modify, or verify the GPT (GUID +Partition Table) partition layout. + +Common arguments: + +interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + +dev + device number + +partition string + Describes the GPT partition layout for a disk. The syntax is similar to + the one used by the :doc:`mbr command <mbr>` command. The string contains + one or more partition descriptors, each separated by a ";". Each descriptor + contains one or more fields, with each field separated by a ",". Fields are + either of the form "key=value" to set a specific value, or simple "flag" to + set a boolean flag + + The first descriptor can optionally be used to describe parameters for the + whole disk with the following fields: + + * uuid_disk=UUID - Set the UUID for the disk + + Partition descriptors can have the following fields: + + * name=<NAME> - The partition name, required + * start=<BYTES> - The partition start offset in bytes, required + * size=<BYTES> - The partition size in bytes or "-" to expand it to the whole free area + * bootable - Set the legacy bootable flag + * uuid=<UUID> - The partition UUID, optional if CONFIG_RANDOM_UUID=y is enabled + * type=<UUID> - The partition type GUID, requires CONFIG_PARTITION_TYPE_GUID=y + + + If 'uuid' is not specified, but CONFIG_RANDOM_UUID is enabled, a random UUID + will be generated for the partition + +gpt enumerate +~~~~~~~~~~~~~ + +Sets the variable 'gpt_partition_list' to be a list of all the partition names +on the device. + +gpt guid +~~~~~~~~ + +Report the GUID of a disk. If 'varname' is specified, the command will set the +variable to the GUID, otherwise it will be printed out. + +gpt read +~~~~~~~~ + +Prints the current state of the GPT partition table. If 'varname' is specified, +the variable will be filled with a partition string in the same format as a +'<partition string>', suitable for passing to other 'gpt' commands. If the +argument is omitted, a human readable description is printed out. +CONFIG_CMD_GPT_RENAME=y is required. + +gpt rename +~~~~~~~~~~ + +Renames all partitions named 'part' to be 'name'. CONFIG_CMD_GPT_RENAME=y is +required. + +gpt repair +~~~~~~~~~~ + +Repairs the GPT partition tables if it they become corrupted. + +gpt set-bootable +~~~~~~~~~~~~~~~~ + +Sets the bootable flag for all partitions in the table. If the partition name +is in 'partition list' (separated by ','), the bootable flag is set, otherwise +it is cleared. CONFIG_CMD_GPT_RENAME=y is required. + +gpt setenv +~~~~~~~~~~ + +The 'gpt setenv' command will set a series of environment variables with +information about the partition named '<partition name>'. The variables are: + +gpt_partition_addr + the starting offset of the partition in blocks as a hexadecimal number + +gpt_partition_size + the size of the partition in blocks as a hexadecimal number + +gpt_partition_name + the name of the partition + +gpt_partition_entry + the partition number in the table, e.g. 1, 2, 3, etc. + +gpt_partition_bootable + 1 if the partition is marked as bootable, 0 if not + +gpt swap +~~~~~~~~ + +Changes the names of all partitions that are named 'name1' to be 'name2', and +all partitions named 'name2' to be 'name1'. CONFIG_CMD_GPT_RENAME=y is +required. + +gpt transpose +~~~~~~~~~~~~~ + +Swaps the order of two partition table entries with indexes 'part1' and 'part2' +in the partition table, but otherwise leaves the actual partition data +untouched. + +gpt verify +~~~~~~~~~~ + +Sets return value $? to 0 (true) if the partition layout on the +specified disk matches the one in the provided partition string, and 1 (false) +if it does not match. If no partition string is specified, the command will +check if the disk is partitioned or not. + +gpt write +~~~~~~~~~ + +(Re)writes the partition table on the disk to match the provided +partition string. It returns 0 on success or 1 on failure. + +Configuration +------------- + +To use the 'gpt' command you must specify CONFIG_CMD_GPT=y. To enable 'gpt +read', 'gpt swap' and 'gpt rename', you must specify CONFIG_CMD_GPT_RENAME=y. + +Examples +~~~~~~~~ + +Create 6 partitions on a disk:: + + => setenv gpt_parts 'uuid_disk=bec9fc2a-86c1-483d-8a0e-0109732277d7; + name=boot,start=4M,size=128M,bootable,type=ebd0a0a2-b9e5-4433-87c0-68b6b72699c7, + name=rootfs,size=3072M,type=0fc63daf-8483-4772-8e79-3d69d8477de4; + name=system-data,size=512M,type=0fc63daf-8483-4772-8e79-3d69d8477de4; + name=[ext],size=-,type=0fc63daf-8483-4772-8e79-3d69d8477de4; + name=user,size=-,type=0fc63daf-8483-4772-8e79-3d69d8477de4; + name=modules,size=100M,type=0fc63daf-8483-4772-8e79-3d69d8477de4; + name=ramdisk,size=8M,type=0fc63daf-8483-4772-8e79-3d69d8477de4 + => gpt write mmc 0 $gpt_parts + + +Verify that the device matches the partition layout described in the variable +$gpt_parts:: + + => gpt verify mmc 0 $gpt_parts + + +Get the information about the partition named 'rootfs':: + + => gpt setenv mmc 0 rootfs + => echo ${gpt_partition_addr} + 2000 + => echo ${gpt_partition_size} + 14a000 + => echo ${gpt_partition_name} + rootfs + => echo ${gpt_partition_entry} + 2 + => echo ${gpt_partition_bootable} + 0 + +Get the list of partition names on the disk:: + + => gpt enumerate + => echo ${gpt_partition_list} + boot rootfs system-data [ext] user modules ramdisk + +Get the GUID for a disk:: + + => gpt guid mmc 0 + bec9fc2a-86c1-483d-8a0e-0109732277d7 + => gpt guid mmc gpt_disk_uuid + => echo ${gpt_disk_uuid} + bec9fc2a-86c1-483d-8a0e-0109732277d7 + +Set the bootable flag for the 'boot' partition and clear it for all others:: + + => gpt set-bootable mmc 0 boot + +Swap the order of the 'boot' and 'rootfs' partition table entries:: + + => gpt setenv mmc 0 rootfs + => echo ${gpt_partition_entry} + 2 + => gpt setenv mmc 0 boot + => echo ${gpt_partition_entry} + 1 + + => gpt transpose mmc 0 1 2 + + => gpt setenv mmc 0 rootfs + => echo ${gpt_partition_entry} + 1 + => gpt setenv mmc 0 boot + => echo ${gpt_partition_entry} + 2 diff --git a/doc/usage/cmd/history.rst b/doc/usage/cmd/history.rst new file mode 100644 index 00000000000..b52b5b220ae --- /dev/null +++ b/doc/usage/cmd/history.rst @@ -0,0 +1,70 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: history (command) + +history command +=============== + +Synopsis +-------- + +:: + + history + +Description +----------- + +The *history* command shows a list of previously entered commands on the +command line. When U-Boot starts, this it is initially empty. Each new command +entered is added to the list. + +Normally these commands can be accessed by pressing the `up arrow` and +`down arrow` keys, which cycle through the list. The `history` command provides +a simple way to view the list. + +Example +------- + +This example shows entering three commands, then `history`. Note that `history` +itself is added to the list. + +:: + + => bootflow scan -l + Scanning for bootflows in all bootdevs + Seq Method State Uclass Part Name Filename + --- ----------- ------ -------- ---- ------------------------ ---------------- + Scanning global bootmeth 'firmware0': + Hunting with: simple_bus + Found 2 extension board(s). + Scanning bootdev 'mmc2.bootdev': + Scanning bootdev 'mmc1.bootdev': + 0 extlinux ready mmc 1 mmc1.bootdev.part_1 /extlinux/extlinux.conf + No more bootdevs + --- ----------- ------ -------- ---- ------------------------ ---------------- + (1 bootflow, 1 valid) + => bootflow select 0 + => bootflow info + Name: mmc1.bootdev.part_1 + Device: mmc1.bootdev + Block dev: mmc1.blk + Method: extlinux + State: ready + Partition: 1 + Subdir: (none) + Filename: /extlinux/extlinux.conf + Buffer: aebdea0 + Size: 253 (595 bytes) + OS: Fedora-Workstation-armhfp-31-1.9 (5.3.7-301.fc31.armv7hl) + Cmdline: (none) + Logo: (none) + FDT: <NULL> + Error: 0 + => history + bootflow scan -l + bootflow select 0 + bootflow info + history + => diff --git a/doc/usage/cmd/host.rst b/doc/usage/cmd/host.rst new file mode 100644 index 00000000000..a70a432b6f2 --- /dev/null +++ b/doc/usage/cmd/host.rst @@ -0,0 +1,119 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: host (command) + +host command +============ + +Synopsis +-------- + +:: + + host bind [-r] <label> [<filename>] + host unbind <label|seq> + host info [<label|seq>] + host dev [<label|seq>] + +Description +----------- + +The host command provides a way to attach disk images on the host to U-Boot +sandbox. This can be useful for testing U-Boot's filesystem implementations. + +Common arguments: + +<label|seq> + This is used to specify a host device. It can either be a label (a string) + or the sequence number of the device. An invalid value causes the command + to fail. + + +host bind +~~~~~~~~~ + +This creates a new host device and binds a file to it. + +Arguments: + +label + Label to use to identify this binding. This can be any string. + +filename: + Host filename to bind to + +Flags: + +-r + Mark the device as removable + + +host unbind +~~~~~~~~~~~ + +This unbinds a host device that was previously bound. The sequence numbers of +other devices remain unchanged. + + +host info +~~~~~~~~~ + +Provides information about a particular host binding, or all of them. + + +host dev +~~~~~~~~ + +Allowing selecting a particular device, or (with no arguments) seeing which one +is selected. + + +Example +------- + +Initially there are no devices:: + + => host info + dev blocks label path + +Bind a device:: + + => host bind -r test2 2MB.ext2.img + => host bind fat 1MB.fat32.img + => host info + dev blocks label path + 0 4096 test2 2MB.ext2.img + 1 2048 fat 1MB.fat32.img + +Select a device by label or sequence number:: + + => host dev fat + Current host device: 1: fat + => host dev 0 + Current host device: 0: test2 + +Write a file:: + + => ext4write host 0 0 /dump 1e00 + File System is consistent + 7680 bytes written in 3 ms (2.4 MiB/s) + => ext4ls host 0 + <DIR> 4096 . + <DIR> 4096 .. + <DIR> 16384 lost+found + 4096 testing + 7680 dump + +Unbind a device:: + + => host unbind test2 + => host info + dev blocks label path + 1 2048 fat 1MB.fat32.img + + +Return value +------------ + +The return value $? indicates whether the command succeeded. diff --git a/doc/usage/cmd/if.rst b/doc/usage/cmd/if.rst new file mode 100644 index 00000000000..813f903a8d8 --- /dev/null +++ b/doc/usage/cmd/if.rst @@ -0,0 +1,72 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +.. index:: + single: if (command) + +if command +========== + +Synopsis +-------- + +:: + + if <test statement> + then + <statements> + fi + + if <test statement> + then + <statements> + else + <statements> + fi + +Description +----------- + +The if command is used to conditionally execute statements. + +test statement + Any command. The test statement set the $? variable. If the value of + $? becomes 0 (true) the statements after the **then** statement will + be executed. Otherwise the statements after the **else** statement. + +Examples +-------- + +The examples shows how the value of a numeric variable can be tested with +the :doc:`itest <itest>` command. + +:: + + => a=1; if itest $a == 0; then echo true; else echo false; fi + false + => a=0; if itest $a == 0; then echo true; else echo false; fi + true + +In the following example we try to load an EFI binary via TFTP. If loading +succeeds, the binary is executed. + +:: + + if tftp $kernel_addr_r shellriscv64.efi; then bootefi $kernel_addr_r; fi + +Return value +------------ + +The value of $? is the return value of the last executed statement. + +:: + + => if true; then true; else true; fi; echo $? + 0 + => if false; then true; else true; fi; echo $? + 0 + => if false; then false; else false; fi; echo $? + 1 + => if true; then false; else false; fi; echo $? + 1 + => if false; then true; fi; echo $? + 1 diff --git a/doc/usage/cmd/imxtract.rst b/doc/usage/cmd/imxtract.rst new file mode 100644 index 00000000000..235d15e445b --- /dev/null +++ b/doc/usage/cmd/imxtract.rst @@ -0,0 +1,84 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: imxtract (command) + +imxtract command +================ + +Synopsis +-------- + +:: + + imxtract addr part [dest] + imxtract addr uname [dest] + +Description +----------- + +The imxtract command is used to extract a part of a multi-image file. + +Two different file formats are supported: + +* FIT images +* legacy U-Boot images + +addr + Address of the multi-image file from which a part shall be extracted + +part + Index (hexadecimal) of the part of a legacy U-Boot image to be extracted + +uname + Name of the part of a FIT image to be extracted + +dest + Destination address (defaults to 0x0) + +The value of environment variable *verify* controls if the hashes and +signatures of FIT images or the check sums of legacy U-Boot images are checked. +To enable checking set *verify* to one of the values *1*, *yes*, *true*. +(Actually only the first letter is checked disregarding the case.) + +To list the parts of an image the *iminfo* command can be used. + +Examples +-------- + +With verify=no incorrect hashes, signatures, or check sums don't stop the +extraction. But correct hashes are still indicated in the output +(here: sha256, sha512). + +.. code-block:: console + + => setenv verify no + => imxtract $loadaddr kernel-1 $kernel_addr_r + ## Copying 'kernel-1' subimage from FIT image at 40200000 ... + sha256+ sha512+ Loading part 0 ... OK + => + +With verify=yes incorrect hashes, signatures, or check sums stop the extraction. + +.. code-block:: console + + => setenv verify yes + => imxtract $loadaddr kernel-1 $kernel_addr_r + ## Copying 'kernel-1' subimage from FIT image at 40200000 ... + sha256 error! + Bad hash value for 'hash-1' hash node in 'kernel-1' image node + Bad Data Hash + => + +Configuration +------------- + +The imxtract command is only available if CONFIG_CMD_XIMG=y. Support for FIT +images requires CONFIG_FIT=y. Support for legacy U-Boot images requires +CONFIG_LEGACY_IMAGE_FORMAT=y. + +Return value +------------ + +On success the return value $? of the command is 0 (true). On failure the +return value is 1 (false). diff --git a/doc/usage/cmd/itest.rst b/doc/usage/cmd/itest.rst new file mode 100644 index 00000000000..adcad05b2d4 --- /dev/null +++ b/doc/usage/cmd/itest.rst @@ -0,0 +1,115 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: itest (command) + +itest command +============= + +Synopsis +-------- + +:: + + itest[.b | .w | .l | .q | .s] [*]<value1> <op> [*]<value2> + +Description +----------- + +The itest command is used to compare two values. The return value $? is set +accordingly. + +By default it is assumed that the values are 4 byte integers. By appending a +postfix (.b, .w, .l, .q, .s) the size can be specified: + +======= ====================================================== +postfix meaning +======= ====================================================== +.b 1 byte integer +.w 2 byte integer +.l 4 byte integer +.q 8 byte integer (only available if CONFIG_PHYS_64BIT=y) +.s string +======= ====================================================== + +value1, value2 + values to compare. Numeric values are hexadecimal. If '*' is prefixed a + hexadecimal address is passed, which points to the value to be compared. + +op + operator, see table + + ======== ====================== + operator meaning + ======== ====================== + -lt less than + < less than + -le less or equal + <= less or equal + -eq equal + == equal + -ne not equal + != not equal + <> not equal + -ge greater or equal + >= greater or equal + -gt greater than + > greater than + ======== ====================== + +Examples +-------- + +The itest command sets the result variable $? to true (0) or false (1): + +:: + + => itest 3 < 4; echo $? + 0 + => itest 3 == 4; echo $? + 1 + +This value can be used in the :doc:`if <if>` command: + +:: + + => if itest 0x3002 < 0x4001; then echo true; else echo false; fi + true + +Numbers will be truncated according to the postfix before comparing: + +:: + + => if itest.b 0x3002 < 0x4001; then echo true; else echo false; fi + false + +Postfix .s causes a string compare. The string '0xa1234' is alphabetically +smaller than '0xb'. + +:: + + => if itest.s 0xa1234 < 0xb; then echo true; else echo false; fi + true + +A value prefixed by '*' is a pointer to the value in memory. + +:: + + => mm 0x4000 + 00004000: 00000004 ? + 00004004: 00000003 ? => + => if itest *0x4000 == 4; then echo true; else echo false; fi + true + => if itest *0x4004 == 3; then echo true; else echo false; fi + true + +Configuration +------------- + +The command is only available if CONFIG_CMD_ITEST=y. + +Return value +------------ + +The return value $? is 0 (true) if the condition is true and 1 (false) +otherwise. diff --git a/doc/usage/cmd/load.rst b/doc/usage/cmd/load.rst new file mode 100644 index 00000000000..bfa45c6f36c --- /dev/null +++ b/doc/usage/cmd/load.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: load (command) + +load command +============ + +Synopsis +-------- + +:: + + load <interface> [<dev[:part]> [<addr> [<filename> [bytes [pos]]]]] + +Description +----------- + +The load command is used to read a file from a filesystem into memory. + +The number of transferred bytes is saved in the environment variable filesize. +The load address is saved in the environment variable fileaddr. + +interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + +dev + device number + +part + partition number, defaults to 0 (whole device) + +addr + load address, defaults to environment variable loadaddr or if loadaddr is + not set to configuration variable CONFIG_SYS_LOAD_ADDR + +filename + path to file, defaults to environment variable bootfile + +bytes + maximum number of bytes to load + +pos + number of bytes to skip + +part, addr, bytes, pos are hexadecimal numbers. + +Example +------- + +:: + + => load mmc 0:1 ${kernel_addr_r} snp.efi + 149280 bytes read in 11 ms (12.9 MiB/s) + => + => load mmc 0:1 ${kernel_addr_r} snp.efi 1000000 + 149280 bytes read in 9 ms (15.8 MiB/s) + => + => load mmc 0:1 ${kernel_addr_r} snp.efi 1000000 100 + 149024 bytes read in 10 ms (14.2 MiB/s) + => + => load mmc 0:1 ${kernel_addr_r} snp.efi 10 + 16 bytes read in 1 ms (15.6 KiB/s) + => + +Configuration +------------- + +The load 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 loaded +even if the number of bytes is less then the specified length. + +If an error occurs, the return value $? is set to 1 (false). diff --git a/doc/usage/cmd/loadb.rst b/doc/usage/cmd/loadb.rst new file mode 100644 index 00000000000..4f9a52c793f --- /dev/null +++ b/doc/usage/cmd/loadb.rst @@ -0,0 +1,73 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: loadb (command) + +loadb command +============= + +Synopsis +-------- + +:: + + loadb [addr [baud]] + +Description +----------- + +The loadb command is used to transfer a file to the device via the serial line +using the Kermit 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 Kermit transmission. After the transmission the baud + rate is reset to the original value. + +Example +------- + +In the example below the terminal emulation program picocom and G-Kermit +serve to transfer a file to a device. + +.. code-block:: bash + + picocom --baud 115200 --send-cmd "gkermit -iXvs" /dev/ttyUSB0 + +After entering the loadb command the key sequence <CTRL-A><CTRL-S> is used to +let picocom prompt for the file name. Picocom invokes G-Kermit for the file +transfer. + +:: + + => loadb 60800000 115200 + ## Ready for binary (kermit) download to 0x60800000 at 115200 bps... + + *** file: helloworld.efi + $ gkermit -iXvs helloworld.efi + G-Kermit 2.01, The Kermit Project, 2021-11-15 + Escape back to your local Kermit and give a RECEIVE command. + + KERMIT READY TO SEND... + | + *** exit status: 0 *** + ## Total Size = 0x00000c00 = 3072 Bytes + ## Start Addr = 0x60800000 + => + +The transfer can be cancelled by pressing <CTRL+C>. + +Configuration +------------- + +The command is only available if CONFIG_CMD_LOADB=y. + +Return value +------------ + +The return value $? is 0 (true) on success, 1 (false) on error. diff --git a/doc/usage/cmd/loadm.rst b/doc/usage/cmd/loadm.rst new file mode 100644 index 00000000000..005840a27bb --- /dev/null +++ b/doc/usage/cmd/loadm.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: loadm (command) + +loadm command +============= + +Synopsis +-------- + +:: + + loadm <src_addr> <dst_addr> <len> + +Description +----------- + +The loadm command is used to copy memory content from source address +to destination address and, if efi is enabled, will setup a "Mem" efi +boot device. + +The number of transferred bytes must be set by bytes parameter + +src_addr + start address of the memory location to be loaded + +dst_addr + destination address of the byte stream to be loaded + +len + number of bytes to be copied in hexadecimal. Can not be 0 (zero). + +Example +------- + +:: + + => loadm ${kernel_addr} ${kernel_addr_r} ${kernel_size} + loaded bin to memory: size: 12582912 + +Configuration +------------- + +The command is only available if CONFIG_CMD_LOADM=y. + +Return value +------------ + +The return value $? is set 0 (true) if the loading is succefull, and +is set to 1 (false) in case of error. + diff --git a/doc/usage/cmd/loads.rst b/doc/usage/cmd/loads.rst new file mode 100644 index 00000000000..0a2ac14acfe --- /dev/null +++ b/doc/usage/cmd/loads.rst @@ -0,0 +1,99 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: loads (command) + +loads command +============= + +Synopsis +-------- + +:: + + loads [offset [baud]] + +Description +----------- + +The loads command is used to transfer a file to the device via the serial line +using the Motorola S-record file format. + +offset + offset added to the addresses in the S-record file + +baud + baud rate to use for download. This parameter is only available if + CONFIG_SYS_LOADS_BAUD_CHANGE=y + +Example +------- + +As example file to be transferred we use a script printing 'hello s-record'. +Here are the commands to create the S-record file: + +.. code-block:: bash + + $ echo 'echo hello s-record' > script.txt + $ mkimage -T script -d script.txt script.scr + Image Name: + Created: Sun Jun 25 10:35:02 2023 + Image Type: PowerPC Linux Script (gzip compressed) + Data Size: 28 Bytes = 0.03 KiB = 0.00 MiB + Load Address: 00000000 + Entry Point: 00000000 + Contents: + Image 0: 20 Bytes = 0.02 KiB = 0.00 MiB + $ srec_cat script.scr -binary -CRLF -Output script.srec + $ echo -e "S9030000FC\r" >> script.srec + $ cat script.srec + S0220000687474703A2F2F737265636F72642E736F75726365666F7267652E6E65742F1D + S1230000270519566D773EB6649815E30000001700000000000000003DE3D97005070601E2 + S12300200000000000000000000000000000000000000000000000000000000000000000BC + S11A00400000000F0000000068656C6C6F20732D7265636F72640A39 + S5030003F9 + S9030000FC + $ + +The load address in the first S1 record is 0x0000. + +The terminal emulation program picocom is invoked with *cat* as the send +command to transfer the file. + +.. code-block:: + + picocom --send-cmd 'cat' --baud 115200 /dev/ttyUSB0 + +After entering the *loads* command the key sequence <CTRL-A><CTRL-S> is used to +let picocom prompt for the file name. Picocom invokes the program *cat* for the +file transfer. The loaded script is executed using the *source* command. + +.. code-block:: + + => loads $scriptaddr + ## Ready for S-Record download ... + + *** file: script.srec + $ cat script.srec + + *** exit status: 0 *** + + ## First Load Addr = 0x4FC00000 + ## Last Load Addr = 0x4FC0005B + ## Total Size = 0x0000005C = 92 Bytes + ## Start Addr = 0x00000000 + => source $scriptaddr + ## Executing script at 4fc00000 + hello s-record + => + +Configuration +------------- + +The command is only available if CONFIG_CMD_LOADS=y. The parameter to set the +baud rate is only available if CONFIG_SYS_LOADS_BAUD_CHANGE=y + +Return value +------------ + +The return value $? is 0 (true) on success, 1 (false) otherwise. diff --git a/doc/usage/cmd/loadx.rst b/doc/usage/cmd/loadx.rst new file mode 100644 index 00000000000..661b36723c3 --- /dev/null +++ b/doc/usage/cmd/loadx.rst @@ -0,0 +1,80 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: loadx (command) + +loadx command +============= + +Synopsis +-------- + +:: + + loadx [addr [baud]] + +Description +----------- + +The loadx command is used to transfer a file to the device via the serial line +using the XMODEM 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. + +.. code-block:: + + picocom --send-cmd 'sx -b vv' --baud 115200 /dev/ttyUSB0 + +After entering the loadx command the key sequence <CTRL-A><CTRL-S> is used to +let picocom prompt for the file name. Picocom invokes the program sx for the +file transfer. + +:: + + => loadx 60800000 115200 + ## Ready for binary (xmodem) download to 0x60800000 at 115200 bps... + C + *** file: helloworld.efi + $ sx -b vv helloworld.efi + sx: cannot open vv: No such file or directory + Sending helloworld.efi, 24 blocks: Give your local XMODEM receive command now. + Xmodem sectors/kbytes sent: 0/ 0kRetry 0: NAK on sector + Bytes Sent: 3072 BPS:1147 + + Transfer incomplete + + *** exit status: 1 *** + ## Total Size = 0x00000c00 = 3072 Bytes + ## Start Addr = 0x60800000 + => + +The transfer can be cancelled by pressing 3 times <CTRL+C> after two seconds +of inactivity on terminal. + +Configuration +------------- + +The command is only available if CONFIG_CMD_LOADB=y. + +Initial timeout in seconds while waiting for transfer is configured by +config option CMD_LOADXY_TIMEOUT or by env variable $loadxy_timeout. +Setting it to 0 means infinite timeout. + +Return value +------------ + +The return value $? is 0 (true) on success, 1 (false) otherwise. diff --git a/doc/usage/cmd/loady.rst b/doc/usage/cmd/loady.rst new file mode 100644 index 00000000000..8367759471e --- /dev/null +++ b/doc/usage/cmd/loady.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: loady (command) + +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 + => + +Transfer can be cancelled by pressing 3 times <CTRL+C> after two seconds +of inactivity on terminal. + +Configuration +------------- + +The command is only available if CONFIG_CMD_LOADB=y. + +Initial timeout in seconds while waiting for transfer is configured by +config option CMD_LOADXY_TIMEOUT or by env variable $loadxy_timeout. +Setting it to 0 means infinite timeout. + +Return value +------------ + +The return value $? is 0 (true) on success, 1 (false) otherwise. diff --git a/doc/usage/cmd/mbr.rst b/doc/usage/cmd/mbr.rst new file mode 100644 index 00000000000..925a1181055 --- /dev/null +++ b/doc/usage/cmd/mbr.rst @@ -0,0 +1,97 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: mbr (command) + +mbr command +=========== + +Synopsis +-------- + +:: + + mbr verify [interface] [device no] [partition list] + mbr write [interface] [device no] [partition list] + +Description +----------- + +The mbr command lets users create or verify the MBR (Master Boot Record) +partition layout based on the provided text description. The partition +layout is alternatively read from the 'mbr_parts' environment variable. +This can be used in scripts to help system image flashing tools to ensure +proper partition layout. + +The syntax of the text description of the partition list is similar to +the one used by the 'gpt' command. + +Supported partition parameters are: + +* name (currently ignored) +* start (partition start offset in bytes) +* size (in bytes or '-' to expand it to the whole free area) +* bootable (boolean flag) +* id (MBR partition type) + +If one wants to create more than 4 partitions, an 'Extended' primary +partition (with 0x05 ID) has to be explicitly provided as a one of the +first 4 entries. + +Here is an example how to create a 6 partitions (3 on the 'extended +volume'), some of the predefined sizes: + +:: + + => setenv mbr_parts 'name=boot,start=4M,size=128M,bootable,id=0x0e; + name=rootfs,size=3072M,id=0x83; + name=system-data,size=512M,id=0x83; + name=[ext],size=-,id=0x05; + name=user,size=-,id=0x83; + name=modules,size=100M,id=0x83; + name=ramdisk,size=8M,id=0x83' + => mbr write mmc 0 + +To check if the layout on the MMC #0 storage device matches the provided +text description one has to issue following command (assuming that +mbr_parts environment variable is set): + +:: + + => mbr verify mmc 0 + +The verify sub-command is especially useful in the system update scripts: + +:: + + => if mbr verify mmc 0; then + echo MBR layout needs to be updated + ... + fi + +The 'mbr write' command returns 0 on success write or 1 on failure. + +The 'mbr verify' returns 0 if the layout matches the one on the storage +device or 1 if not. + +Configuration +------------- + +To use the mbr command you must specify CONFIG_CMD_MBR=y. + +Return value +------------ + +The variable *$?* takes the following values + ++---+------------------------------+ +| 0 | mbr write was succesful | ++---+------------------------------+ +| 1 | mbr write failed | ++---+------------------------------+ +| 0 | mbr verify was succesful | ++---+------------------------------+ +| 1 | mbr verify was not succesful | ++---+------------------------------+ +|-1 | invalid arguments | ++---+------------------------------+ diff --git a/doc/usage/cmd/md.rst b/doc/usage/cmd/md.rst new file mode 100644 index 00000000000..9a9919f9ad0 --- /dev/null +++ b/doc/usage/cmd/md.rst @@ -0,0 +1,107 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: md (command) + +md command +========== + +Synopsis +-------- + +:: + + md <address>[<data_size>] [<length>] + +Description +----------- + +The md command is used to dump the contents of memory. It uses a standard +format that includes the address, hex data and ASCII display. It supports +various data sizes and uses the endianness of the target. + +The specified data_size and length become the defaults for future memory +commands commands. + +address + start address to display + +data_size + size of each value to display (defaults to .l): + + ========= =================== + data_size Output size + ========= =================== + .b byte + .w word (16 bits) + .l long (32 bits) + .q quadword (64 bits) + ========= =================== + +length + number of values to dump. Defaults to 40 (0d64). Note that this is not + the same as the number of bytes, unless .b is used. + +Note that the format of 'md.b' can be emulated from linux with:: + + # This works but requires using sed to get the extra spaces + # <addr> is the address, <f> is the filename + xxd -o <addr> -g1 <f> |sed 's/ / /' >bad + + # This uses a single tool but the offset always starts at 0 + # <f> is the filename + hexdump -v -e '"%08.8_ax: " 16/1 "%02x " " "' -e '16/1 "%_p" "\n" ' <f> + + +Example +------- + +:: + + => md 10000 + 00010000: 00010000 00000000 f0f30f00 00005596 .............U.. + 00010010: 10011010 00000000 10011010 00000000 ................ + 00010020: 10011050 00000000 b96d4cd8 00007fff P........Lm..... + 00010030: 00000000 00000000 f0f30f18 00005596 .............U.. + 00010040: 10011040 00000000 10011040 00000000 @.......@....... + 00010050: b96d4cd8 00007fff 10011020 00000000 .Lm..... ....... + 00010060: 00000003 000000c3 00000000 00000000 ................ + 00010070: 00000000 00000000 f0e892f3 00005596 .............U.. + 00010080: 00000000 000000a1 00000000 00000000 ................ + 00010090: 00000000 00000000 f0e38aa6 00005596 .............U.. + 000100a0: 00000000 000000a6 00000022 00000000 ........"....... + 000100b0: 00000001 00000000 f0e38aa1 00005596 .............U.. + 000100c0: 00000000 000000be 00000000 00000000 ................ + 000100d0: 00000000 00000000 00000000 00000000 ................ + 000100e0: 00000000 00000000 00000000 00000000 ................ + 000100f0: 00000000 00000000 00000000 00000000 ................ + => md.b 10000 + 00010000: 00 00 01 00 00 00 00 00 00 0f f3 f0 96 55 00 00 .............U.. + 00010010: 10 10 01 10 00 00 00 00 10 10 01 10 00 00 00 00 ................ + 00010020: 50 10 01 10 00 00 00 00 d8 4c 6d b9 ff 7f 00 00 P........Lm..... + 00010030: 00 00 00 00 00 00 00 00 18 0f f3 f0 96 55 00 00 .............U.. + => md.b 10000 10 + 00010000: 00 00 01 00 00 00 00 00 00 0f f3 f0 96 55 00 00 .............U.. + => + 00010010: 10 10 01 10 00 00 00 00 10 10 01 10 00 00 00 00 ................ + => + 00010020: 50 10 01 10 00 00 00 00 d8 4c 6d b9 ff 7f 00 00 P........Lm..... + => + => md.q 10000 + 00010000: 0000000000010000 00005596f0f30f00 .............U.. + 00010010: 0000000010011010 0000000010011010 ................ + 00010020: 0000000010011050 00007fffb96d4cd8 P........Lm..... + 00010030: 0000000000000000 00005596f0f30f18 .............U.. + 00010040: 0000000010011040 0000000010011040 @.......@....... + 00010050: 00007fffb96d4cd8 0000000010011020 .Lm..... ....... + 00010060: 000000c300000003 0000000000000000 ................ + 00010070: 0000000000000000 00005596f0e892f3 .............U.. + +The empty commands cause a 'repeat', so that md shows the next available data +in the same format as before. + + +Return value +------------ + +The return value $? is always 0 (true). diff --git a/doc/usage/cmd/mmc.rst b/doc/usage/cmd/mmc.rst new file mode 100644 index 00000000000..5a64400eeae --- /dev/null +++ b/doc/usage/cmd/mmc.rst @@ -0,0 +1,297 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: mmc (command) + +mmc command +=========== + +Synopsis +-------- + +:: + + mmc info + mmc read addr blk# cnt + mmc write addr blk# cnt + mmc erase blk# cnt + mmc rescan [mode] + mmc part + mmc dev [dev] [part] [mode] + mmc list + mmc wp + mmc bootbus <dev> <boot_bus_width> <reset_boot_bus_width> <boot_mode> + mmc bootpart-resize <dev> <dev part size MB> <RPMB part size MB> + mmc partconf <dev> [[varname] | [<boot_ack> <boot_partition> <partition_access>]] + mmc rst-function <dev> <value> + mmc reg read <reg> <offset> [env] + +Description +----------- + +The mmc command is used to control MMC(eMMC/SD) device. + +The 'mmc info' command displays information (Manufacturer ID, OEM, Name, Bus Speed, Mode, ...) of MMC device. + +The 'mmc read' command reads raw data to memory address from MMC device with block offset and count. + +The 'mmc write' command writes raw data to MMC device from memory address with block offset and count. + + addr + memory address + blk# + start block offset + cnt + block count + +The 'mmc erase' command erases *cnt* blocks on the MMC device starting at block *blk#*. + + blk# + start block offset + cnt + block count + +The 'mmc rescan' command scans the available MMC device. + + mode + speed mode to set. + CONFIG_MMC_SPEED_MODE_SET should be enabled. The requested speed mode is + passed as a decimal number according to the following table: + + ========== ========================== + Speed mode Description + ========== ========================== + 0 MMC legacy + 1 MMC High Speed (26MHz) + 2 SD High Speed (50MHz) + 3 MMC High Speed (52MHz) + 4 MMC DDR52 (52MHz) + 5 UHS SDR12 (25MHz) + 6 UHS SDR25 (50MHz) + 7 UHS SDR50 (100MHz) + 8 UHS DDR50 (50MHz) + 9 UHS SDR104 (208MHz) + 10 HS200 (200MHz) + 11 HS400 (200MHz) + 12 HS400ES (200MHz) + ========== ========================== + + A speed mode can be set only if it has already been enabled in the device tree + +The 'mmc part' command displays the list available partition on current mmc device. + +The 'mmc dev' command shows or set current mmc device. + + dev + device number to change + part + partition number to change + + mode + speed mode to set. + CONFIG_MMC_SPEED_MODE_SET should be enabled. The requested speed mode is + passed as a decimal number according to the following table: + + ========== ========================== + Speed mode Description + ========== ========================== + 0 MMC legacy + 1 MMC High Speed (26MHz) + 2 SD High Speed (50MHz) + 3 MMC High Speed (52MHz) + 4 MMC DDR52 (52MHz) + 5 UHS SDR12 (25MHz) + 6 UHS SDR25 (50MHz) + 7 UHS SDR50 (100MHz) + 8 UHS DDR50 (50MHz) + 9 UHS SDR104 (208MHz) + 10 HS200 (200MHz) + 11 HS400 (200MHz) + 12 HS400ES (200MHz) + ========== ========================== + + A speed mode can be set only if it has already been enabled in the device tree + +The 'mmc list' command displays the list available devices. + +The 'mmc wp' command enables "power on write protect" function for boot partitions. + +The 'mmc bootbus' command sets the BOOT_BUS_WIDTH field. (*Refer to eMMC specification*) + + boot_bus_width + 0x0 + x1 (sdr) or x4(ddr) buswidth in boot operation mode (default) + 0x1 + x4 (sdr/ddr) buswidth in boot operation mode + 0x2 + x8 (sdr/ddr) buswidth in boot operation mode + 0x3 + Reserved + + reset_boot_bus_width + 0x0 + Reset buswidth to x1, Single data reate and backward compatible timing after boot operation (default) + 0x1 + Retain BOOT_BUS_WIDTH and BOOT_MODE value after boot operation. This is relevant to Push-pull mode operation only + + boot_mode + 0x0 + Use single data rate + backward compatible timing in boot operation (default) + 0x1 + Use single data rate + High Speed timing in boot operation mode + 0x2 + Use dual data rate in boot operation + 0x3 + Reserved + +The 'mmc partconf' command shows or changes PARTITION_CONFIG field. + + varname + When showing the PARTITION_CONFIG, an optional environment variable to store the current boot_partition value into. + boot_ack + boot acknowledge value + boot_partition + boot partition to enable for boot + 0x0 + Device not boot enabled(default) + 0x1 + Boot partition1 enabled for boot + 0x2 + Boot partition2 enabled for boot + 0x7 + User area enabled for boot + others + Reserved + partition_access + partitions to access + +The 'mmc bootpart-resize' command changes sizes of boot and RPMB partitions. + + dev + device number + boot part size MB + target size of boot partition + RPMB part size MB + target size of RPMB partition + +The 'mmc rst-function' command changes the RST_n_FUNCTION field. +**WARNING** : This is a write-once field. (*Refer to eMMC specification*) + + value + 0x0 + RST_n signal is temporarily disabled (default) + 0x1 + RST_n signal is permanently enabled + 0x2 + RST_n signal is permanently disabled + 0x3 + Reserved + +The 'mmc reg read <reg> <offset> [env]' reads eMMC card register and +either print it to standard output, or store the value in environment +variable. + +<reg> with +optional offset <offset> into the register array, and print it to +standard output or store it into environment variable [env]. + + reg + cid + The Device IDentification (CID) register. Uses offset. + csd + The Device-Specific Data (CSD) register. Uses offset. + dsr + The driver stage register (DSR). + ocr + The operation conditions register (OCR). + rca + The relative Device address (RCA) register. + extcsd + The Extended CSD register. Uses offset. + offset + For 'cid'/'csd' 128 bit registers '[0..3]' in 32-bit increments. For 'extcsd' 512 bit register '[0..512,all]' in 8-bit increments, or 'all' to read the entire register. + env + Optional environment variable into which 32-bit value read from register should be stored. + +Examples +-------- + +The 'mmc info' command displays device's capabilities: +:: + + => mmc info + Device: EXYNOS DWMMC + Manufacturer ID: 45 + OEM: 100 + Name: SDW16 + Bus Speed: 52000000 + Mode: MMC DDR52 (52MHz) + Rd Block Len: 512 + MMC version 5.0 + High Capacity: Yes + Capacity: 14.7 GiB + Bus Width: 8-bit DDR + Erase Group Size: 512 KiB + HC WP Group Size: 8 MiB + User Capacity: 14.7 GiB WRREL + Boot Capacity: 4 MiB ENH + RPMB Capacity: 4 MiB ENH + Boot area 0 is not write protected + Boot area 1 is not write protected + +The raw data can be read/written via 'mmc read/write' command: +:: + + => mmc read 40000000 5000 100 + MMC read: dev # 0, block # 20480, count 256 ... 256 blocks read: OK + + => mmc write 40000000 5000 100 + MMC write: dev # 0, block # 20480, count 256 ... 256 blocks written: OK + +The partition list can be shown via 'mmc part' command: +:: + + => mmc part + Partition Map for MMC device 0 -- Partition Type: DOS + + Part Start Sector Num Sectors UUID Type + 1 8192 131072 dff8751a-01 0e Boot + 2 139264 6291456 dff8751a-02 83 + 3 6430720 1048576 dff8751a-03 83 + 4 7479296 23298048 dff8751a-04 05 Extd + 5 7481344 307200 dff8751a-05 83 + 6 7790592 65536 dff8751a-06 83 + 7 7858176 16384 dff8751a-07 83 + 8 7876608 22900736 dff8751a-08 83 + +The current device can be shown or set via 'mmc dev' command: +:: + + => mmc dev + switch to partitions #0, OK + mmc0(part0) is current device + => mmc dev 2 0 + switch to partitions #0, OK + mmc2 is current device + => mmc dev 0 1 4 + switch to partitions #1, OK + mmc0(part 1) is current device + +The list of available devices can be shown via 'mmc list' command: +:: + + => mmc list + mmc list + EXYNOS DWMMC: 0 (eMMC) + EXYNOS DWMMC: 2 (SD) + +Configuration +------------- + +The mmc command is only available if CONFIG_CMD_MMC=y. +Some commands need to enable more configuration. + +write, erase + CONFIG_MMC_WRITE +bootbus, bootpart-resize, partconf, rst-function + CONFIG_SUPPORT_EMMC_BOOT=y diff --git a/doc/usage/cmd/mtest.rst b/doc/usage/cmd/mtest.rst new file mode 100644 index 00000000000..e01f2a6d575 --- /dev/null +++ b/doc/usage/cmd/mtest.rst @@ -0,0 +1,69 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2022, Heinrich Schuchardt <xypron.glpk@gmx.de> + +.. index:: + single: mtest (command) + +mtest command +============= + +Synopsis +-------- + +:: + + mtest [start [end [pattern [iterations]]]] + +Description +----------- + +The *mtest* command tests the random access memory. It writes long values, reads +them back and checks for differences. The test can be interrupted with CTRL+C. + +The default test uses *pattern* as first value to be written and varies it +between memory addresses. + +An alternative test can be selected with CONFIG_SYS_ALT_MEMTEST=y. It uses +multiple hard coded bit patterns. + +With CONFIGSYS_ALT_MEMTEST_BITFLIP=y a further test is executed. It writes long +values offset by half the size of long and checks if writing to the one address +causes bit flips at the other address. + +start + start address of the memory range tested, defaults to + CONFIG_SYS_MEMTEST_START + +end + end address of the memory range tested, defaults to + CONFIG_SYS_MEMTEST_END. If CONFIGSYS_ALT_MEMTEST_BITFLIP=y, a value will + be written to this address. Otherwise it is excluded from the range. + +pattern + pattern to be written to memory. This is a 64bit value on 64bit systems + and a 32bit value on 32bit systems. It defaults to 0. The value is + ignored if CONFIG_SYS_ALT_MEMTEST=y. + +iterations + number of test repetitions. If the value is not provided the test will + not terminate automatically. Enter CTRL+C instead. + +Examples +-------- + +:: + + => mtest 1000 2000 0x55aa55aa55aa55aa 10 + Testing 00001000 ... 00002000: + Pattern AA55AA55AA55AA55 Writing... Reading... + Tested 16 iteration(s) with 0 errors. + +Configuration +------------- + +The mtest command is enabled by CONFIG_CMD_MEMTEST=y. + +Return value +------------ + +The return value $? is 0 (true) if the command succeeds, 1 (false) otherwise. diff --git a/doc/usage/cmd/mtrr.rst b/doc/usage/cmd/mtrr.rst new file mode 100644 index 00000000000..3c5c3ba3d43 --- /dev/null +++ b/doc/usage/cmd/mtrr.rst @@ -0,0 +1,154 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: mtrr (command) + +mtrr command +============ + +Synopsis +-------- + + mtrr [list] + mtrr set <reg> <type> <start> <size> + mtrr disable <reg> + mtrr enable + + +Description +----------- + +The *mtrr* command is used to dump the Memory Type Range Registers (MTRRs) on +an x86 machine. These register control cache behaviour in selected memory +ranges. + +Note that the number of registers can vary between CPUs. + + +mtrr [list] +~~~~~~~~~~~ + +List the MTRRs. The table shows the following information: + +Reg + Register number (the first is register 0) + +Valid + Shows Y if the register is valid (has bit 11 set), N if not + +Write-type + Shows the behaviour when writing to the memory region. The types are + abbreviated to fit a reasonable line length. Valid types shown below. + + ====== ============== ==================================================== + Value Type Meaning + ====== ============== ==================================================== + 0 Uncacheable Skip cache and write directly to memory + 1 Combine Multiple writes can be combined into one transaction + 4 Through Update cache and also write to memory + 5 Protect Writes are prohibited + 6 Back Update cache but don't write to memory + ====== ============== ==================================================== + +Base + Base memory address from which the register controls behaviour + +Mask + Mask value, which also indicates the size + +Size + Length of memory region within which the register controls behaviour + + +mtrr set +~~~~~~~~ + +This sets the value of a particular MTRR. Parameters are: + +reg + Register number to set, with 0 being the first + +type + Access type to set. See Write-type above for valid types. This uses the name + rather than its numeric value. + +start + Base memory address from which the register should control behaviour + +size + Length of memory region within which the register controls behaviour + + +mtrr disable +~~~~~~~~~~~~ + +This disables a particular register, by clearing its `valid` bit (11). + + +mtrr enable +~~~~~~~~~~~ + +This enables a particular register, by setting its `valid` bit (11). + + +Example +------- + +This shows disabling and enabling an MTRR, as well as setting its type:: + + => mtrr + CPU 0: + Reg Valid Write-type Base || Mask || Size || + 0 Y Back 0000000000000000 0000000f80000000 0000000080000000 + 1 Y Back 0000000080000000 0000000fe0000000 0000000020000000 + 2 Y Back 00000000a0000000 0000000ff0000000 0000000010000000 + 3 Y Uncacheable 00000000ad000000 0000000fff000000 0000000001000000 + 4 Y Uncacheable 00000000ae000000 0000000ffe000000 0000000002000000 + 5 Y Combine 00000000d0000000 0000000ff0000000 0000000010000000 + 6 N Uncacheable 0000000000000000 0000000000000000 0000001000000000 + 7 N Uncacheable 0000000000000000 0000000000000000 0000001000000000 + 8 N Uncacheable 0000000000000000 0000000000000000 0000001000000000 + 9 N Uncacheable 0000000000000000 0000000000000000 0000001000000000 + => mtrr d 5 + => mtrr + CPU 0: + Reg Valid Write-type Base || Mask || Size || + 0 Y Back 0000000000000000 0000000f80000000 0000000080000000 + 1 Y Back 0000000080000000 0000000fe0000000 0000000020000000 + 2 Y Back 00000000a0000000 0000000ff0000000 0000000010000000 + 3 Y Uncacheable 00000000ad000000 0000000fff000000 0000000001000000 + 4 Y Uncacheable 00000000ae000000 0000000ffe000000 0000000002000000 + 5 N Combine 00000000d0000000 0000000ff0000000 0000000010000000 + 6 N Uncacheable 0000000000000000 0000000000000000 0000001000000000 + 7 N Uncacheable 0000000000000000 0000000000000000 0000001000000000 + 8 N Uncacheable 0000000000000000 0000000000000000 0000001000000000 + 9 N Uncacheable 0000000000000000 0000000000000000 0000001000000000 + => mtrr e 5 + => mtrr + CPU 0: + Reg Valid Write-type Base || Mask || Size || + 0 Y Back 0000000000000000 0000000f80000000 0000000080000000 + 1 Y Back 0000000080000000 0000000fe0000000 0000000020000000 + 2 Y Back 00000000a0000000 0000000ff0000000 0000000010000000 + 3 Y Uncacheable 00000000ad000000 0000000fff000000 0000000001000000 + 4 Y Uncacheable 00000000ae000000 0000000ffe000000 0000000002000000 + 5 Y Combine 00000000d0000000 0000000ff0000000 0000000010000000 + 6 N Uncacheable 0000000000000000 0000000000000000 0000001000000000 + 7 N Uncacheable 0000000000000000 0000000000000000 0000001000000000 + 8 N Uncacheable 0000000000000000 0000000000000000 0000001000000000 + 9 N Uncacheable 0000000000000000 0000000000000000 0000001000000000 + => mtrr set 5 Uncacheable d0000000 10000000 + => mtrr + CPU 0: + Reg Valid Write-type Base || Mask || Size || + 0 Y Back 0000000000000000 0000000f80000000 0000000080000000 + 1 Y Back 0000000080000000 0000000fe0000000 0000000020000000 + 2 Y Back 00000000a0000000 0000000ff0000000 0000000010000000 + 3 Y Uncacheable 00000000ad000000 0000000fff000000 0000000001000000 + 4 Y Uncacheable 00000000ae000000 0000000ffe000000 0000000002000000 + 5 Y Uncacheable 00000000d0000000 0000000ff0000000 0000000010000000 + 6 N Uncacheable 0000000000000000 0000000000000000 0000001000000000 + 7 N Uncacheable 0000000000000000 0000000000000000 0000001000000000 + 8 N Uncacheable 0000000000000000 0000000000000000 0000001000000000 + 9 N Uncacheable 0000000000000000 0000000000000000 0000001000000000 + => diff --git a/doc/usage/cmd/panic.rst b/doc/usage/cmd/panic.rst new file mode 100644 index 00000000000..39d32adbc99 --- /dev/null +++ b/doc/usage/cmd/panic.rst @@ -0,0 +1,36 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: panic (command) + +panic command +============= + +Synopsis +-------- + +:: + + panic [message] + +Description +----------- + +Display a message and reset the board. + +message + text to be displayed + +Examples +-------- + +:: + + => panic 'Unrecoverable error' + Unrecoverable error + resetting ... + +Configuration +------------- + +If CONFIG_PANIC_HANG=y, the user has to reset the board manually. diff --git a/doc/usage/cmd/part.rst b/doc/usage/cmd/part.rst new file mode 100644 index 00000000000..e7faeccbb09 --- /dev/null +++ b/doc/usage/cmd/part.rst @@ -0,0 +1,231 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: part (command) + +part command +============ + +Synopsis +-------- + +:: + + part uuid <interface> <dev>:<part> [varname] + part list <interface> <dev> [flags] [varname] + part start <interface> <dev> <part> <varname> + part size <interface> <dev> <part> <varname> + part number <interface> <dev> <part> <varname> + part set <interface> <dev> <part> <type> + part type <interface> <dev>:<part> [varname] + part types + +Description +----------- + +The `part` command is used to manage disk partition related commands. + +The 'part uuid' command prints or sets an environment variable to partition UUID + + interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + dev + device number + part + partition number + varname + an optional environment variable to store the current partition UUID value into. + +The 'part list' command prints or sets an environment variable to the list of partitions + + interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + dev + device number + part + partition number + flags + -bootable + lists only bootable partitions + varname + an optional environment variable to store the list of partitions value into. + +The 'part start' commnad sets an environment variable to the start of the partition (in blocks), +part can be either partition number or partition name. + + interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + dev + device number + part + partition number + varname + a variable to store the current start of the partition value into. + +The 'part size' command sets an environment variable to the size of the partition (in blocks), +part can be either partition number or partition name. + + interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + dev + device number + part + partition number + varname + a variable to store the current size of the partition value into. + +The 'part number' command sets an environment variable to the partition number using the partition name, +part must be specified as partition name. + + interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + dev + device number + part + partition number + varname + a variable to store the current partition number value into + +The 'part set' command sets the type of a partition. This is useful when +autodetection fails or does not do the correct thing: + + interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + dev + device number + part + partition number + type + partition type to use (see 'part types') to check available types + +The 'part type' command prints or sets an environment variable to the partition type UUID. + + interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + dev + device number + part + partition number + varname + a variable to store the current partition type UUID value into + +The 'part types' command list supported partition table types. + +Examples +-------- + +:: + + => host bind 0 ./test_gpt_disk_image.bin + => part uuid host 0:1 + 24156b69-3378-497f-bb3e-b982223de528 + => part uuid host 0:1 varname + => env print varname + varname=24156b69-3378-497f-bb3e-b982223de528 + => + => part list host 0 + + Partition Map for HOST device 0 -- Partition Type: EFI + + Part Start LBA End LBA Name + Attributes + Type GUID + Partition GUID + 1 0x00000800 0x00000fff "second" + attrs: 0x0000000000000000 + type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 + (data) + guid: 24156b69-3378-497f-bb3e-b982223de528 + 2 0x00001000 0x00001bff "first" + attrs: 0x0000000000000000 + type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 + (data) + guid: 5272ee44-29ab-4d46-af6c-4b45ac67d3b7 + => + => part start host 0 2 varname + => env print varname + varname=1000 + => + => part size host 0 2 varname + => env print varname + varname=c00 + => + => part number host 0 2 varname + => env print varname + varname=0x2 + => + => part type host 0:1 + ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 + => part type host 0:1 varname + => env print varname + varname=ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 + => + => part types + Supported partition tables: EFI, AMIGA, DOS, ISO, MAC + +This shows looking at a device with multiple partition tables:: + + => virtio scan + => part list virtio 0 + + Partition Map for VirtIO device 0 -- Partition Type: EFI + + Part Start LBA End LBA Name + Attributes + Type GUID + Partition GUID + 1 0x00000040 0x0092b093 "ISO9660" + attrs: 0x1000000000000001 + type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 + guid: a0891d7e-b930-4513-94d8-f629dbd637b2 + 2 0x0092b094 0x0092d7e7 "Appended2" + attrs: 0x0000000000000000 + type: c12a7328-f81f-11d2-ba4b-00a0c93ec93b + guid: a0891d7e-b930-4513-94db-f629dbd637b2 + 3 0x0092d7e8 0x0092da3f "Gap1" + attrs: 0x1000000000000001 + type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 + guid: a0891d7e-b930-4513-94da-f629dbd637b2 + => ls virtio 0:3 + => part types + Supported partition tables: EFI, DOS, ISO + => part set virtio 0 dos + + Partition Map for VirtIO device 0 -- Partition Type: DOS + + Part Start Sector Num Sectors UUID Type + 1 1 9624191 00000000-01 ee + => part set virtio 0 iso + + Partition Map for VirtIO device 0 -- Partition Type: ISO + + Part Start Sect x Size Type + 1 3020 4 512 U-Boot + 2 9613460 10068 512 U-Boot + => part set virtio 0 efi + + Partition Map for VirtIO device 0 -- Partition Type: EFI + + Part Start LBA End LBA Name + Attributes + Type GUID + Partition GUID + 1 0x00000040 0x0092b093 "ISO9660" + attrs: 0x1000000000000001 + type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 + guid: a0891d7e-b930-4513-94d8-f629dbd637b2 + 2 0x0092b094 0x0092d7e7 "Appended2" + attrs: 0x0000000000000000 + type: c12a7328-f81f-11d2-ba4b-00a0c93ec93b + guid: a0891d7e-b930-4513-94db-f629dbd637b2 + 3 0x0092d7e8 0x0092da3f "Gap1" + attrs: 0x1000000000000001 + type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 + guid: a0891d7e-b930-4513-94da-f629dbd637b2 + => + +Return value +------------ + +The return value $? is set to 0 (true) if the command succededd. If an +error occurs, the return value $? is set to 1 (false). diff --git a/doc/usage/cmd/pause.rst b/doc/usage/cmd/pause.rst new file mode 100644 index 00000000000..6cdd83d3163 --- /dev/null +++ b/doc/usage/cmd/pause.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later: + +.. index:: + single: pause (command) + +pause command +============= + +Synopsis +-------- + +:: + + pause [prompt] + + +Description +----------- + +The pause command delays execution waiting for any user input. + +It can accept a single parameter to change the prompt message. + +Examples +-------- + +Using with the default prompt: + +:: + + => pause + Press any key to continue... + + +Using with a custom prompt: + +:: + + => pause 'Prompt for pause...' + Prompt for pause... + +Note that complex prompts require proper quoting: + +:: + + => pause Prompt for pause... + pause - delay until user input + + Usage: + pause [prompt] - Wait until users presses any key. [prompt] can be used to customize the message. + +Return value +------------ + +The return value $? is always set to 0 (true), unless invoked in an invalid +manner. diff --git a/doc/usage/cmd/pinmux.rst b/doc/usage/cmd/pinmux.rst new file mode 100644 index 00000000000..30c5eb16a68 --- /dev/null +++ b/doc/usage/cmd/pinmux.rst @@ -0,0 +1,98 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: pinmux (command) + +pinmux command +============== + +Synopsis +-------- + +:: + + pinmux list + pinmux dev [pincontroller-name] + pinmux status [-a | pin-name] + +Description +----------- + +The pinmux command is used to show the pin-controller muxing. + +The 'pinmux list' command diplays the available pin-controller. + +The 'pinmux dev' command selects the pin-controller for next commands. + + pincontroller-name + name of the pin-controller to select + +The 'pinmux status' command displays the pin muxing information. + + \-a + display pin muxing of all pin-controllers. + pin-name + name of the pin to display + +Example +------- + +:: + + => pinmux list + | Device | Driver | Parent + | pinctrl-gpio | sandbox_pinctrl_gpio | root_driver + | pinctrl | sandbox_pinctrl | root_driver + => + => pinmux dev pinctrl + dev: pinctrl + => + => pinmux status + P0 : UART TX. + P1 : UART RX. + P2 : I2S SCK. + P3 : I2S SD. + P4 : I2S WS. + P5 : GPIO0 bias-pull-up input-disable. + P6 : GPIO1 drive-open-drain. + P7 : GPIO2 bias-pull-down input-enable. + P8 : GPIO3 bias-disable. + => + => pinmux status P0 + P0 : UART TX. + => + => pinmux status -a + -------------------------- + pinctrl-gpio: + a0 : gpio input . + a1 : gpio input . + a2 : gpio input . + a3 : gpio input . + a4 : gpio input . + a5 : gpio output . + a6 : gpio output . + a7 : gpio input . + a8 : gpio input . + a9 : gpio input . + -------------------------- + pinctrl: + P0 : UART TX. + P1 : UART RX. + P2 : I2S SCK. + P3 : I2S SD. + P4 : I2S WS. + P5 : GPIO0 bias-pull-up input-disable. + P6 : GPIO1 drive-open-drain. + P7 : GPIO2 bias-pull-down input-enable. + P8 : GPIO3 bias-disable. + +Configuration +------------- + +The pinmux command is only available if CONFIG_CMD_PINMUX=y. + +Return value +------------ + +The return value $? is set to 0 (true) if the command succeded and to 1 (false) +otherwise. diff --git a/doc/usage/cmd/printenv.rst b/doc/usage/cmd/printenv.rst new file mode 100644 index 00000000000..dfdb3624934 --- /dev/null +++ b/doc/usage/cmd/printenv.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: printenv (command) + +printenv command +================ + +Synopsis +-------- + +:: + + printenv [-a] [name ...] + printenv -e [-guid guid][-n] [name] + +Description +----------- + +The printenv command is used to print environment or UEFI variables. + +\-a + Print environment variables starting with a period ('.'). + +\-e + Print UEFI variables. Without -e environment variables are printed. + +\-guid *guid* + Specify vendor GUID *guid*. If none is specified, all UEFI variables with + the specified name are printed irrespective of their vendor GUID. + +\-n + don't show hexadecimal dump of value + +name + Variable name. If no name is provided, all variables are printed. + Multiple environment variable names may be specified. + +Examples +-------- + +The following examples demonstrates the effect of the *-a* flag when displaying +environment variables: + +:: + + => setenv .foo bar + => printenv + arch=sandbox + baudrate=115200 + board=sandbox + ... + stdout=serial,vidconsole + + Environment size: 644/8188 bytes + => printenv -a + .foo=bar + arch=sandbox + baudrate=115200 + board=sandbox + ... + stdout=serial,vidconsole + + Environment size: 653/8188 bytes + => + +The next example shows the effect of the *-n* flag when displaying an UEFI +variable and how to specify a vendor GUID: + +:: + + => printenv -e -guid 8be4df61-93ca-11d2-aa0d-00e098032b8c PlatformLangCodes + PlatformLangCodes: + 8be4df61-93ca-11d2-aa0d-00e098032b8c (EFI_GLOBAL_VARIABLE_GUID) + BS|RT|RO, DataSize = 0x6 + 00000000: 65 6e 2d 55 53 00 en-US. + => printenv -e -n PlatformLangCodes + PlatformLangCodes: + 8be4df61-93ca-11d2-aa0d-00e098032b8c (EFI_GLOBAL_VARIABLE_GUID) + BS|RT|RO, DataSize = 0x6 + => + +Configuration +------------- + +UEFI variables are only supported if CONFIG_CMD_NVEDIT_EFI=y. The value of UEFI +variables can only be displayed if CONFIG_HEXDUMP=y. + +Return value +------------ + +The return value $? is 1 (false) if a specified variable is not found. +Otherwise $? is set to 0 (true). diff --git a/doc/usage/cmd/pstore.rst b/doc/usage/cmd/pstore.rst new file mode 100644 index 00000000000..63a437135ec --- /dev/null +++ b/doc/usage/cmd/pstore.rst @@ -0,0 +1,96 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: pstore (command) + +pstore command +============== + +Synopsis +-------- + +:: + + pstore set <addr> <len> [record-size] [console-size] [ftrace-size] [pmsg_size] [ecc-size] + pstore display [record-type] [nb] + pstore save <interface> <dev[:part]> <directory-path> + +Design +------ + +Linux PStore and Ramoops modules (Linux config options PSTORE and PSTORE_RAM) +allow to use memory to pass data from the dying breath of a crashing kernel to +its successor. This command allows to read those records from U-Boot command +line. + +Ramoops is an oops/panic logger that writes its logs to RAM before the system +crashes. It works by logging oopses and panics in a circular buffer. Ramoops +needs a system with persistent RAM so that the content of that area can survive +after a restart. + +Ramoops uses a predefined memory area to store the dump. + +Ramoops parameters can be passed as kernel parameters or through Device Tree, +i.e.:: + + ramoops.mem_address=0x30000000 ramoops.mem_size=0x100000 ramoops.record_size=0x2000 ramoops.console_size=0x2000 memmap=0x100000$0x30000000 + +The same values should be set in U-Boot to be able to retrieve the records. +This values can be set at build time in U-Boot configuration file, or at runtime. +U-Boot automatically patches the Device Tree to pass the Ramoops parameters to +the kernel. + +The PStore configuration parameters are: + +======================= ========== + Name Default +======================= ========== +CMD_PSTORE_MEM_ADDR +CMD_PSTORE_MEM_SIZE 0x10000 +CMD_PSTORE_RECORD_SIZE 0x1000 +CMD_PSTORE_CONSOLE_SIZE 0x1000 +CMD_PSTORE_FTRACE_SIZE 0x1000 +CMD_PSTORE_PMSG_SIZE 0x1000 +CMD_PSTORE_ECC_SIZE 0 +======================= ========== + +Records sizes should be a power of 2. +The memory size and the record/console size must be non-zero. + +Multiple 'dump' records can be stored in the memory reserved for PStore. +The memory size has to be larger than the sum of the record sizes, i.e.:: + + MEM_SIZE >= RECORD_SIZE * n + CONSOLE_SIZE + FTRACE_SIZE + PMSG_SIZE + +Usage +----- + +Generate kernel crash +~~~~~~~~~~~~~~~~~~~~~ + +For test purpose, you can generate a kernel crash by setting reboot timeout to +10 seconds and trigger a panic + +.. code-block:: console + + $ sudo sh -c "echo 1 > /proc/sys/kernel/sysrq" + $ sudo sh -c "echo 10 > /proc/sys/kernel/panic" + $ sudo sh -c "echo c > /proc/sysrq-trigger" + +Retrieve logs in U-Boot +~~~~~~~~~~~~~~~~~~~~~~~ + +First of all, unless PStore parameters as been set during U-Boot configuration +and match kernel ramoops parameters, it needs to be set using 'pstore set', e.g.:: + + => pstore set 0x30000000 0x100000 0x2000 0x2000 + +Then all available dumps can be displayed +using:: + + => pstore display + +Or saved to an existing directory in an Ext2 or Ext4 partition, e.g. on root +directory of 1st partition of the 2nd MMC:: + + => pstore save mmc 1:1 / diff --git a/doc/usage/cmd/qfw.rst b/doc/usage/cmd/qfw.rst new file mode 100644 index 00000000000..40770acb3c0 --- /dev/null +++ b/doc/usage/cmd/qfw.rst @@ -0,0 +1,95 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: qfw (command) + +qfw command +=========== + +Synopsis +-------- + +:: + + qfw list + qfw cpus + qfw load [kernel_addr [initrd_addr]] + +Description +----------- + +The *qfw* command is used to retrieve information from the QEMU firmware. + +The *qfw list* sub-command displays the QEMU firmware files. + +The *qfw cpus* sub-command displays the available CPUs. + +The *qfw load* command is used to load a kernel and an initial RAM disk. + +kernel_addr + address to which the file specified by the -kernel parameter of QEMU shall + be loaded. Defaults to environment variable *loadaddr* and further to + the value of *CONFIG_SYS_LOAD_ADDR*. + +initrd_addr + address to which the file specified by the -initrd parameter of QEMU shall + be loaded. Defaults to environment variable *ramdiskaddr* and further to + the value of *CFG_RAMDISK_ADDR*. + +Examples +-------- + +QEMU firmware files are listed via the *qfw list* command: + +:: + + => qfw list + 00000000 bios-geometry + 00000000 bootorder + 000f0060 etc/acpi/rsdp + bed14040 etc/acpi/tables + 00000000 etc/boot-fail-wait + 00000000 etc/e820 + 00000000 etc/smbios/smbios-anchor + 00000000 etc/smbios/smbios-tables + 00000000 etc/system-states + 00000000 etc/table-loader + 00000000 etc/tpm/log + 00000000 genroms/kvmvapic.bin + +Where an address is shown, it indicates where the data is available for +inspection, e.g. using the :doc:`md`. + +The available CPUs can be shown via the *qfw cpus* command: + +:: + + => qfw cpu + 2 cpu(s) online + +The *-kernel* and *-initrd* parameters allow to specify a kernel and an +initial RAM disk for QEMU: + +.. code-block:: bash + + $ qemu-system-x86_64 -machine pc-i440fx-2.5 -bios u-boot.rom -m 1G \ + -nographic -kernel vmlinuz -initrd initrd + +Now the kernel and the initial RAM disk can be loaded to the U-Boot memory via +the *qfw load* command and booted thereafter. + +:: + + => qfw load ${kernel_addr_r} ${ramdisk_addr_r} + loading kernel to address 0000000001000000 size 5048f0 initrd 0000000004000000 size 3c94891 + => zboot 1000000 5048f0 4000000 3c94891 + Valid Boot Flag + Magic signature found + Linux kernel version 4.19.0-14-amd64 (debian-kernel@lists.debian.org) #1 SMP Debian 4.19.171-2 (2021-01-30) + Building boot_params at 0x00090000 + Loading bzImage at address 100000 (5260160 bytes) + +Configuration +------------- + +The qfw command is only available if CONFIG_CMD_QFW=y. diff --git a/doc/usage/cmd/read.rst b/doc/usage/cmd/read.rst new file mode 100644 index 00000000000..840846728fc --- /dev/null +++ b/doc/usage/cmd/read.rst @@ -0,0 +1,44 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later: + +read and write commands +======================= + +Synopsis +-------- + +:: + + read <interface> <dev[:part|#partname]> <addr> <blk#> <cnt> + write <interface> <dev[:part|#partname]> <addr> <blk#> <cnt> + +The read and write commands can be used for raw access to data in +block devices (or partitions therein), i.e. without going through a +file system. + +read +---- + +The block device is specified using the <interface> (e.g. "mmc") and +<dev> parameters. If the block device has a partition table, one can +optionally specify a partition number (using the :part syntax) or +partition name (using the #partname syntax). The command then reads +the <cnt> blocks of data starting at block number <blk#> of the given +device/partition to the memory address <addr>. + +write +----- + +The write command is completely equivalent to the read command, except +of course that the transfer direction is reversed. + +Examples +-------- + + # Read 2 MiB from partition 3 of mmc device 2 to $loadaddr + read mmc 2.3 $loadaddr 0 0x1000 + + # Read 16 MiB from the partition named 'kernel' of mmc device 1 to $loadaddr + read mmc 1#kernel $loadaddr 0 0x8000 + + # Write to the third sector of the partition named 'bootdata' of mmc device 0 + write mmc 0#bootdata $loadaddr 2 1 diff --git a/doc/usage/cmd/reset.rst b/doc/usage/cmd/reset.rst new file mode 100644 index 00000000000..126db21cdb8 --- /dev/null +++ b/doc/usage/cmd/reset.rst @@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: reset (command) + +reset command +============= + +Synopsis +-------- + +:: + + reset [-w] + +Description +----------- + +Perform reset of the CPU. By default does COLD reset, which resets CPU, +DDR and peripherals, on some boards also resets external PMIC. + +-w + Do warm WARM, reset CPU but keep peripheral/DDR/PMIC active. + + +Return value +------------ + +The return value $? is always set to 0 (true). diff --git a/doc/usage/cmd/rng.rst b/doc/usage/cmd/rng.rst new file mode 100644 index 00000000000..4a61e33d272 --- /dev/null +++ b/doc/usage/cmd/rng.rst @@ -0,0 +1,35 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: rng (command) + +rng command +=========== + +Synopsis +-------- + +:: + + rng list + rng [dev] [n] + +rng list +-------- + +List all the probed rng devices. + +rng [dev] [n] +------------- + +The *rng* command reads the random number generator(RNG) device and +prints the random bytes read on the console. A maximum of 64 bytes can +be read in one invocation of the command. + +dev + The RNG device from which the random bytes are to be + read. Defaults to 0. + +n + Number of random bytes to be read and displayed on the + console. Default value is 0x40. Max value is 0x40. diff --git a/doc/usage/cmd/saves.rst b/doc/usage/cmd/saves.rst new file mode 100644 index 00000000000..b380a4feb6f --- /dev/null +++ b/doc/usage/cmd/saves.rst @@ -0,0 +1,91 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: saves (command) + +saves command +============= + +Synopsis +-------- + +:: + + saves [offset [size [baud]]] + +Description +----------- + +The *saves* command is used to transfer a file from the device via the serial +line using the Motorola S-record file format. + +offset + start address of memory area to save, defaults to 0x0 + +size + size of memory area to save, defaults to 0x0 + +baud + baud rate to use for upload. This parameter is only available if + CONFIG_SYS_LOADS_BAUD_CHANGE=y + +Example +------- + +In the example the *screen* command is used to connect to the U-Boot serial +console. + +In a first screen session a file is loaded from the SD-card and the *saves* +command is invoked. <CTRL+A><k> is used to kill the screen session. + +A new screen session is started which logs the output to a file and the +<ENTER> key is hit to start the file output. <CTRL+A><k> is issued to kill the +screen session. + +The log file is converted to a binary file using the *srec_cat* command. +A negative offset of -1337982976 (= -0x4c000000) is applied to compensate for +the offset used in the *saves* command. + +.. code-block:: + + $ screen /dev/ttyUSB0 115200 + => echo $scriptaddr + 0x4FC00000 + => load mmc 0:1 $scriptaddr boot.txt + 124 bytes read in 1 ms (121.1 KiB/s) + => saves $scriptaddr $filesize + ## Ready for S-Record upload, press ENTER to proceed ... + Really kill this window [y/n] + $ screen -Logfile out.srec -L /dev/ttyUSB0 115200 + S0030000FC + S3154FC00000736574656E76206175746F6C6F616420AD + S3154FC000106E6F0A646863700A6C6F6164206D6D633E + S3154FC0002020303A3120246664745F616464725F72B3 + S3154FC00030206474620A6C6F6164206D6D6320303AC0 + S3154FC000403120246B65726E656C5F616464725F72DA + S3154FC0005020736E702E6566690A626F6F74656669C6 + S3154FC0006020246B65726E656C5F616464725F7220CB + S3114FC00070246664745F616464725F720A38 + S70500000000FA + ## S-Record upload complete + => + Really kill this window [y/n] + $ srec_cat out.srec -offset -1337982976 -Output out.txt -binary 2>/dev/null + $ cat out.txt + setenv autoload no + dhcp + load mmc 0:1 $fdt_addr_r dtb + load mmc 0:1 $kernel_addr_r snp.efi + bootefi $kernel_addr_r $fdt_addr_r + $ + +Configuration +------------- + +The command is only available if CONFIG_CMD_SAVES=y. The parameter to set the +baud rate is only available if CONFIG_SYS_LOADS_BAUD_CHANGE=y + +Return value +------------ + +The return value $? is 0 (true) on success, 1 (false) otherwise. diff --git a/doc/usage/cmd/sbi.rst b/doc/usage/cmd/sbi.rst new file mode 100644 index 00000000000..5492925a8bc --- /dev/null +++ b/doc/usage/cmd/sbi.rst @@ -0,0 +1,59 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: sbi (command) + +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 1.0 + OpenSBI 1.1 + Machine: + Vendor ID 0 + Architecture ID 0 + Implementation ID 0 + Extensions: + Set Timer + Console Putchar + Console Getchar + Clear IPI + Send IPI + Remote FENCE.I + Remote SFENCE.VMA + Remote SFENCE.VMA with ASID + System Shutdown + SBI Base Functionality + Timer Extension + IPI Extension + RFENCE Extension + Hart State Management Extension + System Reset Extension + Performance Monitoring Unit Extension + +The first line indicates the version of the RISC-V SBI specification. +The second line indicates the implementation. +The Machine section shows the values of the machine information registers. +The Extensions section enumerates the implemented SBI extensions. + +Configuration +------------- + +To use the sbi command you must specify CONFIG_CMD_SBI=y. diff --git a/doc/usage/cmd/scmi.rst b/doc/usage/cmd/scmi.rst new file mode 100644 index 00000000000..9591cdc07a5 --- /dev/null +++ b/doc/usage/cmd/scmi.rst @@ -0,0 +1,129 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: scmi (command) + +scmi command +============ + +Synopsis +-------- + +:: + + scmi info + scmi perm_dev <agent id> <device id> <flags> + scmi perm_proto <agent id> <device id> <protocol id> <flags> + scmi reset <agent id> <flags> + +Description +----------- + +Arm System Control and Management Interface (SCMI hereafter) is a set of +standardised interfaces to manage system resources, like clocks, power +domains, pin controls, reset and so on, in a system-wide manner. + +An entity which provides those services is called a SCMI firmware (or +SCMI server if you like) may be placed/implemented by EL3 software or +by a dedicated system control processor (SCP) or else. + +A user of SCMI interfaces, including U-Boot, is called a SCMI agent and +may issues commands, which are defined in each protocol for specific system +resources, to SCMI server via a communication channel, called a transport. +Those interfaces are independent from the server's implementation thanks to +a transport layer. + +For more details, see the `SCMI specification`_. + +While most of system resources managed under SCMI protocols are implemented +and handled as standard U-Boot devices, for example clk_scmi, scmi command +provides additional management functionality against SCMI server. + +scmi info +~~~~~~~~~ + Show base information about SCMI server and supported protocols + +scmi perm_dev +~~~~~~~~~~~~~ + Allow or deny access permission to the device + +scmi perm_proto +~~~~~~~~~~~~~~~ + Allow or deny access to the protocol on the device + +scmi reset +~~~~~~~~~~ + Reset the already-configured permissions against the device + +Parameters are used as follows: + +<agent id> + SCMI Agent ID, hex value + +<device id> + SCMI Device ID, hex value + + Please note that what a device means is not defined + in the specification. + +<protocol id> + SCMI Protocol ID, hex value + + It must not be 0x10 (base protocol) + +<flags> + Flags to control the action, hex value + + 0 to deny, 1 to allow. The other values are reserved and allowed + values may depend on the implemented version of SCMI server in + the future. See SCMI specification for more details. + +Example +------- + +Obtain basic information about SCMI server: + +:: + + => scmi info + SCMI device: scmi + protocol version: 0x20000 + # of agents: 3 + 0: platform + > 1: OSPM + 2: PSCI + # of protocols: 4 + Power domain management + Performance domain management + Clock management + Sensor management + vendor: Linaro + sub vendor: PMWG + impl version: 0x20b0000 + +Ask for access permission to device#0: + +:: + + => scmi perm_dev 1 0 1 + +Reset configurations with all access permission settings retained: + +:: + + => scmi reset 1 0 + +Configuration +------------- + +The scmi command is only available if CONFIG_CMD_SCMI=y. +Default n because this command is mainly for debug purpose. + +Return value +------------ + +The return value ($?) is set to 0 if the operation succeeded, +1 if the operation failed or -1 if the operation failed due to +a syntax error. + +.. _`SCMI specification`: https://developer.arm.com/documentation/den0056/e/?lang=en diff --git a/doc/usage/cmd/scp03.rst b/doc/usage/cmd/scp03.rst new file mode 100644 index 00000000000..5fdddb3e813 --- /dev/null +++ b/doc/usage/cmd/scp03.rst @@ -0,0 +1,36 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: scp03 (command) + +scp03 command +============= + +Synopsis +-------- + +:: + + scp03 enable + scp03 provision + +Description +----------- + +The *scp03* command calls into a Trusted Application executing in a +Trusted Execution Environment to enable (if present) the Secure +Channel Protocol 03 stablished between the processor and the secure +element. + +This protocol encrypts all the communication between the processor and +the secure element using a set of pre-defined keys. These keys can be +rotated (provisioned) using the *provision* request. + +See also +-------- + +For some information on the internals implemented in the TEE, please +check the GlobalPlatform documentation on `Secure Channel Protocol '03'`_ + +.. _Secure Channel Protocol '03': + https://globalplatform.org/wp-content/uploads/2014/07/GPC_2.3_D_SCP03_v1.1.2_PublicRelease.pdf diff --git a/doc/usage/cmd/seama.rst b/doc/usage/cmd/seama.rst new file mode 100644 index 00000000000..17fd559f485 --- /dev/null +++ b/doc/usage/cmd/seama.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: seama (command) + +seama command +============= + +Synopsis +-------- + +:: + + seama <dst_addr> <index> + +Description +----------- + +The seama command is used to load and decode SEAttle iMAges from NAND +flash to memory. + +This type of flash image is found in some D-Link routers such as +DIR-645, DIR-842, DIR-859, DIR-860L, DIR-885L, DIR890L and DCH-M225, +as well as in WD and NEC routers on the ath79 (MIPS), Broadcom +BCM53xx, and RAMIPS platforms. + +This U-Boot command will read and decode a SEAMA image from raw NAND +flash on any platform. As it is always using big endian format for +the data decoding is always necessary on platforms such as ARM. + +dst_addr + destination address of the byte stream to be loaded + +index + the image index (0, 1, 2..) can be omitted + +Example +------- + +:: + + => seama 0x01000000 + Loading SEAMA image 0 from nand0 + SEMA IMAGE: + metadata size 36 + image size 8781764 + checksum 054859cfb1487b59befda98824e09dd6 + Decoding SEAMA image 0x01000040..0x01860004 to 0x01000000 + + +Configuration +------------- + +The command is available if CONFIG_CMD_SEAMA=y. + +Return value +------------ + +The return value $? is set 0 (true) if the loading is succefull, and +is set to 1 (false) in case of error. + +The environment variable $seama_image_size is set to the size of the +loaded SEAMA image. diff --git a/doc/usage/cmd/setexpr.rst b/doc/usage/cmd/setexpr.rst new file mode 100644 index 00000000000..593a0ea91e1 --- /dev/null +++ b/doc/usage/cmd/setexpr.rst @@ -0,0 +1,155 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: setexpr (command) + +setexpr command +=============== + +Synopsis +-------- + +:: + + setexpr[.b, .w, .l .s] <name> [*]<value> <op> [*]<value2> + setexpr[.b, .w, .l] <name> [*]<value> + setexpr <name> fmt <format> [value]... + setexpr <name> gsub r s [t] + setexpr <name> sub r s [t] + +Description +----------- + +The setexpr command is used to set an environment variable to the result +of an evaluation. + +setexpr[.b, .w, .l .s] <name> [*]<value> <op> [*]<value2> + Set environment variable <name> to the result of the evaluated + expression specified by <op>. + +setexpr[.b, .w, .l] name [*]value + Load <value> into environment variable <name> + +setexpr name fmt <format> value + Set environment variable <name> to the result of the C like + format string <format> evaluation of <value>. + +setexpr name gsub <r> <s> [<t>] + For each substring matching the regular expression <r> in the + string <t>, substitute the string <s>. + The result is assigned to <name>. + If <t> is not supplied, use the old value of <name>. + If no substring matching <r> is found in <t>, assign <t> to <name>. + +setexpr name sub <r> <s> [<t>] + Just like gsub(), but replace only the first matching substring + +The setexpr command takes the following arguments: + +format + This parameter contains a C or Bash like format string. + The number of arguments is limited to 4. + The following format types are supported: + + c + single character + d, i + decimal value + o + octal value + s + string + u + unsigned decimal value + x, X + hexadecimal value + '%' + no conversion, instead a % character will be written + + Backslash escapes: + + \" = double quote + \\ = backslash + \a = alert (bell) + \b = backspace + \c = produce no further output + \f = form feed + \n = new line + \r = carriage return + \t = horizontal tab + \v = vertical tab + \NNN = octal number (NNN is 0 to 3 digits) + +name + The name of the environment variable to be set + +op + '|' + name = value | value2 + '&' + name = value & value2 + '+' + name = value + value2 + (This is the only operator supported for strings. + It acts as concatenation operator on strings) + '^' + name = value ^ value2 + '-' + name = value - value2 + '*' + name = value * value2 + '/' + name = value / value2 + '%' + name = value % value2 + +r + Regular expression + +s + Substitution string + +t + string + +value + Can either be an integer value, a string. + If the pointer prefix '*' is given value is treated as memory address. + +value2 + See value + +Example +------- + +:: + + => setexpr foo fmt %d 0x100 + => echo $foo + 256 + => + + => setexpr foo fmt 0x%08x 63 + => echo $foo + 0x00000063 + => + + => setexpr foo fmt %%%o 8 + => echo $foo + %10 + => + +Configuration +------------- + +* The *setexpr* command is only available if CMD_SETEXPR=y. +* The *setexpr fmt* sub-command is only available if CMD_SETEXPR_FMT=y. +* The *setexpr gsub* and *setexpr sub* sub-commands are only available if + CONFIG_REGEX=y. + +Return value +------------ + +The return value $? is set to 0 (true) if the operation was successful. + +If an error occurs, the return value $? is set to 1 (false). diff --git a/doc/usage/cmd/sf.rst b/doc/usage/cmd/sf.rst new file mode 100644 index 00000000000..dfdca46e66c --- /dev/null +++ b/doc/usage/cmd/sf.rst @@ -0,0 +1,248 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: sf (command) + +sf command +========== + +Synopsis +-------- + +:: + + sf probe [[[<bus>:]<cs>] [<hz> [<mode>]]] + sf read <addr> <offset>|<partition> <len> + sf write <addr> <offset>|<partition> <len> + sf erase <offset>|<partition> <len> + sf update <addr> <offset>|<partition> <len> + sf protect lock|unlock <sector> <len> + sf test <offset>|<partition> <len> + +Description +----------- + +The *sf* command is used to access SPI flash, supporting read/write/erase and +a few other functions. + +Probe +----- + +The flash must first be probed with *sf probe* before any of the other +subcommands can be used. All of the parameters are optional: + +bus + SPI bus number containing the SPI-flash chip, e.g. 0. If you don't know + the number, you can use 'dm uclass' to see all the spi devices, + and check the value for 'seq' for each one (here 0 and 2):: + + uclass 89: spi + 0 spi@0 @ 05484960, seq 0 + 1 spi@1 @ 05484b40, seq 2 + +cs + SPI chip-select to use for the chip. This is often 0 and can be omitted, + but in some cases multiple slaves are attached to a SPI controller, + selected by a chip-select line for each one. + +hz + Speed of the SPI bus in hertz. This normally defaults to 100000, i.e. + 100KHz, which is very slow. Note that if the device exists in the + device tree, there might be a speed provided there, in which case this + setting is ignored. + +mode + SPI mode to use: + + ===== ================ + Mode Meaning + ===== ================ + 0 CPOL=0, CPHA=0 + 1 CPOL=0, CPHA=1 + 2 CPOL=1, CPHA=0 + 3 CPOL=1, CPHA=1 + ===== ================ + + Clock phase (CPHA) 0 means that data is transferred (sampled) on the + first clock edge; 1 means the second. + + Clock polarity (CPOL) controls the idle state of the clock, 0 for low, + 1 for high. + The active state is the opposite of idle. + + You may find this `SPI documentation`_ useful. + +Parameters for other subcommands (described below) are as follows: + +addr + Memory address to start transfer + +offset + Flash offset to start transfer + +partition + If the parameter is not numeric, it is assumed to be a partition + description in the format <dev_type><dev_num>,<part_num> which is not + covered here. This requires CONFIG_CMD_MTDPARTS. + +len + Number of bytes to transfer + +Read +~~~~ + +Use *sf read* to read from SPI flash to memory. The read will fail if an +attempt is made to read past the end of the flash. + + +Write +~~~~~ + +Use *sf write* to write from memory to SPI flash. The SPI flash should be +erased first, since otherwise the result is undefined. + +The write will fail if an attempt is made to read past the end of the flash. + + +Erase +~~~~~ + +Use *sf erase* to erase a region of SPI flash. The erase will fail if any part +of the region to be erased is protected or lies past the end of the flash. It +may also fail if the start offset or length are not aligned to an erase region +(e.g. 256 bytes). + + +Update +~~~~~~ + +Use *sf update* to automatically erase and update a region of SPI flash from +memory. This works a sector at a time (typical 4KB or 64KB). For each +sector it first checks if the sector already has the right data. If so it is +skipped. If not, the sector is erased and the new data written. Note that if +the length is not a multiple of the erase size, the space after the data in +the last sector will be erased. If the offset does not start at the beginning +of an erase block, the operation will fail. + +Speed statistics are shown including the number of bytes that were already +correct. + + +Protect +~~~~~~~ + +SPI-flash chips often have a protection feature where the chip is split up into +regions which can be locked or unlocked. With *sf protect* it is possible to +change these settings, if supported by the driver. + +lock|unlock + Selects whether to lock or unlock the sectors + +<sector> + Start sector number to lock/unlock. This may be the byte offset or some + other value, depending on the chip. + +<len> + Number of bytes to lock/unlock + + +Test +~~~~ + +A convenient and fast *sf test* subcommand provides a way to check that SPI +flash is working as expected. This works in four stages: + + * erase - erases the entire region + * check - checks that the region is erased + * write - writes a test pattern to the region, consisting of the U-Boot code + * read - reads back the test pattern to check that it was written correctly + +Memory is allocated for two buffers, each <len> bytes in size. At typical +size is 64KB to 1MB. The offset and size must be aligned to an erase boundary. + +Note that this test will fail if any part of the SPI flash is write-protected. + + +Examples +-------- + +This first example uses sandbox:: + + => sf probe + SF: Detected m25p16 with page size 256 Bytes, erase size 64 KiB, total 2 MiB + => sf read 1000 1100 80000 + device 0 offset 0x1100, size 0x80000 + SF: 524288 bytes @ 0x1100 Read: OK + => md 1000 + 00001000: edfe0dd0 f33a0000 78000000 84250000 ......:....x..%. + 00001010: 28000000 11000000 10000000 00000000 ...(............ + 00001020: 6f050000 0c250000 00000000 00000000 ...o..%......... + 00001030: 00000000 00000000 00000000 00000000 ................ + 00001040: 00000000 00000000 00000000 00000000 ................ + 00001050: 00000000 00000000 00000000 00000000 ................ + 00001060: 00000000 00000000 00000000 00000000 ................ + 00001070: 00000000 00000000 01000000 00000000 ................ + 00001080: 03000000 04000000 00000000 01000000 ................ + 00001090: 03000000 04000000 0f000000 01000000 ................ + 000010a0: 03000000 08000000 1b000000 646e6173 ............sand + 000010b0: 00786f62 03000000 08000000 21000000 box............! + 000010c0: 646e6173 00786f62 01000000 61696c61 sandbox.....alia + 000010d0: 00736573 03000000 07000000 2c000000 ses............, + 000010e0: 6332692f 00003040 03000000 07000000 /i2c@0.......... + 000010f0: 31000000 6963702f 00003040 03000000 ...1/pci@0...... + => sf erase 0 80000 + SF: 524288 bytes @ 0x0 Erased: OK + => sf read 1000 1100 80000 + device 0 offset 0x1100, size 0x80000 + SF: 524288 bytes @ 0x1100 Read: OK + => md 1000 + 00001000: ffffffff ffffffff ffffffff ffffffff ................ + 00001010: ffffffff ffffffff ffffffff ffffffff ................ + 00001020: ffffffff ffffffff ffffffff ffffffff ................ + 00001030: ffffffff ffffffff ffffffff ffffffff ................ + 00001040: ffffffff ffffffff ffffffff ffffffff ................ + 00001050: ffffffff ffffffff ffffffff ffffffff ................ + 00001060: ffffffff ffffffff ffffffff ffffffff ................ + 00001070: ffffffff ffffffff ffffffff ffffffff ................ + 00001080: ffffffff ffffffff ffffffff ffffffff ................ + 00001090: ffffffff ffffffff ffffffff ffffffff ................ + 000010a0: ffffffff ffffffff ffffffff ffffffff ................ + 000010b0: ffffffff ffffffff ffffffff ffffffff ................ + 000010c0: ffffffff ffffffff ffffffff ffffffff ................ + 000010d0: ffffffff ffffffff ffffffff ffffffff ................ + 000010e0: ffffffff ffffffff ffffffff ffffffff ................ + 000010f0: ffffffff ffffffff ffffffff ffffffff ................ + +This second example is running on coral, an x86 Chromebook:: + + => sf probe + SF: Detected w25q128fw with page size 256 Bytes, erase size 4 KiB, total 16 MiB + => sf erase 300000 80000 + SF: 524288 bytes @ 0x300000 Erased: OK + => sf update 1110000 300000 80000 + device 0 offset 0x300000, size 0x80000 + 524288 bytes written, 0 bytes skipped in 0.457s, speed 1164578 B/s + + # This does nothing as the flash is already updated + => sf update 1110000 300000 80000 + device 0 offset 0x300000, size 0x80000 + 0 bytes written, 524288 bytes skipped in 0.196s, speed 2684354 B/s + => sf test 00000 80000 # try a protected region + SPI flash test: + Erase failed (err = -5) + Test failed + => sf test 800000 80000 + SPI flash test: + 0 erase: 18 ticks, 28444 KiB/s 227.552 Mbps + 1 check: 192 ticks, 2666 KiB/s 21.328 Mbps + 2 write: 227 ticks, 2255 KiB/s 18.040 Mbps + 3 read: 189 ticks, 2708 KiB/s 21.664 Mbps + Test passed + 0 erase: 18 ticks, 28444 KiB/s 227.552 Mbps + 1 check: 192 ticks, 2666 KiB/s 21.328 Mbps + 2 write: 227 ticks, 2255 KiB/s 18.040 Mbps + 3 read: 189 ticks, 2708 KiB/s 21.664 Mbps + + +.. _SPI documentation: + https://en.wikipedia.org/wiki/Serial_Peripheral_Interface diff --git a/doc/usage/cmd/size.rst b/doc/usage/cmd/size.rst new file mode 100644 index 00000000000..306fcba0ba4 --- /dev/null +++ b/doc/usage/cmd/size.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: size (command) + +size command +============ + +Synopsis +-------- + +:: + + size <interface> <dev[:part]> <filename> + +Description +----------- + +The size command determines the size of a file and sets the environment variable +filesize to this value. If filename points to a directory, the value is set to +zero. + +If the command fails, the filesize environment variable is not changed. + +dev + device number + +part + partition number, defaults to 1 + +filename + path to file + +Configuration +------------- + +The size command is only available if CONFIG_CMD_FS_GENERIC=y. + +Return value +------------ + +The return value $? is set to 0 (true) if the command succeded and to 1 (false) +otherwise. diff --git a/doc/usage/cmd/sleep.rst b/doc/usage/cmd/sleep.rst new file mode 100644 index 00000000000..a372e4da0e1 --- /dev/null +++ b/doc/usage/cmd/sleep.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2023, Heinrich Schuchardt <heinrich.schuchardt@canonical.com> + +.. index:: + single: sleep (command) + +sleep command +============= + +Synopsis +-------- + +:: + + sleep <delay> + +Description +----------- + +The *sleep* command waits for *delay* seconds. It can be interrupted by +CTRL+C. + +delay + delay in seconds. The value is decimal and can be fractional. + +Example +------- + +The current data and time is display before and after sleeping for 3.2 +seconds: + +:: + + => date; sleep 3.2; date + Date: 2023-01-21 (Saturday) Time: 16:02:41 + Date: 2023-01-21 (Saturday) Time: 16:02:44 + => + +Configuration +------------- + +The command is only available if CONFIG_CMD_SLEEP=y. + +Return value +------------ + +The return value $? is 0 (true) if the command completes. +The return value is 1 (false) if the command is interrupted by CTRL+C. diff --git a/doc/usage/cmd/sm.rst b/doc/usage/cmd/sm.rst new file mode 100644 index 00000000000..e828fddc519 --- /dev/null +++ b/doc/usage/cmd/sm.rst @@ -0,0 +1,51 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: sm (command) + +sm command +========== + +Synopsis +-------- + +:: + + sm serial <address> + sm reboot_reason [name] + sm efuseread <offset> <size> <address> + sm efusewrite <offset> <size> <address> + sm efusedump <offset> <size> + +Description +----------- + +The sm command is used to request services from the secure monitor. User +can call secure monitor to request special TEE function, for example chip +serial number info, reboot reason, etc. + +sm serial + Retrieve chip unique serial number from sm and write it to memory on + appropriate address. + +sm reboot_reason + Print reboot reason to the console, if parameter [name] isn't specified. + If parameter specified, set reboot reason string to environment variable + with this name. + +sm efuseread + Read <size> bytes starting from <offset> from efuse memory bank and write + result to the address <address>. + +sm efusewrite + Write into efuse memory bank, starting from <offset>, the <size> bytes + of data, located at address <address>. + +sm efusedump + Read <size> bytes starting from <offset> from efuse memory bank and print + them to the console. + +Configuration +------------- + +To use the sm command you must specify CONFIG_CMD_MESON=y diff --git a/doc/usage/cmd/smbios.rst b/doc/usage/cmd/smbios.rst new file mode 100644 index 00000000000..1ffd706d7de --- /dev/null +++ b/doc/usage/cmd/smbios.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later: + +smbios command +============== + +Synopsis +-------- + +:: + + smbios + +Description +----------- + +The smbios command displays information from the SMBIOS tables. + +Examples +-------- + +The example below shows an example output of the smbios command. + +:: + + => smbios + SMBIOS 2.8.0 present. + 8 structures occupying 81 bytes + Table at 0x6d35018 + + Handle 0x0100, DMI type 1, 27 bytes at 0x6d35018 + System Information + Manufacturer: QEMU + Product Name: Standard PC (i440FX + PIIX, 1996) + Version: pc-i440fx-2.5 + Serial Number: + UUID 00000000-0000-0000-0000-000000000000 + Wake Up Type: + Serial Number: + SKU Number: + + Handle 0x0300, DMI type 3, 22 bytes at 0x6d35069 + Header and Data: + 00000000: 03 16 00 03 01 01 02 00 00 03 03 03 02 00 00 00 + 00000010: 00 00 00 00 00 00 + Strings: + String 1: QEMU + String 2: pc-i440fx-2.5 + + Handle 0x0400, DMI type 4, 42 bytes at 0x6d35093 + Header and Data: + 00000000: 04 2a 00 04 01 03 01 02 63 06 00 00 fd ab 81 07 + 00000010: 03 00 00 00 d0 07 d0 07 41 01 ff ff ff ff ff ff + 00000020: 00 00 00 01 01 01 02 00 01 00 + Strings: + String 1: CPU 0 + String 2: QEMU + String 3: pc-i440fx-2.5 + + Handle 0x1000, DMI type 16, 23 bytes at 0x6d350d7 + Header and Data: + 00000000: 10 17 00 10 01 03 06 00 00 02 00 fe ff 01 00 00 + 00000010: 00 00 00 00 00 00 00 + + Handle 0x1100, DMI type 17, 40 bytes at 0x6d350f0 + Header and Data: + 00000000: 11 28 00 11 00 10 fe ff ff ff ff ff 80 00 09 00 + 00000010: 01 00 07 02 00 00 00 02 00 00 00 00 00 00 00 00 + 00000020: 00 00 00 00 00 00 00 00 + Strings: + String 1: DIMM 0 + String 2: QEMU + + Handle 0x1300, DMI type 19, 31 bytes at 0x6d35125 + Header and Data: + 00000000: 13 1f 00 13 00 00 00 00 ff ff 01 00 00 10 01 00 + 00000010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 + + Handle 0x2000, DMI type 32, 11 bytes at 0x6d35146 + Header and Data: + 00000000: 20 0b 00 20 00 00 00 00 00 00 00 + + Handle 0x7f00, DMI type 127, 4 bytes at 0x6d35153 + End Of Table + +Configuration +------------- + +The command is only available if CONFIG_CMD_SMBIOS=y. + +Return value +------------ + +The return value $? is 0 (true) on success, 1 (false) otherwise. diff --git a/doc/usage/cmd/sound.rst b/doc/usage/cmd/sound.rst new file mode 100644 index 00000000000..97d610f3745 --- /dev/null +++ b/doc/usage/cmd/sound.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2022, Heinrich Schuchardt <xypron.glpk@gmx.de> + +.. index:: + single: sound (command) + +sound command +============= + +Synopsis +-------- + +:: + + sound init + sound play [[len freq] ...] [len [freq]] + +Description +----------- + +The *sound* command is used to play one or multiple beep sounds. + +sound init + initializes the sound driver. + +sound play + plays a square wave sound. It does not depend on previously calling + *sound init*. + +len + duration of the sound in ms, defaults to 1000 ms + +freq + frequency of the sound in Hz, defaults to 400 Hz + +Examples +-------- + +Beep at 400 Hz for 1000 ms:: + + sound play + +Beep at 400 Hz for 600 ms:: + + sound play 600 + +Beep at 500 Hz for 600 ms:: + + sound play 600 500 + +Play melody:: + + sound play 500 1047 500 880 500 0 500 1047 500 880 500 0 500 784 500 698 500 784 1000 698 + +Configuration +------------- + +The sound command is enabled by CONFIG_CMD_SOUND=y. + +Return value +------------ + +The return value $? is 0 (true) if the command succeeds, 1 (false) otherwise. diff --git a/doc/usage/cmd/source.rst b/doc/usage/cmd/source.rst new file mode 100644 index 00000000000..0de5f33390e --- /dev/null +++ b/doc/usage/cmd/source.rst @@ -0,0 +1,196 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2022, Heinrich Schuchardt <xypron.glpk@gmx.de> + +.. index:: + single: source (command) + +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 +described in :doc:`../fit/signature`. + +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/cmd/temperature.rst b/doc/usage/cmd/temperature.rst new file mode 100644 index 00000000000..945bc8204ac --- /dev/null +++ b/doc/usage/cmd/temperature.rst @@ -0,0 +1,53 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +.. index:: + single: temperature (command) + +temperature command +=================== + +Synopsis +-------- + +:: + + temperature list + temperature get [thermal device name] + +Description +----------- + +The *temperature* command is used to list thermal sensors and get their +readings. + +The 'temperature list' command diplays the available thermal devices. + +The 'temperature get' command is used to get the reading in degrees C from +the desired device which is selected by passing its device name. + + thermal device name + device name of thermal sensor to select + +Example +------- + +:: + + + => temperature list + | Device | Driver | Parent + | tmon@610508110 | sparx5-temp | axi@600000000 + => + => temperature get tmon@610508110 + tmon@610508110: 42 C + +Configuration +------------- + +The *temperature* command is only available if CONFIG_CMD_TEMPERATURE=y. + +Return value +------------ + +The return value $? is set to 0 (true) if the command succeeded and to 1 (false) +otherwise. diff --git a/doc/usage/cmd/tftpput.rst b/doc/usage/cmd/tftpput.rst new file mode 100644 index 00000000000..351c9faa38b --- /dev/null +++ b/doc/usage/cmd/tftpput.rst @@ -0,0 +1,90 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: tftpput (command) + +tftpput command +=============== + +Synopsis +-------- + +:: + + tftpput address size [[hostIPaddr:]filename] + +Description +----------- + +The tftpput command is used to transfer a file to a TFTP server. + +By default the destination port is 69 and the source port is pseudo-random. +If CONFIG_TFTP_PORT=y, the environment variable *tftpsrcp* can be used to set +the source port and the environment variable *tftpdstp* can be used to set +the destination port. + +address + memory address where the data starts + +size + number of bytes to be transferred + +hostIPaddr + IP address of the TFTP server, defaults to the value of environment + variable *serverip* + +filename + path of the file to be written. If not provided, the client's IP address is + used to construct a default file name, e.g. C0.A8.00.28.img for IP address + 192.168.0.40. + +Example +------- + +In the example the following steps are executed: + +* setup client network address +* load a file from the SD-card +* send the file via TFTP to a server + +:: + + => setenv autoload no + => dhcp + BOOTP broadcast 1 + DHCP client bound to address 192.168.1.40 (7 ms) + => load mmc 0:1 $loadaddr test.txt + 260096 bytes read in 13 ms (19.1 MiB/s) + => tftpput $loadaddr $filesize 192.168.1.3:upload/test.txt + Using ethernet@1c30000 device + TFTP to server 192.168.1.3; our IP address is 192.168.1.40 + Filename 'upload/test.txt'. + Save address: 0x42000000 + Save size: 0x3f800 + Saving: ################# + 4.4 MiB/s + done + Bytes transferred = 260096 (3f800 hex) + => + +Configuration +------------- + +The command is only available if CONFIG_CMD_TFTPPUT=y. + +CONFIG_TFTP_BLOCKSIZE defines the size of the TFTP blocks sent. It defaults +to 1468 matching an ethernet MTU of 1500. + +If CONFIG_TFTP_PORT=y, the environment variables *tftpsrcp* and *tftpdstp* can +be used to set the source and the destination ports. + +CONFIG_TFTP_WINDOWSIZE can be used to set the TFTP window size of transmits +after which an ACK response is required. The window size defaults to 1. + +If CONFIG_TFTP_TSIZE=y, the progress bar is limited to 50 '#' characters. +Otherwise an '#' is written per UDP package which may decrease performance. + +Return value +------------ + +The return value $? is 0 (true) on success and 1 (false) otherwise. diff --git a/doc/usage/cmd/trace.rst b/doc/usage/cmd/trace.rst new file mode 100644 index 00000000000..e798b2bbc6b --- /dev/null +++ b/doc/usage/cmd/trace.rst @@ -0,0 +1,166 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: trace (command) + +trace command +============= + +Synopsis +-------- + +:: + + trace stats + trace pause + trace resume + trace funclist [<addr> <size>] + trace calls [<addr> <size>] + +Description +----------- + +The *trace* command is used to control the U-Boot tracing system. It allows +tracing to be paused and resumed, shows statistics for traces and provides a +way to dump out the trace information. + + +trace stats +~~~~~~~~~~~ + +This display tracing statistics, as follows: + +function sites + Functions are binned as a way of reducing the amount of space needed to + hold all the function information. This is controlled by FUNC_SITE_SIZE in + the trace.h header file. The usual value is 4, which provides the finest + granularity (assuming a minimum instruction size of 4 bytes) which means + that every function can be resolved individually. + +function calls + Total number of function calls, including those which were not traced due + to buffer space. This count does not include functions which exceeded the + depth limit. + +untracked function calls + Total number of function calls which did not appear in the U-Boot image. + This can happen if a function is called outside the normal code area. + +traced function calls + Total number of function calls which were actually traced, i.e. are included + in the recorded trace data. + +dropped due to overflow + If the trace buffer was exhausted then this shows the number of records that + were dropped. Try reducing the depth limit or expanding the buffer size. + +maximum observed call depth + Maximum observed call depth while tracing. + +calls not traced due to depth + Counts the number of function calls that were not recorded because they + exceeded the maximum call depth. + +max function calls + Maximum number of function calls which can be recorded in the trace buffer, + given its size. Once `function calls` hits this value, recording stops. + +trace buffer + Address of trace buffer + +call records + Address of first trace record. This is near the start of the trace buffer, + after the function-call counts. + + +trace pause +~~~~~~~~~~~ + +Pauses tracing, so that no more data is added to the trace buffer. + + +trace resume +~~~~~~~~~~~~ + +Resumes tracing, so that new function calls are added to the trace buffer if +there is sufficient space. + + +trace funclist [<addr> <size>] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Dumps a list of functions into the provided buffer. The file uses a format +specific to U-Boot: a header, following by the function offset and call count. + +If the address and size are not given, these are obtained from +:ref:`develop/trace:environment variables`. In any case the environment +variables are updated after the command runs. + +The resulting data should be written out to the host, e.g. using Ethernet or +a filesystem. There are no tools provided to read this sdata. + + +trace calls [<addr> <size>] +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Dumps a list of function calls into the provided buffer. The file uses a format +specific to U-Boot: a header, following by the list of calls. The proftool +tool can be used to convert this information ready for further analysis. + + +Example +------- + +:: + + => trace stats + 269,252 function sites + 38,025,059 function calls + 3 untracked function calls + 7,382,690 traced function calls + 17 maximum observed call depth + 15 call depth limit + 68,667,432 calls not traced due to depth + 22,190,112 max function calls + + trace buffer 6c000000 call records 6c20de78 + => trace resume + => trace pause + +This shows that resuming the trace causes the buffer to overflow:: + + => trace stats + 269,252 function sites + 49,573,694 function calls + 3 untracked function calls + 22,190,112 traced function calls (8289848 dropped due to overflow) + 17 maximum observed call depth + 15 call depth limit + 68,667,432 calls not traced due to depth + 22,190,112 max function calls + + trace buffer 6c000000 call records 6c20de78 + => trace funcs 30000000 0x100000 + Function trace dumped to 30000000, size 0x1e70 + +This shows collecting and writing out the result trace data: + +:: + => trace calls 20000000 0x10000000 + Call list dumped to 20000000, size 0xfdf21a0 + => save mmc 1:1 20000000 /trace ${profoffset} + File System is consistent + file found, deleting + update journal finished + File System is consistent + update journal finished + 266281376 bytes written in 18584 ms (13.7 MiB/s) + +From here you can use proftool to convert it: + +.. code-block:: bash + + tools/proftool -m System.map -t trace -o asc.fg dump-ftrace + + +.. _`ACPI specification`: https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf diff --git a/doc/usage/cmd/true.rst b/doc/usage/cmd/true.rst new file mode 100644 index 00000000000..adf641386b5 --- /dev/null +++ b/doc/usage/cmd/true.rst @@ -0,0 +1,31 @@ +.. index:: + single: true (command) + +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. diff --git a/doc/usage/cmd/ums.rst b/doc/usage/cmd/ums.rst new file mode 100644 index 00000000000..9d379e3c829 --- /dev/null +++ b/doc/usage/cmd/ums.rst @@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: ums (command) + +ums command +=========== + +Synopsis +-------- + +:: + + ums <dev> [<interface>] <devnum[:partnum]> + +Description +----------- + +Use the USB Mass Storage class (also known as UMS) to make accessible an U-Boot +block device (fully or with :ref:`U-Boot's partition syntax <partitions>`) +to a USB host and to enable file transfers. U-Boot, the USB device, acts as a +simple external hard drive plugged on the host USB port. + +This command "ums" stays in the USB's treatment loop until user enters Ctrl-C. + +dev + USB gadget device number + +interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + defaults is "mmc" + +devnum + device number for selected interface + +partnum + partition number or 0 to expose all partitions, defaults to 0 + +Example +------- + +:: + + => ums 0 mmc 0 + => ums 0 usb 1:2 + +Configuration +------------- + +The ums command is only available if CONFIG_CMD_USB_MASS_STORAGE=y +and depends on CONFIG_USB_USB_GADGET and CONFIG_BLK. + +Return value +------------ + +The return value $? is set to 0 (true) when the USB stack was successfully +started and interrupted, with Ctrl-C or after USB cable issue (detection +timeout or cable removal). + +If an error occurs, the return value $? is set to 1 (false). diff --git a/doc/usage/cmd/unbind.rst b/doc/usage/cmd/unbind.rst new file mode 100644 index 00000000000..0309e90f6ea --- /dev/null +++ b/doc/usage/cmd/unbind.rst @@ -0,0 +1,98 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: unbind (command) + +unbind command +============== + +Synopsis +-------- + +:: + + unbind <node path> + unbind <class> <index> + unbind <class> <index> <driver> + +Description +----------- + +The unbind command is used to unbind a device from a driver. This makes the +device unavailable in U-Boot. + +node path + path of the device's device-tree node + +class + device class name + +index + index of the device in the device class + +driver + device driver name + +Example +------- + +Given a system with a real time clock device with device path */pl031@9010000* +and using driver rtc-pl031 unbinding and binding of the device is demonstrated +using the three alternative unbind syntaxes. + +.. code-block:: + + => dm tree + Class Index Probed Driver Name + ----------------------------------------------------------- + root 0 [ + ] root_driver root_driver + ... + rtc 0 [ ] rtc-pl031 |-- pl031@9010000 + ... + => fdt addr $fdtcontroladdr + Working FDT set to 7ed7fdb0 + => fdt print + / { + interrupt-parent = <0x00008003>; + model = "linux,dummy-virt"; + #size-cells = <0x00000002>; + #address-cells = <0x00000002>; + compatible = "linux,dummy-virt"; + ... + pl031@9010000 { + clock-names = "apb_pclk"; + clocks = <0x00008000>; + interrupts = <0x00000000 0x00000002 0x00000004>; + reg = <0x00000000 0x09010000 0x00000000 0x00001000>; + compatible = "arm,pl031", "arm,primecell"; + }; + ... + } + => unbind /pl031@9010000 + => dm tree + Class Index Probed Driver Name + ----------------------------------------------------------- + root 0 [ + ] root_driver root_driver + ... + => unbind /pl031@9010000 + Cannot find a device with path /pl031@9010000 + => bind /pl031@9010000 rtc-pl031 + => dm tree + Class Index Probed Driver Name + ----------------------------------------------------------- + root 0 [ + ] root_driver root_driver + ... + rtc 0 [ ] rtc-pl031 |-- pl031@9010000 + => unbind rtc 0 + => bind /pl031@9010000 rtc-pl031 + => unbind rtc 0 rtc-pl031 + +Configuration +------------- + +The unbind command is only available if CONFIG_CMD_BIND=y. + +Return code +----------- + +The return code $? is 0 (true) on success and 1 (false) on failure. diff --git a/doc/usage/cmd/ut.rst b/doc/usage/cmd/ut.rst new file mode 100644 index 00000000000..45bc9ffbdc5 --- /dev/null +++ b/doc/usage/cmd/ut.rst @@ -0,0 +1,120 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: ut (command) + +ut command +========== + +Synopsis +-------- + +:: + + ut [-r<runs>] [-f] [-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 + +Description +----------- + +The ut command runs unit tests written in C. + +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` by itself. + +Each test is normally run once, although those marked with `UT_TESTF_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. + +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 +fix this, select the 'one' test which breaks. Then tell the 'ut' command to +run this one test after a certain number of other tests have run. Using a +binary search method with `-I` you can quickly figure one which test is causing +the problem. + +Generally all tests in the suite are run. To run just a single test from the +suite, provide the <test> argument. + +See :ref:`develop/tests_writing:writing c tests` for more information on how to +write unit tests. + +Example +------- + +List available unit-test suites:: + + => ut + ut - unit tests + + Usage: + ut [-r] [-f] [<suite>] - run unit tests + -r<runs> Number of times to run each test + -f Force 'manual' tests to run as well + <suite> Test suite to run, or all + + Suites: + all - execute all enabled tests + addrmap - very basic test of addrmap command + bloblist - bloblist implementation + bootstd - standard boot implementation + compression - compressors and bootm decompression + dm - driver model + env - environment + fdt - fdt command + loadm - loadm command parameters and loading memory blob + lib - library functions + log - logging functions + mem - memory-related commands + overlay - device tree overlays + print - printing things to the console + setexpr - setexpr command + str - basic test of string functions + time - very basic test of time functions + unicode - Unicode functions + +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 + +Run just a single test in a suite:: + + => ut bloblist bloblist_test_grow + Test: bloblist_test_grow: bloblist.c + Failures: 0 + +Show information about tests:: + + => ut info + Test suites: 21 + Total tests: 642 diff --git a/doc/usage/cmd/wdt.rst b/doc/usage/cmd/wdt.rst new file mode 100644 index 00000000000..f48b8840907 --- /dev/null +++ b/doc/usage/cmd/wdt.rst @@ -0,0 +1,80 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: wdt (command) + +wdt command +=========== + +Synopsis +-------- + +:: + + wdt list + wdt dev [<name>] + wdt start <timeout_ms> [flags] + wdt stop + wdt reset + wdt expirer [flags] + +Description +----------- + +The wdt command is used to control watchdog timers. + +The 'wdt list' command shows a list of all watchdog devices. + +The 'wdt dev' command called without argument shows the current watchdog device. +The current device is set when passing the name of the device as argument. + +The 'wdt start' command starts the current watchdog timer. + +The 'wdt stop' command stops the current watchdog timer. + +The 'wdt reset' command resets the current watchdog timer without stopping it. + +The 'wdt expire' command let's the current watchdog timer expire immediately. +This will lead to a reset. + +name + name of the watchdog device + +timeout_ms + timeout interval in milliseconds + +flags + unsigned long value passed to the driver. The usage is driver specific. + The value is ignored by most drivers. + +Example +------- + +:: + + => wdt dev + No watchdog timer device set! + => wdt list + watchdog@1c20ca0 (sunxi_wdt) + => wdt dev watchdog@1c20ca0 + => wdt dev + dev: watchdog@1c20ca0 + => wdt start 3000 + => wdt reset + => wdt stop + => wdt expire + + U-Boot SPL 2022.04-rc3 (Mar 25 2022 - 13:48:33 +0000) + + In the example above '(sunxi_wdt)' refers to the driver for the watchdog + device. + +Configuration +------------- + +The command is only available if CONFIG_CMD_WDT=y. + +Return value +------------ + +The return value $? is 0 if the command succeeds, 1 upon failure. diff --git a/doc/usage/cmd/wget.rst b/doc/usage/cmd/wget.rst new file mode 100644 index 00000000000..b8ca35bb140 --- /dev/null +++ b/doc/usage/cmd/wget.rst @@ -0,0 +1,66 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: wget (command) + +wget command +============ + +Synopsis +-------- + +:: + + wget address [[hostIPaddr:]path] + +Description +----------- + +The wget command is used to download a file from an HTTP server. + +wget command will use HTTP over TCP to download files from an HTTP server. +By default the destination port is 80 and the source port is pseudo-random. +The environment variable *httpdstp* can be used to set the destination port. + +address + memory address for the data downloaded + +hostIPaddr + IP address of the HTTP server, defaults to the value of environment + variable *serverip* + +path + path of the file to be downloaded. + +Example +------- + +In the example the following steps are executed: + +* setup client network address +* download a file from the HTTP server + +:: + + => setenv autoload no + => dhcp + BOOTP broadcast 1 + *** Unhandled DHCP Option in OFFER/ACK: 23 + *** Unhandled DHCP Option in OFFER/ACK: 23 + DHCP client bound to address 192.168.1.105 (210 ms) + => wget ${loadaddr} 192.168.1.254:/index.html + HTTP/1.0 302 Found + Packets received 4, Transfer Successful + +Configuration +------------- + +The command is only available if CONFIG_CMD_WGET=y. + +TCP Selective Acknowledgments can be enabled via CONFIG_PROT_TCP_SACK=y. +This will improve the download speed. + +Return value +------------ + +The return value $? is 0 (true) on success and 1 (false) otherwise. diff --git a/doc/usage/cmd/write.rst b/doc/usage/cmd/write.rst new file mode 100644 index 00000000000..f42dc003dd4 --- /dev/null +++ b/doc/usage/cmd/write.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later: + +.. index:: + single: write (command) + +write command +============= + +See :doc:`read`. diff --git a/doc/usage/cmd/xxd.rst b/doc/usage/cmd/xxd.rst new file mode 100644 index 00000000000..f010a9dbb4d --- /dev/null +++ b/doc/usage/cmd/xxd.rst @@ -0,0 +1,53 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: xxd (command) + +xxd command +=========== + +Synopsis +-------- + +:: + + xxd <interface> <dev[:part]> <file> + +Description +----------- + +The xxd command prints the file content as hexdump to standard out. + +interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + +dev + device number + +part + partition number, defaults to 1 + +file + path to file + +Example +------- + +Here is the output for a example text file: + +:: + + => xxd mmc 0:1 hello + 00000000: 68 65 6c 6c 6f 20 77 6f 72 6c 64 0a 00 01 02 03 hello world..... + 00000010: 04 05 .. + => + +Configuration +------------- + +The xxd command is only available if CONFIG_CMD_XXD=y. + +Return value +------------ + +The return value $? is set to 0 (true) if the file is readable, otherwise it returns a non-zero error code. diff --git a/doc/usage/cmdline.rst b/doc/usage/cmdline.rst new file mode 100644 index 00000000000..58240c5279c --- /dev/null +++ b/doc/usage/cmdline.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Command-line Parsing +==================== + +The command line is available in U-Boot proper, enabled by CONFIG_CMDLINE which +is on by default. It is not enabled in SPL. + +There are two different command-line parsers available with U-Boot: +the old "simple" one, and the much more powerful "hush" shell: + +Simple command-line parser +-------------------------- + +This takes very little code space and offers only basic features: + +- supports environment variables (through :doc:`cmd/env`) +- several commands on one line, separated by ';' +- variable substitution using "... ${name} ..." syntax +- special characters ('$', ';') can be escaped by prefixing with '\', + for example:: + + setenv bootcmd bootm \${address} + +- You can also escape text by enclosing in single apostrophes, for example:: + + setenv addip 'setenv bootargs $bootargs ip=$ipaddr:$serverip:$gatewayip:$netmask:$hostname::off' + +Hush shell +---------- + +This is similar to Bourne shell, with control structures like: + +- `if`... `then` ... `else`... `fi` +- `for`... `do` ... `done` +- `while` ... `do` ... `done` +- `until` ... `do` ... `done` + +Hush supports environment ("global") variables (through setenv / saveenv +commands) and local shell variables (through standard shell syntax +`name=value`); only environment variables can be used with the "run" command + +The Hush shell is enabled with `CONFIG_HUSH_PARSER`. + +General rules +------------- + +#. If a command line (or an environment variable executed by a "run" + command) contains several commands separated by semicolon, and + one of these commands fails, then the remaining commands will be + executed anyway. + +#. If you execute several variables with one call to run (i. e. + calling run with a list of variables as arguments), any failing + command will cause "run" to terminate, i. e. the remaining + variables are not executed. + +Representing numbers +-------------------- + +Most U-Boot commands use hexadecimal (hex) as the default base, for convenient +use of addresses, for example:: + + => md 1000 6 + 00001000: 2c786f62 00697073 03000000 0c000000 box,spi......... + 00001010: 67020000 00000000 ...g.... + +There is no need to add a `0x` prefix to the arguments and the output is shown +in hex also, without any prefixes. This helps to avoid clutter. + +Some commands use decimal where it is more natural:: + + => i2c dev 0 + Setting bus to 0 + => i2c speed + Current bus speed=400000 + => i2c speed 100000 + Setting bus speed to 100000 Hz + +In some cases the default is decimal but it is possible to use octal if that is +useful:: + + pmic dev pmic@41 + dev: 1 @ pmic@41 + => pmic write 2 0177 + => pmic read 2 + 0x02: 0x00007f + +It is possible to use a `0x` prefix to use a hex value if that is more +convenient:: + + => i2c speed 0x30000 + Setting bus speed to 196608 Hz diff --git a/doc/usage/dfu.rst b/doc/usage/dfu.rst new file mode 100644 index 00000000000..8cc09c308d8 --- /dev/null +++ b/doc/usage/dfu.rst @@ -0,0 +1,432 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Device Firmware Upgrade (DFU) +============================= + +Overview +-------- + +Device Firmware Upgrade (DFU) enables the download and upload of firmware +to/from U-Boot while connected over USB. + +U-Boot follows the Universal Serial Bus Device Class Specification for +Device Firmware Upgrade Version 1.1 from the USB forum (DFU v1.1 in www.usb.org). + +U-Boot implements this DFU capability (CONFIG_DFU) with the command dfu +(cmd/dfu.c / CONFIG_CMD_DFU) based on: + +- the DFU stack (common/dfu.c and common/spl/spl_dfu.c), based on the + USB DFU download gadget (drivers/usb/gadget/f_dfu.c) +- The access to mediums is done in DFU backends (driver/dfu) + +Today the supported DFU backends are: + +- MMC (RAW or FAT / EXT2 / EXT3 / EXT4 file system / SKIP / SCRIPT) +- NAND +- RAM +- SF (serial flash) +- MTD (all MTD device: NAND, SPI-NOR, SPI-NAND,...) +- virtual + +These DFU backends are also used by + +- the dfutftp (see README.dfutftp) +- the thordown command (cmd/thordown.c and gadget/f_thor.c) + +The "virtual" backend is a generic DFU backend to support a board specific +target (for example OTP), only based on the weak functions: + +- dfu_write_medium_virt +- dfu_get_medium_size_virt +- dfu_read_medium_virt + +Configuration Options +--------------------- + +The following configuration options are relevant to device firmware upgrade: + +* CONFIG_DFU +* CONFIG_DFU_OVER_USB +* CONFIG_DFU_MMC +* CONFIG_DFU_MTD +* CONFIG_DFU_NAND +* CONFIG_DFU_RAM +* CONFIG_DFU_SF +* CONFIG_DFU_SF_PART +* CONFIG_DFU_TIMEOUT +* CONFIG_DFU_VIRTUAL +* CONFIG_CMD_DFU + +Environment variables +--------------------- + +The dfu command uses 3 environment variables: + +dfu_alt_info + The DFU setting for the USB download gadget with a semicolon separated + string of information on each alternate:: + + dfu_alt_info="<alt1>;<alt2>;....;<altN>" + + When several devices are used, the format is: + + - <interface> <dev>'='alternate list (';' separated) + - each interface is separated by '&':: + + dfu_alt_info=\ + "<interface1> <dev1>=<alt1>;....;<altN>&"\ + "<interface2> <dev2>=<altN+1>;....;<altM>&"\ + ...\ + "<interfaceI> <devI>=<altY+1>;....;<altZ>&" + +dfu_bufsiz + size of the DFU buffer, when absent, defaults to + CONFIG_SYS_DFU_DATA_BUF_SIZE (8 MiB by default) + +dfu_hash_algo + name of the hash algorithm to use + +Commands +-------- + +dfu <USB_controller> [<interface> <dev>] list + List the alternate device defined in *dfu_alt_info*. + +dfu <USB_controller> [<interface> <dev>] [<timeout>] + Start the dfu stack on the USB instance with the selected medium + backend and use the *dfu_alt_info* variable to configure the + alternate setting and link each one with the medium. + The dfu command continues until it receives a ^C in the console or + a DFU detach transaction from the HOST. If the CONFIG_DFU_TIMEOUT option + is enabled and a <timeout> parameter is present in the command line, + the DFU operation will be aborted automatically after <timeout> + seconds of waiting for the remote to initiate a DFU session. + +The possible values of <interface> are (with <USB controller> = 0 in the dfu +command example) + +mmc + for eMMC and SD card:: + + dfu 0 mmc <dev> + + each element in *dfu_alt_info* being + + * <name> raw <offset> <size> [mmcpart <num>] raw access to mmc device + * <name> part <dev> <part_id> [offset <byte>] raw access to partition + * <name> fat <dev> <part_id> file in FAT partition + * <name> ext4 <dev> <part_id> file in EXT4 partition + * <name> skip 0 0 ignore flashed data + * <name> script 0 0 execute commands in shell + + with + + offset + is the offset in the device (hexadecimal without "0x") + size + is the size of the access area (hexadecimal without "0x") + or 0 which means whole device + partid + being the GPT or DOS partition index, + num + being the eMMC hardware partition number. + + A value of environment variable *dfu_alt_info* for eMMC could be:: + + u-boot raw 0x3e 0x800 mmcpart 1;bl2 raw 0x1e 0x1d mmcpart 1 + + A value of environment variable *dfu_alt_info* for SD card could be:: + + u-boot raw 0x80 0x800;uImage ext4 0 2 + + If you don't want to flash the given image file to storage, use the "skip" + type entity. + + - It can be used to protect from flashing the wrong image for the specific board. + - Especially, this layout will be useful when the thor protocol is used, + which performs flashing in batch mode, where more than one file is + processed. + + For example, if one makes a single tar file with support for the two + boards with u-boot-<board1>.bin and u-boot-<board2>.bin files, one + can use it to flash a proper u-boot image on both without a failure:: + + u-boot-<board1>.bin raw 0x80 0x800; u-boot-<board2>.bin skip 0 0 + + When flashing a new system image requires you to do some more complex + things than just writing data to the storage medium, one can use 'script' + type. Data written to such an entity will be executed as a command list + in the u-boot's shell. This for example allows you to re-create a partition + layout and even set a new *dfu_alt_info* for the newly created partitions. + Such a script would look like:: + + setenv dfu_alt_info ... + setenv mbr_parts ... + mbr write ... + + Please note that this means the user will be able to execute any + arbitrary commands just like in the u-boot's shell. + +nand + raw slc nand device:: + + dfu 0 nand <dev> + + each element in *dfu_alt_info* being either of + + * <name> raw <offset> <size> raw access to nand device + * <name> part <dev_id> <part_id> raw access to partition + * <name> partubi <dev_id> <part_id> raw access to ubi partition + + with + + offset + is the offset in the nand device (hexadecimal without "0x") + size + is the size of the access area (hexadecimal without "0x") + dev_id + is the NAND device index (decimal only) + part_id + is the NAND partition index (decimal only) + +ram + raw access to ram:: + + dfu 0 ram <dev> + + dev + is not used for RAM target + + each element in *dfu_alt_info* being:: + + <name> ram <offset> <size> raw access to ram + + with + + offset + is the offset in the ram device (hexadecimal without "0x") + size + is the size of the access area (hexadecimal without "0x") + +sf + serial flash : NOR:: + + cmd: dfu 0 sf <dev> + + each element in *dfu_alt_info* being either of: + + * <name> raw <offset> <size> raw access to sf device + * <name> part <dev_id> <part_id> raw access to partition + * <name> partubi <dev_id> <part_id> raw access to ubi partition + + with + + offset + is the offset in the sf device (hexadecimal without "0x") + size + is the size of the access area (hexadecimal without "0x") + dev_id + is the sf device index (the device is "nor<dev_id>") (deximal only) + part_id + is the MTD partition index (decimal only) + +mtd + all MTD device: NAND, SPI-NOR, SPI-NAND,...:: + + cmd: dfu 0 mtd <dev> + + with + + dev + the mtd identifier as defined in mtd command + (nand0, nor0, spi-nand0,...) + + each element in *dfu_alt_info* being either of: + + * <name> raw <offset> <size> for raw access to mtd device + * <name> part <part_id> for raw access to partition + * <name> partubi <part_id> for raw access to ubi partition + + with + + offset + is the offset in the mtd device (hexadecimal without "0x") + size + is the size of the access area (hexadecimal without "0x") + part_id + is the MTD partition index (decimal only) + +virt + virtual flash back end for DFU + + :: + + cmd: dfu 0 virt <dev> + + each element in *dfu_alt_info* being: + + * <name> + +<interface> and <dev> are absent, the dfu command to use multiple devices:: + + cmd: dfu 0 list + cmd: dfu 0 + +*dfu_alt_info* variable provides the list of <interface> <dev> with +alternate list separated by '&' with the same format for each <alt>:: + + mmc <dev>=<alt1>;....;<altN> + nand <dev>=<alt1>;....;<altN> + ram <dev>=<alt1>;....;<altN> + sf <dev>=<alt1>;....;<altN> + mtd <dev>=<alt1>;....;<altN> + virt <dev>=<alt1>;....;<altN> + +Callbacks +--------- + +The weak callback functions can be implemented to manage specific behavior + +dfu_initiated_callback + called when the DFU transaction is started, used to initialize the device + +dfu_flush_callback + called at the end of the DFU write after DFU manifestation, used to manage + the device when the DFU transaction is closed + +Host tools +---------- + +When U-Boot runs the dfu stack, the DFU host tools can be used +to send/receive firmware images on each configured alternate. + +For example dfu-util is a host side implementation of the DFU 1.1 +specifications(http://dfu-util.sourceforge.net/) which works with U-Boot. + +Usage +----- + +Example 1: firmware located in eMMC or SD card, with: + +- alternate 1 (alt=1) for SPL partition (GPT partition 1) +- alternate 2 (alt=2) for U-Boot partition (GPT partition 2) + +The U-Boot configuration is:: + + U-Boot> env set dfu_alt_info "spl part 0 1;u-boot part 0 2" + + U-Boot> dfu 0 mmc 0 list + DFU alt settings list: + dev: eMMC alt: 0 name: spl layout: RAW_ADDR + dev: eMMC alt: 1 name: u-boot layout: RAW_ADDR + + Boot> dfu 0 mmc 0 + +On the Host side: + +list the available alternate setting:: + + $> dfu-util -l + dfu-util 0.9 + + Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. + Copyright 2010-2016 Tormod Volden and Stefan Schmidt + This program is Free Software and has ABSOLUTELY NO WARRANTY + Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ + + Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \ + alt=1, name="u-boot", serial="003A00203438510D36383238" + Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \ + alt=0, name="spl", serial="003A00203438510D36383238" + + To download to U-Boot, use -D option + + $> dfu-util -a 0 -D u-boot-spl.bin + $> dfu-util -a 1 -D u-boot.bin + + To upload from U-Boot, use -U option + + $> dfu-util -a 0 -U u-boot-spl.bin + $> dfu-util -a 1 -U u-boot.bin + + To request a DFU detach and reset the USB connection: + $> dfu-util -a 0 -e -R + + +Example 2: firmware located in NOR (sf) and NAND, with: + +- alternate 1 (alt=1) for SPL partition (NOR GPT partition 1) +- alternate 2 (alt=2) for U-Boot partition (NOR GPT partition 2) +- alternate 3 (alt=3) for U-Boot-env partition (NOR GPT partition 3) +- alternate 4 (alt=4) for UBI partition (NAND GPT partition 1) + +:: + + U-Boot> env set dfu_alt_info \ + "sf 0:0:10000000:0=spl part 0 1;u-boot part 0 2; \ + u-boot-env part 0 3&nand 0=UBI partubi 0,1" + + U-Boot> dfu 0 list + + DFU alt settings list: + dev: SF alt: 0 name: spl layout: RAW_ADDR + dev: SF alt: 1 name: ssbl layout: RAW_ADDR + dev: SF alt: 2 name: u-boot-env layout: RAW_ADDR + dev: NAND alt: 3 name: UBI layout: RAW_ADDR + + U-Boot> dfu 0 + +:: + + $> dfu-util -l + Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\ + intf=0, alt=3, name="UBI", serial="002700333338511934383330" + Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\ + intf=0, alt=2, name="u-boot-env", serial="002700333338511934383330" + Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\ + intf=0, alt=1, name="u-boot", serial="002700333338511934383330" + Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\ + intf=0, alt=0, name="spl", serial="002700333338511934383330" + +Same example with MTD backend + +:: + + U-Boot> env set dfu_alt_info \ + "mtd nor0=spl part 1;u-boot part 2;u-boot-env part 3&"\ + "mtd nand0=UBI partubi 1" + + U-Boot> dfu 0 list + using id 'nor0,0' + using id 'nor0,1' + using id 'nor0,2' + using id 'nand0,0' + DFU alt settings list: + dev: MTD alt: 0 name: spl layout: RAW_ADDR + dev: MTD alt: 1 name: u-boot layout: RAW_ADDR + dev: MTD alt: 2 name: u-boot-env layout: RAW_ADDR + dev: MTD alt: 3 name: UBI layout: RAW_ADDR + +Example 3 + +firmware located in SD Card (mmc) and virtual partition on OTP and PMIC +non-volatile memory + +- alternate 1 (alt=1) for scard +- alternate 2 (alt=2) for OTP (virtual) +- alternate 3 (alt=3) for PMIC NVM (virtual) + +:: + + U-Boot> env set dfu_alt_info \ + "mmc 0=sdcard raw 0 0x100000&"\ + "virt 0=otp" \ + "virt 1=pmic" + +:: + + U-Boot> dfu 0 list + DFU alt settings list: + dev: eMMC alt: 0 name: sdcard layout: RAW_ADDR + dev: VIRT alt: 1 name: otp layout: RAW_ADDR + dev: VIRT alt: 2 name: pmic layout: RAW_ADDR diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst new file mode 100644 index 00000000000..cc33d3ec0f2 --- /dev/null +++ b/doc/usage/environment.rst @@ -0,0 +1,562 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Environment Variables +===================== + +U-Boot supports user configuration using environment variables which +can be made persistent by saving to persistent storage, for example flash +memory. + +Environment variables are set using "env set" (alias "setenv"), printed using +"env print" (alias "printenv"), and saved to persistent storage using +"env save" (alias "saveenv"). Using "env set" +without a value can be used to delete a variable from the +environment. As long as you don't save the environment, you are +working with an in-memory copy. In case the Flash area containing the +environment is erased by accident, a default environment is provided. + +See :doc:`cmd/env` for details. + +Some configuration is controlled by Environment Variables, so that setting the +variable can adjust the behaviour of U-Boot (e.g. autoboot delay, autoloading +from tftp). + +Text-based Environment +---------------------- + +The default environment for a board is created using a `.env` environment file +using a simple text format. The base filename for this is defined by +`CONFIG_ENV_SOURCE_FILE`, or `CONFIG_SYS_BOARD` if that is empty. + +The file must be in the board directory and have a .env extension, so +assuming that there is a board vendor, the resulting filename is therefore:: + + board/<vendor>/<board>/<CONFIG_ENV_SOURCE_FILE>.env + +or:: + + board/<vendor>/<board>/<CONFIG_SYS_BOARD>.env + +This is a plain text file where you can type your environment variables in +the form `var=value`. Blank lines and multi-line variables are supported. +The conversion script looks for a line that starts in column 1 with a string +and has an equals sign immediately afterwards. Spaces before the = are not +permitted. It is a good idea to indent your scripts so that only the 'var=' +appears at the start of a line. + +To add additional text to a variable you can use `var+=value`. This text is +merged into the variable during the make process and made available as a +single value to U-Boot. Variables can contain `+` characters but in the unlikely +event that you want to have a variable name ending in plus, put a backslash +before the `+` so that the script knows you are not adding to an existing +variable but assigning to a new one:: + + maximum\+=value + +This file can include C-style comments. Blank lines and multi-line +variables are supported, and you can use normal C preprocessor directives +and CONFIG defines from your board config also. + +For example, for snapper9260 you would create a text file called +`board/bluewater/snapper9260.env` containing the environment text. + +Example:: + + stdout=serial + #ifdef CONFIG_VIDEO + stdout+=,vidconsole + #endif + bootcmd= + /* U-Boot script for booting */ + + if [ -z ${tftpserverip} ]; then + echo "Use 'setenv tftpserverip a.b.c.d' to set IP address." + fi + + usb start; setenv autoload n; bootp; + tftpboot ${tftpserverip}: + bootm + failed= + /* Print a message when boot fails */ + echo CONFIG_SYS_BOARD boot failed - please check your image + echo Load address is CONFIG_SYS_LOAD_ADDR + +Settings which are common to a group of boards can use #include to bring in +a common file in the `include/env` directory, containing environment +settings. For example:: + + #include <env/ti/mmc.env> + +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. + +Old-style C environment +----------------------- + +Traditionally, the default environment is created in `include/env_default.h`, +and can be augmented by various `CONFIG` defines. See that file for details. In +particular you can define `CFG_EXTRA_ENV_SETTINGS` in your board file +to add environment variables. + +Board maintainers are encouraged to migrate to the text-based environment as it +is easier to maintain. The distro-board script still requires the old-style +environments, so use :doc:`/develop/bootstd/index` instead. + + +List of environment variables +----------------------------- + +Some device configuration options can be set using environment variables. In +many cases the value in the default environment comes from a CONFIG option - see +`include/env_default.h`) for this. + +This is most-likely not complete: + +autostart + If set to "yes" (actually any string starting with 1, y, Y, t, or T) an + image loaded with one of the commands listed below will be automatically + started by internally invoking the bootm command. + + * bootelf - Boot from an ELF image in memory + * bootp - boot image via network using BOOTP/TFTP protocol + * dhcp - boot image via network using DHCP/TFTP protocol + * diskboot - boot from ide device + * nboot - boot from NAND device + * nfs - boot image via network using NFS protocol + * rarpboot - boot image via network using RARP/TFTP protocol + * scsiboot - boot from SCSI device + * tftpboot - boot image via network using TFTP protocol + * usbboot - boot from USB device + + If the environment variable autostart is not set to a value starting with + 1, y, Y, t, or T, an image passed to the "bootm" command will be copied to + the load address (and eventually uncompressed), but NOT be started. + This can be used to load and uncompress arbitrary data. + +baudrate + Used to set the baudrate of the UART - it defaults to CONFIG_BAUDRATE (which + defaults to 115200). + +bootdelay + Delay before automatically running bootcmd. During this time the user + can choose to enter the shell (or the boot menu if + CONFIG_AUTOBOOT_MENU_SHOW=y): + + - 0 to autoboot with no delay, but you can stop it by key input. + - -1 to disable autoboot. + - -2 to autoboot with no delay and not check for abort + + The default value is defined by CONFIG_BOOTDELAY. + The value of 'bootdelay' is overridden by the /config/bootdelay value in + the device-tree if CONFIG_OF_CONTROL=y. + +bootcmd + The command that is run if the user does not enter the shell during the + boot delay. + +bootargs + Command line arguments passed when booting an operating system or binary + image + +bootfile + Name of the image to load with TFTP + +bootm_low + Memory range available for image processing in the bootm + command can be restricted. This variable is given as + a hexadecimal number and defines lowest address allowed + for use by the bootm command. See also "bootm_size" + environment variable. Address defined by "bootm_low" is + also the base of the initial memory mapping for the Linux + kernel -- see the description of CFG_SYS_BOOTMAPSZ and + bootm_mapsize. + +bootm_mapsize + Size of the initial memory mapping for the Linux kernel. + This variable is given as a hexadecimal number and it + defines the size of the memory region starting at base + address bootm_low that is accessible by the Linux kernel + during early boot. If unset, CFG_SYS_BOOTMAPSZ is used + as the default value if it is defined, and bootm_size is + used otherwise. + +bootm_size + Memory range available for image processing in the bootm + command can be restricted. This variable is given as + a hexadecimal number and defines the size of the region + allowed for use by the bootm command. See also "bootm_low" + environment variable. + +bootstopkeysha256, bootdelaykey, bootstopkey + See README.autoboot + +button_cmd_0, button_cmd_0_name ... button_cmd_N, button_cmd_N_name + Used to map commands to run when a button is held during boot. + See CONFIG_BUTTON_CMD. + +updatefile + Location of the software update file on a TFTP server, used + by the automatic software update feature. Please refer to + documentation in doc/README.update for more details. + +autoload + if set to "no" (any string beginning with 'n'), + "bootp" and "dhcp" will just load perform a lookup of the + configuration from the BOOTP server, but not try to + load any image. + +fdt_high + if set this restricts the maximum address that the + flattened device tree will be copied into upon boot. + For example, if you have a system with 1 GB memory + at physical address 0x10000000, while Linux kernel + only recognizes the first 704 MB as low memory, you + may need to set fdt_high as 0x3C000000 to have the + device tree blob be copied to the maximum address + of the 704 MB low memory, so that Linux kernel can + access it during the boot procedure. + + If this is set to the special value 0xffffffff (32-bit machines) or + 0xffffffffffffffff (64-bit machines) then + the fdt will not be copied at all on boot. For this + to work it must reside in writable memory, have + sufficient padding on the end of it for U-Boot to + add the information it needs into it, and the memory + must be accessible by the kernel. This usage is strongly discouraged + however as it also stops U-Boot from ensuring the device tree starting + address is properly aligned and a misaligned tree will cause OS failures. + +fdtcontroladdr + if set this is the address of the control flattened + device tree used by U-Boot when CONFIG_OF_CONTROL is + defined. + +initrd_high + restrict positioning of initrd images: + If this variable is not set, initrd images will be + copied to the highest possible address in RAM; this + is usually what you want since it allows for + maximum initrd size. If for some reason you want to + make sure that the initrd image is loaded below the + CFG_SYS_BOOTMAPSZ limit, you can set this environment + variable to a value of "no" or "off" or "0". + Alternatively, you can set it to a maximum upper + address to use (U-Boot will still check that it + does not overwrite the U-Boot stack and data). + + For instance, when you have a system with 16 MB + RAM, and want to reserve 4 MB from use by Linux, + you can do this by adding "mem=12M" to the value of + the "bootargs" variable. However, now you must make + sure that the initrd image is placed in the first + 12 MB as well - this can be done with:: + + setenv initrd_high 00c00000 + + If you set initrd_high to 0xffffffff (32-bit machines) or + 0xffffffffffffffff (64-bit machines), this is an + indication to U-Boot that all addresses are legal + for the Linux kernel, including addresses in flash + memory. In this case U-Boot will NOT COPY the + ramdisk at all. This may be useful to reduce the + boot time on your system, but requires that this + feature is supported by your Linux kernel. This usage however requires + that the user ensure that there will be no overlap with other parts of the + image such as the Linux kernel BSS. It should not be enabled by default + and only done as part of optimizing a deployment. + +ipaddr + IP address; needed for tftpboot command + +loadaddr + Default load address for commands like "bootp", + "rarpboot", "tftpboot", "loadb" or "diskboot". Note that the optimal + default values here will vary between architectures. On 32bit ARM for + example, some offset from start of memory is used as the Linux kernel + zImage has a self decompressor and it's best if we stay out of where that + will be working. + +loads_echo + see CONFIG_LOADS_ECHO + +serverip + TFTP server IP address; needed for tftpboot command + +bootretry + see CONFIG_BOOT_RETRY_TIME + +bootdelaykey + see CONFIG_AUTOBOOT_DELAY_STR + +bootstopkey + see CONFIG_AUTOBOOT_STOP_STR + +ethprime + controls which network interface is used first. + +ethact + controls which interface is currently active. + For example you can do the following:: + + => setenv ethact FEC + => ping 192.168.0.1 # traffic sent on FEC + => setenv ethact SCC + => ping 10.0.0.1 # traffic sent on SCC + +ethrotate + When set to "no" U-Boot does not go through all + available network interfaces. + It just stays at the currently selected interface. When unset or set to + anything other than "no", U-Boot does go through all + available network interfaces. + +httpdstp + If this is set, the value is used for HTTP's TCP + destination port instead of the default port 80. + +netretry + When set to "no" each network operation will + either succeed or fail without retrying. + When set to "once" the network operation will + fail when all the available network interfaces + are tried once without success. + Useful on scripts which control the retry operation + themselves. + +silent_linux + If set then Linux will be told to boot silently, by + adding 'console=' to its command line. If "yes" it will be + made silent. If "no" it will not be made silent. If + unset, then it will be made silent if the U-Boot console + is silent. + +tftpsrcp + If this is set, the value is used for TFTP's + UDP source port. + +tftpdstp + If this is set, the value is used for TFTP's UDP + destination port instead of the default port 69. + +tftpblocksize + Block size to use for TFTP transfers; if not set, + we use the TFTP server's default block size + +tftptimeout + Retransmission timeout for TFTP packets (in milli- + seconds, minimum value is 1000 = 1 second). Defines + when a packet is considered to be lost so it has to + be retransmitted. The default is 5000 = 5 seconds. + Lowering this value may make downloads succeed + faster in networks with high packet loss rates or + with unreliable TFTP servers. + +tftptimeoutcountmax + maximum count of TFTP timeouts (no + unit, minimum value = 0). Defines how many timeouts + can happen during a single file transfer before that + transfer is aborted. The default is 10, and 0 means + 'no timeouts allowed'. Increasing this value may help + downloads succeed with high packet loss rates, or with + unreliable TFTP servers or client hardware. + +tftpwindowsize + if this is set, the value is used for TFTP's + window size as described by RFC 7440. + This means the count of blocks we can receive before + sending ack to server. + +usb_ignorelist + Ignore USB devices to prevent binding them to an USB device driver. This can + be used to ignore devices are for some reason undesirable or causes crashes + u-boot's USB stack. + An example for undesired behavior is the keyboard emulation of security keys + like Yubikeys. U-boot currently supports only a single USB keyboard device + so try to probe an useful keyboard device. The default environment blocks + Yubico devices as common devices emulating keyboards. + Devices are matched by idVendor and idProduct. The variable contains a comma + separated list of idVendor:idProduct pairs as hexadecimal numbers joined + by a colon. '*' functions as a wildcard for idProduct to block all devices + with the specified idVendor. + +vlan + When set to a value < 4095 the traffic over + Ethernet is encapsulated/received over 802.1q + VLAN tagged frames. + + Note: This appears not to be used in U-Boot. See `README.VLAN`. + +bootpretryperiod + Period during which BOOTP/DHCP sends retries. + Unsigned value, in milliseconds. If not set, the period will + be either the default (28000), or a value based on + CONFIG_NET_RETRY_COUNT, if defined. This value has + precedence over the value based on CONFIG_NET_RETRY_COUNT. + +memmatches + Number of matches found by the last 'ms' command, in hex + +memaddr + Address of the last match found by the 'ms' command, in hex, + or 0 if none + +mempos + Index position of the last match found by the 'ms' command, + in units of the size (.b, .w, .l) of the search + +zbootbase + (x86 only) Base address of the bzImage 'setup' block + +zbootaddr + (x86 only) Address of the loaded bzImage, typically + BZIMAGE_LOAD_ADDR which is 0x100000 + + +Image locations +--------------- + +The following image location variables contain the location of images +used in booting. The "Image" column gives the role of the image and is +not an environment variable name. The other columns are environment +variable names. "File Name" gives the name of the file on a TFTP +server, "RAM Address" gives the location in RAM the image will be +loaded to, and "Flash Location" gives the image's address in NOR +flash or offset in NAND flash. + +*Note* - these variables don't have to be defined for all boards, some +boards currently use other variables for these purposes, and some +boards use these variables for other purposes. + +Also note that most of these variables are just a commonly used set of variable +names, used in some other variable definitions, but are not hard-coded anywhere +in U-Boot code. + +================= ============== ================ ============== +Image File Name RAM Address Flash Location +================= ============== ================ ============== +Linux kernel bootfile kernel_addr_r kernel_addr +device tree blob fdtfile fdt_addr_r fdt_addr +ramdisk ramdiskfile ramdisk_addr_r ramdisk_addr +================= ============== ================ ============== + +When setting the RAM addresses for `kernel_addr_r`, `fdt_addr_r` and +`ramdisk_addr_r` there are several types of constraints to keep in mind. The +one type of constraint is payload requirement. For example, a device tree MUST +be loaded at an 8-byte aligned address as that is what the specification +requires. In a similar manner, the operating system may define restrictions on +where in memory space payloads can be. This is documented for example in Linux, +with both the `Booting ARM Linux`_ and `Booting AArch64 Linux`_ documents. +Finally, there are practical constraints. We do not know the size of a given +payload a user will use but each payload must not overlap or it will corrupt +the other payload. A similar problem can happen when a payload ends up being in +the OS BSS area. For these reasons we need to ensure our default values here +are both unlikely to lead to failure to boot and sufficiently explained so that +they can be optimized for boot time or adjusted for smaller memory +configurations. + +On different architectures we will have different constraints. It is important +that we follow whatever documented requirements are available to best ensure +forward compatibility. What follows are examples to highlight how to provide +reasonable default values in different cases. + +Texas Instruments OMAP2PLUS (ARMv7) example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On these families of processors we are on a 32bit ARMv7 core. As booting some +form of Linux is our most common payload we will also keep in mind the +documented requirements for booting that Linux provides. These values are also +known to be fine for booting a number of other operating systems (or their +loaders). In this example we define the following variables and values:: + + loadaddr=0x82000000 + kernel_addr_r=${loadaddr} + fdt_addr_r=0x88000000 + ramdisk_addr_r=0x88080000 + bootm_size=0x10000000 + +The first thing to keep in mind is that DRAM starts at 0x80000000. We set a +32MiB buffer from the start of memory as our default load address and set +``kernel_addr_r`` to that. This is because the Linux ``zImage`` decompressor +will typically then be able to avoid doing a relocation itself. It also MUST be +within the first 128MiB of memory. The next value is we set ``fdt_addr_r`` to +be at 128MiB offset from the start of memory. This location is suggested by the +kernel documentation and is exceedingly unlikely to be overwritten by the +kernel itself given other architectural constraints. We then allow for the +device tree to be up to 512KiB in size before placing the ramdisk in memory. We +then say that everything should be within the first 256MiB of memory so that +U-Boot can relocate things as needed to ensure proper alignment. We pick 256MiB +as our value here because we know there are very few platforms on in this +family with less memory. It could be as high as 768MiB and still ensure that +everything would be visible to the kernel, but again we go with what we assume +is the safest assumption. + +Automatically updated variables +------------------------------- + +The following environment variables may be used and automatically +updated by the network boot commands ("bootp" and "rarpboot"), +depending the information provided by your boot server: + +========= =================================================== +Variable Notes +========= =================================================== +bootfile see above +dnsip IP address of your Domain Name Server +dnsip2 IP address of your secondary Domain Name Server +gatewayip IP address of the Gateway (Router) to use +hostname Target hostname +ipaddr See above +netmask Subnet Mask +rootpath Pathname of the root filesystem on the NFS server +serverip see above +========= =================================================== + + +Special environment variables +----------------------------- + +There are two special Environment Variables: + +serial# + contains hardware identification information such as type string and/or + serial number +ethaddr + Ethernet address. If CONFIG_REGEX=y, also eth*addr (where * is an integer). + +These variables can be set only once (usually during manufacturing of +the board). U-Boot refuses to delete or overwrite these variables +once they have been set, unless CONFIG_ENV_OVERWRITE is enabled in the board +configuration. + +Also: + +ver + Contains the U-Boot version string as printed + with the "version" command. This variable is + readonly (see CONFIG_VERSION_VARIABLE). + +Please note that changes to some configuration parameters may take +only effect after the next boot (yes, that's just like Windows). + + +External environment file +------------------------- + +The `CONFIG_USE_DEFAULT_ENV_FILE` option provides a way to bypass the +environment generation in U-Boot. If enabled, then `CONFIG_DEFAULT_ENV_FILE` +provides the name of a file which is converted into the environment, +completely bypassing the standard environment variables in `env_default.h`. + +The format is the same as accepted by the mkenvimage tool, with lines containing +key=value pairs. Blank lines and lines beginning with # are ignored. + +Future work may unify this feature with the text-based environment, perhaps +moving the contents of `env_default.h` to a text file. + +Implementation +-------------- + +See :doc:`../develop/environment` for internal development details. + +.. _`Booting ARM Linux`: https://www.kernel.org/doc/html/latest/arm/booting.html +.. _`Booting AArch64 Linux`: https://www.kernel.org/doc/html/latest/arm64/booting.html diff --git a/doc/usage/fdt_overlays.rst b/doc/usage/fdt_overlays.rst new file mode 100644 index 00000000000..81d0d37f3f1 --- /dev/null +++ b/doc/usage/fdt_overlays.rst @@ -0,0 +1,134 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2017, Pantelis Antoniou <pantelis.antoniou@konsulko.com> + +Device Tree Overlays +==================== + +Overlay Syntax +-------------- + +Device-tree overlays require a slightly different syntax compared to traditional +device-trees. Please refer to dt-object-internal.txt in the device-tree compiler +sources for information regarding the internal format of overlays: +https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tree/Documentation/dt-object-internal.txt + +Building Overlays +----------------- + +In a nutshell overlays provides a means to manipulate a symbol a previous +device-tree or device-tree overlay has defined. It requires both the base +device-tree and all the overlays to be compiled with the *-@* command line +switch of the device-tree compiler so that symbol information is included. + +Note + Support for *-@* option can only be found in dtc version 1.4.4 or newer. + Only version 4.14 or higher of the Linux kernel includes a built in version + of dtc that meets this requirement. + +Building a binary device-tree overlay follows the same process as building a +traditional binary device-tree. For example: + +**base.dts** + +:: + + /dts-v1/; + / { + foo: foonode { + foo-property; + }; + }; + +.. code-block:: console + + $ dtc -@ -I dts -O dtb -o base.dtb base.dts + +**overlay.dtso** + +:: + + /dts-v1/; + /plugin/; + / { + fragment@1 { + target = <&foo>; + __overlay__ { + overlay-1-property; + bar: barnode { + bar-property; + }; + }; + }; + }; + +.. code-block:: console + + $ dtc -@ -I dts -O dtb -o overlay.dtbo overlay.dtso + +Ways to Utilize Overlays in U-Boot +---------------------------------- + +There are two ways to apply overlays in U-Boot. + +* Include and define overlays within a FIT image and have overlays + automatically applied. + +* Manually load and apply overlays + +The remainder of this document will discuss using overlays via the manual +approach. For information on using overlays as part of a FIT image please see: +doc/uImage.FIT/overlay-fdt-boot.txt + +Manually Loading and Applying Overlays +-------------------------------------- + +1. Figure out where to place both the base device tree blob and the + overlay. Make sure you have enough space to grow the base tree without + overlapping anything. + +:: + + => setenv fdtaddr 0x87f00000 + => setenv fdtovaddr 0x87fc0000 + +2. Load the base binary device-tree and the binary device-tree overlay. + +:: + + => load ${devtype} ${bootpart} ${fdtaddr} ${bootdir}/base.dtb + => load ${devtype} ${bootpart} ${fdtovaddr} ${bootdir}/overlay.dtbo + +3. Set the base binary device-tree as the working fdt tree. + +:: + + => fdt addr $fdtaddr + +4. Grow it enough so it can encompass all applied overlays + +:: + + => fdt resize 8192 + +5. You are now ready to apply the overlay. + +:: + + => fdt apply $fdtovaddr + +6. Boot system like you would do with a traditional dtb. + +For bootm: + +:: + + => bootm ${kerneladdr} - ${fdtaddr} + +For bootz: + +:: + + => bootz ${kerneladdr} - ${fdtaddr} + +Please note that in case of an error, both the base and overlays are going +to be invalidated, so keep copies to avoid reloading. diff --git a/doc/usage/fit/beaglebone_vboot.rst b/doc/usage/fit/beaglebone_vboot.rst new file mode 100644 index 00000000000..1298ba1ae08 --- /dev/null +++ b/doc/usage/fit/beaglebone_vboot.rst @@ -0,0 +1,611 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Verified Boot on the Beaglebone Black +===================================== + +Introduction +------------ + +Before reading this, please read :doc:`verified-boot` and :doc:`signature`. +These instructions are for mainline U-Boot from v2014.07 onwards. + +There is quite a bit of documentation in this directory describing how +verified boot works in U-Boot. There is also a test which runs through the +entire process of signing an image and running U-Boot (sandbox) to check it. +However, it might be useful to also have an example on a real board. + +Beaglebone Black is a fairly common board so seems to be a reasonable choice +for an example of how to enable verified boot using U-Boot. + +First a note that may to help avoid confusion. U-Boot and Linux both use +device tree. They may use the same device tree source, but it is seldom useful +for them to use the exact same binary from the same place. More typically, +U-Boot has its device tree packaged with it, and the kernel's device tree is +packaged with the kernel. In particular this is important with verified boot, +since U-Boot's device tree must be immutable. If it can be changed then the +public keys can be changed and verified boot is useless. An attacker can +simply generate a new key and put his public key into U-Boot so that +everything verifies. On the other hand the kernel's device tree typically +changes when the kernel changes, so it is useful to package an updated device +tree with the kernel binary. U-Boot supports the latter with its flexible FIT +format (Flat Image Tree). + + +Overview +-------- + +The steps are roughly as follows: + +#. Build U-Boot for the board, with the verified boot options enabled. + +#. Obtain a suitable Linux kernel + +#. Create a Image Tree Source file (ITS) file describing how you want the + kernel to be packaged, compressed and signed. + +#. Create a key pair + +#. Sign the kernel + +#. Put the public key into U-Boot's image + +#. Put U-Boot and the kernel onto the board + +#. Try it + + +Step 1: Build U-Boot +-------------------- + +a. Set up the environment variable to point to your toolchain. You will need + this for U-Boot and also for the kernel if you build it. For example if you + installed a Linaro version manually it might be something like:: + + export CROSS_COMPILE=/opt/linaro/gcc-linaro-arm-linux-gnueabihf-4.8-2013.08_linux/bin/arm-linux-gnueabihf- + + or if you just installed gcc-arm-linux-gnueabi then it might be:: + + export CROSS_COMPILE=arm-linux-gnueabi- + +b. Configure and build U-Boot with verified boot enabled. Note that we use the +am335x_evm target since it covers all boards based on the AM335x evaluation +board:: + + export UBOOT=/path/to/u-boot + cd $UBOOT + # You can add -j10 if you have 10 CPUs to make it faster + make O=b/am335x_evm am335x_evm_config all + export UOUT=$UBOOT/b/am335x_evm + +c. You will now have a U-Boot image:: + + file b/am335x_evm/u-boot-dtb.img + b/am335x_evm/u-boot-dtb.img: u-boot legacy uImage, + U-Boot 2014.07-rc2-00065-g2f69f8, Firmware/ARM, Firmware Image + (Not compressed), 395375 bytes, Sat May 31 16:19:04 2014, + Load Address: 0x80800000, Entry Point: 0x00000000, + Header CRC: 0x0ABD6ACA, Data CRC: 0x36DEF7E4 + + +Step 2: Build Linux +------------------- + +a. Find the kernel image ('Image') and device tree (.dtb) file you plan to + use. In our case it is am335x-boneblack.dtb and it is built with the kernel. + At the time of writing an SD Boot image can be obtained from here:: + + http://www.elinux.org/Beagleboard:Updating_The_Software#Image_For_Booting_From_microSD + + You can write this to an SD card and then mount it to extract the kernel and + device tree files. + + You can also build a kernel. Instructions for this are are here:: + + http://elinux.org/Building_BBB_Kernel + + or you can use your favourite search engine. Following these instructions + produces a kernel Image and device tree files. For the record the steps + were:: + + export KERNEL=/path/to/kernel + cd $KERNEL + git clone git://github.com/beagleboard/kernel.git . + git checkout v3.14 + ./patch.sh + cp configs/beaglebone kernel/arch/arm/configs/beaglebone_defconfig + cd kernel + make beaglebone_defconfig + make uImage dtbs # -j10 if you have 10 CPUs + export OKERNEL=$KERNEL/kernel/arch/arm/boot + +b. You now have the 'Image' and 'am335x-boneblack.dtb' files needed to boot. + + +Step 3: Create the ITS +---------------------- + +Set up a directory for your work:: + + export WORK=/path/to/dir + cd $WORK + +Put this into a file in that directory called sign.its:: + + /dts-v1/; + + / { + description = "Beaglebone black"; + #address-cells = <1>; + + images { + kernel { + data = /incbin/("Image.lzo"); + type = "kernel"; + arch = "arm"; + os = "linux"; + compression = "lzo"; + load = <0x80008000>; + entry = <0x80008000>; + hash-1 { + algo = "sha256"; + }; + }; + fdt-1 { + description = "beaglebone-black"; + data = /incbin/("am335x-boneblack.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + hash-1 { + algo = "sha256"; + }; + }; + }; + configurations { + default = "conf-1"; + conf-1 { + kernel = "kernel"; + fdt = "fdt-1"; + signature-1 { + algo = "sha256,rsa2048"; + key-name-hint = "dev"; + sign-images = "fdt", "kernel"; + }; + }; + }; + }; + + +The explanation for this is all in the documentation you have already read. +But briefly it packages a kernel and device tree, and provides a single +configuration to be signed with a key named 'dev'. The kernel is compressed +with LZO to make it smaller. + + +Step 4: Create a key pair +------------------------- + +See :doc:`signature` for details on this step:: + + cd $WORK + mkdir keys + openssl genrsa -F4 -out keys/dev.key 2048 + openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt + +Note: keys/dev.key contains your private key and is very secret. If anyone +gets access to that file they can sign kernels with it. Keep it secure. + + +Step 5: Sign the kernel +----------------------- + +We need to use mkimage (which was built when you built U-Boot) to package the +Linux kernel into a FIT (Flat Image Tree, a flexible file format that U-Boot +can load) using the ITS file you just created. + +At the same time we must put the public key into U-Boot device tree, with the +'required' property, which tells U-Boot that this key must be verified for the +image to be valid. You will make this key available to U-Boot for booting in +step 6:: + + ln -s $OKERNEL/dts/am335x-boneblack.dtb + ln -s $OKERNEL/Image + ln -s $UOUT/u-boot-dtb.img + cp $UOUT/arch/arm/dts/am335x-boneblack.dtb am335x-boneblack-pubkey.dtb + lzop Image + $UOUT/tools/mkimage -f sign.its -K am335x-boneblack-pubkey.dtb -k keys -r image.fit + +You should see something like this:: + + FIT description: Beaglebone black + Created: Sun Jun 1 12:50:30 2014 + Image 0 (kernel) + Description: unavailable + Created: Sun Jun 1 12:50:30 2014 + Type: Kernel Image + Compression: lzo compressed + Data Size: 7790938 Bytes = 7608.34 kB = 7.43 MB + Architecture: ARM + OS: Linux + Load Address: 0x80008000 + Entry Point: 0x80008000 + Hash algo: sha256 + Hash value: 51b2adf9c1016ed46f424d85dcc6c34c46a20b9bee7227e06a6b6320ca5d35c1 + Image 1 (fdt-1) + Description: beaglebone-black + Created: Sun Jun 1 12:50:30 2014 + Type: Flat Device Tree + Compression: uncompressed + Data Size: 31547 Bytes = 30.81 kB = 0.03 MB + Architecture: ARM + Hash algo: sha256 + Hash value: 807d5842a04132261ba092373bd40c78991bc7ce173d1175cd976ec37858e7cd + Default Configuration: 'conf-1' + Configuration 0 (conf-1) + Description: unavailable + Kernel: kernel + FDT: fdt-1 + + +Now am335x-boneblack-pubkey.dtb contains the public key and image.fit contains +the signed kernel. Jump to step 6 if you like, or continue reading to increase +your understanding. + +You can also run fit_check_sign to check it:: + + $UOUT/tools/fit_check_sign -f image.fit -k am335x-boneblack-pubkey.dtb + +which results in:: + + Verifying Hash Integrity ... sha256,rsa2048:dev+ + ## Loading kernel from FIT Image at 7fc6ee469000 ... + Using 'conf-1' configuration + Verifying Hash Integrity ... + sha256,rsa2048:dev+ + OK + + Trying 'kernel' kernel subimage + Description: unavailable + Created: Sun Jun 1 12:50:30 2014 + Type: Kernel Image + Compression: lzo compressed + Data Size: 7790938 Bytes = 7608.34 kB = 7.43 MB + Architecture: ARM + OS: Linux + Load Address: 0x80008000 + Entry Point: 0x80008000 + Hash algo: sha256 + Hash value: 51b2adf9c1016ed46f424d85dcc6c34c46a20b9bee7227e06a6b6320ca5d35c1 + Verifying Hash Integrity ... + sha256+ + OK + + Unimplemented compression type 4 + ## Loading fdt from FIT Image at 7fc6ee469000 ... + Using 'conf-1' configuration + Trying 'fdt-1' fdt subimage + Description: beaglebone-black + Created: Sun Jun 1 12:50:30 2014 + Type: Flat Device Tree + Compression: uncompressed + Data Size: 31547 Bytes = 30.81 kB = 0.03 MB + Architecture: ARM + Hash algo: sha256 + Hash value: 807d5842a04132261ba092373bd40c78991bc7ce173d1175cd976ec37858e7cd + Verifying Hash Integrity ... + sha256+ + OK + + Loading Flat Device Tree ... OK + + ## Loading ramdisk from FIT Image at 7fc6ee469000 ... + Using 'conf-1' configuration + Could not find subimage node + + Signature check OK + + +At the top, you see "sha256,rsa2048:dev+". This means that it checked an RSA key +of size 2048 bits using SHA256 as the hash algorithm. The key name checked was +'dev' and the '+' means that it verified. If it showed '-' that would be bad. + +Once the configuration is verified it is then possible to rely on the hashes +in each image referenced by that configuration. So fit_check_sign goes on to +load each of the images. We have a kernel and an FDT but no ramkdisk. In each +case fit_check_sign checks the hash and prints sha256+ meaning that the SHA256 +hash verified. This means that none of the images has been tampered with. + +There is a test in test/vboot which uses U-Boot's sandbox build to verify that +the above flow works. + +But it is fun to do this by hand, so you can load image.fit into a hex editor +like ghex, and change a byte in the kernel:: + + $UOUT/tools/fit_info -f image.fit -n /images/kernel -p data + NAME: kernel + LEN: 7790938 + OFF: 168 + +This tells us that the kernel starts at byte offset 168 (decimal) in image.fit +and extends for about 7MB. Try changing a byte at 0x2000 (say) and run +fit_check_sign again. You should see something like:: + + Verifying Hash Integrity ... sha256,rsa2048:dev+ + ## Loading kernel from FIT Image at 7f5a39571000 ... + Using 'conf-1' configuration + Verifying Hash Integrity ... + sha256,rsa2048:dev+ + OK + + Trying 'kernel' kernel subimage + Description: unavailable + Created: Sun Jun 1 13:09:21 2014 + Type: Kernel Image + Compression: lzo compressed + Data Size: 7790938 Bytes = 7608.34 kB = 7.43 MB + Architecture: ARM + OS: Linux + Load Address: 0x80008000 + Entry Point: 0x80008000 + Hash algo: sha256 + Hash value: 51b2adf9c1016ed46f424d85dcc6c34c46a20b9bee7227e06a6b6320ca5d35c1 + Verifying Hash Integrity ... + sha256 error + Bad hash value for 'hash-1' hash node in 'kernel' image node + Bad Data Hash + + ## Loading fdt from FIT Image at 7f5a39571000 ... + Using 'conf-1' configuration + Trying 'fdt-1' fdt subimage + Description: beaglebone-black + Created: Sun Jun 1 13:09:21 2014 + Type: Flat Device Tree + Compression: uncompressed + Data Size: 31547 Bytes = 30.81 kB = 0.03 MB + Architecture: ARM + Hash algo: sha256 + Hash value: 807d5842a04132261ba092373bd40c78991bc7ce173d1175cd976ec37858e7cd + Verifying Hash Integrity ... + sha256+ + OK + + Loading Flat Device Tree ... OK + + ## Loading ramdisk from FIT Image at 7f5a39571000 ... + Using 'conf-1' configuration + Could not find subimage node + + Signature check Bad (error 1) + + +It has detected the change in the kernel. + +You can also be sneaky and try to switch images, using the libfdt utilities +that come with dtc (package name is device-tree-compiler but you will need a +recent version like 1.4:: + + dtc -v + Version: DTC 1.4.0 + +First we can check which nodes are actually hashed by the configuration:: + + $ fdtget -l image.fit / + images + configurations + + $ fdtget -l image.fit /configurations + conf-1 + fdtget -l image.fit /configurations/conf-1 + signature-1 + + $ fdtget -p image.fit /configurations/conf-1/signature-1 + hashed-strings + hashed-nodes + timestamp + signer-version + signer-name + value + algo + key-name-hint + sign-images + + $ fdtget image.fit /configurations/conf-1/signature-1 hashed-nodes + / /configurations/conf-1 /images/fdt-1 /images/fdt-1/hash /images/kernel /images/kernel/hash-1 + +This gives us a bit of a look into the signature that mkimage added. Note you +can also use fdtdump to list the entire device tree. + +Say we want to change the kernel that this configuration uses +(/images/kernel). We could just put a new kernel in the image, but we will +need to change the hash to match. Let's simulate that by changing a byte of +the hash:: + + fdtget -tx image.fit /images/kernel/hash-1 value + 51b2adf9 c1016ed4 6f424d85 dcc6c34c 46a20b9b ee7227e0 6a6b6320 ca5d35c1 + fdtput -tx image.fit /images/kernel/hash-1 value 51b2adf9 c1016ed4 6f424d85 dcc6c34c 46a20b9b ee7227e0 6a6b6320 ca5d35c8 + +Now check it again:: + + $UOUT/tools/fit_check_sign -f image.fit -k am335x-boneblack-pubkey.dtb + Verifying Hash Integrity ... sha256,rsa2048:devrsa_verify_with_keynode: RSA failed to verify: -13 + rsa_verify_with_keynode: RSA failed to verify: -13 + - + Failed to verify required signature 'key-dev' + Signature check Bad (error 1) + +This time we don't even get as far as checking the images, since the +configuration signature doesn't match. We can't change any hashes without the +signature check noticing. The configuration is essentially locked. U-Boot has +a public key for which it requires a match, and will not permit the use of any +configuration that does not match that public key. The only way the +configuration will match is if it was signed by the matching private key. + +It would also be possible to add a new signature node that does match your new +configuration. But that won't work since you are not allowed to change the +configuration in any way. Try it with a fresh (valid) image if you like by +running the mkimage link again. Then:: + + fdtput -p image.fit /configurations/conf-1/signature-1 value fred + $UOUT/tools/fit_check_sign -f image.fit -k am335x-boneblack-pubkey.dtb + Verifying Hash Integrity ... - + sha256,rsa2048:devrsa_verify_with_keynode: RSA failed to verify: -13 + rsa_verify_with_keynode: RSA failed to verify: -13 + - + Failed to verify required signature 'key-dev' + Signature check Bad (error 1) + + +Of course it would be possible to add an entirely new configuration and boot +with that, but it still needs to be signed, so it won't help. + + +6. Put the public key into U-Boot's image +----------------------------------------- + +Having confirmed that the signature is doing its job, let's try it out in +U-Boot on the board. U-Boot needs access to the public key corresponding to +the private key that you signed with so that it can verify any kernels that +you sign:: + + cd $UBOOT + make O=b/am335x_evm EXT_DTB=${WORK}/am335x-boneblack-pubkey.dtb + +Here we are overriding the normal device tree file with our one, which +contains the public key. + +Now you have a special U-Boot image with the public key. It can verify can +kernel that you sign with the private key as in step 5. + +If you like you can take a look at the public key information that mkimage +added to U-Boot's device tree:: + + fdtget -p am335x-boneblack-pubkey.dtb /signature/key-dev + required + algo + rsa,r-squared + rsa,modulus + rsa,n0-inverse + rsa,num-bits + key-name-hint + +This has information about the key and some pre-processed values which U-Boot +can use to verify against it. These values are obtained from the public key +certificate by mkimage, but require quite a bit of code to generate. To save +code space in U-Boot, the information is extracted and written in raw form for +U-Boot to easily use. The same mechanism is used in Google's Chrome OS. + +Notice the 'required' property. This marks the key as required - U-Boot will +not boot any image that does not verify against this key. + + +7. Put U-Boot and the kernel onto the board +------------------------------------------- + +The method here varies depending on how you are booting. For this example we +are booting from an micro-SD card with two partitions, one for U-Boot and one +for Linux. Put it into your machine and write U-Boot and the kernel to it. +Here the card is /dev/sde:: + + cd $WORK + export UDEV=/dev/sde1 # Change thes two lines to the correct device + export KDEV=/dev/sde2 + sudo mount $UDEV /mnt/tmp && sudo cp $UOUT/u-boot-dtb.img /mnt/tmp/u-boot.img && sleep 1 && sudo umount $UDEV + sudo mount $KDEV /mnt/tmp && sudo cp $WORK/image.fit /mnt/tmp/boot/image.fit && sleep 1 && sudo umount $KDEV + + +8. Try it +--------- + +Boot the board using the commands below:: + + setenv bootargs console=ttyO0,115200n8 quiet root=/dev/mmcblk0p2 ro rootfstype=ext4 rootwait + ext2load mmc 0:2 82000000 /boot/image.fit + bootm 82000000 + +You should then see something like this:: + + U-Boot# setenv bootargs console=ttyO0,115200n8 quiet root=/dev/mmcblk0p2 ro rootfstype=ext4 rootwait + U-Boot# ext2load mmc 0:2 82000000 /boot/image.fit + 7824930 bytes read in 589 ms (12.7 MiB/s) + U-Boot# bootm 82000000 + ## Loading kernel from FIT Image at 82000000 ... + Using 'conf-1' configuration + Verifying Hash Integrity ... sha256,rsa2048:dev+ OK + Trying 'kernel' kernel subimage + Description: unavailable + Created: 2014-06-01 19:32:54 UTC + Type: Kernel Image + Compression: lzo compressed + Data Start: 0x820000a8 + Data Size: 7790938 Bytes = 7.4 MiB + Architecture: ARM + OS: Linux + Load Address: 0x80008000 + Entry Point: 0x80008000 + Hash algo: sha256 + Hash value: 51b2adf9c1016ed46f424d85dcc6c34c46a20b9bee7227e06a6b6320ca5d35c1 + Verifying Hash Integrity ... sha256+ OK + ## Loading fdt from FIT Image at 82000000 ... + Using 'conf-1' configuration + Trying 'fdt-1' fdt subimage + Description: beaglebone-black + Created: 2014-06-01 19:32:54 UTC + Type: Flat Device Tree + Compression: uncompressed + Data Start: 0x8276e2ec + Data Size: 31547 Bytes = 30.8 KiB + Architecture: ARM + Hash algo: sha256 + Hash value: 807d5842a04132261ba092373bd40c78991bc7ce173d1175cd976ec37858e7cd + Verifying Hash Integrity ... sha256+ OK + Booting using the fdt blob at 0x8276e2ec + Uncompressing Kernel Image ... OK + Loading Device Tree to 8fff5000, end 8ffffb3a ... OK + + Starting kernel ... + + [ 0.582377] omap_init_mbox: hwmod doesn't have valid attrs + [ 2.589651] musb-hdrc musb-hdrc.0.auto: Failed to request rx1. + [ 2.595830] musb-hdrc musb-hdrc.0.auto: musb_init_controller failed with status -517 + [ 2.606470] musb-hdrc musb-hdrc.1.auto: Failed to request rx1. + [ 2.612723] musb-hdrc musb-hdrc.1.auto: musb_init_controller failed with status -517 + [ 2.940808] drivers/rtc/hctosys.c: unable to open rtc device (rtc0) + [ 7.248889] libphy: PHY 4a101000.mdio:01 not found + [ 7.253995] net eth0: phy 4a101000.mdio:01 not found on slave 1 + systemd-fsck[83]: Angstrom: clean, 50607/218160 files, 306348/872448 blocks + + .---O---. + | | .-. o o + | | |-----.-----.-----.| | .----..-----.-----. + | | | __ | ---'| '--.| .-'| | | + | | | | | |--- || --'| | | ' | | | | + '---'---'--'--'--. |-----''----''--' '-----'-'-'-' + -' | + '---' + + The Angstrom Distribution beaglebone ttyO0 + + Angstrom v2012.12 - Kernel 3.14.1+ + + beaglebone login: + +At this point your kernel has been verified and you can be sure that it is one +that you signed. As an exercise, try changing image.fit as in step 5 and see +what happens. + + +Further Improvements +-------------------- + +Several of the steps here can be easily automated. In particular it would be +capital if signing and packaging a kernel were easy, perhaps a simple make +target in the kernel. A starting point for this is the 'make image.fit' target +for ARM64 in Linux from v6.9 onwards. + +Some mention of how to use multiple .dtb files in a FIT might be useful. + +Perhaps the verified boot feature could be integrated into the Amstrom +distribution. + + +.. sectionauthor:: Simon Glass <sjg@chromium.org>, 2-June-14 diff --git a/doc/usage/fit/howto.rst b/doc/usage/fit/howto.rst new file mode 100644 index 00000000000..b5097d4460b --- /dev/null +++ b/doc/usage/fit/howto.rst @@ -0,0 +1,419 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +How to use images in the new image format +========================================= + +Overview +-------- + +The new uImage format allows more flexibility in handling images of various +types (kernel, ramdisk, etc.), it also enhances integrity protection of images +with cryptographic checksums. + +Two auxiliary tools are needed on the development host system in order to +create an uImage in the new format: mkimage and dtc, although only one +(mkimage) is invoked directly. dtc is called from within mkimage and operates +behind the scenes, but needs to be present in the $PATH nevertheless. It is +important that the dtc used has support for binary includes -- refer to:: + + git://git.kernel.org/pub/scm/utils/dtc/dtc.git + +for its latest version. mkimage (together with dtc) takes as input +an image source file, which describes the contents of the image and defines +its various properties used during booting. By convention, image source file +has the ".its" extension, also, the details of its format are provided in +:doc:`source_file_format`. The actual data that is to be included in +the uImage (kernel, ramdisk, etc.) is specified in the image source file in the +form of paths to appropriate data files. The outcome of the image creation +process is a binary file (by convention with the ".itb" extension) that +contains all the referenced data (kernel, ramdisk, etc.) and other information +needed by U-Boot to handle the uImage properly. The uImage file is then +transferred to the target (e.g., via tftp) and booted using the bootm command. + +To summarize the prerequisites needed for new uImage creation: + +- mkimage +- dtc (with support for binary includes) +- image source file (`*.its`) +- image data file(s) + + +Here's a graphical overview of the image creation and booting process:: + + image source file mkimage + dtc transfer to target + + ---------------> image file --------------------> bootm + image data file(s) + +SPL usage +--------- + +The SPL can make use of the new image format as well, this traditionally +is used to ship multiple device tree files within one image. Code in the SPL +will choose the one matching the current board and append this to the +U-Boot proper binary to be automatically used up by it. +Aside from U-Boot proper and one device tree blob the SPL can load multiple, +arbitrary image files as well. These binaries should be specified in their +own subnode under the /images node, which should then be referenced from one or +multiple /configurations subnodes. The required images must be enumerated in +the "loadables" property as a list of strings. + +If a platform specific image source file (.its) is shipped with the U-Boot +source, it can be specified using the CONFIG_SPL_FIT_SOURCE Kconfig symbol. +In this case it will be automatically used by U-Boot's Makefile to generate +the image. +If a static source file is not flexible enough, CONFIG_SPL_FIT_GENERATOR +can point to a script which generates this image source file during +the build process. It gets passed a list of device tree files (taken from the +CONFIG_OF_LIST symbol). + +The SPL also records to a DT all additional images (called loadables) which are +loaded. The information about loadables locations is passed via the DT node with +fit-images name. + +Finally, if there are multiple xPL phases (e.g. SPL, VPL), images can be marked +as intended for a particular phase using the 'phase' property. For example, if +fit_image_load() is called with image_ph(IH_PHASE_SPL, IH_TYPE_FIRMWARE), then +only the image listed into the "firmware" property where phase is set to "spl" +will be loaded. + +Loadables Example +----------------- +Consider the following case for an ARM64 platform where U-Boot runs in EL2 +started by ATF where SPL is loading U-Boot (as loadables) and ATF (as firmware). + +:: + + /dts-v1/; + + / { + description = "Configuration to load ATF before U-Boot"; + + images { + uboot { + description = "U-Boot (64-bit)"; + data = /incbin/("u-boot-nodtb.bin"); + type = "firmware"; + os = "u-boot"; + arch = "arm64"; + compression = "none"; + load = <0x8 0x8000000>; + entry = <0x8 0x8000000>; + hash { + algo = "sha256"; + }; + }; + atf { + description = "ARM Trusted Firmware"; + data = /incbin/("bl31.bin"); + type = "firmware"; + os = "arm-trusted-firmware"; + arch = "arm64"; + compression = "none"; + load = <0xfffea000>; + entry = <0xfffea000>; + hash { + algo = "sha256"; + }; + }; + fdt_1 { + description = "zynqmp-zcu102-revA"; + data = /incbin/("arch/arm/dts/zynqmp-zcu102-revA.dtb"); + type = "flat_dt"; + arch = "arm64"; + compression = "none"; + load = <0x100000>; + hash { + algo = "sha256"; + }; + }; + }; + configurations { + default = "config_1"; + + config_1 { + description = "zynqmp-zcu102-revA"; + firmware = "atf"; + loadables = "uboot"; + fdt = "fdt_1"; + }; + }; + }; + +In this case the SPL records via fit-images DT node the information about +loadables U-Boot image:: + + ZynqMP> fdt addr $fdtcontroladdr + ZynqMP> fdt print /fit-images + fit-images { + uboot { + os = "u-boot"; + type = "firmware"; + size = <0x001017c8>; + entry = <0x00000008 0x08000000>; + load = <0x00000008 0x08000000>; + }; + }; + +As you can see entry and load properties are 64bit wide to support loading +images above 4GB (in past entry and load properties where just 32bit). + + +Example 1 -- old-style (non-FDT) kernel booting +----------------------------------------------- + +Consider a simple scenario, where a PPC Linux kernel built from sources on the +development host is to be booted old-style (non-FDT) by U-Boot on an embedded +target. Assume that the outcome of the build is vmlinux.bin.gz, a file which +contains a gzip-compressed PPC Linux kernel (the only data file in this case). +The uImage can be produced using the image source file +doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is +in the current working directory; if desired, an alternative path can be +specified in the kernel.its file). Here's how to create the image and inspect +its contents: + +[on the host system]:: + + $ mkimage -f kernel.its kernel.itb + DTC: dts->dtb on file "kernel.its" + $ + $ mkimage -l kernel.itb + FIT description: Simple image with single Linux kernel + Created: Tue Mar 11 17:26:15 2008 + Image 0 (kernel) + Description: Vanilla Linux kernel + Type: Kernel Image + Compression: gzip compressed + Data Size: 943347 Bytes = 921.24 kB = 0.90 MB + Architecture: PowerPC + OS: Linux + Load Address: 0x00000000 + Entry Point: 0x00000000 + Hash algo: crc32 + Hash value: 2ae2bb40 + Hash algo: sha256 + Hash value: c22f6bb5a3f96942507a37e7d6a9333ebdc7da57971bc4c082113fe082fdc40f + Default Configuration: 'config-1' + Configuration 0 (config-1) + Description: Boot Linux kernel + Kernel: kernel + + +The resulting image file kernel.itb can be now transferred to the target, +inspected and booted (note that first three U-Boot commands below are shown +for completeness -- they are part of the standard booting procedure and not +specific to the new image format). + +[on the target system]:: + + => print nfsargs + nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath} + => print addip + addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off panic=1 + => run nfsargs addip + => tftp 900000 /path/to/tftp/location/kernel.itb + Using FEC device + TFTP from server 192.168.1.1; our IP address is 192.168.160.5 + Filename '/path/to/tftp/location/kernel.itb'. + Load address: 0x900000 + Loading: ################################################################# + done + Bytes transferred = 944464 (e6950 hex) + => iminfo + + ## Checking Image at 00900000 ... + FIT image found + FIT description: Simple image with single Linux kernel + Created: 2008-03-11 16:26:15 UTC + Image 0 (kernel) + Description: Vanilla Linux kernel + Type: Kernel Image + Compression: gzip compressed + Data Start: 0x009000e0 + Data Size: 943347 Bytes = 921.2 kB + Architecture: PowerPC + OS: Linux + Load Address: 0x00000000 + Entry Point: 0x00000000 + Hash algo: crc32 + Hash value: 2ae2bb40 + Hash algo: sha256 + Hash value: c22f6bb5a3f96942507a37e7d6a9333ebdc7da57971bc4c082113fe082fdc40f + Default Configuration: 'config-1' + Configuration 0 (config-1) + Description: Boot Linux kernel + Kernel: kernel + + => bootm + ## Booting kernel from FIT Image at 00900000 ... + Using 'config-1' configuration + Trying 'kernel' kernel subimage + Description: Vanilla Linux kernel + Type: Kernel Image + Compression: gzip compressed + Data Start: 0x009000e0 + Data Size: 943347 Bytes = 921.2 kB + Architecture: PowerPC + OS: Linux + Load Address: 0x00000000 + Entry Point: 0x00000000 + Hash algo: crc32 + Hash value: 2ae2bb40 + Hash algo: sha256 + Hash value: c22f6bb5a3f96942507a37e7d6a9333ebdc7da57971bc4c082113fe082fdc40f + Verifying Hash Integrity ... crc32+ sha1+ OK + Uncompressing Kernel Image ... OK + Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb + Linux version 2.4.25 (m8@hekate) (gcc version 4.0.0 (DENX ELDK 4.0 4.0.0)) #2 czw lip 5 17:56:18 CEST 2007 + On node 0 totalpages: 65536 + zone(0): 65536 pages. + zone(1): 0 pages. + zone(2): 0 pages. + Kernel command line: root=/dev/nfs rw nfsroot=192.168.1.1:/opt/eldk-4.1/ppc_6xx ip=192.168.160.5:192.168.1.1::255.255.0.0:lite5200b:eth0:off panic=1 + Calibrating delay loop... 307.20 BogoMIPS + + +Example 2 -- new-style (FDT) kernel booting +------------------------------------------- + +Consider another simple scenario, where a PPC Linux kernel is to be booted +new-style, i.e., with a FDT blob. In this case there are two prerequisite data +files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can +be produced using image source file doc/uImage.FIT/kernel_fdt.its like this +(note again, that both prerequisite data files are assumed to be present in +the current working directory -- image source file kernel_fdt.its can be +modified to take the files from some other location if needed): + +[on the host system]:: + + $ mkimage -f kernel_fdt.its kernel_fdt.itb + DTC: dts->dtb on file "kernel_fdt.its" + $ + $ mkimage -l kernel_fdt.itb + FIT description: Simple image with single Linux kernel and FDT blob + Created: Tue Mar 11 16:29:22 2008 + Image 0 (kernel) + Description: Vanilla Linux kernel + Type: Kernel Image + Compression: gzip compressed + Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB + Architecture: PowerPC + OS: Linux + Load Address: 0x00000000 + Entry Point: 0x00000000 + Hash algo: crc32 + Hash value: 2c0cc807 + Hash algo: sha256 + Hash value: a3e9e18b793873827d27c97edfbca67c404a1972d9f36cf48e73ff85d69a422c + Image 1 (fdt-1) + Description: Flattened Device Tree blob + Type: Flat Device Tree + Compression: uncompressed + Data Size: 16384 Bytes = 16.00 kB = 0.02 MB + Architecture: PowerPC + Hash algo: crc32 + Hash value: 0d655d71 + Hash algo: sha256 + Hash value: e9b9a40c5e2e12213ac819e7ccad7271ef43eb5edf9b421f0fa0b4b51bfdb214 + Default Configuration: 'conf-1' + Configuration 0 (conf-1) + Description: Boot Linux kernel with FDT blob + Kernel: kernel + FDT: fdt-1 + + +The resulting image file kernel_fdt.itb can be now transferred to the target, +inspected and booted: + +[on the target system]:: + + => tftp 900000 /path/to/tftp/location/kernel_fdt.itb + Using FEC device + TFTP from server 192.168.1.1; our IP address is 192.168.160.5 + Filename '/path/to/tftp/location/kernel_fdt.itb'. + Load address: 0x900000 + Loading: ################################################################# + ########### + done + Bytes transferred = 1109776 (10ef10 hex) + => iminfo + + ## Checking Image at 00900000 ... + FIT image found + FIT description: Simple image with single Linux kernel and FDT blob + Created: 2008-03-11 15:29:22 UTC + Image 0 (kernel) + Description: Vanilla Linux kernel + Type: Kernel Image + Compression: gzip compressed + Data Start: 0x009000ec + Data Size: 1092037 Bytes = 1 MB + Architecture: PowerPC + OS: Linux + Load Address: 0x00000000 + Entry Point: 0x00000000 + Hash algo: crc32 + Hash value: 2c0cc807 + Hash algo: sha256 + Hash value: a3e9e18b793873827d27c97edfbca67c404a1972d9f36cf48e73ff85d69a422c + Image 1 (fdt-1) + Description: Flattened Device Tree blob + Type: Flat Device Tree + Compression: uncompressed + Data Start: 0x00a0abdc + Data Size: 16384 Bytes = 16 kB + Architecture: PowerPC + Hash algo: crc32 + Hash value: 0d655d71 + Hash algo: sha256 + Hash value: e9b9a40c5e2e12213ac819e7ccad7271ef43eb5edf9b421f0fa0b4b51bfdb214 + Default Configuration: 'conf-1' + Configuration 0 (conf-1) + Description: Boot Linux kernel with FDT blob + Kernel: kernel + FDT: fdt-1 + => bootm + ## Booting kernel from FIT Image at 00900000 ... + Using 'conf-1' configuration + Trying 'kernel' kernel subimage + Description: Vanilla Linux kernel + Type: Kernel Image + Compression: gzip compressed + Data Start: 0x009000ec + Data Size: 1092037 Bytes = 1 MB + Architecture: PowerPC + OS: Linux + Load Address: 0x00000000 + Entry Point: 0x00000000 + Hash algo: crc32 + Hash value: 2c0cc807 + Hash algo: sha1 + Hash value: a3e9e18b793873827d27c97edfbca67c404a1972d9f36cf48e73ff85d69a422c + Verifying Hash Integrity ... crc32+ sha1+ OK + Uncompressing Kernel Image ... OK + ## Flattened Device Tree from FIT Image at 00900000 + Using 'conf-1' configuration + Trying 'fdt-1' FDT blob subimage + Description: Flattened Device Tree blob + Type: Flat Device Tree + Compression: uncompressed + Data Start: 0x00a0abdc + Data Size: 16384 Bytes = 16 kB + Architecture: PowerPC + Hash algo: crc32 + Hash value: 0d655d71 + Hash algo: sha1 + Hash value: e9b9a40c5e2e12213ac819e7ccad7271ef43eb5edf9b421f0fa0b4b51bfdb214 + Verifying Hash Integrity ... crc32+ sha1+ OK + Booting using the fdt blob at 0xa0abdc + Loading Device Tree to 007fc000, end 007fffff ... OK + [ 0.000000] Using lite5200 machine description + [ 0.000000] Linux version 2.6.24-rc6-gaebecdfc (m8@hekate) (gcc version 4.0.0 (DENX ELDK 4.1 4.0.0)) #1 Sat Jan 12 15:38:48 CET 2008 + + +Example 3 -- advanced booting +----------------------------- + +Refer to :doc:`multi` for an image source file that allows more +sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs). + +.. sectionauthor:: Bartlomiej Sieka <tur@semihalf.com> diff --git a/doc/usage/fit/index.rst b/doc/usage/fit/index.rst new file mode 100644 index 00000000000..a822bf20cb2 --- /dev/null +++ b/doc/usage/fit/index.rst @@ -0,0 +1,32 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Flat Image Tree (FIT) +===================== + +U-Boot uses Flat Image Tree (FIT) as a standard file format for packaging +images that it reads and boots. Documentation about FIT is available in +`the Flattened Image Tree project <https://fitspec.osfw.foundation/>`_. + +.. toctree:: + :maxdepth: 1 + + beaglebone_vboot + howto + kernel_fdt + kernel_fdts_compressed + kernel + multi + multi_spl + multi-with-fpga + multi-with-loadables + overlay-fdt-boot + sec_firmware_ppa + signature + sign-configs + sign-images + source_file_format + uefi + update3 + update_uboot + verified-boot + x86-fit-boot
\ No newline at end of file diff --git a/doc/usage/fit/kernel.rst b/doc/usage/fit/kernel.rst new file mode 100644 index 00000000000..e56017985b2 --- /dev/null +++ b/doc/usage/fit/kernel.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Single kernel +============= + +:: + + /dts-v1/; + + / { + description = "Simple image with single Linux kernel"; + #address-cells = <1>; + + images { + kernel { + description = "Vanilla Linux kernel"; + data = /incbin/("./vmlinux.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha256"; + }; + }; + }; + + configurations { + default = "config-1"; + config-1 { + description = "Boot Linux kernel"; + kernel = "kernel"; + }; + }; + }; + + +For x86 a setup node is also required: see x86-fit-boot:: + + /dts-v1/; + + / { + description = "Simple image with single Linux kernel on x86"; + #address-cells = <1>; + + images { + kernel { + description = "Vanilla Linux kernel"; + data = /incbin/("./image.bin.lzo"); + type = "kernel"; + arch = "x86"; + os = "linux"; + compression = "lzo"; + load = <0x01000000>; + entry = <0x00000000>; + hash-2 { + algo = "sha256"; + }; + }; + + setup { + description = "Linux setup.bin"; + data = /incbin/("./setup.bin"); + type = "x86_setup"; + arch = "x86"; + os = "linux"; + compression = "none"; + load = <0x00090000>; + entry = <0x00090000>; + hash-2 { + algo = "sha256"; + }; + }; + }; + + configurations { + default = "config-1"; + config-1 { + description = "Boot Linux kernel"; + kernel = "kernel"; + setup = "setup"; + }; + }; + }; + +Note: the above assumes a 32-bit kernel. To directly boot a 64-bit kernel, +change both arch values to "x86_64". U-Boot will then change to 64-bit mode +before booting the kernel (see boot_linux_kernel()). diff --git a/doc/usage/fit/kernel_fdt.rst b/doc/usage/fit/kernel_fdt.rst new file mode 100644 index 00000000000..9cc26fb7831 --- /dev/null +++ b/doc/usage/fit/kernel_fdt.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Single kernel and FDT blob +========================== + +:: + + /dts-v1/; + + / { + description = "Simple image with single Linux kernel and FDT blob"; + #address-cells = <1>; + + images { + kernel { + description = "Vanilla Linux kernel"; + data = /incbin/("./vmlinux.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha256"; + }; + }; + fdt-1 { + description = "Flattened Device Tree blob"; + data = /incbin/("./target.dtb"); + type = "flat_dt"; + arch = "ppc"; + compression = "none"; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha256"; + }; + }; + }; + + configurations { + default = "conf-1"; + conf-1 { + description = "Boot Linux kernel with FDT blob"; + kernel = "kernel"; + fdt = "fdt-1"; + }; + }; + }; diff --git a/doc/usage/fit/kernel_fdts_compressed.rst b/doc/usage/fit/kernel_fdts_compressed.rst new file mode 100644 index 00000000000..b57871da58b --- /dev/null +++ b/doc/usage/fit/kernel_fdts_compressed.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Kernel and multiple compressed FDT blobs +======================================== + +Since the FDTs are compressed, configurations must provide a compatible +string to match directly. + +:: + + /dts-v1/; + + / { + description = "Image with single Linux kernel and compressed FDT blobs"; + #address-cells = <1>; + + images { + kernel { + description = "Vanilla Linux kernel"; + data = /incbin/("./vmlinux.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha256"; + }; + }; + fdt@1 { + description = "Flattened Device Tree blob 1"; + data = /incbin/("./myboard-var1.dtb"); + type = "flat_dt"; + arch = "ppc"; + compression = "gzip"; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha256"; + }; + }; + fdt@2 { + description = "Flattened Device Tree blob 2"; + data = /incbin/("./myboard-var2.dtb"); + type = "flat_dt"; + arch = "ppc"; + compression = "lzma"; + hash-1 { + algo = "crc32"; + }; + hash-2 { + algo = "sha256"; + }; + }; + }; + + configurations { + default = "conf@1"; + conf@1 { + description = "Boot Linux kernel with FDT blob 1"; + kernel = "kernel"; + fdt = "fdt@1"; + compatible = "myvendor,myboard-variant1"; + }; + conf@2 { + description = "Boot Linux kernel with FDT blob 2"; + kernel = "kernel"; + fdt = "fdt@2"; + compatible = "myvendor,myboard-variant2"; + }; + }; + }; diff --git a/doc/usage/fit/multi-with-fpga.rst b/doc/usage/fit/multi-with-fpga.rst new file mode 100644 index 00000000000..4c7f1bebd5a --- /dev/null +++ b/doc/usage/fit/multi-with-fpga.rst @@ -0,0 +1,70 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Multiple kernels, ramdisks and FDT blobs with FPGA +================================================== + +This example makes use of the 'loadables' field:: + + /dts-v1/; + + / { + description = "Configuration to load fpga before Kernel"; + #address-cells = <1>; + + images { + fdt-1 { + description = "zc706"; + data = /incbin/("/tftpboot/devicetree.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + load = <0x10000000>; + hash-1 { + algo = "sha256"; + }; + }; + + fpga { + description = "FPGA"; + data = /incbin/("/tftpboot/download.bit"); + type = "fpga"; + arch = "arm"; + compression = "none"; + load = <0x30000000>; + compatible = "u-boot,fpga-legacy" + hash-1 { + algo = "sha256"; + }; + }; + + linux_kernel { + description = "Linux"; + data = /incbin/("/tftpboot/zImage"); + type = "kernel"; + arch = "arm"; + os = "linux"; + compression = "none"; + load = <0x8000>; + entry = <0x8000>; + hash-1 { + algo = "sha256"; + }; + }; + }; + + configurations { + default = "config-2"; + config-1 { + description = "Linux"; + kernel = "linux_kernel"; + fdt = "fdt-1"; + }; + + config-2 { + description = "Linux with fpga"; + kernel = "linux_kernel"; + fdt = "fdt-1"; + loadables = "fpga"; + }; + }; + }; diff --git a/doc/usage/fit/multi-with-loadables.rst b/doc/usage/fit/multi-with-loadables.rst new file mode 100644 index 00000000000..7849cb544f1 --- /dev/null +++ b/doc/usage/fit/multi-with-loadables.rst @@ -0,0 +1,91 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Multiple kernels, ramdisks and FDT blobs with Xen +================================================= + +This example makes use of the 'loadables' field:: + + /dts-v1/; + + / { + description = "Configuration to load a Xen Kernel"; + #address-cells = <1>; + + images { + xen_kernel { + description = "xen binary"; + data = /incbin/("./xen"); + type = "kernel"; + arch = "arm"; + os = "linux"; + compression = "none"; + load = <0xa0000000>; + entry = <0xa0000000>; + hash-1 { + algo = "sha256"; + }; + }; + + fdt-1 { + description = "xexpress-ca15 tree blob"; + data = /incbin/("./vexpress-v2p-ca15-tc1.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + load = <0xb0000000>; + hash-1 { + algo = "sha256"; + }; + }; + + fdt-2 { + description = "xexpress-ca15 tree blob"; + data = /incbin/("./vexpress-v2p-ca15-tc1.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + load = <0xb0400000>; + hash-1 { + algo = "sha256"; + }; + }; + + linux_kernel { + description = "Linux Image"; + data = /incbin/("./Image"); + type = "kernel"; + arch = "arm"; + os = "linux"; + compression = "none"; + load = <0xa0000000>; + entry = <0xa0000000>; + hash-1 { + algo = "sha256"; + }; + }; + }; + + configurations { + default = "config-2"; + + config-1 { + description = "Just plain Linux"; + kernel = "linux_kernel"; + fdt = "fdt-1"; + }; + + config-2 { + description = "Xen one loadable"; + kernel = "xen_kernel"; + fdt = "fdt-1"; + loadables = "linux_kernel"; + }; + + config-3 { + description = "Xen two loadables"; + kernel = "xen_kernel"; + fdt = "fdt-1"; + loadables = "linux_kernel", "fdt-2"; + }; + }; + }; diff --git a/doc/usage/fit/multi.rst b/doc/usage/fit/multi.rst new file mode 100644 index 00000000000..e68752b2ad0 --- /dev/null +++ b/doc/usage/fit/multi.rst @@ -0,0 +1,136 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Multiple kernels, ramdisks and FDT blobs +======================================== + +:: + + /dts-v1/; + + / { + description = "Various kernels, ramdisks and FDT blobs"; + #address-cells = <1>; + + images { + kernel-1 { + description = "vanilla-2.6.23"; + data = /incbin/("./vmlinux.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "sha256"; + }; + hash-2 { + algo = "sha512"; + }; + }; + + kernel-2 { + description = "2.6.23-denx"; + data = /incbin/("./2.6.23-denx.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "sha256"; + }; + }; + + kernel-3 { + description = "2.4.25-denx"; + data = /incbin/("./2.4.25-denx.bin.gz"); + type = "kernel"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "sha256"; + }; + }; + + ramdisk-1 { + description = "eldk-4.2-ramdisk"; + data = /incbin/("./eldk-4.2-ramdisk"); + type = "ramdisk"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "sha256"; + }; + }; + + ramdisk-2 { + description = "eldk-3.1-ramdisk"; + data = /incbin/("./eldk-3.1-ramdisk"); + type = "ramdisk"; + arch = "ppc"; + os = "linux"; + compression = "gzip"; + load = <00000000>; + entry = <00000000>; + hash-1 { + algo = "crc32"; + }; + }; + + fdt-1 { + description = "tqm5200-fdt"; + data = /incbin/("./tqm5200.dtb"); + type = "flat_dt"; + arch = "ppc"; + compression = "none"; + hash-1 { + algo = "crc32"; + }; + }; + + fdt-2 { + description = "tqm5200s-fdt"; + data = /incbin/("./tqm5200s.dtb"); + type = "flat_dt"; + arch = "ppc"; + compression = "none"; + load = <00700000>; + hash-1 { + algo = "sha256"; + }; + }; + + }; + + configurations { + default = "config-1"; + + config-1 { + description = "tqm5200 vanilla-2.6.23 configuration"; + kernel = "kernel-1"; + ramdisk = "ramdisk-1"; + fdt = "fdt-1"; + }; + + config-2 { + description = "tqm5200s denx-2.6.23 configuration"; + kernel = "kernel-2"; + ramdisk = "ramdisk-1"; + fdt = "fdt-2"; + }; + + config-3 { + description = "tqm5200s denx-2.4.25 configuration"; + kernel = "kernel-3"; + ramdisk = "ramdisk-2"; + }; + }; + }; diff --git a/doc/usage/fit/multi_spl.rst b/doc/usage/fit/multi_spl.rst new file mode 100644 index 00000000000..74b6f865abd --- /dev/null +++ b/doc/usage/fit/multi_spl.rst @@ -0,0 +1,101 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Multiple images for SPL +======================= + +(Bogus) example FIT image description file demonstrating the usage +of multiple images loaded by the SPL. +Several binaries will be loaded at their respective load addresses. + +For booting U-Boot, "firmware" is searched first. If not found, "loadables" +is used to identify images to be loaded into memory. If falcon boot is +enabled, "kernel" is searched first. If not found, it falls back to the +same flow as booting U-Boot. Changing image type will result skipping +specific image. + +Finally the one image specifying an entry point will be entered by the SPL. + +:: + + /dts-v1/; + + / { + description = "multiple firmware blobs and U-Boot, loaded by SPL"; + #address-cells = <0x1>; + + images { + + uboot { + description = "U-Boot (64-bit)"; + type = "standalone"; + arch = "arm64"; + compression = "none"; + load = <0x4a000000>; + }; + + atf { + description = "ARM Trusted Firmware"; + type = "firmware"; + arch = "arm64"; + compression = "none"; + load = <0x18000>; + entry = <0x18000>; + }; + + mgmt-firmware { + description = "arisc management processor firmware"; + type = "firmware"; + arch = "or1k"; + compression = "none"; + load = <0x40000>; + }; + + fdt-1 { + description = "Pine64+ DT"; + type = "flat_dt"; + compression = "none"; + load = <0x4fa00000>; + arch = "arm64"; + }; + + fdt-2 { + description = "Pine64 DT"; + type = "flat_dt"; + compression = "none"; + load = <0x4fa00000>; + arch = "arm64"; + }; + + kernel { + description = "4.7-rc5 kernel"; + type = "kernel"; + compression = "none"; + load = <0x40080000>; + arch = "arm64"; + }; + + initrd { + description = "Debian installer initrd"; + type = "ramdisk"; + compression = "none"; + load = <0x4fe00000>; + arch = "arm64"; + }; + }; + + configurations { + default = "config-1"; + + config-1 { + description = "sun50i-a64-pine64-plus"; + loadables = "uboot", "atf", "kernel", "initrd"; + fdt = "fdt-1"; + }; + + config-2 { + description = "sun50i-a64-pine64"; + loadables = "uboot", "atf", "mgmt-firmware"; + fdt = "fdt-2"; + }; + }; + }; diff --git a/doc/usage/fit/overlay-fdt-boot.rst b/doc/usage/fit/overlay-fdt-boot.rst new file mode 100644 index 00000000000..a7db1a37f7a --- /dev/null +++ b/doc/usage/fit/overlay-fdt-boot.rst @@ -0,0 +1,227 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot FDT Overlay FIT usage +============================ + +Introduction +------------ + +In many cases it is desirable to have a single FIT image support a multitude +of similar boards and their expansion options. The same kernel on DT enabled +platforms can support this easily enough by providing a DT blob upon boot +that matches the desired configuration. + +This document focuses on specifically using overlays as part of a FIT image. +General information regarding overlays including its syntax and building it +can be found in doc/README.fdt-overlays + +Configuration without overlays +------------------------------ + +Take a hypothetical board named 'foo' where there are different supported +revisions, reva and revb. Assume that both board revisions can use add a bar +add-on board, while only the revb board can use a baz add-on board. + +Without using overlays the configuration would be as follows for every case:: + + /dts-v1/; + / { + images { + kernel { + data = /incbin/("./zImage"); + type = "kernel"; + arch = "arm"; + os = "linux"; + load = <0x82000000>; + entry = <0x82000000>; + }; + fdt-1 { + data = /incbin/("./foo-reva.dtb"); + type = "flat_dt"; + arch = "arm"; + }; + fdt-2 { + data = /incbin/("./foo-revb.dtb"); + type = "flat_dt"; + arch = "arm"; + }; + fdt-3 { + data = /incbin/("./foo-reva-bar.dtb"); + type = "flat_dt"; + arch = "arm"; + }; + fdt-4 { + data = /incbin/("./foo-revb-bar.dtb"); + type = "flat_dt"; + arch = "arm"; + }; + fdt-5 { + data = /incbin/("./foo-revb-baz.dtb"); + type = "flat_dt"; + arch = "arm"; + }; + fdt-6 { + data = /incbin/("./foo-revb-bar-baz.dtb"); + type = "flat_dt"; + arch = "arm"; + }; + }; + + configurations { + default = "foo-reva.dtb; + foo-reva.dtb { + kernel = "kernel"; + fdt = "fdt-1"; + }; + foo-revb.dtb { + kernel = "kernel"; + fdt = "fdt-2"; + }; + foo-reva-bar.dtb { + kernel = "kernel"; + fdt = "fdt-3"; + }; + foo-revb-bar.dtb { + kernel = "kernel"; + fdt = "fdt-4"; + }; + foo-revb-baz.dtb { + kernel = "kernel"; + fdt = "fdt-5"; + }; + foo-revb-bar-baz.dtb { + kernel = "kernel"; + fdt = "fdt-6"; + }; + }; + }; + +Note the blob needs to be compiled for each case and the combinatorial explosion of +configurations. A typical device tree blob is in the low hunderds of kbytes so a +multitude of configuration grows the image quite a bit. + +Booting this image is done by using:: + + # bootm <addr>#<config> + +Where config is one of:: + + foo-reva.dtb, foo-revb.dtb, foo-reva-bar.dtb, foo-revb-bar.dtb, + foo-revb-baz.dtb, foo-revb-bar-baz.dtb + +This selects the DTB to use when booting. + +Configuration using overlays +---------------------------- + +Device tree overlays can be applied to a base DT and result in the same blob +being passed to the booting kernel. This saves on space and avoid the combinatorial +explosion problem:: + + /dts-v1/; + / { + images { + kernel { + data = /incbin/("./zImage"); + type = "kernel"; + arch = "arm"; + os = "linux"; + load = <0x82000000>; + entry = <0x82000000>; + }; + fdt-1 { + data = /incbin/("./foo.dtb"); + type = "flat_dt"; + arch = "arm"; + load = <0x87f00000>; + }; + fdt-2 { + data = /incbin/("./reva.dtbo"); + type = "flat_dt"; + arch = "arm"; + load = <0x87fc0000>; + }; + fdt-3 { + data = /incbin/("./revb.dtbo"); + type = "flat_dt"; + arch = "arm"; + load = <0x87fc0000>; + }; + fdt-4 { + data = /incbin/("./bar.dtbo"); + type = "flat_dt"; + arch = "arm"; + load = <0x87fc0000>; + }; + fdt-5 { + data = /incbin/("./baz.dtbo"); + type = "flat_dt"; + arch = "arm"; + load = <0x87fc0000>; + }; + }; + + configurations { + default = "foo-reva.dtb; + foo-reva.dtb { + kernel = "kernel"; + fdt = "fdt-1", "fdt-2"; + }; + foo-revb.dtb { + kernel = "kernel"; + fdt = "fdt-1", "fdt-3"; + }; + foo-reva-bar.dtb { + kernel = "kernel"; + fdt = "fdt-1", "fdt-2", "fdt-4"; + }; + foo-revb-bar.dtb { + kernel = "kernel"; + fdt = "fdt-1", "fdt-3", "fdt-4"; + }; + foo-revb-baz.dtb { + kernel = "kernel"; + fdt = "fdt-1", "fdt-3", "fdt-5"; + }; + foo-revb-bar-baz.dtb { + kernel = "kernel"; + fdt = "fdt-1", "fdt-3", "fdt-4", "fdt-5"; + }; + bar { + fdt = "fdt-4"; + }; + baz { + fdt = "fdt-5"; + }; + }; + }; + +Booting this image is exactly the same as the non-overlay example. +u-boot will retrieve the base blob and apply the overlays in sequence as +they are declared in the configuration. + +Note the minimum amount of different DT blobs, as well as the requirement for +the DT blobs to have a load address; the overlay application requires the blobs +to be writeable. + +Configuration using overlays and feature selection +-------------------------------------------------- + +Although the configuration in the previous section works is a bit inflexible +since it requires all possible configuration options to be laid out before +hand in the FIT image. For the add-on boards the extra config selection method +might make sense. + +Note the two bar & baz configuration nodes. To boot a reva board with +the bar add-on board enabled simply use:: + + => bootm <addr>#foo-reva.dtb#bar + +While booting a revb with bar and baz is as follows:: + + => bootm <addr>#foo-revb.dtb#bar#baz + +The limitation for a feature selection configuration node is that a single +fdt option is currently supported. + +.. sectionauthor:: Pantelis Antoniou <pantelis.antoniou@konsulko.com>, 12/6/2017 diff --git a/doc/usage/fit/sec_firmware_ppa.rst b/doc/usage/fit/sec_firmware_ppa.rst new file mode 100644 index 00000000000..4cb292cb4ee --- /dev/null +++ b/doc/usage/fit/sec_firmware_ppa.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +SEC Firmware and multiple loadable images +========================================= + +Example FIT image description file demonstrating the usage +of SEC Firmware and multiple loadable images loaded by U-Boot. +For booting PPA (SEC Firmware), "firmware" is searched and loaded. + +Multiple binaries will be loaded as "loadables" (if present) at their +respective load offsets from firmware image address. + +:: + + /dts-v1/; + + /{ + description = "PPA Firmware"; + #address-cells = <1>; + images { + firmware@1 { + description = "PPA Firmware: <version>"; + data = /incbin/("../obj/monitor.bin"); + type = "firmware"; + arch = "arm64"; + compression = "none"; + }; + trustedOS@1 { + description = "Trusted OS"; + data = /incbin/("../../tee.bin"); + type = "OS"; + arch = "arm64"; + compression = "none"; + load = <0x00200000>; + }; + fuse_scr { + description = "Fuse Script"; + data = /incbin/("../../fuse_scr.bin"); + type = "firmware"; + arch = "arm64"; + compression = "none"; + load = <0x00180000>; + }; + }; + + configurations { + default = "config-1"; + config-1 { + description = "PPA Secure firmware"; + firmware = "firmware@1"; + loadables = "trustedOS@1", "fuse_scr"; + }; + }; + }; diff --git a/doc/usage/fit/sign-configs.rst b/doc/usage/fit/sign-configs.rst new file mode 100644 index 00000000000..6d98d44430c --- /dev/null +++ b/doc/usage/fit/sign-configs.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Signed configurations +===================== + +:: + + /dts-v1/; + + / { + description = "Chrome OS kernel image with one or more FDT blobs"; + #address-cells = <1>; + + images { + kernel { + data = /incbin/("test-kernel.bin"); + type = "kernel_noload"; + arch = "sandbox"; + os = "linux"; + compression = "lzo"; + load = <0x4>; + entry = <0x8>; + kernel-version = <1>; + hash-1 { + algo = "sha256"; + }; + }; + fdt-1 { + description = "snow"; + data = /incbin/("sandbox-kernel.dtb"); + type = "flat_dt"; + arch = "sandbox"; + compression = "none"; + fdt-version = <1>; + hash-1 { + algo = "sha256"; + }; + }; + }; + configurations { + default = "conf-1"; + conf-1 { + kernel = "kernel"; + fdt = "fdt-1"; + signature { + algo = "sha256,rsa2048"; + key-name-hint = "dev"; + sign-images = "fdt", "kernel"; + }; + }; + }; + }; diff --git a/doc/usage/fit/sign-images.rst b/doc/usage/fit/sign-images.rst new file mode 100644 index 00000000000..ca7d10fab83 --- /dev/null +++ b/doc/usage/fit/sign-images.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Signed Images +============= + +:: + + /dts-v1/; + + / { + description = "Chrome OS kernel image with one or more FDT blobs"; + #address-cells = <1>; + + images { + kernel { + data = /incbin/("test-kernel.bin"); + type = "kernel_noload"; + arch = "sandbox"; + os = "linux"; + compression = "none"; + load = <0x4>; + entry = <0x8>; + kernel-version = <1>; + signature { + algo = "sha256,rsa2048"; + key-name-hint = "dev"; + }; + }; + fdt-1 { + description = "snow"; + data = /incbin/("sandbox-kernel.dtb"); + type = "flat_dt"; + arch = "sandbox"; + compression = "none"; + fdt-version = <1>; + signature { + algo = "sha256,rsa2048"; + key-name-hint = "dev"; + }; + }; + }; + configurations { + default = "conf-1"; + conf-1 { + kernel = "kernel"; + fdt = "fdt-1"; + }; + }; + }; diff --git a/doc/usage/fit/signature.rst b/doc/usage/fit/signature.rst new file mode 100644 index 00000000000..b868dcbf9fd --- /dev/null +++ b/doc/usage/fit/signature.rst @@ -0,0 +1,696 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot FIT Signature Verification +================================= + +Introduction +------------ + +FIT supports hashing of images so that these hashes can be checked on +loading. This protects against corruption of the image. However it does not +prevent the substitution of one image for another. + +The signature feature allows the hash to be signed with a private key such +that it can be verified using a public key later. Provided that the private +key is kept secret and the public key is stored in a non-volatile place, +any image can be verified in this way. + +See :doc:`verified-boot` for more general information on verified boot. + + +Concepts +-------- + +Some familiarity with public key cryptography is assumed in this section. + +The procedure for signing is as follows: + + - hash an image in the FIT + - sign the hash with a private key to produce a signature + - store the resulting signature in the FIT + +The procedure for verification is: + + - read the FIT + - obtain the public key + - extract the signature from the FIT + - hash the image from the FIT + - verify (with the public key) that the extracted signature matches the + hash + +The signing is generally performed by mkimage, as part of making a firmware +image for the device. The verification is normally done in U-Boot on the +device. + + +Algorithms +---------- +In principle any suitable algorithm can be used to sign and verify a hash. +U-Boot supports a few hashing and verification algorithms. See below for +details. + +While it is acceptable to bring in large cryptographic libraries such as +openssl on the host side (e.g. mkimage), it is not desirable for U-Boot. +For the run-time verification side, it is important to keep code and data +size as small as possible. + +For this reason the RSA image verification uses pre-processed public keys +which can be used with a very small amount of code - just some extraction +of data from the FDT and exponentiation mod n. Code size impact is a little +under 5KB on Tegra Seaboard, for example. + +It is relatively straightforward to add new algorithms if required. If +another RSA variant is needed, then it can be added with the +U_BOOT_CRYPTO_ALGO() macro. If another algorithm is needed (such as DSA) then +it can be placed in a directory alongside lib/rsa/, and its functions added +using U_BOOT_CRYPTO_ALGO(). + + +Creating an RSA key pair and certificate +---------------------------------------- +To create a new public/private key pair, size 2048 bits:: + + $ openssl genpkey -algorithm RSA -out keys/dev.key \ + -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537 + +To create a certificate for this containing the public key:: + + $ openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt + +If you like you can look at the public key also:: + + $ openssl rsa -in keys/dev.key -pubout + + +Public Key Storage +------------------ +In order to verify an image that has been signed with a public key we need to +have a trusted public key. This cannot be stored in the signed image, since +it would be easy to alter. For this implementation we choose to store the +public key in U-Boot's control FDT (using CONFIG_OF_CONTROL). + +Public keys should be stored as sub-nodes in a /signature node. Required +properties are: + +algo + Algorithm name (e.g. "sha256,rsa2048" or "sha512,ecdsa256") + +Optional properties are: + +key-name-hint + Name of key used for signing. This is only a hint since it + is possible for the name to be changed. Verification can proceed by checking + all available signing keys until one matches. + +required + If present this indicates that the key must be verified for the + image / configuration to be considered valid. Only required keys are + normally verified by the FIT image booting algorithm. Valid values are + "image" to force verification of all images, and "conf" to force verification + of the selected configuration (which then relies on hashes in the images to + verify those). + +Each signing algorithm has its own additional properties. + +For RSA the following are mandatory: + +rsa,num-bits + Number of key bits (e.g. 2048) + +rsa,modulus + Modulus (N) as a big-endian multi-word integer + +rsa,exponent + Public exponent (E) as a 64 bit unsigned integer + +rsa,r-squared + (2^num-bits)^2 as a big-endian multi-word integer + +rsa,n0-inverse + -1 / modulus[0] mod 2^32 + +For ECDSA the following are mandatory: + +ecdsa,curve + Name of ECDSA curve (e.g. "prime256v1") + +ecdsa,x-point + Public key X coordinate as a big-endian multi-word integer + +ecdsa,y-point + Public key Y coordinate as a big-endian multi-word integer + +These parameters can be added to a binary device tree using parameter -K of the +mkimage command:: + + tools/mkimage -f fit.its -K control.dtb -k keys -r image.fit + +Here is an example of a generated device tree node:: + + signature { + key-dev { + required = "conf"; + algo = "sha256,rsa2048"; + rsa,r-squared = <0xb76d1acf 0xa1763ca5 0xeb2f126 + 0x742edc80 0xd3f42177 0x9741d9d9 + 0x35bb476e 0xff41c718 0xd3801430 + 0xf22537cb 0xa7e79960 0xae32a043 + 0x7da1427a 0x341d6492 0x3c2762f5 + 0xaac04726 0x5b262d96 0xf984e86d + 0xb99443c7 0x17080c33 0x940f6892 + 0xd57a95d1 0x6ea7b691 0xc5038fa8 + 0x6bb48a6e 0x73f1b1ea 0x37160841 + 0xe05715ce 0xa7c45bbd 0x690d82d5 + 0x99c2454c 0x6ff117b3 0xd830683b + 0x3f81c9cf 0x1ca38a91 0x0c3392e4 + 0xd817c625 0x7b8e9a24 0x175b89ea + 0xad79f3dc 0x4d50d7b4 0x9d4e90f8 + 0xad9e2939 0xc165d6a4 0x0ada7e1b + 0xfb1bf495 0xfc3131c2 0xb8c6e604 + 0xc2761124 0xf63de4a6 0x0e9565f9 + 0xc8e53761 0x7e7a37a5 0xe99dcdae + 0x9aff7e1e 0xbd44b13d 0x6b0e6aa4 + 0x038907e4 0x8e0d6850 0xef51bc20 + 0xf73c94af 0x88bea7b1 0xcbbb1b30 + 0xd024b7f3>; + rsa,modulus = <0xc0711d6cb 0x9e86db7f 0x45986dbe + 0x023f1e8c9 0xe1a4c4d0 0x8a0dfdc9 + 0x023ba0c48 0x06815f6a 0x5caa0654 + 0x07078c4b7 0x3d154853 0x40729023 + 0x0b007c8fe 0x5a3647e5 0x23b41e20 + 0x024720591 0x66915305 0x0e0b29b0 + 0x0de2ad30d 0x8589430f 0xb1590325 + 0x0fb9f5d5e 0x9eba752a 0xd88e6de9 + 0x056b3dcc6 0x9a6b8e61 0x6784f61f + 0x000f39c21 0x5eec6b33 0xd78e4f78 + 0x0921a305f 0xaa2cc27e 0x1ca917af + 0x06e1134f4 0xd48cac77 0x4e914d07 + 0x0f707aa5a 0x0d141f41 0x84677f1d + 0x0ad47a049 0x028aedb6 0xd5536fcf + 0x03fef1e4f 0x133a03d2 0xfd7a750a + 0x0f9159732 0xd207812e 0x6a807375 + 0x06434230d 0xc8e22dad 0x9f29b3d6 + 0x07c44ac2b 0xfa2aad88 0xe2429504 + 0x041febd41 0x85d0d142 0x7b194d65 + 0x06e5d55ea 0x41116961 0xf3181dde + 0x068bf5fbc 0x3dd82047 0x00ee647e + 0x0d7a44ab3>; + rsa,exponent = <0x00 0x10001>; + rsa,n0-inverse = <0xb3928b85>; + rsa,num-bits = <0x800>; + key-name-hint = "dev"; + }; + }; + + +Signed Configurations +--------------------- +While signing images is useful, it does not provide complete protection +against several types of attack. For example, it is possible to create a +FIT with the same signed images, but with the configuration changed such +that a different one is selected (mix and match attack). It is also possible +to substitute a signed image from an older FIT version into a newer FIT +(roll-back attack). + +As an example, consider this FIT:: + + / { + images { + kernel-1 { + data = <data for kernel1> + signature-1 { + algo = "sha256,rsa2048"; + value = <...kernel signature 1...> + }; + }; + kernel-2 { + data = <data for kernel2> + signature-1 { + algo = "sha256,rsa2048"; + value = <...kernel signature 2...> + }; + }; + fdt-1 { + data = <data for fdt1>; + signature-1 { + algo = "sha256,rsa2048"; + value = <...fdt signature 1...> + }; + }; + fdt-2 { + data = <data for fdt2>; + signature-1 { + algo = "sha256,rsa2048"; + value = <...fdt signature 2...> + }; + }; + }; + configurations { + default = "conf-1"; + conf-1 { + kernel = "kernel-1"; + fdt = "fdt-1"; + }; + conf-2 { + kernel = "kernel-2"; + fdt = "fdt-2"; + }; + }; + }; + +Since both kernels are signed it is easy for an attacker to add a new +configuration 3 with kernel 1 and fdt 2:: + + configurations { + default = "conf-1"; + conf-1 { + kernel = "kernel-1"; + fdt = "fdt-1"; + }; + conf-2 { + kernel = "kernel-2"; + fdt = "fdt-2"; + }; + conf-3 { + kernel = "kernel-1"; + fdt = "fdt-2"; + }; + }; + +With signed images, nothing protects against this. Whether it gains an +advantage for the attacker is debatable, but it is not secure. + +To solve this problem, we support signed configurations. In this case it +is the configurations that are signed, not the image. Each image has its +own hash, and we include the hash in the configuration signature. + +So the above example is adjusted to look like this:: + + / { + images { + kernel-1 { + data = <data for kernel1> + hash-1 { + algo = "sha256"; + value = <...kernel hash 1...> + }; + }; + kernel-2 { + data = <data for kernel2> + hash-1 { + algo = "sha256"; + value = <...kernel hash 2...> + }; + }; + fdt-1 { + data = <data for fdt1>; + hash-1 { + algo = "sha256"; + value = <...fdt hash 1...> + }; + }; + fdt-2 { + data = <data for fdt2>; + hash-1 { + algo = "sha256"; + value = <...fdt hash 2...> + }; + }; + }; + configurations { + default = "conf-1"; + conf-1 { + kernel = "kernel-1"; + fdt = "fdt-1"; + signature-1 { + algo = "sha256,rsa2048"; + value = <...conf 1 signature...>; + }; + }; + conf-2 { + kernel = "kernel-2"; + fdt = "fdt-2"; + signature-1 { + algo = "sha256,rsa2048"; + value = <...conf 1 signature...>; + }; + }; + }; + }; + + +You can see that we have added hashes for all images (since they are no +longer signed), and a signature to each configuration. In the above example, +mkimage will sign configurations/conf-1, the kernel and fdt that are +pointed to by the configuration (/images/kernel-1, /images/kernel-1/hash-1, +/images/fdt-1, /images/fdt-1/hash-1) and the root structure of the image +(so that it isn't possible to add or remove root nodes). The signature is +written into /configurations/conf-1/signature-1/value. It can easily be +verified later even if the FIT has been signed with other keys in the +meantime. + + +Details +------- +The signature node contains a property ('hashed-nodes') which lists all the +nodes that the signature was made over. The image is walked in order and each +tag processed as follows: + +DTB_BEGIN_NODE + The tag and the following name are included in the signature + if the node or its parent are present in 'hashed-nodes' + +DTB_END_NODE + The tag is included in the signature if the node or its parent + are present in 'hashed-nodes' + +DTB_PROPERTY + The tag, the length word, the offset in the string table, and + the data are all included if the current node is present in 'hashed-nodes' + and the property name is not 'data'. + +DTB_END + The tag is always included in the signature. + +DTB_NOP + The tag is included in the signature if the current node is present + in 'hashed-nodes' + +In addition, the signature contains a property 'hashed-strings' which contains +the offset and length in the string table of the strings that are to be +included in the signature (this is done last). + +IMPORTANT: To verify the signature outside u-boot, it is vital to not only +calculate the hash of the image and verify the signature with that, but also to +calculate the hashes of the kernel, fdt, and ramdisk images and check those +match the hash values in the corresponding 'hash*' subnodes. + + +Verification +------------ +FITs are verified when loaded. After the configuration is selected a list +of required images is produced. If there are 'required' public keys, then +each image must be verified against those keys. This means that every image +that might be used by the target needs to be signed with 'required' keys. + +This happens automatically as part of a bootm command when FITs are used. + +For Signed Configurations, the default verification behavior can be changed by +the following optional property in /signature node in U-Boot's control FDT. + +required-mode + Valid values are "any" to allow verified boot to succeed if + the selected configuration is signed by any of the 'required' keys, and "all" + to allow verified boot to succeed if the selected configuration is signed by + all of the 'required' keys. + +This property can be added to a binary device tree using fdtput as shown in +below examples:: + + fdtput -t s control.dtb /signature required-mode any + fdtput -t s control.dtb /signature required-mode all + + +Enabling FIT Verification +------------------------- +In addition to the options to enable FIT itself, the following CONFIGs must +be enabled: + +CONFIG_FIT_SIGNATURE + enable signing and verification in FITs + +CONFIG_RSA + enable RSA algorithm for signing + +CONFIG_ECDSA + enable ECDSA algorithm for signing + +WARNING: When relying on signed FIT images with required signature check +the legacy image format is default disabled by not defining +CONFIG_LEGACY_IMAGE_FORMAT + + +Testing +------- + +An easy way to test signing and verification is to use the test script +provided in test/vboot/vboot_test.sh. This uses sandbox (a special version +of U-Boot which runs under Linux) to show the operation of a 'bootm' +command loading and verifying images. + +A sample run is show below:: + + $ make O=sandbox sandbox_config + $ make O=sandbox + $ O=sandbox ./test/vboot/vboot_test.sh + + +Simple Verified Boot Test +------------------------- + +Please see :doc:`verified-boot` for more information:: + + /home/hs/ids/u-boot/sandbox/tools/mkimage -D -I dts -O dtb -p 2000 + Build keys + do sha1 test + Build FIT with signed images + Test Verified Boot Run: unsigned signatures:: OK + Sign images + Test Verified Boot Run: signed images: OK + Build FIT with signed configuration + Test Verified Boot Run: unsigned config: OK + Sign images + Test Verified Boot Run: signed config: OK + check signed config on the host + Signature check OK + OK + Test Verified Boot Run: signed config: OK + Test Verified Boot Run: signed config with bad hash: OK + do sha256 test + Build FIT with signed images + Test Verified Boot Run: unsigned signatures:: OK + Sign images + Test Verified Boot Run: signed images: OK + Build FIT with signed configuration + Test Verified Boot Run: unsigned config: OK + Sign images + Test Verified Boot Run: signed config: OK + check signed config on the host + Signature check OK + OK + Test Verified Boot Run: signed config: OK + Test Verified Boot Run: signed config with bad hash: OK + + Test passed + + +Software signing: keydir vs keyfile +----------------------------------- + +In the simplest case, signing is done by giving mkimage the 'keyfile'. This is +the path to a file containing the signing key. + +The alternative is to pass the 'keydir' argument. In this case the filename of +the key is derived from the 'keydir' and the "key-name-hint" property in the +FIT. In this case the "key-name-hint" property is mandatory, and the key must +exist in "<keydir>/<key-name-hint>.<ext>" Here the extension "ext" is +specific to the signing algorithm. + + +Hardware Signing with PKCS#11 or with HSM +----------------------------------------- + +Securely managing private signing keys can challenging, especially when the +keys are stored on the file system of a computer that is connected to the +Internet. If an attacker is able to steal the key, they can sign malicious FIT +images which will appear genuine to your devices. + +An alternative solution is to keep your signing key securely stored on hardware +device like a smartcard, USB token or Hardware Security Module (HSM) and have +them perform the signing. PKCS#11 is standard for interfacing with these crypto +device. + +Requirements: + - Smartcard/USB token/HSM which can work with some openssl engine + - openssl + +For pkcs11 engine usage: + - libp11 (provides pkcs11 engine) + - p11-kit (recommended to simplify setup) + - opensc (for smartcards and smartcard like USB devices) + - gnutls (recommended for key generation, p11tool) + +For generic HSMs respective openssl engine must be installed and locateable by +openssl. This may require setting up LD_LIBRARY_PATH if engine is not installed +to openssl's default search paths. + +PKCS11 engine support forms "key id" based on "keydir" and with +"key-name-hint". "key-name-hint" is used as "object" name (if not defined in +keydir). "keydir" (if defined) is used to define (prefix for) which PKCS11 source +is being used for lookup up for the key. + +PKCS11 engine key ids + "pkcs11:<keydir>;object=<key-name-hint>;type=<public|private>" + +or, if keydir contains "object=" + "pkcs11:<keydir>;type=<public|private>" + +or + "pkcs11:object=<key-name-hint>;type=<public|private>", + +Generic HSM engine support forms "key id" based on "keydir" and with +"key-name-hint". If "keydir" is specified for mkimage it is used as a prefix in +"key id" and is appended with "key-name-hint". + +Generic engine key ids: + "<keydir><key-name-hint>" + +or + "< key-name-hint>" + +In order to set the pin in the HSM, an environment variable "MKIMAGE_SIGN_PIN" +can be specified. + +The following examples use the Nitrokey Pro using pkcs11 engine. Instructions +for other devices may vary. + +Notes on pkcs11 engine setup: + +Make sure p11-kit, opensc are installed and that p11-kit is setup to use opensc. +/usr/share/p11-kit/modules/opensc.module should be present on your system. + + +Generating Keys On the Nitrokey:: + + $ gpg --card-edit + + Reader ...........: Nitrokey Nitrokey Pro (xxxxxxxx0000000000000000) 00 00 + Application ID ...: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + Version ..........: 2.1 + Manufacturer .....: ZeitControl + Serial number ....: xxxxxxxx + Name of cardholder: [not set] + Language prefs ...: de + Sex ..............: unspecified + URL of public key : [not set] + Login data .......: [not set] + Signature PIN ....: forced + Key attributes ...: rsa2048 rsa2048 rsa2048 + Max. PIN lengths .: 32 32 32 + PIN retry counter : 3 0 3 + Signature counter : 0 + Signature key ....: [none] + Encryption key....: [none] + Authentication key: [none] + General key info..: [none] + + gpg/card> generate + Make off-card backup of encryption key? (Y/n) n + + Please note that the factory settings of the PINs are + PIN = '123456' Admin PIN = '12345678' + You should change them using the command --change-pin + + What keysize do you want for the Signature key? (2048) 4096 + The card will now be re-configured to generate a key of 4096 bits + Note: There is no guarantee that the card supports the requested size. + If the key generation does not succeed, please check the + documentation of your card to see what sizes are allowed. + What keysize do you want for the Encryption key? (2048) 4096 + The card will now be re-configured to generate a key of 4096 bits + What keysize do you want for the Authentication key? (2048) 4096 + The card will now be re-configured to generate a key of 4096 bits + Please specify how long the key should be valid. + 0 = key does not expire + <n> = key expires in n days + <n>w = key expires in n weeks + <n>m = key expires in n months + <n>y = key expires in n years + Key is valid for? (0) + Key does not expire at all + Is this correct? (y/N) y + + GnuPG needs to construct a user ID to identify your key. + + Real name: John Doe + Email address: john.doe@email.com + Comment: + You selected this USER-ID: + "John Doe <john.doe@email.com>" + + Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o + + +Using p11tool to get the token URL: + +Depending on system configuration, gpg-agent may need to be killed first:: + + $ p11tool --provider /usr/lib/opensc-pkcs11.so --list-tokens + Token 0: + URL: pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29 + Label: OpenPGP card (User PIN (sig)) + Type: Hardware token + Manufacturer: ZeitControl + Model: PKCS#15 emulated + Serial: 000xxxxxxxxx + Module: (null) + + + Token 1: + URL: pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%29 + Label: OpenPGP card (User PIN) + Type: Hardware token + Manufacturer: ZeitControl + Model: PKCS#15 emulated + Serial: 000xxxxxxxxx + Module: (null) + +Use the portion of the signature token URL after "pkcs11:" as the keydir argument (-k) to mkimage below. + + +Use the URL of the token to list the private keys:: + + $ p11tool --login --provider /usr/lib/opensc-pkcs11.so --list-privkeys \ + "pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29" + Token 'OpenPGP card (User PIN (sig))' with URL 'pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29' requires user PIN + Enter PIN: + Object 0: + URL: pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29;id=%01;object=Signature%20key;type=private + Type: Private key + Label: Signature key + Flags: CKA_PRIVATE; CKA_NEVER_EXTRACTABLE; CKA_SENSITIVE; + ID: 01 + +Use the label, in this case "Signature key" as the key-name-hint in your FIT. + +Create the fitImage:: + + $ ./tools/mkimage -f fit-image.its fitImage + + +Sign the fitImage with the hardware key:: + + $ ./tools/mkimage -F -k \ + "pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29" \ + -K u-boot.dtb -N pkcs11 -r fitImage + + +Future Work +----------- + +- Roll-back protection using a TPM is done using the tpm command. This can + be scripted, but we might consider a default way of doing this, built into + bootm. + + +Possible Future Work +-------------------- + +- More sandbox tests for failure modes +- Passwords for keys/certificates +- Perhaps implement OAEP +- Enhance bootm to permit scripted signature verification (so that a script + can verify an image but not actually boot it) + + +.. sectionauthor:: Simon Glass <sjg@chromium.org>, 1-1-13 diff --git a/doc/usage/fit/source_file_format.rst b/doc/usage/fit/source_file_format.rst new file mode 100644 index 00000000000..2bd8e792350 --- /dev/null +++ b/doc/usage/fit/source_file_format.rst @@ -0,0 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Flattened Image Tree (FIT) Format +================================= + +FIT format documentation has been moved to +`a separate project <https://fitspec.osfw.foundation/>`_. Updates to the +format/specification should be submitted there. diff --git a/doc/usage/fit/uefi.rst b/doc/usage/fit/uefi.rst new file mode 100644 index 00000000000..3bbacb5cad0 --- /dev/null +++ b/doc/usage/fit/uefi.rst @@ -0,0 +1,72 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +UEFI +==== + +Example FIT image description file demonstrating the usage of the +bootm command to launch UEFI binaries. + +Two boot configurations are available to enable booting GRUB2 on QEMU, +the former uses a FDT blob contained in the FIT image, while the later +relies on the FDT provided by the board emulator. + +:: + + /dts-v1/; + + / { + description = "GRUB2 EFI and QEMU FDT blob"; + #address-cells = <1>; + + images { + efi-grub { + description = "GRUB EFI Firmware"; + data = /incbin/("bootarm.efi"); + type = "kernel_noload"; + arch = "arm"; + os = "efi"; + compression = "none"; + load = <0x0>; + entry = <0x0>; + hash-1 { + algo = "sha256"; + }; + }; + + fdt-qemu { + description = "QEMU DTB"; + data = /incbin/("qemu-arm.dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + hash-1 { + algo = "sha256"; + }; + }; + }; + + configurations { + default = "config-grub-fdt"; + + config-grub-fdt { + description = "GRUB EFI Boot w/ FDT"; + kernel = "efi-grub"; + fdt = "fdt-qemu"; + signature-1 { + algo = "sha256,rsa2048"; + key-name-hint = "dev"; + sign-images = "kernel", "fdt"; + }; + }; + + config-grub-nofdt { + description = "GRUB EFI Boot w/o FDT"; + kernel = "efi-grub"; + signature-1 { + algo = "sha256,rsa2048"; + key-name-hint = "dev"; + sign-images = "kernel"; + }; + }; + }; + }; diff --git a/doc/usage/fit/update3.rst b/doc/usage/fit/update3.rst new file mode 100644 index 00000000000..24235801470 --- /dev/null +++ b/doc/usage/fit/update3.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Automatic software update: multiple files +========================================= + +:: + + /dts-v1/; + + / { + description = "Automatic software updates: kernel, ramdisk, FDT"; + #address-cells = <1>; + + images { + update-1 { + description = "Linux kernel binary"; + data = /incbin/("./vmlinux.bin.gz"); + compression = "none"; + type = "firmware"; + load = <FF700000>; + hash-1 { + algo = "sha256"; + }; + }; + update-2 { + description = "Ramdisk image"; + data = /incbin/("./ramdisk_image.gz"); + compression = "none"; + type = "firmware"; + load = <FF8E0000>; + hash-1 { + algo = "sha256"; + }; + }; + + update-3 { + description = "FDT blob"; + data = /incbin/("./blob.fdt"); + compression = "none"; + type = "firmware"; + load = <FFAC0000>; + hash-1 { + algo = "sha256"; + }; + }; + }; + }; diff --git a/doc/usage/fit/update_uboot.rst b/doc/usage/fit/update_uboot.rst new file mode 100644 index 00000000000..811d008d13d --- /dev/null +++ b/doc/usage/fit/update_uboot.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Automatic software update +========================= + +Make sure the flashing addresses ('load' prop) is correct for your board! + +:: + + /dts-v1/; + + / { + description = "Automatic U-Boot update"; + #address-cells = <1>; + + images { + update-1 { + description = "U-Boot binary"; + data = /incbin/("./u-boot.bin"); + compression = "none"; + type = "firmware"; + load = <0xFFFC0000>; + hash-1 { + algo = "sha256"; + }; + }; + }; + }; diff --git a/doc/usage/fit/verified-boot.rst b/doc/usage/fit/verified-boot.rst new file mode 100644 index 00000000000..301207711db --- /dev/null +++ b/doc/usage/fit/verified-boot.rst @@ -0,0 +1,107 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot Verified Boot +==================== + +Introduction +------------ + +Verified boot here means the verification of all software loaded into a +machine during the boot process to ensure that it is authorised and correct +for that machine. + +Verified boot extends from the moment of system reset to as far as you wish +into the boot process. An example might be loading U-Boot from read-only +memory, then loading a signed kernel, then using the kernel's dm-verity +driver to mount a signed root filesystem. + +A key point is that it is possible to field-upgrade the software on machines +which use verified boot. Since the machine will only run software that has +been correctly signed, it is safe to read software from an updatable medium. +It is also possible to add a secondary signed firmware image, in read-write +memory, so that firmware can easily be upgraded in a secure manner. + + +Signing +------- + +Verified boot uses cryptographic algorithms to 'sign' software images. +Images are signed using a private key known only to the signer, but can +be verified using a public key. As its name suggests the public key can be +made available without risk to the verification process. The private and +public keys are mathematically related. For more information on how this +works look up "public key cryptography" and "RSA" (a particular algorithm). + +The signing and verification process looks something like this:: + + + Signing Verification + ======= ============ + + +--------------+ * + | RSA key pair | * +---------------+ + | .key .crt | * | Public key in | + +--------------+ +------> public key ----->| trusted place | + | | * +---------------+ + | | * | + v | * v + +---------+ | * +--------------+ + | |---------+ * | | + | signer | * | U-Boot | + | |---------+ * | signature |--> yes/no + +---------+ | * | verification | + ^ | * | | + | | * +--------------+ + | | * ^ + +----------+ | * | + | Software | +----> signed image -------------+ + | image | * + +----------+ * + + +The signature algorithm relies only on the public key to do its work. Using +this key it checks the signature that it finds in the image. If it verifies +then we know that the image is OK. + +The public key from the signer allows us to verify and therefore trust +software from updatable memory. + +It is critical that the public key be secure and cannot be tampered with. +It can be stored in read-only memory, or perhaps protected by other on-chip +crypto provided by some modern SOCs. If the public key can be changed, then +the verification is worthless. + + +Chaining Images +--------------- + +The above method works for a signer providing images to a run-time U-Boot. +It is also possible to extend this scheme to a second level, like this: + +#. Master private key is used by the signer to sign a first-stage image. +#. Master public key is placed in read-only memory. +#. Secondary private key is created and used to sign second-stage images. +#. Secondary public key is placed in first stage images +#. We use the master public key to verify the first-stage image. We then + use the secondary public key in the first-stage image to verify the second- + state image. +#. This chaining process can go on indefinitely. It is recommended to use a + different key at each stage, so that a compromise in one place will not + affect the whole change. + + +Flattened Image Tree (FIT) +-------------------------- + +The FIT format is already widely used in U-Boot. It is a flattened device +tree (FDT) in a particular format, with images contained within. FITs +include hashes to verify images, so it is relatively straightforward to +add signatures as well. + +The public key can be stored in U-Boot's CONFIG_OF_CONTROL device tree in +a standard place. Then when a FIT is loaded it can be verified using that +public key. Multiple keys and multiple signatures are supported. + +See :doc:`signature` for more information. + +.. sectionauthor:: Simon Glass <sjg@chromium.org> 1-1-13 diff --git a/doc/usage/fit/x86-fit-boot.rst b/doc/usage/fit/x86-fit-boot.rst new file mode 100644 index 00000000000..9e3e32204d5 --- /dev/null +++ b/doc/usage/fit/x86-fit-boot.rst @@ -0,0 +1,269 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Booting Linux on x86 with FIT +============================= + +Background +---------- + +Generally Linux x86 uses its own very complex booting method. There is a setup +binary which contains all sorts of parameters and a compressed self-extracting +binary for the kernel itself, often with a small built-in serial driver to +display decompression progress. + +The x86 CPU has various processor modes. I am no expert on these, but my +understanding is that an x86 CPU (even a really new one) starts up in a 16-bit +'real' mode where only 1MB of memory is visible, moves to 32-bit 'protected' +mode where 4GB is visible (or more with special memory access techniques) and +then to 64-bit 'long' mode if 64-bit execution is required. + +Partly the self-extracting nature of Linux was introduced to cope with boot +loaders that were barely capable of loading anything. Even changing to 32-bit +mode was something of a challenge, so putting this logic in the kernel seemed +to make sense. + +Bit by bit more and more logic has been added to this post-boot pre-Linux +wrapper: + +- Changing to 32-bit mode +- Decompression +- Serial output (with drivers for various chips) +- Load address randomisation +- Elf loader complete with relocation (for the above) +- Random number generator via 3 methods (again for the above) +- Some sort of EFI mini-loader (1000+ glorious lines of code) +- Locating and tacking on a device tree and ramdisk + +To my mind, if you sit back and look at things from first principles, this +doesn't make a huge amount of sense. Any boot loader worth its salts already +has most of the above features and more besides. The boot loader already knows +the layout of memory, has a serial driver, can decompress things, includes an +ELF loader and supports device tree and ramdisks. The decision to duplicate +all these features in a Linux wrapper caters for the lowest common +denominator: a boot loader which consists of a BIOS call to load something off +disk, followed by a jmp instruction. + +(Aside: On ARM systems, we worry that the boot loader won't know where to load +the kernel. It might be easier to just provide that information in the image, +or in the boot loader rather than adding a self-relocator to put it in the +right place. Or just use ELF? + +As a result, the x86 kernel boot process is needlessly complex. The file +format is also complex, and obfuscates the contents to a degree that it is +quite a challenge to extract anything from it. This bzImage format has become +so prevalent that is actually isn't possible to produce the 'raw' kernel build +outputs with the standard Makefile (as it is on ARM for example, at least at +the time of writing). + +This document describes an alternative boot process which uses simple raw +images which are loaded into the right place by the boot loader and then +executed. + + +Build the kernel +---------------- + +Note: these instructions assume a 32-bit kernel. U-Boot also supports directly +booting a 64-bit kernel by jumping into 64-bit mode first (see below). + +You can build the kernel as normal with 'make'. This will create a file called +'vmlinux'. This is a standard ELF file and you can look at it if you like:: + + $ objdump -h vmlinux + + vmlinux: file format elf32-i386 + + Sections: + Idx Name Size VMA LMA File off Algn + 0 .text 00416850 81000000 01000000 00001000 2**5 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, CODE + 1 .notes 00000024 81416850 01416850 00417850 2**2 + CONTENTS, ALLOC, LOAD, READONLY, CODE + 2 __ex_table 00000c50 81416880 01416880 00417880 2**3 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 3 .rodata 00154b9e 81418000 01418000 00419000 2**5 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 4 __bug_table 0000597c 8156cba0 0156cba0 0056dba0 2**0 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 5 .pci_fixup 00001b80 8157251c 0157251c 0057351c 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 6 .tracedata 00000024 8157409c 0157409c 0057509c 2**0 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 7 __ksymtab 00007ec0 815740c0 015740c0 005750c0 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 8 __ksymtab_gpl 00004a28 8157bf80 0157bf80 0057cf80 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 9 __ksymtab_strings 0001d6fc 815809a8 015809a8 005819a8 2**0 + CONTENTS, ALLOC, LOAD, READONLY, DATA + 10 __init_rodata 00001c3c 8159e0a4 0159e0a4 0059f0a4 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 11 __param 00000ff0 8159fce0 0159fce0 005a0ce0 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 12 __modver 00000330 815a0cd0 015a0cd0 005a1cd0 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 13 .data 00063000 815a1000 015a1000 005a2000 2**12 + CONTENTS, ALLOC, LOAD, RELOC, DATA + 14 .init.text 0002f104 81604000 01604000 00605000 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, CODE + 15 .init.data 00040cdc 81634000 01634000 00635000 2**12 + CONTENTS, ALLOC, LOAD, RELOC, DATA + 16 .x86_cpu_dev.init 0000001c 81674cdc 01674cdc 00675cdc 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 17 .altinstructions 0000267c 81674cf8 01674cf8 00675cf8 2**0 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 18 .altinstr_replacement 00000942 81677374 01677374 00678374 2**0 + CONTENTS, ALLOC, LOAD, READONLY, CODE + 19 .iommu_table 00000014 81677cb8 01677cb8 00678cb8 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 20 .apicdrivers 00000004 81677cd0 01677cd0 00678cd0 2**2 + CONTENTS, ALLOC, LOAD, RELOC, DATA + 21 .exit.text 00001a80 81677cd8 01677cd8 00678cd8 2**0 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, CODE + 22 .data..percpu 00007880 8167a000 0167a000 0067b000 2**12 + CONTENTS, ALLOC, LOAD, RELOC, DATA + 23 .smp_locks 00003000 81682000 01682000 00683000 2**2 + CONTENTS, ALLOC, LOAD, RELOC, READONLY, DATA + 24 .bss 000a1000 81685000 01685000 00686000 2**12 + ALLOC + 25 .brk 00424000 81726000 01726000 00686000 2**0 + ALLOC + 26 .comment 00000049 00000000 00000000 00686000 2**0 + CONTENTS, READONLY + 27 .GCC.command.line 0003e055 00000000 00000000 00686049 2**0 + CONTENTS, READONLY + 28 .debug_aranges 0000f4c8 00000000 00000000 006c40a0 2**3 + CONTENTS, RELOC, READONLY, DEBUGGING + 29 .debug_info 0440b0df 00000000 00000000 006d3568 2**0 + CONTENTS, RELOC, READONLY, DEBUGGING + 30 .debug_abbrev 0022a83b 00000000 00000000 04ade647 2**0 + CONTENTS, READONLY, DEBUGGING + 31 .debug_line 004ead0d 00000000 00000000 04d08e82 2**0 + CONTENTS, RELOC, READONLY, DEBUGGING + 32 .debug_frame 0010a960 00000000 00000000 051f3b90 2**2 + CONTENTS, RELOC, READONLY, DEBUGGING + 33 .debug_str 001b442d 00000000 00000000 052fe4f0 2**0 + CONTENTS, READONLY, DEBUGGING + 34 .debug_loc 007c7fa9 00000000 00000000 054b291d 2**0 + CONTENTS, RELOC, READONLY, DEBUGGING + 35 .debug_ranges 00098828 00000000 00000000 05c7a8c8 2**3 + CONTENTS, RELOC, READONLY, DEBUGGING + +There is also the setup binary mentioned earlier. This is at +arch/x86/boot/setup.bin and is about 12KB in size. It includes the command +line and various settings need by the kernel. Arguably the boot loader should +provide all of this also, but setting it up is some complex that the kernel +helps by providing a head start. + +As you can see the code loads to address 0x01000000 and everything else +follows after that. We could load this image using the 'bootelf' command but +we would still need to provide the setup binary. This is not supported by +U-Boot although I suppose you could mostly script it. This would permit the +use of a relocatable kernel. + +All we need to boot is the vmlinux file and the setup.bin file. + + +Create a FIT +------------ + +To create a FIT you will need a source file describing what should go in the +FIT. See kernel.its for an example for x86 and also instructions on setting +the 'arch' value for booting 64-bit kernels if desired. Put this into a file +called image.its. + +Note that setup is loaded to the special address of 0x90000 (a special address +you just have to know) and the kernel is loaded to 0x01000000 (the address you +saw above). This means that you will need to load your FIT to a different +address so that U-Boot doesn't overwrite it when decompressing. Something like +0x02000000 will do so you can set CONFIG_SYS_LOAD_ADDR to that. + +In that example the kernel is compressed with lzo. Also we need to provide a +flat binary, not an ELF. So the steps needed to set things are are:: + + # Create a flat binary + objcopy -O binary vmlinux vmlinux.bin + + # Compress it into LZO format + lzop vmlinux.bin + + # Build a FIT image + mkimage -f image.its image.fit + +(be careful to run the mkimage from your U-Boot tools directory since it +will have x86_setup support.) + +You can take a look at the resulting fit file if you like:: + + $ dumpimage -l image.fit + FIT description: Simple image with single Linux kernel on x86 + Created: Tue Oct 7 10:57:24 2014 + Image 0 (kernel) + Description: Vanilla Linux kernel + Created: Tue Oct 7 10:57:24 2014 + Type: Kernel Image + Compression: lzo compressed + Data Size: 4591767 Bytes = 4484.15 kB = 4.38 MB + Architecture: Intel x86 + OS: Linux + Load Address: 0x01000000 + Entry Point: 0x00000000 + Hash algo: sha256 + Hash value: 4bbf49981ade163ed089f8525236fedfe44508e9b02a21a48294a96a1518107b + Image 1 (setup) + Description: Linux setup.bin + Created: Tue Oct 7 10:57:24 2014 + Type: x86 setup.bin + Compression: uncompressed + Data Size: 12912 Bytes = 12.61 kB = 0.01 MB + Hash algo: sha256 + Hash value: 6aa50c2e0392cb119cdf0971dce8339f100608ed3757c8200b0e39e889e432d2 + Default Configuration: 'config-1' + Configuration 0 (config-1) + Description: Boot Linux kernel + Kernel: kernel + + +Booting the FIT +--------------- + +To make it boot you need to load it and then use 'bootm' to boot it. A +suitable script to do this from a network server is:: + + bootp + tftp image.fit + bootm + +This will load the image from the network and boot it. The command line (from +the 'bootargs' environment variable) will be passed to the kernel. + +If you want a ramdisk you can add it as normal with FIT. If you want a device +tree then x86 doesn't normally use those - it has ACPI instead. + + +Why Bother? +----------- + +#. It demystifies the process of booting an x86 kernel +#. It allows use of the standard U-Boot boot file format +#. It allows U-Boot to perform decompression - problems will provide an error + message and you are still in the boot loader. It is possible to investigate. +#. It avoids all the pre-loader code in the kernel which is quite complex to + follow +#. You can use verified/secure boot and other features which haven't yet been + added to the pre-Linux +#. It makes x86 more like other architectures in the way it boots a kernel. + You can potentially use the same file format for the kernel, and the same + procedure for building and packaging it. + + +References +---------- + +In the Linux kernel, Documentation/x86/boot.txt defines the boot protocol for +the kernel including the setup.bin format. This is handled in U-Boot in +arch/x86/lib/zimage.c and arch/x86/lib/bootm.c. + +Various files in the same directory as this file describe the FIT format. + + +.. sectionauthor:: Simon Glass <sjg@chromium.org> 7-Oct-2014 diff --git a/doc/usage/index.rst b/doc/usage/index.rst new file mode 100644 index 00000000000..49b354e6ffd --- /dev/null +++ b/doc/usage/index.rst @@ -0,0 +1,131 @@ +Use U-Boot +========== + +.. toctree:: + :maxdepth: 1 + + spl_boot + blkmap + dfu + environment + fdt_overlays + fit/index + netconsole + partitions + cmdline + semihosting + measured_boot + +Shell commands +-------------- + +.. toctree:: + :maxdepth: 1 + + cmd/acpi + cmd/addrmap + cmd/armffa + cmd/askenv + cmd/base + cmd/bdinfo + cmd/bind + cmd/blkcache + cmd/bootd + cmd/bootdev + cmd/bootefi + cmd/bootelf + cmd/bootflow + cmd/booti + cmd/bootm + cmd/bootmenu + cmd/bootmeth + cmd/bootz + cmd/button + cmd/cat + cmd/cbsysinfo + cmd/cedit + cmd/cli + cmd/cls + cmd/cmp + cmd/coninfo + cmd/conitrace + cmd/cp + cmd/cyclic + cmd/dm + cmd/ebtupdate + cmd/echo + cmd/efi + cmd/eficonfig + cmd/env + cmd/event + cmd/exception + cmd/exit + cmd/extension + cmd/false + cmd/fatinfo + cmd/fatload + cmd/fdt + cmd/font + cmd/for + cmd/fwu_mdata + cmd/gpio + cmd/gpt + cmd/history + cmd/host + cmd/if + cmd/itest + cmd/imxtract + cmd/load + cmd/loadb + cmd/loadm + cmd/loads + cmd/loadx + cmd/loady + cmd/mbr + cmd/md + cmd/mmc + cmd/mtest + cmd/mtrr + cmd/panic + cmd/part + cmd/pause + cmd/pinmux + cmd/printenv + cmd/pstore + cmd/qfw + cmd/read + cmd/reset + cmd/rng + cmd/saves + cmd/sbi + cmd/scmi + cmd/scp03 + cmd/seama + cmd/setexpr + cmd/sf + cmd/size + cmd/sleep + cmd/sm + cmd/smbios + cmd/sound + cmd/source + cmd/temperature + cmd/tftpput + cmd/trace + cmd/true + cmd/ums + cmd/unbind + cmd/ut + cmd/wdt + cmd/wget + cmd/write + cmd/xxd + +Booting OS +---------- + +.. toctree:: + :maxdepth: 1 + + os/plan9 + os/vxworks diff --git a/doc/usage/measured_boot.rst b/doc/usage/measured_boot.rst new file mode 100644 index 00000000000..05c439e9ac6 --- /dev/null +++ b/doc/usage/measured_boot.rst @@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Measured Boot +============= + +U-Boot can perform a measured boot, the process of hashing various components +of the boot process, extending the results in the TPM and logging the +component's measurement in memory for the operating system to consume. + +The functionality is available when booting via the EFI subsystem or 'bootm' +command. + +UEFI measured boot +------------------ + +The EFI subsystem implements the `EFI TCG protocol +<https://trustedcomputinggroup.org/resource/tcg-efi-protocol-specification/>`_ +and the `TCG PC Client Specific Platform Firmware Profile Specification +<https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/>`_ +which defines the binaries to be measured and the corresponding PCRs to be used. + +Requirements +~~~~~~~~~~~~ + +* A hardware TPM 2.0 supported by an enabled U-Boot driver +* CONFIG_EFI_TCG2_PROTOCOL=y +* CONFIG_EFI_TCG2_PROTOCOL_EVENTLOG_SIZE=y +* optional CONFIG_EFI_TCG2_PROTOCOL_MEASURE_DTB=y will measure the loaded DTB + in PCR 1 + +Legacy measured boot +-------------------- + +The commands booti, bootm, and bootz can be used for measured boot +using the legacy entry point of the Linux kernel. + +By default, U-Boot will measure the operating system (linux) image, the +initrd image, and the "bootargs" environment variable. By enabling +CONFIG_MEASURE_DEVICETREE, U-Boot will also measure the devicetree image in PCR1. + +The operating system typically would verify that the hashes found in the +TPM PCRs match the contents of the event log. This can further be checked +against the hash results of previous boots. + +Requirements +~~~~~~~~~~~~ + +* A hardware TPM 2.0 supported by an enabled U-Boot driver +* CONFIG_TPMv2=y +* CONFIG_MEASURED_BOOT=y +* Device-tree configuration of the TPM device to specify the memory area + for event logging. The TPM device node must either contain a phandle to + a reserved memory region or "linux,sml-base" and "linux,sml-size" + indicating the address and size of the memory region. An example can be + found in arch/sandbox/dts/test.dts +* The operating system must also be configured to use the memory regions + specified in the U-Boot device-tree in order to make use of the event + log. diff --git a/doc/usage/netconsole.rst b/doc/usage/netconsole.rst new file mode 100644 index 00000000000..df27b78342f --- /dev/null +++ b/doc/usage/netconsole.rst @@ -0,0 +1,144 @@ +Network console +=============== + +In U-Boot, we implemented the networked console via the standard +"devices" mechanism, which means that you can switch between the +serial and network input/output devices by adjusting the 'stdin', +'stdout', and 'stderr' environment variables. To switch to the +networked console, set either of these variables to "nc". Input and +output can be switched independently. + +The default buffer size can be overridden by setting +CFG_NETCONSOLE_BUFFER_SIZE. + +We use an environment variable 'ncip' to set the IP address and the +port of the destination. The format is <ip_addr>:<port>. If <port> is +omitted, the value of 6666 is used. If the env var doesn't exist, the +broadcast address and port 6666 are used. If it is set to an IP +address of 0 (or 0.0.0.0) then no messages are sent to the network. +The source / listening port can be configured separately by setting +the 'ncinport' environment variable and the destination port can be +configured by setting the 'ncoutport' environment variable. Note that +you need to set up the network interface (e.g. using DHCP) before it +can be used for network console. + +For example, if your server IP is 192.168.1.1, you could use: + +.. prompt:: bash => + + env set nc 'env set stdout nc; env set stderr nc; env set stdin nc' + env set ncip '192.168.1.1' + env save + run nc + +On the host side, please use this script to access the console + +.. code-block:: bash + + tools/netconsole <ip> [port] + +The script uses netcat to talk to the board over UDP. It requires you to +specify the target IP address (or host name, assuming DNS is working). The +script can be interrupted by pressing ^T (CTRL-T). + +Be aware that in some distributives (Fedora Core 5 at least) +usage of nc has been changed and -l and -p options are considered +as mutually exclusive. If nc complains about options provided, +you can just remove the -p option from the script. + +It turns out that 'netcat' cannot be used to listen to broadcast +packets. We developed our own tool 'ncb' (see tools directory) that +listens to broadcast packets on a given port and dumps them to the +standard output. It will be built when compiling for a board which +has CONFIG_NETCONSOLE defined. If the netconsole script can find it +in PATH or in the same directory, it will be used instead. + +For Linux, the network-based console needs special configuration. +Minimally, the host IP address needs to be specified. This can be +done either via the kernel command line, or by passing parameters +while loading the netconsole.o module (when used in a loadable module +configuration). Please refer to Documentation/networking/logging.txt +file for the original Ingo Molnar's documentation on how to pass +parameters to the loadable module. + +The format of the kernel command line parameter (for the static +configuration) is as follows + +.. code-block:: bash + + netconsole=[src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr] + +where + +src-port + source for UDP packets (defaults to 6665) + +src-ip + source IP to use (defaults to the interface's address) + +dev + network interface (defaults to eth0) + +tgt-port + port for logging agent (defaults to 6666) + +tgt-ip + IP address for logging agent (this is the required parameter) + +tgt-macaddr + ethernet MAC address for logging agent (defaults to broadcast) + +Examples + +.. code-block:: bash + + netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc + netconsole=@/,@192.168.3.1/ + +Please note that for the Linux networked console to work, the +ethernet interface has to be up by the time the netconsole driver is +initialized. This means that in case of static kernel configuration, +the respective Ethernet interface has to be brought up using the "IP +Autoconfiguration" kernel feature, which is usually done by defaults +in the ELDK-NFS-based environment. + +To browse the Linux network console output, use the 'netcat' tool invoked +as follows: + +.. code-block:: bash + + nc -u -l -p 6666 + +Note that unlike the U-Boot implementation the Linux netconsole is +unidirectional, i. e. you have console output only in Linux. + +Setup via environment +--------------------- + +If persistent environment is enabled in your U-Boot configuration, you +can configure the network console using the environment. For example: + +.. prompt:: bash => + + env set autoload no + env set hostname "u-boot" + env set bootdelay 5 + env set nc 'dhcp; env set stdout nc; env set stderr nc; env set stdin nc' + env set ncip '192.168.1.1' + env set preboot "${preboot}; run nc;" + env save + reset + +``autoload no`` tells the ``dhcp`` command to configure the network +interface without trying to load an image. ``hostname "u-boot"`` sets +the hostname to be sent in DHCP requests, so they are easy to +recognize in the DHCP server log. The command in ``nc`` calls ``dhcp`` +to make sure the network interface is set up before enabling +netconsole. + +Adding ``nc`` to ``preboot`` tells U-Boot to activate netconsole +before trying to find any boot options, so you can interact with it if +desired. + +``env save`` stores the settings persistently, and ``reset`` then +triggers a fresh start that will use the changed settings. diff --git a/doc/usage/os/plan9.rst b/doc/usage/os/plan9.rst new file mode 100644 index 00000000000..f91712c0094 --- /dev/null +++ b/doc/usage/os/plan9.rst @@ -0,0 +1,22 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Steven Stallion +.. June 2013 + +Plan 9 +====== + +Plan 9 from Bell Labs kernel images require additional setup to pass +configuration information to the kernel. An environment variable named +confaddr must be defined with the same value as CONFADDR (see mem.h). +Use of this facility is optional, but should be preferable to manual +configuration. + +When booting an image, arguments supplied to the bootm command will be +copied to CONFADDR. If no arguments are specified, the contents of the +bootargs environment variable will be copied. + +If no command line arguments or bootargs are defined, CONFADDR is left +uninitialized to permit manual configuration. For example, PC-style +configuration could be simulated by issuing a fatload in bootcmd:: + + # setenv bootcmd fatload mmc 0 $confaddr plan9.ini; ...; bootm diff --git a/doc/usage/os/vxworks.rst b/doc/usage/os/vxworks.rst new file mode 100644 index 00000000000..0fe33d2d34c --- /dev/null +++ b/doc/usage/os/vxworks.rst @@ -0,0 +1,124 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2013, Miao Yan <miao.yan@windriver.com> +.. Copyright (C) 2015-2018, Bin Meng <bmeng.cn@gmail.com> +.. Copyright (C) 2019, Lihua Zhao <lihua.zhao@windriver.com> + +VxWorks +======= + +This document describes the information about U-Boot loading VxWorks kernel. + +Status +------ +U-Boot supports loading VxWorks kernels via 'bootvx' and 'bootm' commands. +For booting old kernels (6.9.x) on PowerPC and ARM, and all kernel versions +on other architectures, 'bootvx' shall be used. For booting VxWorks 7 kernels +on PowerPC/ARM/RISC-V, 'bootm' shall be used. + +With CONFIG_EFI_LOADER option, it's possible to chain load a VxWorks x86 kernel +via the UEFI boot loader application for VxWorks loaded by 'bootefi' command. + +VxWorks 7 on PowerPC/ARM/RISC-V +------------------------------- +From VxWorks 7, VxWorks starts adopting device tree as its hardware description +mechanism (for PowerPC and ARM), thus requiring boot interface changes. +This section will describe the new interface. + +Since VxWorks 7 SR0640 release, VxWorks starts using Linux compatible standard +DTB for some boards. With that, the exact same bootm flow as used by Linux is +used, which includes board-specific DTB fix up. To keep backward compatibility, +only when the least significant bit of flags in bootargs is set, the standard +DTB will be used. Otherwise it falls back to the legacy bootm flow. + +For legacy bootm flow, make sure the least significant bit of flags in bootargs +is cleared. The calling convention is described below: + +For PowerPC, the calling convention of the new VxWorks entry point conforms to +the ePAPR standard, which is shown below (see ePAPR for more details): + +.. code-block:: c + + void (*kernel_entry)(fdt_addr, 0, 0, EPAPR_MAGIC, boot_IMA, 0, 0) + +For ARM, the calling convention is shown below: + +.. code-block:: c + + void (*kernel_entry)(void *fdt_addr) + +When using the Linux compatible standard DTB, the calling convention of VxWorks +entry point is exactly the same as the Linux kernel. + +For RISC-V, there is no legacy bootm flow as VxWorks always uses the same boot +interface as the Linux kernel, with the calling convention below:: + + void (*kernel_entry)(unsigned long hartid, void *fdt_addr) + +When booting a VxWorks 7 kernel (uImage format), the parameters passed to bootm +is like below:: + + bootm <kernel image address> - <device tree address> + +VxWorks bootline +---------------- +When using 'bootvx', the kernel bootline must be prepared by U-Boot at a +board-specific address before loading VxWorks. U-Boot supplies its address +via "bootaddr" environment variable. To check where the bootline should be +for a specific board, go to the VxWorks BSP for that board, and look for a +parameter called BOOT_LINE_ADRS. Assign its value to "bootaddr". A typical +value for "bootaddr" on an x86 board is 0x101200. + +If a "bootargs" variable is defined, its content will be copied to the memory +location pointed by "bootaddr" as the kernel bootline. If "bootargs" is not +there, command 'bootvx' can construct a valid bootline using the following +environments variables: bootdev, bootfile, ipaddr, netmask, serverip, +gatewayip, hostname, othbootargs. + +When using 'bootm', just define "bootargs" in the environment and U-Boot will +handle bootline fix up for the kernel dtb automatically. + +When using 'bootefi' to chain load an x86 kernel, the UEFI boot loader +application for VxWorks takes care of the kernel bootline preparation. + +Serial console +-------------- +It's very common that VxWorks BSPs configure a different baud rate for the +serial console from what is being used by U-Boot. For example, VxWorks tends +to use 9600 as the default baud rate on all x86 BSPs while U-Boot uses 115200. +Please configure both U-Boot and VxWorks to use the same baud rate, or it may +look like VxWorks hangs somewhere as nothing outputs on the serial console. + +x86-specific information +------------------------ +Before direct loading an x86 kernel via 'bootvx', one additional environment +variable need to be provided. This is "vx_phys_mem_base", which represent the +physical memory base address of VxWorks. + +Check VxWorks kernel configuration to look for LOCAL_MEM_LOCAL_ADRS. For +VxWorks 7, this is normally a virtual address and you need find out its +corresponding physical address and assign its value to "vx_phys_mem_base". + +For boards on which ACPI is not supported by U-Boot yet, VxWorks kernel must +be configured to use MP table and virtual wire interrupt mode. This requires +INCLUDE_MPTABLE_BOOT_OP and INCLUDE_VIRTUAL_WIRE_MODE to be included in a +VxWorks kernel configuration. + +Both 32-bit x86 and 64-bit x64 kernels can be loaded. + +There are two types of graphics console drivers in VxWorks. One is the 80x25 +VGA text mode driver. The other one is the EFI console bitmapped graphics mode +driver. To make these drivers function, U-Boot needs to load and run the VGA +BIOS of the graphics card first. + + - If the kernel is configured with 80x25 VGA text mode driver, + CONFIG_FRAMEBUFFER_SET_VESA_MODE must be unset in U-Boot. + - If the kernel is configured with bitmapped graphics mode driver, + CONFIG_FRAMEBUFFER_SET_VESA_MODE need remain set but care must be taken + at which VESA mode is to be set. The supported pixel format is 32-bit + RGBA, hence the available VESA mode can only be one of the following: + + * FRAMEBUFFER_VESA_MODE_10F + * FRAMEBUFFER_VESA_MODE_112 + * FRAMEBUFFER_VESA_MODE_115 + * FRAMEBUFFER_VESA_MODE_118 + * FRAMEBUFFER_VESA_MODE_11B diff --git a/doc/usage/partitions.rst b/doc/usage/partitions.rst new file mode 100644 index 00000000000..acf4573097d --- /dev/null +++ b/doc/usage/partitions.rst @@ -0,0 +1,91 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. _partitions: + +Partitions +========== + +Synopsis +-------- + +:: + + <command> <interface> [devnum][.hwpartnum][:partnum|#partname] + +Description +----------- + +Many U-Boot commands allow specifying partitions (or whole disks) using a +generic syntax. + +interface + The interface used to access the partition's device, like ``mmc`` or + ``scsi``. For a full list of supported interfaces, consult the + ``uclass_idname_str`` array in ``drivers/block/blk-uclass.c`` + +devnum + The device number. This defaults to 0. + +hwpartnum + The hardware partition number. All devices have at least one hardware + partition. On most devices, hardware partition 0 specifies the whole + device. On eMMC devices, hardware partition 0 is the user partition, + hardware partitions 1 and 2 are the boot partitions, hardware partition + 3 is the RPMB partition, and further partitions are general-purpose + user-created partitions. The default hardware partition number is 0. + +partnum + The partition number, starting from 1. The partition number 0 specifies + that the whole device is to be used as one "partition." + +partname + The partition name. This is the partition label for GPT partitions. For + MBR partitions, the following syntax is used:: + + <devtype><devletter><partnum> + + devtype + The devtype field is set in dependence of the device class: + + ======= =============== + devtype device class + ======= =============== + hd IDE or SATA + sd SCSI + usbd USB + mmcsd eMMC or SD-card + xx others + ======= =============== + + See the ``part_set_generic_name`` function in ``disk/part.c`` + for the complete list. + + devletter + The device number as an offset from ``a``. For example, device + number 2 would have a device letter of ``c``. + + partnum + The partition number. This is the same as above. + +If neither ``partname`` nor ``partnum`` is specified and there is a partition +table, then partition 1 is used. If there is no partition table, then the whole +device is used as one "partition." If none of ``devnum``, ``hwpartnum``, +``partnum``, or ``partname`` is specified, or only ``-`` is specified, then +``devnum`` defaults to the value of the ``bootdevice`` environmental variable. + +Examples +-------- + +List the root directory contents on MMC device 2, hardware partition 1, +and partition number 3:: + + ls mmc 2.1:3 / + +Load ``/kernel.itb`` to address ``0x80000000`` from SCSI device 0, hardware partition +0, and the partition labeled ``boot``:: + + load scsi #boot 0x80000000 /kernel.itb + +Print the partition UUID of the SATA device ``$bootdevice``, hardware partition +0, and partition number 0:: + + part uuid sata - diff --git a/doc/usage/semihosting.rst b/doc/usage/semihosting.rst new file mode 100644 index 00000000000..9303a6364d5 --- /dev/null +++ b/doc/usage/semihosting.rst @@ -0,0 +1,107 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2014 Broadcom Corporation. + +Semihosting +=========== + +Semihosting is ARM's way of having a real or virtual target communicate +with a host or host debugger for basic operations such as file I/O, +console I/O, etc. Please see `Arm's semihosting documentation +<https://developer.arm.com/documentation/100863/latest/>`_ for more +information. + +Platform Support +---------------- + +Versatile Express +^^^^^^^^^^^^^^^^^ + +For developing on armv8 virtual fastmodel platforms, semihosting is a +valuable tool since it allows access to image/configuration files before +eMMC or other NV media are available. + +There are two main ARM virtual Fixed Virtual Platform (FVP) models, +`Versatile Express (VE) FVP and BASE FVP +<http://www.arm.com/products/tools/models/fast-models/foundation-model.php>`_. +The initial vexpress64 U-Boot board created here runs on the VE virtual +platform using the license-free Foundation_v8 simulator. Fortunately, +the Foundation_v8 simulator also supports the BASE_FVP model which +companies can purchase licenses for and contain much more functionality. +So we can, in U-Boot, run either model by either using the VE FVP (default), +or turning on ``CONFIG_BASE_FVP`` for the more full featured model. + +Rather than create a new armv8 board similar to ``armltd/vexpress64``, add +semihosting calls to the existing one, enabled with ``CONFIG_SEMIHOSTING`` +and ``CONFIG_BASE_FVP`` both set. Also reuse the existing board config file +vexpress_aemv8.h but differentiate the two models by the presence or +absence of ``CONFIG_BASE_FVP``. This change is tested and works on both the +Foundation and Base fastmodel simulators. + +QEMU +^^^^ + +Another ARM emulator which supports semihosting is `QEMU +<https://www.qemu.org/>`_. To enable semihosting, enable +``CONFIG_SERIAL_PROBE_ALL`` when configuring U-Boot, and use +``-semihosting`` when invoking QEMU. Adding ``-nographic`` can also be +helpful. When using a semihosted serial console, QEMU will block waiting +for input. This will cause the GUI to become unresponsive. To mitigate +this, try adding ``-nographic``. For more information about building and +running QEMU, refer to the :doc:`board documentation +<../board/emulation/qemu-arm>`. + +OpenOCD +^^^^^^^ + +Any ARM platform can use semihosting with an attached debugger. One such +debugger with good support for a variety of boards and JTAG adapters is +`OpenOCD <https://openocd.org/>`_. Semihosting is not enabled by default, +so you will need to enable it:: + + $ openocd -f <your board config> -c init -c halt -c \ + 'arm semihosting enable' -c resume + +Note that enabling semihosting can only be done after attaching to the +board with ``init``, and must be done while the CPU is halted. For a more +extended example, refer to the :ref:`LS1046ARDB docs <ls1046ardb_jtag>`. + +Loading files +------------- + +The semihosting code adds a "semihosting filesystem":: + + load hostfs - <address> <image> + +That will load an image from the host filesystem into RAM at the specified +address. If you are using U-Boot SPL, you can also use ``BOOT_DEVICE_SMH`` +which will load ``CONFIG_SPL_FS_LOAD_PAYLOAD_NAME``. + +Host console +------------ + +U-Boot can use the host's console instead of a physical serial device by +enabling ``CONFIG_SERIAL_SEMIHOSTING``. If you don't have +``CONFIG_DM_SERIAL`` enabled, make sure you disable any other serial +drivers. + +Migrating from ``smhload`` +-------------------------- + +If you were using the ``smhload`` command, you can migrate commands like:: + + smhload <file> <address> [<end var>] + +to a generic load command like:: + + load hostfs - <address> <file> + +The ``load`` command will set the ``filesize`` variable with the size of +the file. The ``fdt chosen`` command has been updated to take a size +instead of an end address. If you were adding the initramfs to your device +tree like:: + + fdt chosen <address> <end var> + +you can now run:: + + fdt chosen <address> $filesize diff --git a/doc/usage/spl_boot.rst b/doc/usage/spl_boot.rst new file mode 100644 index 00000000000..93419f158af --- /dev/null +++ b/doc/usage/spl_boot.rst @@ -0,0 +1,321 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Booting from TPL/SPL +==================== + +The main U-Boot binary may be too large to be loaded directly by the Boot ROM. +This was the original driver for splitting up U-Boot into multiple boot stages. + +U-Boot typically goes through the following boot phases where TPL, VPL, and SPL +are optional. While many boards use SPL only few use TPL. + +TPL + Tertiary Program Loader. Very early init, as tiny as possible. This loads SPL + (or VPL if enabled). + +VPL + Verifying Program Loader. Optional verification step, which can select one of + several SPL binaries, if A/B verified boot is enabled. Implementation of the + VPL logic is work-in-progress. For now it just boots into SPL. + +SPL + Secondary Program Loader. Sets up SDRAM and loads U-Boot proper. It may also + load other firmware components. + +U-Boot + U-Boot proper. This is the only stage containing command. It also implements + logic to load an operating system, e.g. via UEFI. + +.. note:: + + The naming convention on the PowerPC architecture deviates from the other + archtitectures. Here the boot sequence is SPL->TPL->U-Boot. + +Further usages for U-Boot SPL comprise: + +* launching BL31 of ARM Trusted Firmware which invokes U-Boot as BL33 +* launching EDK II +* launching Linux, e.g. :doc:`Falcon Mode <../develop/falcon>` +* launching RISC-V OpenSBI which invokes main U-Boot + +Target binaries +--------------- + +Binaries loaded by SPL/TPL can be: + +* raw binaries where the entry address equals the start address. This is the + only binary format supported by TPL. +* :doc:`FIT <fit/index>` images +* legacy U-Boot images + +Configuration +~~~~~~~~~~~~~ + +Raw images are only supported in SPL if CONFIG_SPL_RAW_IMAGE_SUPPORT=y. + +CONFIG_SPL_FIT=y and CONFIG_SPL_LOAD_FIT=y are needed to load FIT images. + +CONFIG_SPL_LEGACY_IMAGE_FORMAT=y is needed to load legacy U-Boot images. +CONFIG_SPL_LEGACY_IMAGE_CRC_CHECK=y enables checking the CRC32 of legacy U-Boot +images. + +Image load methods +------------------ + +The image boot methods available for a board must be defined in two places: + +The board code implements a function board_boot_order() enumerating up to +five boot methods and the sequence in which they are tried. (The maximum +number of boot methods is currently hard coded as variable spl_boot_list[]). +If there is only one boot method function, spl_boot_device() may be implemented +instead. + +The configuration controls which of these boot methods are actually available. + +Loading from block devices +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MMC1, MMC2, MMC2_2 + These methods read an image from SD card or eMMC. The first digit after + 'MMC' indicates the device number. Required configuration settings include: + + * CONFIG_SPL_MMC=y or CONFIG_TPL_MMC=y + + To use a PCI connected MMC controller you need to additionally specify: + + * CONFIG_SPL_PCI=y + + * CONFIG_SPL_PCI_PNP=y + + * CONFIG_MMC=y + + * CONFIG_MMC_PCI=y + + * CONFIG_MMC_SDHCI=y + + To load from a file system use: + + * CONFIG_SPL_FS_FAT=y or CONFIG_SPL_FS_EXT=y + + * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME="<filepath>" + +NVMe + This methods load the image from an NVMe drive. + Required configuration settings include: + + * CONFIG_SPL_PCI=y + + * CONFIG_SPL_PCI_PNP=y + + * CONFIG_SPL_NVME=y + + * CONFIG_SPL_NVME_PCI=y + + * CONFIG_SPL_NVME_BOOT_DEVICE (number of the NVMe device) + + * CONFIG_SYS_NVME_BOOT_PARTITION (partition to read from) + + To load from a file system use: + + * CONFIG_SPL_FS_FAT=y or CONFIG_SPL_FS_EXT=y + + * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME="<filepath>" + +SATA + This method reads an image from a SATA drive. + Required configuration settings include: + + * CONFIG_SPL_SATA=y or CONFIG_TPL_SATA=y + + To use a PCIe connecte SATA controller you additionally need: + + * CONFIG_SPL_PCI=y + + * CONFIG_SPL_SATA=y + + * CONFIG_SPL_AHCI_PCI=y + + * CONFIG_SPL_PCI_PNP=y + + To load from a file system use: + + * CONFIG_SPL_FS_FAT=y + + * CONFIG_SYS_SATA_FAT_BOOT_PARTITION=<partition number> + + * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME="<filepath>" + +USB + The USB method loads an image from a USB block device. + Required configuration settings include: + + * CONFIG_SPL_USB_HOST=y + + * CONFIG_SPL_USB_STORAGE=y + + To use a PCI connected USB 3.0 controller you additionally need: + + * CONFIG_SPL_FS_FAT=y + + * CONFIG_SPL_PCI=y + + * CONFIG_SPL_PCI_PNP=y + + * CONFIG_USB=y + + * CONFIG_USB_XHCI_HCD=y + + * CONFIG_USB_XHCI_PCI=y + + To load from a file system use: + + * CONFIG_SPL_FS_FAT=y or CONFIG_SPL_FS_EXT=y + + * CONFIG_SYS_USB_FAT_BOOT_PARTITION=<partition number> + + * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME="<filepath>" + +Loading from raw flash devices +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +NAND + This method loads the image from NAND flash. To read from raw NAND the + following configuration settings are required: + + * CONFIG_SPL_NAND_SUPPORT=y or CONFIG_TPL_NAND_SUPPORT=y + + If CONFIG_SPL_NAND_RAW_ONLY=y only raw images can be loaded. + + For using UBI (Unsorted Block Images) volumes to read from NAND the + following configuration settings are required: + + * CONFIG_SPL_UBI=y or CONFIG_TPL_UBI=y + + The UBI volume to read can either be specified + + * by name using CONFIG_SPL_UBI_LOAD_BY_VOLNAME or + + * by number using CONFIG_SPL_UBI_LOAD_MONITOR_ID. + +NOR + This method loads the image from NOR flash. + Required configuration settings include: + + * CONFIG_SPL_NOR_SUPPORT=y or CONFIG_TPL_NOR_SUPPORT=y + +OneNAND + This methods loads the image from a OneNAND device. To read from raw OneNAND + the following configuration settings are required: + + * CONFIG_SPL_ONENAND_SUPPORT=y or CONFIG_TPL_ONENAND_SUPPORT=y + + For using the Ubi file system to read from NAND the following configuration + settings are required: + + * CONFIG_SPL_UBI=y or CONFIG_TPL_UBI=y + +SPI + This method loads an image form SPI NOR flash. + Required configuration settings include: + + * CONFIG_SPL_DM_SPI=y + + * CONFIG_SPL_SPI_FLASH=y + + * CONFIG_SPI_LOAD=y or CONFIG_TPL_SPI_LOAD=y + + +Sunxi SPI + This method which is specific to Allwinner SoCs loads an image form SPI NOR + flash. Required configuration settings include: + + * CONFIG_SPL_SPI_SUNXI=y + +Loading from other devices +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +BOOTROM + The binary is loaded by the boot ROM. + Required configuration settings include: + + * CONFIG_SPL_BOOTROM_SUPPORT=y or CONFIG_TPL_BOOTROM_SUPPORT=y + +DFU + :doc:`Device Firmware Upgrade <dfu>` is used to load the binary into RAM. + Required configuration settings include: + + * CONFIG_DFU=y + + * CONFIG_SPL_RAM_SUPPORT=y or CONFIG TPL_RAM_SUPPORT=y + +Ethernet + This method loads an image over Ethernet. The BOOTP protocol is used to find + a TFTP server and binary name. The binary is downloaded via the TFTP + protocol. Required configuration settings include: + + * CONFIG_SPL_NET=y or CONFIG_TPL_NET=y + + * CONFIG_SPL_ETH_DEVICE=y or CONFIG_DM_USB_GADGET=y + +FEL + This method does not actually load an image for U-Boot. + FEL is a routine contained in the boot ROM of Allwinner SoCs which serves + for the initial programming or recovery via USB + +RAM + This method uses an image preloaded into RAM. + Required configuration settings include: + + * CONFIG_SPL_RAM_SUPPORT=y or CONFIG_TPL_RAM_SUPPORT=y + + * CONFIG_RAM_DEVICE=y + +Sandbox file + On the sandbox this method loads an image from the host file system. + +Sandbox image + On the sandbox this method loads an image from the host file system. + +Semihosting + When running in an ARM or RISC-V virtual machine the semihosting method can + be used to load an image from the host file system. + Required configuration settings include: + + * CONFIG_SPL_SEMIHOSTING=y + + * CONFIG_SPL_SEMIHOSTING_FALLBACK=y + + * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME=<path to file> + +UART + This method loads an image via the Y-Modem protocol from the UART. + Required configuration settings include: + + * CONFIG_SPL_YMODEM_SUPPORT=y or CONFIG_TPL_YMODEM_SUPPORT=y + +USB SDP + This method loads the image using the Serial Download Protocol as + implemented by the boot ROM of the i.MX family of SoCs. + + Required configuration settings include: + + * CONFIG_SPL_SERIAL=y + + * CONFIG_SPL_USB_SDP_SUPPORT=y or CONFIG_TPL_USB_SDP_SUPPORT + +VBE Simple + This method is used by the VPL stage to extract the next stage image from + the loaded image. + + Required configuration settings include: + + * CONFIG_VPL=y + + * CONFIG_SPL_BOOTMETH_VBE_SIMPLE_FW=y or CONFIG_TPL_BOOTMETH_VBE_SIMPLE_FW=y + +XIP + This method executes an image in place. + + Required configuration settings include: + + * CONFIG_SPL_XIP_SUPPORT |