diff options
Diffstat (limited to 'doc/usage')
| -rw-r--r-- | doc/usage/cmd/gpt.rst | 184 | ||||
| -rw-r--r-- | doc/usage/index.rst | 2 | ||||
| -rw-r--r-- | doc/usage/spl_boot.rst | 321 |
3 files changed, 507 insertions, 0 deletions
diff --git a/doc/usage/cmd/gpt.rst b/doc/usage/cmd/gpt.rst new file mode 100644 index 0000000000..6387c8116f --- /dev/null +++ b/doc/usage/cmd/gpt.rst @@ -0,0 +1,184 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +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 setenv <interface> <dev> <partition name> + gpt swap <interface> <dev> <name1> <name2> + 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 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 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 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 + +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 diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 3326ec82ff..fa702920fa 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -4,6 +4,7 @@ Use U-Boot .. toctree:: :maxdepth: 1 + spl_boot blkmap dfu environment @@ -65,6 +66,7 @@ Shell commands cmd/for cmd/fwu_mdata cmd/gpio + cmd/gpt cmd/host cmd/imxtract cmd/load diff --git a/doc/usage/spl_boot.rst b/doc/usage/spl_boot.rst new file mode 100644 index 0000000000..93419f158a --- /dev/null +++ b/doc/usage/spl_boot.rst @@ -0,0 +1,321 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Booting from TPL/SPL +==================== + +The main U-Boot binary may be too large to be loaded directly by the Boot ROM. +This was the original driver for splitting up U-Boot into multiple boot stages. + +U-Boot typically goes through the following boot phases where TPL, VPL, and SPL +are optional. While many boards use SPL only few use TPL. + +TPL + Tertiary Program Loader. Very early init, as tiny as possible. This loads SPL + (or VPL if enabled). + +VPL + Verifying Program Loader. Optional verification step, which can select one of + several SPL binaries, if A/B verified boot is enabled. Implementation of the + VPL logic is work-in-progress. For now it just boots into SPL. + +SPL + Secondary Program Loader. Sets up SDRAM and loads U-Boot proper. It may also + load other firmware components. + +U-Boot + U-Boot proper. This is the only stage containing command. It also implements + logic to load an operating system, e.g. via UEFI. + +.. note:: + + The naming convention on the PowerPC architecture deviates from the other + archtitectures. Here the boot sequence is SPL->TPL->U-Boot. + +Further usages for U-Boot SPL comprise: + +* launching BL31 of ARM Trusted Firmware which invokes U-Boot as BL33 +* launching EDK II +* launching Linux, e.g. :doc:`Falcon Mode <../develop/falcon>` +* launching RISC-V OpenSBI which invokes main U-Boot + +Target binaries +--------------- + +Binaries loaded by SPL/TPL can be: + +* raw binaries where the entry address equals the start address. This is the + only binary format supported by TPL. +* :doc:`FIT <fit/index>` images +* legacy U-Boot images + +Configuration +~~~~~~~~~~~~~ + +Raw images are only supported in SPL if CONFIG_SPL_RAW_IMAGE_SUPPORT=y. + +CONFIG_SPL_FIT=y and CONFIG_SPL_LOAD_FIT=y are needed to load FIT images. + +CONFIG_SPL_LEGACY_IMAGE_FORMAT=y is needed to load legacy U-Boot images. +CONFIG_SPL_LEGACY_IMAGE_CRC_CHECK=y enables checking the CRC32 of legacy U-Boot +images. + +Image load methods +------------------ + +The image boot methods available for a board must be defined in two places: + +The board code implements a function board_boot_order() enumerating up to +five boot methods and the sequence in which they are tried. (The maximum +number of boot methods is currently hard coded as variable spl_boot_list[]). +If there is only one boot method function, spl_boot_device() may be implemented +instead. + +The configuration controls which of these boot methods are actually available. + +Loading from block devices +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MMC1, MMC2, MMC2_2 + These methods read an image from SD card or eMMC. The first digit after + 'MMC' indicates the device number. Required configuration settings include: + + * CONFIG_SPL_MMC=y or CONFIG_TPL_MMC=y + + To use a PCI connected MMC controller you need to additionally specify: + + * CONFIG_SPL_PCI=y + + * CONFIG_SPL_PCI_PNP=y + + * CONFIG_MMC=y + + * CONFIG_MMC_PCI=y + + * CONFIG_MMC_SDHCI=y + + To load from a file system use: + + * CONFIG_SPL_FS_FAT=y or CONFIG_SPL_FS_EXT=y + + * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME="<filepath>" + +NVMe + This methods load the image from an NVMe drive. + Required configuration settings include: + + * CONFIG_SPL_PCI=y + + * CONFIG_SPL_PCI_PNP=y + + * CONFIG_SPL_NVME=y + + * CONFIG_SPL_NVME_PCI=y + + * CONFIG_SPL_NVME_BOOT_DEVICE (number of the NVMe device) + + * CONFIG_SYS_NVME_BOOT_PARTITION (partition to read from) + + To load from a file system use: + + * CONFIG_SPL_FS_FAT=y or CONFIG_SPL_FS_EXT=y + + * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME="<filepath>" + +SATA + This method reads an image from a SATA drive. + Required configuration settings include: + + * CONFIG_SPL_SATA=y or CONFIG_TPL_SATA=y + + To use a PCIe connecte SATA controller you additionally need: + + * CONFIG_SPL_PCI=y + + * CONFIG_SPL_SATA=y + + * CONFIG_SPL_AHCI_PCI=y + + * CONFIG_SPL_PCI_PNP=y + + To load from a file system use: + + * CONFIG_SPL_FS_FAT=y + + * CONFIG_SYS_SATA_FAT_BOOT_PARTITION=<partition number> + + * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME="<filepath>" + +USB + The USB method loads an image from a USB block device. + Required configuration settings include: + + * CONFIG_SPL_USB_HOST=y + + * CONFIG_SPL_USB_STORAGE=y + + To use a PCI connected USB 3.0 controller you additionally need: + + * CONFIG_SPL_FS_FAT=y + + * CONFIG_SPL_PCI=y + + * CONFIG_SPL_PCI_PNP=y + + * CONFIG_USB=y + + * CONFIG_USB_XHCI_HCD=y + + * CONFIG_USB_XHCI_PCI=y + + To load from a file system use: + + * CONFIG_SPL_FS_FAT=y or CONFIG_SPL_FS_EXT=y + + * CONFIG_SYS_USB_FAT_BOOT_PARTITION=<partition number> + + * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME="<filepath>" + +Loading from raw flash devices +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +NAND + This method loads the image from NAND flash. To read from raw NAND the + following configuration settings are required: + + * CONFIG_SPL_NAND_SUPPORT=y or CONFIG_TPL_NAND_SUPPORT=y + + If CONFIG_SPL_NAND_RAW_ONLY=y only raw images can be loaded. + + For using UBI (Unsorted Block Images) volumes to read from NAND the + following configuration settings are required: + + * CONFIG_SPL_UBI=y or CONFIG_TPL_UBI=y + + The UBI volume to read can either be specified + + * by name using CONFIG_SPL_UBI_LOAD_BY_VOLNAME or + + * by number using CONFIG_SPL_UBI_LOAD_MONITOR_ID. + +NOR + This method loads the image from NOR flash. + Required configuration settings include: + + * CONFIG_SPL_NOR_SUPPORT=y or CONFIG_TPL_NOR_SUPPORT=y + +OneNAND + This methods loads the image from a OneNAND device. To read from raw OneNAND + the following configuration settings are required: + + * CONFIG_SPL_ONENAND_SUPPORT=y or CONFIG_TPL_ONENAND_SUPPORT=y + + For using the Ubi file system to read from NAND the following configuration + settings are required: + + * CONFIG_SPL_UBI=y or CONFIG_TPL_UBI=y + +SPI + This method loads an image form SPI NOR flash. + Required configuration settings include: + + * CONFIG_SPL_DM_SPI=y + + * CONFIG_SPL_SPI_FLASH=y + + * CONFIG_SPI_LOAD=y or CONFIG_TPL_SPI_LOAD=y + + +Sunxi SPI + This method which is specific to Allwinner SoCs loads an image form SPI NOR + flash. Required configuration settings include: + + * CONFIG_SPL_SPI_SUNXI=y + +Loading from other devices +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +BOOTROM + The binary is loaded by the boot ROM. + Required configuration settings include: + + * CONFIG_SPL_BOOTROM_SUPPORT=y or CONFIG_TPL_BOOTROM_SUPPORT=y + +DFU + :doc:`Device Firmware Upgrade <dfu>` is used to load the binary into RAM. + Required configuration settings include: + + * CONFIG_DFU=y + + * CONFIG_SPL_RAM_SUPPORT=y or CONFIG TPL_RAM_SUPPORT=y + +Ethernet + This method loads an image over Ethernet. The BOOTP protocol is used to find + a TFTP server and binary name. The binary is downloaded via the TFTP + protocol. Required configuration settings include: + + * CONFIG_SPL_NET=y or CONFIG_TPL_NET=y + + * CONFIG_SPL_ETH_DEVICE=y or CONFIG_DM_USB_GADGET=y + +FEL + This method does not actually load an image for U-Boot. + FEL is a routine contained in the boot ROM of Allwinner SoCs which serves + for the initial programming or recovery via USB + +RAM + This method uses an image preloaded into RAM. + Required configuration settings include: + + * CONFIG_SPL_RAM_SUPPORT=y or CONFIG_TPL_RAM_SUPPORT=y + + * CONFIG_RAM_DEVICE=y + +Sandbox file + On the sandbox this method loads an image from the host file system. + +Sandbox image + On the sandbox this method loads an image from the host file system. + +Semihosting + When running in an ARM or RISC-V virtual machine the semihosting method can + be used to load an image from the host file system. + Required configuration settings include: + + * CONFIG_SPL_SEMIHOSTING=y + + * CONFIG_SPL_SEMIHOSTING_FALLBACK=y + + * CONFIG_SPL_FS_LOAD_PAYLOAD_NAME=<path to file> + +UART + This method loads an image via the Y-Modem protocol from the UART. + Required configuration settings include: + + * CONFIG_SPL_YMODEM_SUPPORT=y or CONFIG_TPL_YMODEM_SUPPORT=y + +USB SDP + This method loads the image using the Serial Download Protocol as + implemented by the boot ROM of the i.MX family of SoCs. + + Required configuration settings include: + + * CONFIG_SPL_SERIAL=y + + * CONFIG_SPL_USB_SDP_SUPPORT=y or CONFIG_TPL_USB_SDP_SUPPORT + +VBE Simple + This method is used by the VPL stage to extract the next stage image from + the loaded image. + + Required configuration settings include: + + * CONFIG_VPL=y + + * CONFIG_SPL_BOOTMETH_VBE_SIMPLE_FW=y or CONFIG_TPL_BOOTMETH_VBE_SIMPLE_FW=y + +XIP + This method executes an image in place. + + Required configuration settings include: + + * CONFIG_SPL_XIP_SUPPORT |