diff options
Diffstat (limited to 'doc')
30 files changed, 1203 insertions, 198 deletions
diff --git a/doc/README.fuse b/doc/README.fuse deleted file mode 100644 index 1bc91c44a6a..00000000000 --- a/doc/README.fuse +++ /dev/null @@ -1,67 +0,0 @@ -Fuse API functions and commands - -The fuse API allows to control a fusebox and how it is used by the upper -hardware layers. - -A fuse corresponds to a single non-volatile memory bit that can be programmed -(i.e. blown, set to 1) only once. The programming operation is irreversible. A -fuse that has not been programmed reads 0. - -Fuses can be used by SoCs to store various permanent configuration and data, -e.g. boot configuration, security configuration, MAC addresses, etc. - -A fuse word is the smallest group of fuses that can be read at once from the -fusebox control IP registers. This is limited to 32 bits with the current API. - -A fuse bank is the smallest group of fuse words having a common ID, as defined -by each SoC. - -Upon startup, the fusebox control IP reads the fuse values and stores them to a -volatile shadow cache. - -See the README files of the drivers implementing this API in order to know the -SoC- and implementation-specific details. - -Functions / commands: - - int fuse_read(u32 bank, u32 word, u32 *val); - fuse read <bank> <word> [<cnt>] - Read fuse words from the shadow cache. - - int fuse_sense(u32 bank, u32 word, u32 *val); - fuse sense <bank> <word> [<cnt>] - Sense - i.e. read directly from the fusebox, skipping the shadow cache - - fuse words. This operation does not update the shadow cache. - - This is useful to know the true value of fuses if an override has been - performed (see below). - - int fuse_prog(u32 bank, u32 word, u32 val); - fuse prog [-y] <bank> <word> <hexval> [<hexval>...] - Program fuse words. This operation directly affects the fusebox and is - irreversible. The shadow cache is updated accordingly or not, depending on - each IP. - - Only the bits to be programmed should be set in the input value (i.e. for - fuse bits that have already been programmed and hence should be left - unchanged by a further programming, it is preferable to clear the - corresponding bits in the input value in order not to perform a new - hardware programming operation on these fuse bits). - - int fuse_override(u32 bank, u32 word, u32 val); - fuse override <bank> <word> <hexval> [<hexval>...] - Override fuse words in the shadow cache. - - The fusebox is unaffected, so following this operation, the shadow cache - may differ from the fusebox values. Read or sense operations can then be - used to get the values from the shadow cache or from the fusebox. - - This is useful to change the behaviors linked to some cached fuse values, - either because this is needed only temporarily, or because some of the - fuses have already been programmed or are locked (if the SoC allows to - override a locked fuse). - -Configuration: - - CONFIG_CMD_FUSE - Define this to enable the fuse commands. diff --git a/doc/arch/sandbox/sandbox.rst b/doc/arch/sandbox/sandbox.rst index a8b0d7f0395..7e641306da2 100644 --- a/doc/arch/sandbox/sandbox.rst +++ b/doc/arch/sandbox/sandbox.rst @@ -658,10 +658,10 @@ that are mapped into that memory: ======== ======================== =============================== Addr Config Usage ======== ======================== =============================== - 100 CONFIG_SYS_FDT_LOAD_ADDR Device tree - b000 CONFIG_BLOBLIST_ADDR Blob list - 10000 CFG_MALLOC_F_ADDR Early memory allocation + 100 CONFIG_BLOBLIST_ADDR Blob list + 1000 CONFIG_SYS_FDT_LOAD_ADDR Device tree f0000 CONFIG_PRE_CON_BUF_ADDR Pre-console buffer + f4000 CFG_MALLOC_F_ADDR Early memory allocation 100000 TCG Event log TCG Event Log 200000 CONFIG_TRACE_EARLY_ADDR Early trace buffer (if enabled). Also used 400000 CONFIG_TEXT_BASE Load buffer for U-Boot (sandbox_spl only) diff --git a/doc/board/amlogic/odroid-n2.rst b/doc/board/amlogic/odroid-n2.rst index 883720f8fbf..5222a21c808 100644 --- a/doc/board/amlogic/odroid-n2.rst +++ b/doc/board/amlogic/odroid-n2.rst @@ -54,10 +54,9 @@ image so it is necessary to obtain binaries from sources published by the board $ tar xvfJ gcc-linaro-arm-none-eabi-4.8-2013.11_linux.tar.xz $ export PATH=$PWD/gcc-linaro-aarch64-none-elf-4.8-2013.11_linux/bin:$PWD/gcc-linaro-arm-none-eabi-4.8-2013.11_linux/bin:$PATH - $ DIR=odroid-n2 - $ git clone --depth 1 https://github.com/hardkernel/u-boot.git -b odroidn2-v2015.01 $DIR + $ git clone --depth 1 https://github.com/hardkernel/u-boot.git -b odroidg12-v2015.01 odroidg12 - $ cd odroid-n2 + $ cd odroidg12 $ make odroidn2_defconfig $ make $ export UBOOTDIR=$PWD @@ -74,12 +73,8 @@ Go back to the mainline U-Boot source tree then: $ cp $UBOOTDIR/fip/g12b/bl2.bin fip/ $ cp $UBOOTDIR/fip/g12b/bl30.bin fip/ $ cp $UBOOTDIR/fip/g12b/bl31.img fip/ - $ cp $UBOOTDIR/fip/g12b/ddr3_1d.fw fip/ $ cp $UBOOTDIR/fip/g12b/ddr4_1d.fw fip/ $ cp $UBOOTDIR/fip/g12b/ddr4_2d.fw fip/ - $ cp $UBOOTDIR/fip/g12b/diag_lpddr4.fw fip/ - $ cp $UBOOTDIR/fip/g12b/lpddr4_1d.fw fip/ - $ cp $UBOOTDIR/fip/g12b/lpddr4_2d.fw fip/ $ cp $UBOOTDIR/fip/g12b/piei.fw fip/ $ cp $UBOOTDIR/fip/g12b/aml_ddr.fw fip/ $ cp u-boot.bin fip/bl33.bin @@ -113,7 +108,7 @@ Go back to the mainline U-Boot source tree then: --level v3 --type bl31 $ $UBOOTDIR/fip/g12b/aml_encrypt_g12b --bl3sig --input fip/bl33.bin --compress lz4 \ --output fip/bl33.bin.enc \ - --level v3 --type bl33 --compress lz4 + --level v3 --type bl33 $ $UBOOTDIR/fip/g12b/aml_encrypt_g12b --bl2sig --input fip/bl2_new.bin \ --output fip/bl2.n.bin.sig $ $UBOOTDIR/fip/g12b/aml_encrypt_g12b --bootmk \ @@ -124,11 +119,7 @@ Go back to the mainline U-Boot source tree then: --bl33 fip/bl33.bin.enc \ --ddrfw1 fip/ddr4_1d.fw \ --ddrfw2 fip/ddr4_2d.fw \ - --ddrfw3 fip/ddr3_1d.fw \ --ddrfw4 fip/piei.fw \ - --ddrfw5 fip/lpddr4_1d.fw \ - --ddrfw6 fip/lpddr4_2d.fw \ - --ddrfw7 fip/diag_lpddr4.fw \ --ddrfw8 fip/aml_ddr.fw \ --level v3 diff --git a/doc/board/armltd/vexpress64.rst b/doc/board/armltd/vexpress64.rst index a7f771d2667..109337d7fe3 100644 --- a/doc/board/armltd/vexpress64.rst +++ b/doc/board/armltd/vexpress64.rst @@ -19,6 +19,11 @@ view", which gives a comprehensive model on which to build and test software. The supported FVPs are available free of charge and can be downloaded from the Arm developer site [1]_ (user registration might be required). +The Architecture Envelope Models (AEM) FVPs offer virtual platforms for Armv8-A, +Armv9-A, and Armv8-R architectures, including a comprehensive set of System IP. +For general use though, the Armv8-A Base Rev C FVP, which emulates a generic 64-bit +Armv8-A hardware platform, is a suitable option. + Supported features: * GICv3 @@ -31,6 +36,50 @@ into the TF-A build: ``make PLAT=<platform> all fip BL33=u-boot.bin`` The FVPs can be debugged using Arm Development Studio [2]_. +Building U-Boot +^^^^^^^^^^^^^^^ + +Set the ``CROSS_COMPILE`` environment variable as usual, and run: + +.. code-block:: bash + + make vexpress_fvp_defconfig + make + +Running U-Boot +^^^^^^^^^^^^^^ + +Set ``CROSS_COMPILE`` as usual and build TF-A: + +.. code-block:: bash + + git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git + cd trusted-firmware-a + make PLAT=fvp BL33=/path/to/u-boot.bin fiptool all fip + +This command generates the ROM image `bl1.bin`, and a boot image `fip.bin` in +TF-A's FIP format [5]_. It contains all images executed by TF-A, including U-Boot. +Note that TF-A outputs the built binaries into `build/fvp/release/`. + +If you already have a FIP image, and are primarily interested in updating the BL33 +image (i.e., U-Boot), use `fiptool` from TF-A: + +.. code-block:: bash + + make fiptool + tools/fiptool/fiptool update --nt-fw=/path/to/u-boot.bin /path/to/fip.bin + +To run the FVP: + +.. code-block:: bash + + FVP_Base_RevC-2xAEMvA -C bp.flashloader0.fname=fip.bin \ + -C bp.secureflashloader.fname=bl1.bin \ + -C bp.vis.disable_visualisation=1 + +This setup relies on semi-hosting, as well as, having a kernel image (``Image``) +and ramdisk (``ramdisk.img``) in the current working directory. + Juno ---- @@ -43,10 +92,27 @@ Juno is an Arm development board with the following features: More details can be found in the board documentation [3]_. +Bloblist Support +---------------- + +The ``vexpress_fvp_bloblist_defconfig`` configures U-Boot to be compiled for +Vexpress64 with Bloblist as the primary method for information handoff between +boot stages. U-Boot offers three methods to set up a bloblist: using a +predefined bloblist at a specified address, dynamically allocating memory for a +bloblist, or utilizing a standard passage-provided bloblist with automatic size +detection. + +By default, ``vexpress_fvp_bloblist_defconfig`` uses the standard passage method mandatorily +(CONFIG_BLOBLIST_PASSAGE_MANDATORY) because TF-A provides a Transfer List in non-secure +memory that U-Boot can utilise. This Bloblist, which is referred to as a Transfer List in +TF-A, contains all necessary data for the handoff process, including DT and ACPI +tables. + References ---------- -.. [1] https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms +.. [1] https://developer.arm.com/Tools%20and%20Software/Fixed%20Virtual%20Platforms/Arm%20Architecture%20FVPs .. [2] https://developer.arm.com/tools-and-software/embedded/arm-development-studio .. [3] https://developer.arm.com/tools-and-software/development-boards/juno-development-board -.. [4] https://trustedfirmware-a.readthedocs.io/
\ No newline at end of file +.. [4] https://trustedfirmware-a.readthedocs.io/ +.. [5] https://trustedfirmware-a.readthedocs.io/en/latest/getting_started/image-terminology.html#firmware-image-package-fip diff --git a/doc/board/index.rst b/doc/board/index.rst index b055046e649..7ad1137c94a 100644 --- a/doc/board/index.rst +++ b/doc/board/index.rst @@ -43,6 +43,7 @@ Board-specific doc microsoft/index nxp/index openpiton/index + ouya/index phytec/index purism/index qualcomm/index @@ -69,4 +70,5 @@ Board-specific doc variscite/index wexler/index xen/index + xiaomi/index xilinx/index diff --git a/doc/board/ouya/index.rst b/doc/board/ouya/index.rst new file mode 100644 index 00000000000..7413240a1b8 --- /dev/null +++ b/doc/board/ouya/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +OUYA +==== + +.. toctree:: + :maxdepth: 2 + + ouya diff --git a/doc/board/ouya/ouya.rst b/doc/board/ouya/ouya.rst new file mode 100644 index 00000000000..641affc6294 --- /dev/null +++ b/doc/board/ouya/ouya.rst @@ -0,0 +1,124 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for the Ouya Game Console (ouya) +======================================= + +``DISCLAMER!`` Moving your Ouya to use U-Boot assumes replacement of the +vendor bootloader. Vendor android firmwares will no longer be able to run on the +device. This replacement IS reversible. + +Quick Start +----------- + +- Build U-Boot +- Process U-Boot +- Flashing U-Boot into the eMMC +- Boot +- Self Upgrading + +Build U-Boot +------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=arm-none-eabi- + $ make ouya_defconfig + $ make + +After the build succeeds, you will obtain the final ``u-boot-dtb-tegra.bin`` +image, ready for further processing. + +Process U-Boot +-------------- + +``DISCLAMER!`` All questions related to the re-crypt work should be asked +in re-crypt repo issues. NOT HERE! + +re-crypt is a tool that processes the ``u-boot-dtb-tegra.bin`` binary into form +usable by device. This process is required only on the first installation or +to recover the device in case of a failed update. + +Permanent installation can be performed either by using the nv3p protocol or by +pre-loading just built U-Boot into RAM. + +Processing for the NV3P protocol +******************************** + +.. code-block:: bash + + $ git clone https://gitlab.com/grate-driver/re-crypt.git + $ cd re-crypt # place your u-boot-dtb-tegra.bin here + $ ./re-crypt.py --dev ouya + +The script will produce a ``repart-block.bin`` ready to flash. + +Processing for pre-loaded U-Boot +******************************** + +The procedure is the same, but the ``--split`` argument is used with the +``re-crypt.py``. The script will produce ``bct.img`` and ``ebt.img`` ready +to flash. + +Flashing U-Boot into the eMMC +----------------------------- + +Permanent installation can be performed either by using the nv3p protocol or by +pre-loading just built U-Boot into RAM. Regardless of the method bct and bootloader +will end up in boot0 and boot1 partitions of eMMC. + +Flashing with the NV3P protocol +******************************* + +``DISCLAMER!`` All questions related to NvFlash should be asked in the proper +place. NOT HERE! Flashing U-Boot will erase all eMMC, so make a backup before! + +Nv3p is a custom Nvidia protocol used to recover bricked devices. Devices can +enter it by pre-loading vendor bootloader with the Fusée Gelée. + +With nv3p, ``repart-block.bin`` is used. It contains BCT and a bootloader in +encrypted state in form, which can just be written RAW at the start of eMMC. + +.. code-block:: bash + + $ ./run_bootloader.sh -s T30 -t ./bct/ouya.bct -b android_bootloader.bin + $ ./utiils/nvflash_v1.13.87205 --resume --rawdevicewrite 0 1024 repart-block.bin + +When flashing is done, reboot the device. + +Flashing with a pre-loaded U-Boot +********************************* + +U-Boot pre-loaded into RAM acts the same as when it was booted "cold". Currently +U-Boot supports bootmenu entry fastboot, which allows to write a processed copy +of U-Boot permanently into eMMC. + +While pre-loading U-Boot, interrupt bootflow by pressing ``CTRL + C`` (USB keyboard +must be plugged in before U-Boot is preloaded, else it will not work), input +``bootmenu`` from the keyboard and hit enter. The bootmenu will appear. There, select +``fastboot`` using the up and down arrows and enter key. After, on host PC, do: + +.. code-block:: bash + + $ fastboot flash 0.1 bct.img + $ fastboot flash 0.2 ebt.img + $ fastboot reboot + +Device will reboot. + +Boot +---- + +To boot Linux, U-Boot will look for an ``extlinux.conf`` on eMMC. Additionally, +bootmenu provides entries to mount eMMC as mass storage, fastboot, reboot, +reboot RCM, poweroff, enter U-Boot console and update bootloader (check +the next chapter). + +Flashing ``repart-block.bin`` eliminates vendor restrictions on eMMC and allows +the user to use/partition it in any way the user desires. + +Self Upgrading +-------------- + +Place your ``u-boot-dtb-tegra.bin`` on the first partition of the USB. Enter +bootmenu, choose update bootloader option with Enter and U-Boot should update +itself. Once the process is completed, U-Boot will ask to press any button to reboot. diff --git a/doc/board/phytec/k3-common.rst b/doc/board/phytec/k3-common.rst new file mode 100644 index 00000000000..ffb50b51ad6 --- /dev/null +++ b/doc/board/phytec/k3-common.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Wadim Egorov <w.egorov@phytec.de> + +Environment +----------- + + +Variables Set at Runtime +~~~~~~~~~~~~~~~~~~~~~~~~ + +At runtime the `boot` environment variable is set to reflect the source from which the board was booted. This ensures that the correct boot path is followed for further system initialization. + + +Environment Storage Selection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The environment is loaded from a storage location based on the boot device: + +* If booted from eMMC or uSD card, the environment is retrieved from FAT or a fixed offset if configured. + +* If booted from SPI, the environment is retrieved from SPI flash if enabled. + +For all other boot devices, the environment is not stored persistently (ENVL_NOWHERE). + + +Saving the Environment +~~~~~~~~~~~~~~~~~~~~~~ + +The `saveenv` command will store the environment on the same device the board was booted from, ensuring consistency between boot sources and stored configurations. + + +Capsule Updates +--------------- + +Capsules for each of these binaries are automatically generated as part of the build process and are named `<binary>-capsule.bin`. For example, the capsule for `u-boot.img` is named `uboot-capsule.bin`. + + + +Performing an Update +~~~~~~~~~~~~~~~~~~~~ + +Each board has a dynamically generated GUID. To retrieve it, run: + +.. code-block:: + + efidebug capsule esrt + +To update the firmware, follow these steps on the board. Ensure the capsule binaries are available on a uSD card. + +.. code-block:: bash + + load mmc 1:1 $loadaddr tiboot3-capsule.bin + efidebug capsule update $loadaddr + + load mmc 1:1 $loadaddr tispl-capsule.bin + efidebug capsule update $loadaddr + + load mmc 1:1 $loadaddr uboot-capsule.bin + efidebug capsule update $loadaddr + +These commands load the capsule binaries into memory and trigger the EFI capsule update process. + + +Important Notes +~~~~~~~~~~~~~~~ + +The updates are applied to the boot device from which the board is currently running. For eMMC, updates are always applied to the first boot partition. Capsule updates can be performed on eMMC, OSPI NOR, or a uSD card, depending on the boot device. For any additional configuration or troubleshooting, refer to :ref:`uefi_capsule_update_ref`. diff --git a/doc/board/phytec/phycore-am62ax.rst b/doc/board/phytec/phycore-am62ax.rst index 0c5b4814fc2..e1f741011e7 100644 --- a/doc/board/phytec/phycore-am62ax.rst +++ b/doc/board/phytec/phycore-am62ax.rst @@ -176,6 +176,8 @@ Boot switches should be changed with power off. - 11011100 - 00000000 +.. include:: k3-common.rst + Further Information ------------------- diff --git a/doc/board/phytec/phycore-am62x.rst b/doc/board/phytec/phycore-am62x.rst index 56c1fd8354b..36315b49931 100644 --- a/doc/board/phytec/phycore-am62x.rst +++ b/doc/board/phytec/phycore-am62x.rst @@ -176,6 +176,8 @@ Boot switches should be changed with power off. - 11001010 - 00100000 +.. include:: k3-common.rst + Further Information ------------------- diff --git a/doc/board/phytec/phycore-am64x.rst b/doc/board/phytec/phycore-am64x.rst index 01c42b90660..71f1fd7b404 100644 --- a/doc/board/phytec/phycore-am64x.rst +++ b/doc/board/phytec/phycore-am64x.rst @@ -175,6 +175,8 @@ Boot switches should be changed with power off. - 11011100 - 00000000 +.. include:: k3-common.rst + Further Information ------------------- diff --git a/doc/board/qualcomm/index.rst b/doc/board/qualcomm/index.rst index 8c7969987a9..66bc922033a 100644 --- a/doc/board/qualcomm/index.rst +++ b/doc/board/qualcomm/index.rst @@ -10,3 +10,4 @@ Qualcomm rb3gen2 board debugging + rdp diff --git a/doc/board/qualcomm/rdp.rst b/doc/board/qualcomm/rdp.rst new file mode 100644 index 00000000000..fd14f1d9829 --- /dev/null +++ b/doc/board/qualcomm/rdp.rst @@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. sectionauthor:: Varadarajan Narayanan <quic_varada@quicinc.com> + +Qualcomm Reference Design Platform (RDP) +======================================== + +Qualcomm RDPs are development boards based on the Qualcomm IPQ series of +SoCs. These SoCs are used as the application processors in WiFi router +platforms. RDPs come in multiple variants with differences in storage +medium (NOR, NAND, MMC), no. of USB and PCIe ports, n/w ports etc. + +.. _Qualcomm's product page: https://www.qualcomm.com/products/internet-of-things/networking/wi-fi-networks/networking-pro-series/qualcomm-networking-pro-820-platform + +Installation +------------ +First, setup ``CROSS_COMPILE`` for aarch64. Then, build U-Boot for ``IPQ9574``:: + + $ export CROSS_COMPILE=<aarch64 toolchain prefix> + $ make qcom_ipq9574_mmc_defconfig + $ make -j8 + +This will build ``u-boot.elf`` in the configured output directory. + +Although the RDPs do not have secure boot set up by default, the firmware still +expects firmware ELF images to be "signed". The signature does not provide any +security in this case, but it provides the firmware with some required metadata. + +To "sign" ``u-boot.elf`` you can use e.g. `qtestsign`_:: + + $ qtestsign -v6 aboot -o u-boot.mbn u-boot.elf + +Then install the resulting ``u-boot.mbn`` to the ``0:APPSBL`` partition +on your device with:: + + IPQ9574# tftpboot path/to/u-boot.mbn + IPQ9574# mmc part (note down the start & end block no.s of '0:APPSBL' partition) + IPQ9574# mmc erase <start blk no> <count> + IPQ9574# mmc write $fileaddr <blk no> <count> + +U-Boot should be running after a reboot (``reset``). + +.. WARNING + Boards with newer software versions would automatically go the emergency + download (EDL) mode if U-Boot is not functioning as expected. If its a + runtime failure at Uboot, the system will get reset (due to watchdog) + and XBL will try to boot from next bank and if Bank B also doesn't have + a functional image and is not booting fine, then the system will enter + EDL. A tool like bkerler's `edl`_ can be used for flashing with the + firehose loader binary appropriate for the board. + + Note that the support added is very basic. Restoring the original U-Boot + on boards with older version of the software requires a debugger. + +.. _qtestsign: https://github.com/msm8916-mainline/qtestsign +.. _edl: https://github.com/bkerler/edl diff --git a/doc/board/xiaomi/index.rst b/doc/board/xiaomi/index.rst new file mode 100644 index 00000000000..109ab4a251f --- /dev/null +++ b/doc/board/xiaomi/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Xiaomi +====== + +.. toctree:: + :maxdepth: 2 + + mocha diff --git a/doc/board/xiaomi/mocha.rst b/doc/board/xiaomi/mocha.rst new file mode 100644 index 00000000000..be3e333127b --- /dev/null +++ b/doc/board/xiaomi/mocha.rst @@ -0,0 +1,112 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for the Xiaomi Mi Pad tablet +=================================== + +``DISCLAMER!`` Moving your Xiaomi Mi Pad to use U-Boot assumes replacement +of the vendor bootloader. Vendor Android firmwares will no longer be able +to run on the device. This replacement IS reversible. + +Quick Start +----------- + +- Build U-Boot +- Boot U-Boot +- Process and flash U-Boot +- Boot Linux +- Self Upgrading +- Chainload configuration + +Build U-Boot +------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=arm-none-eabi- + $ make mocha_defconfig + $ make + +After the build succeeds, you will obtain the final ``u-boot-dtb-tegra.bin`` +image, ready for booting or further processing. + +Boot U-Boot +----------- +Existing tegrarcm loader can be used to pre-load U-Boot you have build +into RAM and basically perform a tethered cold-boot. + +.. code-block:: bash + + $ tegrarcm --bct mocha.bct --bootloader u-boot-dtb-tegra.bin --loadaddr 0x80108000 + +U-Boot will try to load Linux kernel and if fails, it will turn the +tablet off. While pre-loading U-Boot, hold the ``volume down`` button +which will trigger the bootmenu. + +Process and flash U-Boot +------------------------ + +``DISCLAMER!`` All questions related to the re-crypt work should be asked +in re-crypt repo issues. NOT HERE! + +re-crypt is a tool that processes the ``u-boot-dtb-tegra.bin`` binary into +form usable by device. This process is required only on the first +installation or to recover the device in case of a failed update. + +.. code-block:: bash + + $ git clone https://gitlab.com/grate-driver/re-crypt.git + $ cd re-crypt # place your u-boot-dtb-tegra.bin here + $ ./re-crypt.py --dev mocha + +The script will produce ``bct.img`` and ``ebt.img`` ready to flash. + +Permanent installation can be performed by pre-loading just built U-Boot +into RAM via tegrarcm. While pre-loading U-Boot, hold the ``volume down`` +button which will trigger the bootmenu. There, select ``fastboot`` using +the volume and power buttons. + +After, on host PC, do: + +.. code-block:: bash + + $ fastboot flash 0.1 bct.img + $ fastboot flash 0.2 ebt.img + $ fastboot reboot + +Device will reboot. + +Boot Linux +---------- + +To boot Linux, U-Boot will look for an ``extlinux.conf`` on MicroSD and then on +eMMC. Additionally, if the ``volume down`` button is pressed while booting, the +device will enter bootmenu. Bootmenu contains entries to mount MicroSD and eMMC +as mass storage, fastboot, reboot, reboot RCM, poweroff, enter U-Boot console +and update bootloader (check the next chapter). + +Flashing ``bct.img`` and ``ebt.img`` eliminates vendor restrictions on eMMC and +allows the user to use/partition it in any way the user desires. + +Self Upgrading +-------------- + +Place your ``u-boot-dtb-tegra.bin`` on the first partition of the MicroSD card +and insert it into the tablet. Enter bootmenu, choose update the bootloader +option with the Power button and U-Boot should update itself. Once the process +is completed, U-Boot will ask to press any button to reboot. + +Chainload configuration +----------------------- + +To build U-Boot without SPL suitable for chainloading adjust mocha_defconfig: + +.. code-block:: + + CONFIG_TEXT_BASE=0x80A00000 + CONFIG_SKIP_LOWLEVEL_INIT=y + # CONFIG_OF_BOARD_SETUP is not set + CONFIG_TEGRA_SUPPORT_NON_SECURE=y + +After the build succeeds, you will obtain the final ``u-boot-dtb.bin`` +file, ready for booting using vendor bootloader's fastboot or which can be +further processed into a flashable image. diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index e3ce97cc4f5..9fe5630ab16 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -235,8 +235,9 @@ means that `default_get_bootflow()` is used. This simply obtains the block device and calls a bootdev helper function to do the rest. The implementation of `bootdev_find_in_blk()` checks the partition table, and attempts to read a file from a filesystem on the partition number given by the -`@iter->part` parameter. If there are any bootable partitions in the table, -then only bootable partitions are considered. +`@iter->part` parameter. If there are any bootable partitions in the table and +the BOOTFLOWIF_ONLY_BOOTABLE flag is set in `@iter->flags`, then only bootable +partitions are considered. Each bootdev has a priority, which indicates the order in which it is used, if `boot_targets` is not used. Faster bootdevs are used first, since they are diff --git a/doc/develop/driver-model/design.rst b/doc/develop/driver-model/design.rst index 92f638a0204..30093737200 100644 --- a/doc/develop/driver-model/design.rst +++ b/doc/develop/driver-model/design.rst @@ -843,8 +843,10 @@ steps (see device_probe()): activated and 'known' by the uclass. For some platforms, certain devices must be probed to get the platform into -a working state. To help with this, drivers marked with DM_FLAG_PROBE_AFTER_BIND -will be probed immediately after all devices are bound. For now, this happens in +a working state. To help with this, devices marked with DM_FLAG_PROBE_AFTER_BIND +will be probed immediately after all devices are bound. This flag must be set +on the device in its ``bind()`` function with +``dev_or_flags(dev, DM_FLAG_PROBE_AFTER_BIND)``. For now, this happens in SPL, before relocation and after relocation. See the call to ``dm_autoprobe()`` for where this is done. diff --git a/doc/develop/py_testing.rst b/doc/develop/py_testing.rst index b50473039be..502053f09fc 100644 --- a/doc/develop/py_testing.rst +++ b/doc/develop/py_testing.rst @@ -41,13 +41,11 @@ will be required. The following is an incomplete list: * dfu-util * dtc * openssl -* sudo OR guestmount * e2fsprogs * util-linux * coreutils * dosfstools * efitools -* guestfs-tools * mount * mtools * sbsigntool @@ -64,23 +62,12 @@ The test script supports either: physical board, attach to the board's console stream, and reset the board. Further details are described later. -The usage of command 'sudo' should be avoided in tests. To create disk images -use command virt-make-fs which is provided by package guestfs-tools. This -command creates a virtual machine with QEMU in which the disk image is -generated. - -Command virt-make-fs needs read access to the current kernel. On Ubuntu only -root has this privilege. You can add a script /etc/initramfs-tools/hooks/vmlinuz -with the following content to overcome the problem: - -.. code-block:: bash - - #!/bin/sh - echo "chmod a+r vmlinuz-*" - chmod a+r /boot/vmlinuz-* - -The script should be chmod 755. It will be invoked whenever the initial RAM file -system is updated. +The usage of the command 'sudo' is not allowed in tests. Using elevated +priviledges can lead to security concerns. Furthermore not all users may have +administrator rights. Therefore the command 'sudo' must not be used in tests. +To create disk images we have helper functions located in +`test/py/tests/fs_helper.py` which shall be used in any tests that require +creating disk images. Using `virtualenv` to provide requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -125,7 +112,7 @@ browser, but may be read directly as plain text, perhaps with the aid of the If sandbox crashes (e.g. with a segfault) you will see message like this:: - test/py/u_boot_spawn.py:171: in expect + test/py/spawn.py:171: in expect c = os.read(self.fd, 1024).decode(errors='replace') E ValueError: U-Boot exited with signal 11 (Signals.SIGSEGV) @@ -506,24 +493,24 @@ Writing tests Please refer to the pytest documentation for details of writing pytest tests. Details specific to the U-Boot test suite are described below. -A test fixture named `u_boot_console` should be used by each test function. This +A test fixture named `ubman` should be used by each test function. This provides the means to interact with the U-Boot console, and retrieve board and environment configuration information. -The function `u_boot_console.run_command()` executes a shell command on the +The function `ubman.run_command()` executes a shell command on the U-Boot console, and returns all output from that command. This allows validation or interpretation of the command output. This function validates that certain strings are not seen on the U-Boot console. These include shell error messages and the U-Boot sign-on message (in order to detect unexpected -board resets). See the source of `u_boot_console_base.py` for a complete list of +board resets). See the source of `console_base.py` for a complete list of "bad" strings. Some test scenarios are expected to trigger these strings. Use -`u_boot_console.disable_check()` to temporarily disable checking for specific +`ubman.disable_check()` to temporarily disable checking for specific strings. See `test_unknown_cmd.py` for an example. Board- and board-environment configuration values may be accessed as sub-fields -of the `u_boot_console.config` object, for example -`u_boot_console.config.ram_base`. +of the `ubman.config` object, for example +`ubman.config.ram_base`. Build configuration values (from `.config`) may be accessed via the dictionary -`u_boot_console.config.buildconfig`, with keys equal to the Kconfig variable +`ubman.config.buildconfig`, with keys equal to the Kconfig variable names. diff --git a/doc/develop/release_cycle.rst b/doc/develop/release_cycle.rst index b108f9b11e0..cbbc2bad0eb 100644 --- a/doc/develop/release_cycle.rst +++ b/doc/develop/release_cycle.rst @@ -53,7 +53,7 @@ Current Status * U-Boot v2025.04 was released on Monday, 07 April 2025. -* The Merge Window for the next release (v2025.04) is **open** until the -rc1 +* The Merge Window for the next release (v2025.07) is **open** until the -rc1 release on Monday, 28 April 2025. * The next branch is now **closed** until the -rc2 release on Monday, 12 May diff --git a/doc/develop/tests_writing.rst b/doc/develop/tests_writing.rst index 54efb7e1b04..7ea17081def 100644 --- a/doc/develop/tests_writing.rst +++ b/doc/develop/tests_writing.rst @@ -116,19 +116,19 @@ below are approximate, as measured on an AMD 2950X system. Here is is the test in Python:: @pytest.mark.buildconfigspec('cmd_memory') - def test_md(u_boot_console): + def test_md(ubman): """Test that md reads memory as expected, and that memory can be modified using the mw command.""" - ram_base = u_boot_utils.find_ram_base(u_boot_console) + ram_base = utils.find_ram_base(ubman) addr = '%08x' % ram_base val = 'a5f09876' expected_response = addr + ': ' + val - u_boot_console.run_command('mw ' + addr + ' 0 10') - response = u_boot_console.run_command('md ' + addr + ' 10') + ubman.run_command('mw ' + addr + ' 0 10') + response = ubman.run_command('md ' + addr + ' 10') assert(not (expected_response in response)) - u_boot_console.run_command('mw ' + addr + ' ' + val) - response = u_boot_console.run_command('md ' + addr + ' 10') + ubman.run_command('mw ' + addr + ' ' + val) + response = ubman.run_command('md ' + addr + ' 10') assert(expected_response in response) This runs a few commands and checks the output. Note that it runs a command, @@ -261,7 +261,7 @@ with the suite. For example, to add a new mem_search test:: /* Test 'ms' command with 32-bit values */ static int mem_test_ms_new_thing(struct unit_test_state *uts) { - /* test code here*/ + /* test code here */ return 0; } @@ -291,32 +291,20 @@ suite. For example:: /* Declare a new wibble test */ #define WIBBLE_TEST(_name, _flags) UNIT_TEST(_name, _flags, wibble_test) - /* Tetss go here */ - - /* At the bottom of the file: */ - - int do_ut_wibble(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[]) - { - struct unit_test *tests = UNIT_TEST_SUITE_START(wibble_test); - const int n_ents = UNIT_TEST_SUITE_COUNT(wibble_test); - - return cmd_ut_category("cmd_wibble", "wibble_test_", tests, n_ents, argc, argv); - } + /* Tests go here */ Then add new tests to it as above. Register this new suite in test/cmd_ut.c by adding to cmd_ut_sub[]:: - /* Within cmd_ut_sub[]... */ - - U_BOOT_CMD_MKENT(wibble, CONFIG_SYS_MAXARGS, 1, do_ut_wibble, "", ""), + /* with the other SUITE_DECL() declarations */ + SUITE_DECL(wibble); -and adding new help to ut_help_text[]:: + /* Within suites[]... */ + SUITE(wibble, "my test of wibbles"); - "ut wibble - Test the wibble feature\n" - -If your feature is conditional on a particular Kconfig, then you can use #ifdef -to control that. +If your feature is conditional on a particular Kconfig, you do not need to add +an #ifdef since the suite will automatically be compiled out in that case. Finally, add the test to the build by adding to the Makefile in the same directory:: @@ -326,17 +314,35 @@ directory:: Note that CMDLINE is never enabled in SPL, so this test will only be present in U-Boot proper. See below for how to do SPL tests. -As before, you can add an extra Kconfig check if needed:: +You can add an extra Kconfig check if needed:: ifneq ($(CONFIG_$(XPL_)WIBBLE),) obj-$(CONFIG_$(XPL_)CMDLINE) += wibble.o endif +Each suite can have an optional init and uninit function. These are run before +and after any suite tests, respectively:: + + #define WIBBLE_TEST_INIT(_name, _flags) UNIT_TEST_INIT(_name, _flags, wibble_test) + #define WIBBLE_TEST_UNINIT(_name, _flags) UNIT_TEST_UNINIT(_name, _flags, wibble_test) -Example commit: 919e7a8fb64 ("test: Add a simple test for bloblist") [1] + static int wibble_test_init(struct unit_test_state *uts) + { + /* init code here */ + + return 0; + } + WIBBLE_TEST_INIT(wibble_test_init, 0); -[1] https://gitlab.denx.de/u-boot/u-boot/-/commit/919e7a8fb64 + static int wibble_test_uninit(struct unit_test_state *uts) + { + /* uninit code here */ + + return 0; + } + WIBBLE_TEST_INIT(wibble_test_uninit, 0); +Both functions are included in the totals for each suite. Making the test run from pytest ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/device-tree-bindings/mtd/cadence,nand.yaml b/doc/device-tree-bindings/mtd/cadence,nand.yaml new file mode 100644 index 00000000000..11ce023ec64 --- /dev/null +++ b/doc/device-tree-bindings/mtd/cadence,nand.yaml @@ -0,0 +1,98 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/cadence,nand.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Cadence NAND controller + +maintainers: + - Dinesh Maniyam <dinesh.maniyam@intel.com> + +properties: + compatible: + enum: + - cdns,nand + + reg-names: + description: | + There are two register regions: + reg: register interface + sdma: host data/command interface + items: + - const: reg + - const: sdma + + reg: + minItems: 2 + maxItems: 2 + + interrupts: + maxItems: 1 + + clocks: + description: | + There is one controller core clock + maxItems: 1 + + resets: + description: | + There are two resets: + controller core reset + combo-phy register reset + minItems: 1 + maxItems: 2 + + cdns,board-delay-ps: + description: | + Estimated Board delay. The value includes the total + round trip delay for the signals and is used for deciding on values + associated with data read capture. The example formula for SDR mode is + the following: + board delay = RE#PAD delay + PCB trace to device + PCB trace from device + + DQ PAD delay + enum: + - 4830 + +patternProperties: + "^nand@[a-f0-9]$": + type: object + properties: + compatible: + const: cdns,nand + + reg: + maxItems: 1 + + label: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + - cdns,board-delay-ps + +unevaluatedProperties: false + +examples: + - | + nand-controller@60000000 { + compatible = "cdns,nand"; + reg = <0x60000000 0x10000>, <0x80000000 0x1000>; + reg-names = "reg", "sdma"; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&clk>; + cdns,board-delay-ps = <4830>; + interrupts = <2 0>; + nand@0 { + label = "nand-0"; + reg = <0>; + }; + nand@1 { + label = "nand-1"; + reg = <1>; + }; + }; diff --git a/doc/device-tree-bindings/pinctrl/adi,adsp-pinctrl.yaml b/doc/device-tree-bindings/pinctrl/adi,adsp-pinctrl.yaml new file mode 100644 index 00000000000..418ebd5ce41 --- /dev/null +++ b/doc/device-tree-bindings/pinctrl/adi,adsp-pinctrl.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: (GPL-2.0+ OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pinctrl/adi,adsp-pinctrl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Pinctrl Driver for Analog Devices SC5xx Processors + +maintainers: + - Vasileios Bimpikas <vasileios.bimpikas@analog.com> + - Utsav Agarwal <utsav.agarwal@analog.com> + - Arturs Artamonovs <arturs.artamonovs@analog.com> + +description: | + This driver provides an interface for performing pin configuration + Analog Devices SoCs using the ADSP PORT hardware for pin + configuration according to the HRM. Currently this is only the + SC5xx series. + +properties: + compatible: + const: adi,adsp-pinctrl + + reg: + maxItems: 1 + + adi,npins: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Total number of pins available to this SoC's pin controller, + found in the HRM. + +patternProperties: + '_pins$': + type: object + + properties: + adi,pins: + $ref: /schemas/types.yaml#/definitions/uint32-array + description: + For n pins, 2n values must be provided as a sequence of pin + name as identified with the ADI_ADSP_PIN() macro and a pin + function constant, both defined in + include/dt-bindings/pinctrl/adi-adsp.h. + + required: + - adi,pins + + additionalProperties: false + +required: + - compatible + - reg + - adi,npins + +additionalProperties: false + +examples: + - | + #include <dt-bindings/pinctrl/adi-adsp.h> + + soc { + pinctrl0: pinctrl@0x31004000 { + compatible = "adi,adsp-pinctrl"; + reg = <0x31004000 0x500>; + adi,npins = <135>; + uart0_default: uart0_pins { + adi,pins = <ADI_ADSP_PIN('A', 6) ADI_ADSP_PINFUNC_ALT1>, + <ADI_ADSP_PIN('A', 7) ADI_ADSP_PINFUNC_ALT1>; + }; + }; + + }; diff --git a/doc/usage/cmd/acpi.rst b/doc/usage/cmd/acpi.rst index 9f30972fe53..e652968d584 100644 --- a/doc/usage/cmd/acpi.rst +++ b/doc/usage/cmd/acpi.rst @@ -11,7 +11,7 @@ Synopsis :: - acpi list + acpi list [-c] acpi items [-d] acpi dump <name> acpi set <address> @@ -38,6 +38,9 @@ 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`_. +The `-c` flag tells U-Boot to verify the checksums and print 'OK' or 'BAD' next +to each table. + 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. @@ -259,5 +262,20 @@ pointer:: WAET bff76a3b 28 v01 BOCHS BXPC 1 BXPC 1 SSDT bff95040 c5 v02 COREv4 COREBOOT 2a CORE 20221020 +This shows checking that the checksums are correct for each table:: + + => acpi list -c + Name Base Size Detail + ---- ---------------- ----- ---------------------------- + RSDP bec9a000 24 v00 BOCHS OK OK + RSDT bec9bd4a 38 v01 BOCHS BXPC 1 BXPC 1 OK + FACP bec9bb46 74 v01 BOCHS BXPC 1 BXPC 1 OK + DSDT bec9a080 1ac6 v01 BOCHS BXPC 1 BXPC 1 OK + FACS bec9a040 40 + APIC bec9bbba 78 v03 BOCHS BXPC 1 BXPC 1 OK + HPET bec9bc32 38 v01 BOCHS BXPC 1 BXPC 1 OK + SRAT bec9bc6a b8 v01 BOCHS BXPC 1 BXPC 1 OK + WAET bec9bd22 28 v01 BOCHS BXPC 1 BXPC 1 OK + .. _`ACPI specification`: https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf diff --git a/doc/usage/cmd/fuse.rst b/doc/usage/cmd/fuse.rst new file mode 100644 index 00000000000..42c6e209f99 --- /dev/null +++ b/doc/usage/cmd/fuse.rst @@ -0,0 +1,176 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: fuse (command) + +fuse command +============ + +Synopsis +-------- + +:: + + fuse read <bank> <word> [<cnt>] + fuse cmp <bank> <word> <hexval> + fuse readm <bank> <word> <addr> [<cnt>] + fuse sense <bank> <word> [<cnt>] + fuse prog [-y] <bank> <word> <hexval> [<hexval>...] + fuse override <bank> <word> <hexval> [<hexval>...] + fuse writebuff [-y] <addr> + +Description +----------- + +The fuse API allows to control a fusebox and how it is used by the upper +hardware layers. + +A fuse corresponds to a single non-volatile memory bit that can be programmed +(i.e., blown, set to 1) only once. The programming operation is irreversible. +A fuse that has not been programmed reads as 0. + +Fuses can be used by SoCs to store various permanent configurations and data, +such as boot configurations, security settings, MAC addresses, etc. + +A fuse 'word' is the smallest group of fuses that can be read at once from +the fusebox control IP registers. In the current API, this is limited to 32 bits. + +A fuse 'bank' is the smallest group of fuse words having a common ID, as +defined by each SoC. + +Upon startup, the fusebox control IP reads the fuse values and stores them in a +volatile shadow cache. + +Commands +-------- + +- **fuse read <bank> <word> [<cnt>]** + Reads 1 or 'cnt' fuse words, starting at 'word' from the shadow cache. + +- **fuse cmp <bank> <word> <hexval>** + Compares 'hexval' to fuse at 'word'. + +- **fuse readm <bank> <word> <addr> [<cnt>]** + Reads 1 or 'cnt' fuse words, starting at 'word' into memory at 'addr'. + +- **fuse sense <bank> <word> [<cnt>]** + Sense 1 or 'cnt' fuse words, starting at 'word'. + Sense - i.e. read directly from the fusebox, skipping the shadow cache - + fuse words. This operation does not update the shadow cache. This is + useful to know the true value of fuses if an override has been + performed (see below). + +- **fuse prog [-y] <bank> <word> <hexval> [<hexval>...]** + Permanently programs 1 or several fuse words, starting at 'word'. + This operation directly affects the fusebox and is irreversible. The + shadow cache is updated accordingly or not, depending on each IP. + Only the bits to be programmed should be set in the input value (i.e. + for fuse bits that have already been programmed and hence should be + left unchanged by a further programming, it is preferable to clear + the corresponding bits in the input value in order not to perform a + new hardware programming operation on these fuse bits). + +- **fuse override <bank> <word> <hexval> [<hexval>...]** + Override 1 or several fuse words, starting at 'word' in the shadow cache. + The fusebox is unaffected, so following this operation, the shadow cache + may differ from the fusebox values. Read or sense operations can then be + used to get the values from the shadow cache or from the fusebox. + This is useful to change the behaviours linked to some cached fuse values, + either because this is needed only temporarily, or because some of the + fuses have already been programmed or are locked (if the SoC allows to + override a locked fuse). + +- **fuse writebuff [-y] <addr>** + Programs fuse data using a structured buffer in memory starting at 'addr'. + This operation directly affects the fusebox and is irreversible. + + The structure of the buffer should contain all necessary details for + programming fuses, such as the values to be written to the fuse, optional + metadata for validation or programming constraints and any configuration + data required for the operation. Define CONFIG_CMD_FUSE_WRITEBUFF to + enable the fuse writebuff command. + +Examples +-------- + +fuse read +~~~~~~~~~ + +:: + + u-boot=> fuse read 0 1 + Reading bank 0: + + Word 0x00000001: 00000001 + +fuse cmp +~~~~~~~~ + +:: + + u-boot=> fuse cmp 0 1 0x1 + Comparing bank 0: + + Word 0x00000001: + Value 0x00000001:0x00000001 + passed + +fuse readm +~~~~~~~~~~ + +:: + + u-boot=> fuse readm 0 1 0x83000000 + Reading bank 0 len 1 to 0x83000000 + +fuse sense +~~~~~~~~~~ + +:: + + u-boot=> fuse sense 0 1 + Sensing bank 0: + + Word 0x00000001: 00000001 + +fuse prog +~~~~~~~~~ + +:: + + u-boot=> fuse prog 0 1 0x00000002 + Programming bank 0 word 0x00000001 to 0x00000002... + Warning: Programming fuses is an irreversible operation! + This may brick your system. + Use this command only if you are sure of what you are doing! + + Really perform this fuse programming? <y/N> + y + +fuse override +~~~~~~~~~~~~~ + +:: + + u-boot=> fuse override 0 1 0x00000003 + Overriding bank 0 word 0x00000001 with 0x00000003... + +fuse writebuff +~~~~~~~~~~~~~~ + +:: + + u-boot=> fuse writebuff -y 0x84000000 + Programming fuses with buffer at addr 0x84000000 + +Configuration +------------- + +The fuse commands are available if CONFIG_CMD_FUSE=y. +The fuse writebuff command is available if CONFIG_CMD_FUSE_WRITEBUFF=y. + +Return code +----------- + +The return value $? is set to 0 (true) if the command is successful, +1 (false) otherwise. diff --git a/doc/usage/cmd/meminfo.rst b/doc/usage/cmd/meminfo.rst index 6c94493cccc..e10bdc6832c 100644 --- a/doc/usage/cmd/meminfo.rst +++ b/doc/usage/cmd/meminfo.rst @@ -18,7 +18,8 @@ Description The meminfo command shows the amount of memory. If ``CONFIG_CMD_MEMINFO_MAP`` is enabled, then it also shows the layout of memory used by U-Boot and the region -which is free for use by images. +which is free for use by images. In architectures that support it, it also prints +the mapped pages and their permissions. The latter is architecture specific. The layout of memory is set up before relocation, within the init sequence in ``board_init_f()``, specifically the various ``reserve_...()`` functions. This @@ -26,8 +27,9 @@ The layout of memory is set up before relocation, within the init sequence in ending with the stack. This results in the maximum possible amount of memory being left free for image-loading. -The meminfo command writes the DRAM size, then the rest of its outputs in 5 -columns: +The meminfo command writes the DRAM size. If the architecture also supports it, +page table entries will be shown next. Finally the rest of the outputs are +printed in 5 columns: Region Name of the region @@ -99,28 +101,61 @@ free Free memory, which is available for loading images. The base address of this is ``gd->ram_base`` which is generally set by ``CFG_SYS_SDRAM_BASE``. +Aarch64 specific flags +---------------------- + +More information on the output can be found +Chapter D8 - The AArch64 Virtual Memory System Architecture at +https://developer.arm.com/documentation/ddi0487/latest/ + +In short, for a stage 1 translation regime the following apply: + +* RWX: Pages mapped with Read, Write and Execute permissions +* RO: Pages mapped with Read-Only permissions +* PXN: PXN (Privileged Execute Never) applies to execution at EL1 and above +* UXN: UXN (Unprivileged Execute Never) applies to EL0 + Example ------- This example shows output with both ``CONFIG_CMD_MEMINFO`` and -``CONFIG_CMD_MEMINFO_MAP`` enabled:: - - => meminfo - DRAM: 256 MiB +``CONFIG_CMD_MEMINFO_MAP`` enabled for aarch64 qemu:: + + DRAM: 8 GiB + Walking pagetable at 000000023ffe0000, va_bits: 40. Using 4 levels + [0x0000023ffe1000] | Table | | | + [0x0000023ffe2000] | Table | | | + [0x00000000000000 - 0x00000008000000] | Block | RWX | Normal | Inner-shareable + [0x00000008000000 - 0x00000040000000] | Block | PXN UXN | Device-nGnRnE | Non-shareable + [0x00000040000000 - 0x00000200000000] | Block | RWX | Normal | Inner-shareable + [0x0000023ffea000] | Table | | | + [0x00000200000000 - 0x0000023f600000] | Block | RWX | Normal | Inner-shareable + [0x0000023ffeb000] | Table | | | + [0x0000023f600000 - 0x0000023f68c000] | Pages | RWX | Normal | Inner-shareable + [0x0000023f68c000 - 0x0000023f74f000] | Pages | RO | Normal | Inner-shareable + [0x0000023f74f000 - 0x0000023f794000] | Pages | PXN UXN RO | Normal | Inner-shareable + [0x0000023f794000 - 0x0000023f79d000] | Pages | PXN UXN | Normal | Inner-shareable + [0x0000023f79d000 - 0x0000023f800000] | Pages | RWX | Normal | Inner-shareable + [0x0000023f800000 - 0x00000240000000] | Block | RWX | Normal | Inner-shareable + [0x00000240000000 - 0x00004000000000] | Block | RWX | Normal | Inner-shareable + [0x0000023ffe3000] | Table | | | + [0x00004010000000 - 0x00004020000000] | Block | PXN UXN | Device-nGnRnE | Non-shareable + [0x0000023ffe4000] | Table | | | + [0x00008000000000 - 0x00010000000000] | Block | PXN UXN | Device-nGnRnE | Non-shareable Region Base Size End Gap ------------------------------------------------ - video f000000 1000000 10000000 - code ec3a000 3c5d28 efffd28 2d8 - malloc 8c38000 6002000 ec3a000 0 - board_info 8c37f90 68 8c37ff8 8 - global_data 8c37d80 208 8c37f88 8 - devicetree 8c33000 4d7d 8c37d7d 3 - bootstage 8c32c20 3c8 8c32fe8 18 - bloblist 8c32000 400 8c32400 820 - stack 7c31ff0 1000000 8c31ff0 10 - free 0 7c31ff0 7c31ff0 0 - + video 23f7e0000 800000 23ffe0000 + code 23f68a000 156000 23f7e0000 0 + malloc 23e64a000 1040000 23f68a000 0 + board_info 23e649f80 78 23e649ff8 8 + global_data 23e649df0 188 23e649f78 8 + devicetree 23e549df0 100000 23e649df0 0 + bloblist 23e547000 2000 23e549000 df0 + stack 23d546ff0 1000000 23e546ff0 10 + lmb 23d546ff0 0 23d546ff0 0 + lmb 23d543000 3ff0 23d546ff0 0 + free 40000000 23d543000 27d543000 ffffffffc0000000 Return value ------------ diff --git a/doc/usage/cmd/mv.rst b/doc/usage/cmd/mv.rst new file mode 100644 index 00000000000..99864371038 --- /dev/null +++ b/doc/usage/cmd/mv.rst @@ -0,0 +1,61 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +.. index:: + single: mv (command) + +mv command +========== + +Synopsis +-------- + +:: + + mv <interface> [<dev[:part]>] <old_path> <new_path> + +Description +----------- + +The mv command renames/moves a file or directory within a filesystem. + +interface + interface for accessing the block device (mmc, sata, scsi, usb, ....) + +dev + device number + +part + partition number, defaults to 0 (whole device) + +old_path + existing path to file/directory + +new_path + new path/name for the rename/move + + +Example +------- + + # Rename file 'foo' in directory 'dir' to 'bar' + mv mmc 0:0 dir/foo dir/bar + + # Move file 'f' from directory 'foo' to existing directory 'bar' renaming + # 'f' to 'g' + mv mmc 0:0 foo/f bar/g + + # Move directory 'abc' in directory 'dir1' into existing directory 'dir2' + mv mmc 0:0 dir1/abc dir2 + +Configuration +------------- + +The mv 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 +renamed/moved. + +If an error occurs, the return value $? is set to 1 (false). diff --git a/doc/usage/cmd/ut.rst b/doc/usage/cmd/ut.rst index e794922c806..1acf3126680 100644 --- a/doc/usage/cmd/ut.rst +++ b/doc/usage/cmd/ut.rst @@ -11,34 +11,44 @@ Synopsis :: - ut [-r<runs>] [-fs] [-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 + ut [-r<runs>] [-f] [-I<n>:<one_test>] [-r<n>] [<suite> | 'all' [<test>]] + ut [-s] info Description ----------- The ut command runs unit tests written in C. +suite + Specifies the suite to run, This can be a single suite, or a comma-separated + list + +test + Speciifes a particular test to run, within a suite, or all suites + +-f + Forces running of a manual test. + +-r <n> + Specifies the number of types to run each test + +-I <n>:<one_test> + Test to run after <n> other tests have run. This is used to find which test + causes another test to fail. If the one test fails, testing stops + immediately. + 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 info -s`. - Each test is normally run once, although those marked with `UTF_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. +:ref:`develop/tests_writing:mixing python and c` for more information on manual +tests. 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 @@ -50,9 +60,22 @@ the problem. Generally all tests in the suite are run. To run just a single test from the suite, provide the <test> argument. +To specify a list of suites to run, <suites> can also be a comma-separated list. + See :ref:`develop/tests_writing:writing c tests` for more information on how to write unit tests. +ut all +~~~~~~ + +Instead of a suite name 'all' may be used to run all tests. + +ut info +~~~~~~~ + +This provides information about the total number of suites and tests. Use the +`-s` flag to show a detailed list of suites. + Example ------- @@ -97,26 +120,84 @@ List available unit-test suites:: 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 + => ut common + Running 14 common tests + Test: cli_ch_test: cread.c + Test: cread_test: cread.c + Test: dm_test_cyclic_running: cyclic.c + Test: print_display_buffer: print.c + Test: print_do_hex_dump: print.c + Test: print_efi_ut: print.c + Test: print_guid: print.c + Test: print_hexdump_line: print.c + Test: print_printf: print.c + Test: snprint: print.c + Test: test_autoboot: test_autoboot.c + Enter password "a" in 1 seconds to stop autoboot + Enter password "a" in 1 seconds to stop autoboot + Enter password "a" in 1 seconds to stop autoboot + Enter password "a" in 1 seconds to stop autoboot + Enter password "a" in 1 seconds to stop autoboot + Enter password "a" in 1 seconds to stop autoboot + Autoboot password unlock not successful + Test: test_event_base: event.c + Test: test_event_probe: event.c + Test: test_event_probe: event.c (flat tree) + Test: test_event_simple: event.c + Tests run: 14, 2611 ms, average 186 ms, skipped: 2, failures: 0 Run just a single test in a suite:: - => ut bloblist bloblist_test_grow - Test: bloblist_test_grow: bloblist.c - Failures: 0 + => ut fdt_overlay change_int_property + Test: fdt_overlay_init: cmd_ut_fdt_overlay.c + Test: change_int_property: cmd_ut_fdt_overlay.c + Tests run: 2, 0 ms, average 0 ms, failures: 0 + +Run a selection of three suites:: + + => ut bloblist,mem,fdt_overlay + Running 14 bloblist tests + Test: align: bloblist.c + Test: bad_blob: bloblist.c + Test: blob: bloblist.c + Test: blob_ensure: bloblist.c + Test: blob_maxsize: bloblist.c + Test: checksum: bloblist.c + Test: cmd_info: bloblist.c + Test: cmd_list: bloblist.c + Test: grow: bloblist.c + Test: init: bloblist.c + Test: reloc: bloblist.c + Test: resize_fail: bloblist.c + Test: resize_last: bloblist.c + Test: shrink: bloblist.c + Tests run: 14, 1 ms, average: 0 ms, failures: 0 + Running 13 mem tests + Test: cp_b: mem_copy.c + Test: cp_l: mem_copy.c + Test: cp_q: mem_copy.c + Test: cp_w: mem_copy.c + Test: ms_b: mem_search.c + Test: ms_cont: mem_search.c + Test: ms_cont_end: mem_search.c + Test: ms_l: mem_search.c + Test: ms_limit: mem_search.c + Test: ms_mult: mem_search.c + Test: ms_quiet: mem_search.c + Test: ms_s: mem_search.c + Test: ms_w: mem_search.c + Tests run: 13, 13 ms, average: 1 ms, failures: 0 + Running 10 fdt_overlay tests + Test: fdt_overlay_init: cmd_ut_fdt_overlay.c + Test: add_node_by_path: cmd_ut_fdt_overlay.c + Test: add_node_by_phandle: cmd_ut_fdt_overlay.c + Test: add_str_property: cmd_ut_fdt_overlay.c + Test: add_subnode_property: cmd_ut_fdt_overlay.c + Test: change_int_property: cmd_ut_fdt_overlay.c + Test: change_str_property: cmd_ut_fdt_overlay.c + Test: local_phandle: cmd_ut_fdt_overlay.c + Test: local_phandles: cmd_ut_fdt_overlay.c + Test: stacked: cmd_ut_fdt_overlay.c + Tests run: 10, 12 ms, average: 1 ms, failures: 0 + Suites run: 3, total tests run: 37, 26 ms, average: 0 ms, failures: 0 + Average test time: 0 ms, worst case 'mem' took 1 ms diff --git a/doc/usage/cmd/wget.rst b/doc/usage/cmd/wget.rst index 48bedf1e845..cc82e495a29 100644 --- a/doc/usage/cmd/wget.rst +++ b/doc/usage/cmd/wget.rst @@ -12,7 +12,9 @@ Synopsis :: wget [address] [host:]path - wget [address] url # lwIP only + wget [address] url # lwIP only + wget cacert none|optional|required # lwIP only + wget cacert <address> <size> # lwIP only Description @@ -54,6 +56,32 @@ address url HTTP or HTTPS URL, that is: http[s]://<host>[:<port>]/<path>. +The cacert (stands for 'Certification Authority certificates') subcommand is +used to provide root certificates for the purpose of HTTPS authentication. It +also allows to enable or disable authentication. + +wget cacert <address> <size> + +address + memory address of the root certificates in X509 DER format + +size + the size of the root certificates + +wget cacert none|optional|required + +none + certificate verification is disabled. HTTPS is used without any server + authentication (unsafe) +optional + certificate verification is enabled provided root certificates have been + provided via wget cacert <addr> <size> or wget cacert builtin. Otherwise + HTTPS is used without any server authentication (unsafe). +required + certificate verification is mandatory. If no root certificates have been + configured, HTTPS transfers will fail. + + Examples -------- @@ -97,11 +125,61 @@ In the example the following steps are executed: 1694892032 bytes transferred in 492181 ms (3.3 MiB/s) Bytes transferred = 1694892032 (65060000 hex) +Here is an example showing how to configure built-in root certificates as +well as providing some at run time. In this example it is assumed that +CONFIG_WGET_BUILTIN_CACERT_PATH=DigiCertTLSRSA4096RootG5.crt downloaded from +https://cacerts.digicert.com/DigiCertTLSRSA4096RootG5.crt. + +:: + + # Make sure IP is configured + => dhcp + # When built-in certificates are configured, authentication is mandatory + # (i.e., "wget cacert required"). Use a test server... + => wget https://digicert-tls-rsa4096-root-g5.chain-demos.digicert.com/ + 1864 bytes transferred in 1 ms (1.8 MiB/s) + Bytes transferred = 1864 (748 hex) + # Another server not signed against Digicert will fail + => wget https://www.google.com/ + Certificate verification failed + + HTTP client error 4 + # Disable authentication to allow the command to proceed anyways + => wget cacert none + => wget https://www.google.com/ + WARNING: no CA certificates, HTTPS connections not authenticated + 16683 bytes transferred in 15 ms (1.1 MiB/s) + Bytes transferred = 16683 (412b hex) + # Force verification but unregister the CA certificates + => wget cacert required + => wget cacert 0 0 + # Unsurprisingly, download fails + => wget https://digicert-tls-rsa4096-root-g5.chain-demos.digicert.com/ + Error: cacert authentication mode is 'required' but no CA certificates given + # Get the same certificates as above from the network + => wget cacert none + => wget https://cacerts.digicert.com/DigiCertTLSRSA4096RootG5.crt + WARNING: no CA certificates, HTTPS connections not authenticated + 1386 bytes transferred in 1 ms (1.3 MiB/s) + Bytes transferred = 1386 (56a hex) + # Register them and force authentication + => wget cacert $fileaddr $filesize + => wget cacert required + # Authentication is operational again + => wget https://digicert-tls-rsa4096-root-g5.chain-demos.digicert.com/ + 1864 bytes transferred in 1 ms (1.8 MiB/s) + Bytes transferred = 1864 (748 hex) + # The builtin certificates can be restored at any time + => wget cacert builtin + Configuration ------------- The command is only available if CONFIG_CMD_WGET=y. -To enable lwIP support set CONFIG_NET_LWIP=y. +To enable lwIP support set CONFIG_NET_LWIP=y. In this case, root certificates +support can be enabled via CONFIG_WGET_BUILTIN_CACERT=y +CONFIG_WGET_BUILTIN_CACERT_PATH=<some path> (for built-in certificates) and/or +CONFIG_WGET_CACERT=y (for the wget cacert command). TCP Selective Acknowledgments in the legacy network stack can be enabled via CONFIG_PROT_TCP_SACK=y. This will improve the download speed. Selective diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst index 30fc16794fc..7e2f2863d06 100644 --- a/doc/usage/environment.rst +++ b/doc/usage/environment.rst @@ -87,6 +87,18 @@ settings. For example:: #include <env/ti/mmc.env> +Quotes are not suppressed, for example:: + + fdtfile=CONFIG_DEFAULT_DEVICE_TREE.dtb + # produces: fdtfile="sun7i-a20-pcduino3.dtb" + +For this particular issue you can use ``DEFAULT_DEVICE_TREE`` instead:: + + fdtfile=DEFAULT_DEVICE_TREE.dtb + # produces: fdtfile=sun7i-a20-pcduino3.dtb + +There is no general way to remove quotes. + If CONFIG_ENV_SOURCE_FILE is empty and the default filename is not present, then the old-style C environment is used instead. See below. diff --git a/doc/usage/index.rst b/doc/usage/index.rst index bf2335dc8f0..372ef56c967 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -72,6 +72,7 @@ Shell commands cmd/fdt cmd/font cmd/for + cmd/fuse cmd/fwu_mdata cmd/gpio cmd/gpt @@ -93,6 +94,7 @@ Shell commands cmd/msr cmd/mtest cmd/mtrr + cmd/mv cmd/optee cmd/panic cmd/part |