diff options
Diffstat (limited to 'doc/usage/cmd')
96 files changed, 10349 insertions, 0 deletions
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..f759abab354 --- /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` 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/bootflow.rst b/doc/usage/cmd/bootflow.rst new file mode 100644 index 00000000000..6519e4880a9 --- /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` 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..2903977ee54 --- /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` 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 extlinunx 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..a7e21693a67 --- /dev/null +++ b/doc/usage/cmd/env.rst @@ -0,0 +1,384 @@ +.. 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 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 print [-a | name ...] + env print -e [-guid guid] [-n] [name ...] + env run var [...] + env save + env erase + env load + 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: + ++ *editenv* = *env edit* ++ *grepenv* = *env grep* ++ *setenv* = *env set* ++ *askenv* = *env ask* ++ *run* = *env run* + +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. + +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. + +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 when 'name'. + \-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. + +Erase +~~~~~ + +The *env erase* command erases the U-Boot environment. + +Load +~~~~ + +The *env load* command loads the U-Boot environment from 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 + +flags + CONFIG_CMD_ENV_FLAGS + +erase + CONFIG_CMD_ERASEENV + +export + CONFIG_CMD_EXPORTENV + +grep + CONFIG_CMD_GREPENV, CONFIG_REGEX for '-e' option + +import + CONFIG_CMD_IMPORTENV + +info + CONFIG_CMD_NVEDIT_INFO + +load + CONFIG_CMD_NVEDIT_LOAD + +run + CONFIG_CMD_RUN + +save + CONFIG_CMD_SAVEENV + +select + CONFIG_CMD_NVEDIT_SELECT + +set, print + CONFIG_CMD_NVEDIT_EFI for '-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..6b3dbe7b0a0 --- /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. + +Example +------- + +The examples shows how the value of a numeric variable can be tested with +**itest**. + +:: + + => 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/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. |