diff options
Diffstat (limited to 'doc')
40 files changed, 955 insertions, 165 deletions
diff --git a/doc/api/index.rst b/doc/api/index.rst index a108718ea99..506843ed74a 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -25,6 +25,8 @@ U-Boot API documentation rng sandbox serial + setjmp sysreset timer unicode + uthread diff --git a/doc/api/setjmp.rst b/doc/api/setjmp.rst new file mode 100644 index 00000000000..c30e51c2b55 --- /dev/null +++ b/doc/api/setjmp.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Long jump API +============= + +.. kernel-doc:: include/setjmp.h + :doc: Overview + +.. kernel-doc:: include/setjmp.h + :internal: + +Example +------- + +Here is an example showing how to use the a long jump functions and +initjmp() in particular: + +.. literalinclude:: ../../test/lib/initjmp.c + :language: c + :linenos: diff --git a/doc/api/uthread.rst b/doc/api/uthread.rst new file mode 100644 index 00000000000..8b25cc1ff80 --- /dev/null +++ b/doc/api/uthread.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Uthread API +=========== + +.. kernel-doc:: include/uthread.h + :doc: Overview + +.. kernel-doc:: include/uthread.h + :internal: + +Example +------- + +Here is an example of how to use this API: + +.. literalinclude:: ../../test/lib/uthread.c + :language: c + :linenos: diff --git a/doc/arch/arm64.rst b/doc/arch/arm64.rst index 19662be6fc6..d72200ffdb9 100644 --- a/doc/arch/arm64.rst +++ b/doc/arch/arm64.rst @@ -14,11 +14,11 @@ Notes ----- 1. U-Boot can run at any exception level it is entered in, it is - recommened to enter it in EL3 if U-Boot takes some responsibilities of a + recommended to enter it in EL3 if U-Boot takes some responsibilities of a classical firmware (like initial hardware setup, CPU errata workarounds or SMP bringup). U-Boot can be entered in EL2 when its main purpose is that of a boot loader. It can drop to lower exception levels before - entering the OS. For ARMv8-R it is recommened to enter at S-EL1, as for this + entering the OS. For ARMv8-R it is recommended to enter at S-EL1, as for this architecture there is no S-EL3. 2. U-Boot for arm64 is compiled with AArch64-gcc. AArch64-gcc diff --git a/doc/board/asus/index.rst b/doc/board/asus/index.rst index 2cac04ce04a..a9ba7a5ac53 100644 --- a/doc/board/asus/index.rst +++ b/doc/board/asus/index.rst @@ -9,3 +9,4 @@ ASUS grouper transformer_t20 transformer_t30 + transformer_t114 diff --git a/doc/board/asus/transformer_t114.rst b/doc/board/asus/transformer_t114.rst new file mode 100644 index 00000000000..3e42b5dd9a3 --- /dev/null +++ b/doc/board/asus/transformer_t114.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for the ASUS Transformer device family +============================================= + +Quick Start +----------- + +- Build U-Boot +- Boot U-Boot by loading it into RAM (coldboot) +- Chainloading U-Boot from the vendor bootloader +- Boot + +Build U-Boot +------------ + +U-Boot can be built in two forms: U-Boot with SPL, which is used for booting +by loading directly into RAM and U-Boot without SPL, which can be flashed +and chainloaded from the vendor bootloader. + +To build U-Boot with SPL proseed: + +.. code-block:: bash + + $ export CROSS_COMPILE=arm-none-eabi- + $ make tf701t_defconfig + $ make + +After the build succeeds, you will obtain the final ``u-boot-dtb-tegra.bin`` +file, ready for cold booting by loading into RAM. + +To build U-Boot without SPL adjust tf701t_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 with fastboot boot or which can be further processed into +a flashable boot.img. + +Boot U-Boot by loading it into RAM (coldboot) +--------------------------------------------- + +Done fairly simply by using fusee-tools (using run_bootloader.sh) and placing +``u-boot-dtb-tegra.bin`` generated on the previous step into fusee-tools dir. +This method requires constant access to the host PC or payloader and can fully +eliminate influence of the vendor bootloader onto the boot process. + +.. code-block:: bash + + $ ./run_bootloader.sh -s T114 -t ./bct/tf701t.bct + +Chainloading U-Boot from the vendor bootloader +---------------------------------------------- + +``u-boot-dtb.bin`` has to be further packed into Android boot image form, +where ``u-boot-dtb.bin`` acts as kernel, while dtb and ramdisk parts should +not be included. Then the generated boot image can be flashed into the /boot +partition of the tablet using vendor bootloader's fastboot and will act as +the bootloader of the last stage. + +Boot +---- +In both cases after U-Boot obtains control it performs search of extlinux.conf +first on the dock USB device is available, then on MicroSD card if available +and lastly on eMMC. If none of the devices above are present, then the device +is turned off. + +If during boot of U-Boot Volume Down button is pressed, the device will enter +U-Boot bootmenu. diff --git a/doc/board/index.rst b/doc/board/index.rst index 7ad1137c94a..3c5a2c7d1cf 100644 --- a/doc/board/index.rst +++ b/doc/board/index.rst @@ -41,6 +41,8 @@ Board-specific doc mediatek/index microchip/index microsoft/index + motorola/index + nvidia/index nxp/index openpiton/index ouya/index diff --git a/doc/board/motorola/index.rst b/doc/board/motorola/index.rst new file mode 100644 index 00000000000..9666ff2f4ab --- /dev/null +++ b/doc/board/motorola/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Motorola +======== + +.. toctree:: + :maxdepth: 2 + + mot diff --git a/doc/board/motorola/mot.rst b/doc/board/motorola/mot.rst new file mode 100644 index 00000000000..d0f89bcd357 --- /dev/null +++ b/doc/board/motorola/mot.rst @@ -0,0 +1,104 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for the Motorola Atrix 4G (MB860) and Droid X2 (MB870) +============================================================= + +``DISCLAMER!`` Moving your device 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 if you have backups. + +Quick Start +----------- + +- Prerequisites +- Build U-Boot +- Process U-Boot +- Flashing U-Boot into the eMMC +- Boot +- Self Upgrading + +Prerequisites +------------- + +In order to work with RCM/APX mode, both devices require a factory cable which +is made by routing 5V to the ID pin of a micro-USB cable (5v is applied to both +ID and dedicated 5v). This way, the host PC can detect the device in RCM mode, +and the device can operate without a battery. + +Build U-Boot +------------ + +Device support is implemented by applying config fragment to a generic +board defconfig. Valid fragments are ``daytona.config`` and ``olympus.config``. + +.. code-block:: bash + + $ export CROSS_COMPILE=arm-none-eabi- + $ make mot_defconfig olympus.config # For Atrix 4G + $ 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. You need to know your device +individual SBK to continue. + +.. 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 olympus --sbk <your sbk> --split + +where SBK has next form ``0xXXXXXXXX`` ``0xXXXXXXXX`` ``0xXXXXXXXX`` ``0xXXXXXXXX`` + +The script will produce ``bct.img`` and ``ebt.img`` ready to flash. + +Flashing U-Boot into the eMMC +----------------------------- + +``DISCLAMER!`` All questions related to fusee-tools should be asked in the proper +place. NOT HERE! Flashing U-Boot will erase all eMMC, so make a backup before! + +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, 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 +---- + +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 ``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 MicroSD card +and insert it into the device. 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. diff --git a/doc/board/nvidia/index.rst b/doc/board/nvidia/index.rst new file mode 100644 index 00000000000..7c105445559 --- /dev/null +++ b/doc/board/nvidia/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +NVIDIA +====== + +.. toctree:: + :maxdepth: 2 + + tegratab diff --git a/doc/board/nvidia/tegratab.rst b/doc/board/nvidia/tegratab.rst new file mode 100644 index 00000000000..c6d97ce3828 --- /dev/null +++ b/doc/board/nvidia/tegratab.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +U-Boot for the Nvidia Tegra Note 7 +================================== + +Quick Start +----------- + +- Build U-Boot +- Boot U-Boot by loading it into RAM (coldboot) +- Chainloading U-Boot from the vendor bootloader +- Boot + +Build U-Boot +------------ + +U-Boot can be built in two forms: U-Boot with SPL, which is used for booting +by loading directly into RAM and U-Boot without SPL, which can be flashed +and chainloaded from the vendor bootloader. + +To build U-Boot with SPL proseed: + +.. code-block:: bash + + $ export CROSS_COMPILE=arm-none-eabi- + $ make tegratab_defconfig + $ make + +After the build succeeds, you will obtain the final ``u-boot-dtb-tegra.bin`` +file, ready for cold booting by loading into RAM. + +To build U-Boot without SPL adjust tegratab_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 with fastboot boot or which can be further processed into +a flashable boot.img. + +Boot U-Boot by loading it into RAM (coldboot) +--------------------------------------------- + +Done fairly simply by using fusee-tools (using run_bootloader.sh) and placing +``u-boot-dtb-tegra.bin`` generated on the previous step into fusee-tools dir. +This method requires constant access to the host PC or payloader and can fully +eliminate influence of the vendor bootloader onto the boot process. + +.. code-block:: bash + + $ ./run_bootloader.sh -s T114 -t ./bct/tegratab.bct + +Chainloading U-Boot from the vendor bootloader +---------------------------------------------- + +``u-boot-dtb.bin`` has to be further packed into Android boot image form, +where ``u-boot-dtb.bin`` acts as kernel, while dtb and ramdisk parts should +not be included. Then the generated boot image can be flashed into the /boot +partition of the tablet using vendor bootloader's fastboot and will act as +the bootloader of the last stage. + +Boot +---- +In both cases after U-Boot obtains control it performs search of extlinux.conf +first on the dock USB device is available, then on MicroSD card if available +and lastly on eMMC. If none of the devices above are present, then the device +is turned off. + +If during boot of U-Boot Volume Down button is pressed, the device will enter +U-Boot bootmenu. diff --git a/doc/board/qualcomm/board.rst b/doc/board/qualcomm/board.rst index 4d793209f9e..003d59a18eb 100644 --- a/doc/board/qualcomm/board.rst +++ b/doc/board/qualcomm/board.rst @@ -90,6 +90,11 @@ Or for db410c (and other boards not supported by the generic target):: make CROSS_COMPILE=aarch64-linux-gnu- O=.output dragonboard410c_defconfig make O=.output -j$(nproc) +Or for smartphones:: + + make CROSS_COMPILE=aarch64-linux-gnu- O=.output qcom_defconfig qcom-phone.config + make O=.output -j$(nproc) + - gzip u-boot:: gzip u-boot-nodtb.bin diff --git a/doc/board/qualcomm/index.rst b/doc/board/qualcomm/index.rst index 66bc922033a..e2fcbfa19c2 100644 --- a/doc/board/qualcomm/index.rst +++ b/doc/board/qualcomm/index.rst @@ -9,5 +9,6 @@ Qualcomm dragonboard410c rb3gen2 board + phones debugging rdp diff --git a/doc/board/qualcomm/phones.rst b/doc/board/qualcomm/phones.rst new file mode 100644 index 00000000000..1d27196cf54 --- /dev/null +++ b/doc/board/qualcomm/phones.rst @@ -0,0 +1,144 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Caleb Connolly <caleb.connolly@linaro.org> + +====================================== +Booting U-Boot on Qualcomm smartphones +====================================== + +About this +---------- + +This page attempts to the describe U-Boot support for Qualcomm phones, as a user guide but also a +technical introduction to How Stuff Works to help new porters. + +In broad strokes, U-Boot should boot if the SoC is supported, and the device is already capable of +booting an upstream Linux kernel. + +The list of supported Qualcomm SoCs changes often, for now it is best to look in +``drivers/clk/qcom/`` to get a rough idea. + +For building instructions, see :doc:`board`. + +Phone bringup +------------- + +It is usually easier to get Linux booting first, there are many good resources for this such as the +`postmarketOS wiki`_. Once the device can boot Linux with logs on the display and ideally USB gadget +support, it is highly likely that U-Boot will boot as well. + +For logs on display, you should have a simple framebuffer node defined in your DT, newer devices +require that this follow the downstream naming scheme (that the DTB is compiled with labels enabled +and the framebuffer reserved-memory region is labelled ``cont_splash``). Once this is working in +Linux it should also work in U-Boot. + +In practise, U-Boot still has many more papercuts than Linux, which can be sticking points when +porting a new device. In particular, drivers failing to bind/probe (especially pre-relocation) can +be tricky to debug without UART since U-Boot will simply panic with no way to inform you of +the error. As a result, bringing up a new device can be quite frustrating, but there are quite a few +things you can try. + +The phone config +^^^^^^^^^^^^^^^^ + +Since most phones lack a physical keyboard or serial port, a special config fragment and environment +file can be used to provide a more seamless experience. This can be enabled by generating the config +with:: + + make CROSS_COMPILE=aarch64-linux-gnu- O=.output qcom_defconfig qcom-phone.config + +The config and associated environment file can be found in board/qualcomm/. The main changes are: + +- Panic on hang (so the panic message can be read on the display) +- Boot retry (to automatically open and re-open the bootmenu) +- A boot menu with helpful shortcuts (including USB console gadget) +- Launch the boot menu if power is held during boot or on boot failure + +Fastboot mode +------------- + +U-Boot's fastboot implementation is much more limited than Qualcomm's, and currently does not have a +backend for UFS storage. If your device uses eMMC or has an sdcard slot, fastboot will use that by +default. + +You may need to run the fastboot command on your PC as root since the USB product/vendor ID may not +match the android udev rules. + +You can also use fastboot to run arbitrary U-Boot commands with ``fastboot oem run`` + +Retrieving early logs +^^^^^^^^^^^^^^^^^^^^^ + +U-Boot is configured to save it's internal log to a buffer, this can help with debugging some driver +bind/probe issues. If your device can boot and has working USB, you can enable fastboot mode (either +via the U-Boot menu or by adding ``run fastboot`` to the end of the ``preboot=`` config in +``board/qualcomm/qcom-phone.env``). + +You can then retrieve U-Boot's log buffer with the ``fastboot oem log`` command on your PC. + +Hang/crash bisection +-------------------- + +Without a way to get logs, we can still get quite far with only a few bits of information: what +happens when you ``fastboot boot u-boot.img``? + +Does the device disconnect? +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This can be verified by watching ``dmesg -w``. If it stays connected, it likely means the boot image +doesn't match what the bootloader expected, use ``unpack_bootimg`` to compare it with a known-good +boot image (ideally one with an upstream kernel). + +Does the device hang? +^^^^^^^^^^^^^^^^^^^^^ + +If it stays on a black screen and does nothing, then that's a hang! Since ``qcom-phone.config`` +enables CONFIG_PANIC_HANG, this likely means that you're successfully executing U-Boot code (yay!), +but something is causing a panic. + +It could also be due to a bad memory or register access triggering a secure interrupt, it's worth +waiting for around a minute to see if the device eventually reboots or goes to crashdump mode. You +can also disable CONFIG_PANIC_HANG and see if that causes the device to reboot instead, if so then +it is definitely a U-Boot panic. + +With enough time and patience, it should be possible to narrow down the cause of the panic by +inserting calls to ``reset_cpu()`` (with CONFIG_PANIC_HANG enabled). Then if the device resets you +know it executed the ``reset_cpu()`` call. + +A good place to start is ``board_fdt_blob_setup()`` in ``arch/arm/mach-snapdragon/board.c``, this +function is called extremely early so adding a reset call is a good way to validate that U-Boot is +definitely running. + +You can then do a binary search starting from the end of ``board_init_f()`` / start of +``board_init_r()`` and work from there using the init sequences for reference. + +The Qualcomm RAM parsing code is a likely culprit, as ABL is known to sometimes give bogus entries +in the memory node which can trip U-Boot up. + +To rule out crashes that might be caused by specific drivers, it's a good idea to disable them and +re-enable them one by one. Here is a non-exhaustive list of drivers to disable: + +- pinctrl +- mmc +- scsi/ufs +- usb (dwc3) +- phy (usb, ufs) +- clk (remove clock references from your framebuffer node in DT) + +Ideally, it would be possible to use the framebuffer as an early console / debug output, at the time +of writing there are out of tree patches for this but they haven't been submitted upstream yet. + +Does the device reboot or go to crashdump mode? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On many devices crashdump mode is disabled, so they will reboot instead (maybe after some delay). +The same approach as suggested above can be used to figure out where the crash occurs. + +If the device is rebooting, you can insert calls to ``hang()`` instead of ``reset_cpu()`` when +following the instructions above. + +The most likely cause of a crashdump is the pinctrl/gpio driver or the SMMU driver, ensure that the +``apps_smmu`` node in your SoCs devicetree file has one of its compatible strings referenced in +``drivers/iommu/qcom-hyp-smmu.c``, you can also try disabling the pinctrl driver for your SoC (or +``CONFIG_PINCTRL`` altogether). + +.. _`postmarketOS wiki`: https://wiki.postmarketos.org/wiki/Mainlining diff --git a/doc/board/rockchip/rockchip.rst b/doc/board/rockchip/rockchip.rst index 1407080f1f4..b06f87b137c 100644 --- a/doc/board/rockchip/rockchip.rst +++ b/doc/board/rockchip/rockchip.rst @@ -66,6 +66,7 @@ List of mainline supported Rockchip boards: - FriendlyElec NanoPi R2C Plus (nanopi-r2c-plus-rk3328) - FriendlyElec NanoPi R2S (nanopi-r2s-rk3328) - FriendlyElec NanoPi R2S Plus (nanopi-r2s-plus-rk3328) + - Generic RK3328 (generic-rk3328) - Pine64 Rock64 (rock64-rk3328) - Radxa ROCK Pi E (rock-pi-e-rk3328) - Xunlong Orange Pi R1 Plus (orangepi-r1-plus-rk3328) @@ -83,6 +84,7 @@ List of mainline supported Rockchip boards: - FriendlyElec NanoPi M4 (nanopi-m4-rk3399) - FriendlyElec NanoPi M4B (nanopi-m4b-rk3399) - FriendlyARM NanoPi NEO4 (nanopi-neo4-rk3399) + - Generic RK3399 (generic-rk3399) - Google Bob (chromebook_bob) - Google Kevin (chromebook_kevin) - Khadas Edge (khadas-edge-rk3399) @@ -97,6 +99,10 @@ List of mainline supported Rockchip boards: - Rockchip Evb-RK3399 (evb_rk3399) - Theobroma Systems RK3399-Q7 SoM - Puma (puma_rk3399) +* rk3528 + - Generic RK3528 (generic-rk3528) + - Radxa E20C (radxa-e20c-rk3528) + * rk3566 - Anbernic RGxx3 (anbernic-rgxx3-rk3566) - FriendlyElec NanoPi R3S (nanopi-r3s-rk3566) @@ -126,6 +132,9 @@ List of mainline supported Rockchip boards: - Radxa ROCK 3A (rock-3a-rk3568) - Radxa ROCK 3B (rock-3b-rk3568) +* rk3576 + - Firefly ROC-RK3576-PC (roc-pc-rk3576) + * rk3588 - ArmSoM Sige7 (sige7-rk3588) - Rockchip EVB (evb-rk3588) @@ -258,6 +267,15 @@ To build rk3399 boards: make evb-rk3399_defconfig make CROSS_COMPILE=aarch64-linux-gnu- +To build rk3528 boards: + +.. code-block:: bash + + export BL31=../rkbin/bin/rk35/rk3528_bl31_v1.18.elf + export ROCKCHIP_TPL=../rkbin/bin/rk35/rk3528_ddr_1056MHz_v1.10.bin + make generic-rk3528_defconfig + make CROSS_COMPILE=aarch64-linux-gnu- + To build rk3568 boards: .. code-block:: bash @@ -268,6 +286,15 @@ To build rk3568 boards: make evb-rk3568_defconfig make CROSS_COMPILE=aarch64-linux-gnu- +To build rk3576 boards: + +.. code-block:: bash + + export BL31=../rkbin/bin/rk35/rk3576_bl31_v1.04.elf + export ROCKCHIP_TPL=../rkbin/bin/rk35/rk3576_ddr_lp4_2112MHz_lp5_2736MHz_v1.03.bin + make roc-pc-rk3576_defconfig + make CROSS_COMPILE=aarch64-linux-gnu- + To build rk3588 boards: .. code-block:: bash diff --git a/doc/board/starfive/deepcomputing_fml13v01.rst b/doc/board/starfive/deepcomputing_fml13v01.rst new file mode 100644 index 00000000000..5d9612483b4 --- /dev/null +++ b/doc/board/starfive/deepcomputing_fml13v01.rst @@ -0,0 +1,80 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +DeepComputing Framework Motherboard (FLM13V01) +============================================== + +The DeepComputing Framework motherboard (FLM13V01) can be combined with a +13 inch Framework laptop chassis to provide a complete laptop. + +U-Boot for the board uses the same binaries as the VisionFive 2 board. +Currently only serial console output is supported by mainline U-Boot. + +Building +-------- + +Setup the cross compilation environment variable: + +.. code-block:: bash + + export CROSS_COMPILE=riscv64-linux-gnu- + +The M-mode software OpenSBI provides the supervisor binary interface (SBI) and +is responsible for the switch to S-Mode. It is a prerequisite for building +U-Boot. Support for the JH7110 was introduced in OpenSBI 1.2. It is recommended +to use a current release. + +.. code-block:: bash + + git clone https://github.com/riscv/opensbi.git + cd opensbi + make PLATFORM=generic FW_TEXT_START=0x40000000 FW_OPTIONS=0 + export OPENSBI="$(pwd)/build/platform/generic/firmware/fw_dynamic.bin" + +Now build U-Boot SPL and main U-Boot. + +.. code-block:: bash + + cd <U-Boot-dir> + make starfive_visionfive2_defconfig + make + +This will generate the U-Boot SPL image (spl/u-boot-spl.bin.normal.out) as well +as the FIT image (u-boot.itb) with OpenSBI, U-Boot, and device-trees. + +Device-tree selection +--------------------- + +The product ID stored in the board EEPROM is used by U-Boot SPL to select the +right configuration and device-tree from the u-boot.itb FIT image. + +Furthermore if variable $fdtfile has not been saved in the environment it is +set based on the product ID to *starfive/jh7110-deepcomputing-fml13v01.dtb*. + +To overrule this default the variable can be set manually and saved in the +environment + +.. code-block:: console + + setenv fdtfile my_device-tree.dtb + env save + +Power switch +------------ + +A tiny power switch is located in right upper corner of the board. + +Open case detection +------------------- + +The board has an open case detection switch. Red lights will flash and the +board will not boot if the switch is not held down. + +UART +---- + +UART 0 is exposed via the side channel contacts SBU1 and SBU2 of the lower, +right USB C connector. A USB C cable and a breakout board are needed for +physical access. It depends on the cable orientation on which of SBU1 and SBU2 +you will find RX and TX. The signal voltage is 3.3 V. The baud rate is 115200. + +.. include:: jh7110_common.rst diff --git a/doc/board/starfive/index.rst b/doc/board/starfive/index.rst index 2cba1b6dc56..66abc6f9d98 100644 --- a/doc/board/starfive/index.rst +++ b/doc/board/starfive/index.rst @@ -6,6 +6,7 @@ StarFive .. toctree:: :maxdepth: 1 + deepcomputing_fml13v01 milk-v_mars pine64_star64 visionfive2 diff --git a/doc/board/starfive/jh7110_common.rst b/doc/board/starfive/jh7110_common.rst new file mode 100644 index 00000000000..4a8058ee5da --- /dev/null +++ b/doc/board/starfive/jh7110_common.rst @@ -0,0 +1,103 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Boot source selection +--------------------- + +The board provides DIP switches to select the device for loading the boot +firmware. + +=========== === === +Boot source SW1 SW2 +=========== === === +UART OFF OFF +SD-card ON OFF +eMMC OFF ON +SPI flash ON ON +=========== === === + +Flashing a new U-Boot version +----------------------------- + +U-Boot SPL is provided as file spl/u-boot-spl.bin.normal.out. Main U-Boot is +in file u-boot.itb. + +Assuming your new U-Boot version is on partition 1 of an SD-card you could +install it to the SPI flash with: + +.. code-block:: console + + sf probe + load mmc 1:1 $kernel_addr_r u-boot-spl.bin.normal.out + sf update $kernel_addr_r 0 $filesize + load mmc 1:1 $kernel_addr_r u-boot.itb + sf update $kernel_addr_r 0x100000 $filesize + +For loading the files from a TFTP server refer to the dhcp and tftpboot +commands. + +After updating U-Boot you may want to erase a saved environment and reboot. + +.. code-block:: console + + env erase + reset + +Booting from SD-Card +-------------------- + +The device boot ROM loads U-Boot SPL (u-boot-spl.bin.normal.out) from the +partition with type GUID 2E54B353-1271-4842-806F-E436D6AF6985. You are free +to choose any partition number. + +With the default configuration U-Boot SPL loads the U-Boot FIT image +(u-boot.itb) from partition 2 (CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION=0x2). +When formatting it is recommended to use GUID +BC13C2FF-59E6-4262-A352-B275FD6F7172 for this partition. + +Booting from eMMC +----------------- + +The device boot ROM tries to load U-Boot SPL (u-boot-spl.bin.normal.out) from +sector 0 of the eMMC's main hardware partition. But this conflicts with GPT +partitioning. Fortunately eMMC can alternatively load U-Boot SPL from a backup +position. + +For U-Boot SPL (u-boot-spl.bin.normal.out) starting at sector 2048 (position +0x100000) write the following bytes to the eMMC device after GPT partitioning: + +======= ======================== +Address Bytes +======= ======================== +0x0000 40 02 00 00 00 00 10 00 +0x0290 40 02 00 00 00 00 10 00 +======= ======================== + +With the default configuration U-Boot SPL loads the U-Boot FIT image +(u-boot.itb) from partition 2 (CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION=0x2). +When formatting it is recommended to use GUID +BC13C2FF-59E6-4262-A352-B275FD6F7172 for this partition. + +Booting from UART +----------------- + +The boot ROM supports the X-modem protocol to upload +spl/u-boot-spl.bin.normal.out. U-Boot SPL support loading the FIT image +u-boot.itb via the Y-modem protocol. + +Due to restrictions of the boot ROM not all X-modem implementations are +compatible. The package tio (https://github.com/tio/tio) has been found to be +usable. + +Debug UART +---------- + +By default the SBI interface is used for the debug UART. But this only works +in main U-Boot. To enable the debug UART in SPL, too, use the following +settings:: + + CONFIG_DEBUG_UART=y + CONFIG_DEBUG_UART_NS16550=y + CONFIG_DEBUG_UART_BASE=0x10000000 + CONFIG_SPL_DEBUG_UART_BASE=0x10000000 + CONFIG_DEBUG_UART_CLOCK=24000000 + CONFIG_DEBUG_UART_SHIFT=2 diff --git a/doc/board/starfive/milk-v_mars.rst b/doc/board/starfive/milk-v_mars.rst index 554932ecfd4..ce4539a46f1 100644 --- a/doc/board/starfive/milk-v_mars.rst +++ b/doc/board/starfive/milk-v_mars.rst @@ -8,7 +8,7 @@ board. In U-Boot SPL the actual board is detected and the device-tree patched accordingly. Building -~~~~~~~~ +-------- 1. Add the RISC-V toolchain to your PATH. 2. Setup ARCH & cross compilation environment variable: @@ -40,7 +40,7 @@ This will generate the U-Boot SPL image (spl/u-boot-spl.bin.normal.out) as well as the FIT image (u-boot.itb) with OpenSBI and U-Boot. Device-tree selection -~~~~~~~~~~~~~~~~~~~~~ +--------------------- Depending on the board version U-Boot set variable $fdtfile to either starfive/jh7110-starfive-visionfive-2-v1.2a.dtb or @@ -57,15 +57,8 @@ environment or the configuration variable CONFIG_DEFAULT_FDT_FILE can be used to set to provide a default value. -Boot source selection -~~~~~~~~~~~~~~~~~~~~~ - -The board provides the DIP switches MSEL[1:0] to select the boot device out of -SPI flash, eMMC, SD-card, UART. To select booting from SD-card set the DIP -switches MSEL[1:0] to 10. - Preparing the SD-Card -~~~~~~~~~~~~~~~~~~~~~ +--------------------- The device firmware loads U-Boot SPL (u-boot-spl.bin.normal.out) from the partition with type GUID 2E54B353-1271-4842-806F-E436D6AF6985. You are free @@ -105,7 +98,4 @@ Copy U-Boot to the SD card sudo cp jh7110-starfive-visionfive-2.dtb /mnt/ sudo umount /mnt -Booting -~~~~~~~ - -Once you plugin the sdcard and power up, you should see the U-Boot prompt. +.. include:: jh7110_common.rst diff --git a/doc/board/starfive/pine64_star64.rst b/doc/board/starfive/pine64_star64.rst index 52e9a907917..d1752c452da 100644 --- a/doc/board/starfive/pine64_star64.rst +++ b/doc/board/starfive/pine64_star64.rst @@ -8,7 +8,7 @@ In U-Boot SPL the actual board is detected and the device-tree patched accordingly. Building -~~~~~~~~ +-------- 1. Add the RISC-V toolchain to your PATH. 2. Setup ARCH & cross compilation environment variable: @@ -40,7 +40,7 @@ This will generate the U-Boot SPL image (spl/u-boot-spl.bin.normal.out) as well as the FIT image (u-boot.itb) with OpenSBI and U-Boot. Device-tree selection -~~~~~~~~~~~~~~~~~~~~~ +--------------------- U-Boot will set variable $fdtfile to starfive/jh7110-pine64-star64.dtb. @@ -55,21 +55,8 @@ environment or the configuration variable CONFIG_DEFAULT_FDT_FILE can be used to set to provide a default value. -Boot source selection -~~~~~~~~~~~~~~~~~~~~~ - -Boot mode is selected by an MSEL-DIP marked S1804 and GPIO_0 position adjacent -to the 40pin GPIO header. ON/ONKE and number markings of the MSEL-DIP are -misleading; Instead refer to the ``L`` (0) and ``H`` (1) silkscreen for -accurate selection. - -+ (QSPI) Flash: 00 -+ SD: 01 -+ EMMC: 10 -+ UART: 11 - Preparing the SD-Card -~~~~~~~~~~~~~~~~~~~~~ +--------------------- The device firmware loads U-Boot SPL (u-boot-spl.bin.normal.out) from the partition with type GUID 2E54B353-1271-4842-806F-E436D6AF6985. You are free @@ -109,13 +96,10 @@ Copy U-Boot to the SD card sudo cp jh7110-starfive-visionfive-2.dtb /mnt/ sudo umount /mnt -Booting -~~~~~~~ - -Once you plugin the sdcard and power up, you should see the U-Boot prompt. +.. include:: jh7110_common.rst Serial Number and MAC address issues -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------ U-Boot requires valid EEPROM data to determine which board-specific fix-up to apply at runtime. This affects the size of memory initialized, network mac diff --git a/doc/board/starfive/visionfive2.rst b/doc/board/starfive/visionfive2.rst index 2c68df3ce4d..11121a1751a 100644 --- a/doc/board/starfive/visionfive2.rst +++ b/doc/board/starfive/visionfive2.rst @@ -36,7 +36,7 @@ Currently, the u-boot.itb is used as a dynamic of the OpenSBI FW_DYNAMIC firmware with the latest. Building -~~~~~~~~ +-------- 1. Add the RISC-V toolchain to your PATH. 2. Setup ARCH & cross compilation environment variable: @@ -72,7 +72,7 @@ This will generate the U-Boot SPL image (spl/u-boot-spl.bin.normal.out) as well as the FIT image (u-boot.itb) with OpenSBI and U-Boot. Device-tree selection -~~~~~~~~~~~~~~~~~~~~~ +--------------------- Depending on the board version U-Boot set variable $fdtfile to either starfive/jh7110-starfive-visionfive-2-v1.2a.dtb or @@ -90,7 +90,7 @@ or the configuration variable CONFIG_DEFAULT_FDT_FILE can be used to provide a default value. Flashing -~~~~~~~~ +-------- The device firmware loads U-Boot SPL (u-boot-spl.bin.normal.out) from the partition with type GUID 2E54B353-1271-4842-806F-E436D6AF6985. You are free @@ -116,6 +116,7 @@ Format the SD card (make sure the disk has GPT, otherwise use gdisk to switch) --new=2:8192:16383 --change-name=2:uboot --typecode=2:BC13C2FF-59E6-4262-A352-B275FD6F7172 \ --new=3:16384:1654784 --change-name=3:system --typecode=3:EBD0A0A2-B9E5-4433-87C0-68B6B72699C7 \ /dev/sdb + sudo mkfs.vfat -F32 /dev/sdb3 Program the SD card @@ -132,16 +133,10 @@ Program the SD card sudo cp jh7110-starfive-visionfive-2.dtb /mnt/ sudo umount /mnt -Booting -~~~~~~~ - -The board provides the DIP switches MSEL[1:0] to select the boot device. -To select booting from SD-card set the DIP switches MSEL[1:0] to 10. - -Once you plugin the sdcard and power up, you should see the U-Boot prompt. +.. include:: jh7110_common.rst Sample boot log from StarFive VisionFive2 board -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------------------------- .. code-block:: none @@ -479,34 +474,3 @@ Sample boot log from StarFive VisionFive2 board Welcome to Buildroot buildroot login: - -Booting from SPI ----------------- - -Use Building steps from "Booting from MMC using U-Boot SPL" section. - -Partition the SPI in Linux via mtdblock. (Require to boot the board in -SD boot mode by enabling MTD block in Linux) - -Use prebuilt image from here [1], which support to partition the SPI flash. - - -Program the SPI (Require to boot the board in SD boot mode) - -Execute below steps on U-Boot proper, - -.. code-block:: none - - sf probe - fatload mmc 1:3 $kernel_addr_r u-boot.itb - sf update $kernel_addr_r 0x100000 $filesize - - fatload mmc 1:3 $kernel_addr_r u-boot-spl.bin.normal.out - sf update $kernel_addr_r 0x0 $filesize - - -Power off the board - -Change DIP switches MSEL[1:0] are set to 00, select the boot mode to flash - -Power up the board. diff --git a/doc/board/ti/am62ax_sk.rst b/doc/board/ti/am62ax_sk.rst index 262340ef59a..43a1db68873 100644 --- a/doc/board/ti/am62ax_sk.rst +++ b/doc/board/ti/am62ax_sk.rst @@ -81,16 +81,16 @@ Set the variables corresponding to this platform: .. include:: ../ti/k3.rst :start-after: .. k3_rst_include_start_common_env_vars_defn :end-before: .. k3_rst_include_end_common_env_vars_defn -.. code-block:: bash +.. prompt:: bash - $ export UBOOT_CFG_CORTEXR=am62ax_evm_r5_defconfig - $ export UBOOT_CFG_CORTEXA=am62ax_evm_a53_defconfig - $ export TFA_BOARD=lite - $ # we dont use any extra TFA parameters - $ unset TFA_EXTRA_ARGS - $ export OPTEE_PLATFORM=k3-am62ax - $ # we dont use any extra OPTEE parameters - $ unset OPTEE_EXTRA_ARGS + export UBOOT_CFG_CORTEXR=am62ax_evm_r5_defconfig + export UBOOT_CFG_CORTEXA=am62ax_evm_a53_defconfig + export TFA_BOARD=lite + # we dont use any extra TFA parameters + unset TFA_EXTRA_ARGS + export OPTEE_PLATFORM=k3-am62ax + # we dont use any extra OPTEE parameters + unset OPTEE_EXTRA_ARGS 1. Trusted Firmware-A: @@ -212,6 +212,6 @@ detailed setup information. To start OpenOCD and connect to the board -.. code-block:: bash +.. prompt:: bash openocd -f board/ti_am62a7evm.cfg diff --git a/doc/board/ti/am62px_sk.rst b/doc/board/ti/am62px_sk.rst index 99bdc034869..a07d6a4da45 100644 --- a/doc/board/ti/am62px_sk.rst +++ b/doc/board/ti/am62px_sk.rst @@ -91,15 +91,15 @@ Set the variables corresponding to this platform: :start-after: .. k3_rst_include_start_common_env_vars_defn :end-before: .. k3_rst_include_end_common_env_vars_defn -.. code-block:: bash +.. prompt:: bash - $ export UBOOT_CFG_CORTEXR=am62px_evm_r5_defconfig - $ export UBOOT_CFG_CORTEXA=am62px_evm_a53_defconfig - $ export TFA_BOARD=lite - $ # we dont use any extra TFA parameters - $ unset TFA_EXTRA_ARGS - $ export OPTEE_PLATFORM=k3-am62x - $ export OPTEE_EXTRA_ARGS="CFG_WITH_SOFTWARE_PRNG=y" + export UBOOT_CFG_CORTEXR=am62px_evm_r5_defconfig + export UBOOT_CFG_CORTEXA=am62px_evm_a53_defconfig + export TFA_BOARD=lite + # we dont use any extra TFA parameters + unset TFA_EXTRA_ARGS + export OPTEE_PLATFORM=k3-am62x + export OPTEE_EXTRA_ARGS="CFG_WITH_SOFTWARE_PRNG=y" .. am62px_evm_rst_include_start_build_steps @@ -312,6 +312,6 @@ detailed setup information. To start OpenOCD and connect to the board -.. code-block:: bash +.. prompt:: bash openocd -f board/ti_am62pevm.cfg diff --git a/doc/board/ti/j722s_evm.rst b/doc/board/ti/j722s_evm.rst index e5a1be50c4f..9c53fa50858 100644 --- a/doc/board/ti/j722s_evm.rst +++ b/doc/board/ti/j722s_evm.rst @@ -68,13 +68,12 @@ Set the variables corresponding to this platform: :start-after: .. k3_rst_include_start_common_env_vars_defn :end-before: .. k3_rst_include_end_common_env_vars_defn -.. code-block:: bash +.. prompt:: bash - $ export UBOOT_CFG_CORTEXR=j722s_evm_r5_defconfig - $ export UBOOT_CFG_CORTEXA=j722s_evm_a53_defconfig - $ export TFA_BOARD=lite - $ export OPTEE_PLATFORM=k3-am62x - $ export OPTEE_EXTRA_ARGS="CFG_WITH_SOFTWARE_PRNG=y" + export UBOOT_CFG_CORTEXR=j722s_evm_r5_defconfig + export UBOOT_CFG_CORTEXA=j722s_evm_a53_defconfig + export TFA_BOARD=lite + export OPTEE_PLATFORM=k3-am62x .. j722s_evm_rst_include_start_build_steps @@ -259,6 +258,6 @@ detailed setup information. To start OpenOCD and connect to the board -.. code-block:: bash +.. prompt:: bash openocd -f board/ti_j722sevm.cfg diff --git a/doc/board/ti/j784s4_evm.rst b/doc/board/ti/j784s4_evm.rst index a1e927cb743..349fb394d74 100644 --- a/doc/board/ti/j784s4_evm.rst +++ b/doc/board/ti/j784s4_evm.rst @@ -81,14 +81,14 @@ Set the variables corresponding to this platform: .. include:: k3.rst :start-after: .. k3_rst_include_start_common_env_vars_defn :end-before: .. k3_rst_include_end_common_env_vars_defn -.. code-block:: bash +.. prompt:: bash - $ export UBOOT_CFG_CORTEXR=j784s4_evm_r5_defconfig - $ export UBOOT_CFG_CORTEXA=j784s4_evm_a72_defconfig - $ export TFA_BOARD=j784s4 - $ export TFA_EXTRA_ARGS="K3_USART=0x8" - $ export OPTEE_PLATFORM=k3-j784s4 - $ export OPTEE_EXTRA_ARGS="CFG_CONSOLE_UART=0x8" + export UBOOT_CFG_CORTEXR=j784s4_evm_r5_defconfig + export UBOOT_CFG_CORTEXA=j784s4_evm_a72_defconfig + export TFA_BOARD=j784s4 + export TFA_EXTRA_ARGS="K3_USART=0x8" + export OPTEE_PLATFORM=k3-j784s4 + export OPTEE_EXTRA_ARGS="CFG_CONSOLE_UART=0x8" .. j784s4_evm_rst_include_start_build_steps @@ -326,6 +326,6 @@ Debugging U-Boot on J784S4-EVM and AM69-SK To start OpenOCD and connect to J784S4-EVM or AM69-SK board, use the following. -.. code-block:: bash +.. prompt:: bash openocd -f board/ti_j784s4evm.cfg diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst index 0deb4d768f9..b79f1526446 100644 --- a/doc/board/ti/k3.rst +++ b/doc/board/ti/k3.rst @@ -460,7 +460,7 @@ The Kernel FIT Image that we have has Kernel Image, DTB and the DTBOs. It supports packing multiple images and configurations that allow you to choose any configuration at runtime to boot from. -.. code-block:: +.. code-block:: dts /dts-v1/; @@ -484,7 +484,7 @@ choose any configuration at runtime to boot from. * Sample Images -.. code-block:: +.. code-block:: dts kernel-1 { description = "Linux kernel"; @@ -533,7 +533,7 @@ corresponding configuration node as follows. * Sample Configurations -.. code-block:: +.. code-block:: dts conf-ti_k3-j721e-common-proc-board.dtb { description = "Linux kernel, FDT blob"; @@ -585,7 +585,7 @@ Generating the fitImage For e.g - .. code-block:: + .. code-block:: diff diff --git a/configs/j721e_evm_a72_defconfig b/configs/j721e_evm_a72_defconfig index a5c1df7e0054..6d0126d955ef 100644 @@ -605,7 +605,7 @@ Generating the fitImage For e.g - .. code-block:: + .. code-block:: diff diff --git a/arch/arm/dts/k3-j721e-binman.dtsi b/arch/arm/dts/k3-j721e-binman.dtsi index 673be646b1e3..752fa805fe8d 100644 diff --git a/doc/board/toradex/index.rst b/doc/board/toradex/index.rst index 89fbdcbb9e9..7d510a80112 100644 --- a/doc/board/toradex/index.rst +++ b/doc/board/toradex/index.rst @@ -9,6 +9,7 @@ Toradex apalis-imx8 colibri_imx7 colibri-imx8x + smarc-imx8mp verdin-am62 verdin-imx8mm verdin-imx8mp diff --git a/doc/board/toradex/smarc-imx8mp.rst b/doc/board/toradex/smarc-imx8mp.rst new file mode 100644 index 00000000000..6083ce6ba4c --- /dev/null +++ b/doc/board/toradex/smarc-imx8mp.rst @@ -0,0 +1,116 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Toradex SMARC iMX8M Plus Module +=============================== + +- SoM: https://www.toradex.com/computer-on-modules/smarc-arm-family/nxp-imx-8m-plus +- Carrier board: https://www.toradex.com/products/carrier-board/smarc-development-board-kit + +Quick Start +----------- + +- Build the ARM trusted firmware binary +- Get the DDR firmware +- Build U-Boot +- Flash to eMMC +- Boot + +Get and Build the ARM Trusted Firmware (Trusted Firmware A) +----------------------------------------------------------- + +.. code-block:: bash + + $ echo "Downloading and building TF-A..." + $ git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git + $ cd trusted-firmware-a + +Then build ATF (TF-A): + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-linux-gnu- + $ make PLAT=imx8mp IMX_BOOT_UART_BASE=0x30a60000 bl31 + $ cp build/imx8mp/release/bl31.bin ../ + +Get the DDR Firmware +-------------------- + +.. code-block:: bash + + $ cd .. + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.10.1.bin + $ chmod +x firmware-imx-8.10.1.bin + $ ./firmware-imx-8.10.1.bin + $ cp firmware-imx-8.10.1/firmware/ddr/synopsys/lpddr4*_202006.bin ./ + +Build U-Boot +------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-linux-gnu- + $ make toradex-smarc-imx8mp_defconfig + $ make + +Flash to eMMC +------------- + +.. code-block:: bash + + > tftpboot ${loadaddr} flash.bin + > setexpr blkcnt ${filesize} + 0x1ff && setexpr blkcnt ${blkcnt} / 0x200 + > mmc dev 0 1 && mmc write ${loadaddr} 0x0 ${blkcnt} + +As a convenience, instead of the last two commands, one may also use the update +U-Boot wrapper: + +.. code-block:: bash + + > run update_uboot + +Boot +---- + +ATF, U-Boot proper and u-boot.dtb images are packed into a FIT image, +which is loaded and parsed by SPL. + +Boot sequence is: + +* SPL ---> ATF (TF-A) ---> U-Boot proper + +Output:: + + U-Boot SPL 2025.04-rc5-00023-g34c31be81211 (Apr 04 2025 - 15:36:23 +0100) + Training FAILED + DDR configured as single rank + SEC0: RNG instantiated + Normal Boot + Trying to boot from BOOTROM + Boot Stage: Primary boot + Find img info 0x4802f200, size 1100 + Need continue download 1024 + NOTICE: Do not release JR0 to NS as it can be used by HAB + NOTICE: BL31: v2.11.0(release):v2.11.0-723-gbd298f5c30ac + NOTICE: BL31: Built : 14:18:43, Apr 4 2025 + + + U-Boot 2025.04-rc5-00023-g34c31be81211 (Apr 04 2025 - 15:36:23 +0100) + + CPU: Freescale i.MX8MP[8] rev1.1 1600 MHz (running at 1200 MHz) + CPU: Industrial temperature grade (-40C to 105C) at 72C + Reset cause: POR + DRAM: 4 GiB + Core: 312 devices, 32 uclasses, devicetree: separate + WDT: Started watchdog@30280000 with servicing every 1000ms (60s timeout) + MMC: FSL_SDHC: 1, FSL_SDHC: 0 + Loading Environment from MMC... Reading from MMC(0)... OK + In: serial@30a60000 + Out: serial@30a60000 + Err: serial@30a60000 + Model: Toradex 0097 SMARC iMX8M Plus Quad 4GB WB IT V1.0A + Serial#: 15603364 + SEC0: RNG instantiated + Net: Get shared mii bus on ethernet@30be0000 + eth1: ethernet@30be0000, eth0: ethernet@30bf0000 [PRIME] + Hit any key to stop autoboot: 0 + SMARC iMX8MP # diff --git a/doc/build/gcc.rst b/doc/build/gcc.rst index d8fcfdc4bf2..480e0e3091e 100644 --- a/doc/build/gcc.rst +++ b/doc/build/gcc.rst @@ -31,7 +31,7 @@ Depending on the build targets further packages maybe needed python3-pkg-resources python3-pycryptodome python3-pyelftools \ python3-pytest python3-pytest-xdist python3-sphinxcontrib.apidoc \ python3-sphinx-rtd-theme python3-subunit python3-testtools \ - python3-virtualenv swig uuid-dev + python3-venv swig uuid-dev SUSE based ~~~~~~~~~~ diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst index fa3cd6aec82..bc18b2ebb7b 100644 --- a/doc/develop/codingstyle.rst +++ b/doc/develop/codingstyle.rst @@ -154,6 +154,73 @@ See `here <https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#function-documentation>`_ for style. +Conditional Compilation +----------------------- + +Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c +files; doing so makes code harder to read and logic harder to follow. Instead, +use such conditionals in a header file defining functions for use in those .c +files, providing no-op stub versions in the #else case, and then call those +functions unconditionally from .c files. The compiler will avoid generating +any code for the stub calls, producing identical results, but the logic will +remain easy to follow. + +Prefer to compile out entire functions, rather than portions of functions or +portions of expressions. Rather than putting an ifdef in an expression, factor +out part or all of the expression into a separate helper function and apply the +conditional to that function. + +If you have a function or variable which may potentially go unused in a +particular configuration, and the compiler would warn about its definition +going unused, mark the definition as __maybe_unused rather than wrapping it in +a preprocessor conditional. (However, if a function or variable *always* goes +unused, delete it.) + +Within code, where possible, use the IS_ENABLED macro to convert a Kconfig +symbol into a C boolean expression, and use it in a normal C conditional: + +.. code-block:: c + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +The compiler will constant-fold the conditional away, and include or exclude +the block of code just as with an #ifdef, so this will not add any runtime +overhead. However, this approach still allows the C compiler to see the code +inside the block, and check it for correctness (syntax, types, symbol +references, etc). Thus, you still have to use an #ifdef if the code inside the +block references symbols that will not exist if the condition is not met. + +When working with xPL (see :doc:`spl` for more information) we need to take +further care to use the right macro. In the case where a symbol may be +referenced with an xPL-specific Kconfig symbol, use the CONFIG_IS_ENABLED macro +instead, in a similar manner: + +.. code-block:: c + + if (CONIG_IS_ENABLED(SOMETHING)) { + ... + } + +When dealing with a Kconfig symbol that has both a normal name and one or more +xPL-prefixed names, the Makefile needs special consideration as well. The +PHASE\_ macro helps us in this situation thusly: + +.. code-block:: make + + obj-$(CONFIG_$(PHASE_)SOMETHING) += something.o + +At the end of any non-trivial #if or #ifdef block (more than a few lines), +place a comment after the #endif on the same line, noting the conditional +expression used. For instance: + +.. code-block:: c + + #ifdef CONFIG_SOMETHING + ... + #endif /* CONFIG_SOMETHING */ + Driver model ------------ diff --git a/doc/develop/devicetree/dt_qemu.rst b/doc/develop/devicetree/dt_qemu.rst index 8ba2b225590..b452e2a997a 100644 --- a/doc/develop/devicetree/dt_qemu.rst +++ b/doc/develop/devicetree/dt_qemu.rst @@ -16,15 +16,22 @@ Obtaining the QEMU devicetree Where QEMU generates its own devicetree to pass to U-Boot you can use `-dtb u-boot.dtb` to force QEMU to use U-Boot's in-tree version. -To obtain the devicetree that qemu generates, add `-machine dumpdtb=qemu.dtb`, -e.g.:: - - qemu-system-arm -machine virt -machine dumpdtb=qemu.dtb - - qemu-system-aarch64 -machine virt -machine dumpdtb=qemu.dtb - - qemu-system-riscv64 -machine virt -machine dumpdtb=qemu.dtb - +To obtain the devicetree that QEMU generates, add `dumpdtb=qemu.dtb` to the +`-machine` argument, e.g. + +.. code-block:: bash + + qemu-system-aarch64 \ + -machine virt,gic-version=3,dumpdtb=qemu.dtb \ + -cpu cortex-a57 \ + -smp 4 \ + -memory 8G \ + -chardev socket,id=chrtpm,path=/tmp/mytpm1/swtpm-sock \ + -tpmdev emulator,id=tpm0,chardev=chrtpm \ + -device tpm-tis-device,tpmdev=tpm0 + +Except for the dumpdtb=qemu.dtb sub-parameter use the same qemu-system-<arch> +invocation that you would use to start U-Boot to to get a complete device-tree. Merging in U-Boot nodes/properties ---------------------------------- diff --git a/doc/develop/driver-model/design.rst b/doc/develop/driver-model/design.rst index 30093737200..633545944d1 100644 --- a/doc/develop/driver-model/design.rst +++ b/doc/develop/driver-model/design.rst @@ -312,7 +312,7 @@ drivers/demo/demo-shape.c): .name = "demo_shape_drv", .id = UCLASS_DEMO, .ops = &shape_ops, - .priv_data_size = sizeof(struct shape_data), + .priv_auto = sizeof(struct shape_data), }; diff --git a/doc/develop/py_testing.rst b/doc/develop/py_testing.rst index 502053f09fc..217ae447035 100644 --- a/doc/develop/py_testing.rst +++ b/doc/develop/py_testing.rst @@ -69,19 +69,19 @@ 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Using a Python sandbox to provide requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The recommended way to run the test suite, in order to ensure reproducibility -is to use `virtualenv` to set up the necessary environment. This can be done -via the following commands: +is to use a Python sandbox such as `python -m venv` to set up the necessary +environment. This can be done via the following commands: .. code-block:: console $ cd /path/to/u-boot - $ sudo apt-get install python3 python3-virtualenv - $ virtualenv -p /usr/bin/python3 venv + $ sudo apt-get install python3 python3-venv + $ python3 -m venv venv $ . ./venv/bin/activate $ pip install -r test/py/requirements.txt diff --git a/doc/develop/release_cycle.rst b/doc/develop/release_cycle.rst index cbbc2bad0eb..73b354db94e 100644 --- a/doc/develop/release_cycle.rst +++ b/doc/develop/release_cycle.rst @@ -1,3 +1,5 @@ +.. |next_ver| replace:: v2025.07 + Release Cycle ============= @@ -53,13 +55,13 @@ Current Status * U-Boot v2025.04 was released on Monday, 07 April 2025. -* The Merge Window for the next release (v2025.07) is **open** until the -rc1 +* The Merge Window for the next release (|next_ver|) was **closed** with the -rc1 release on Monday, 28 April 2025. * The next branch is now **closed** until the -rc2 release on Monday, 12 May 2025. -* Release "v2025.07" is scheduled for Monday, 07 July 2025. +* Release "|next_ver|" is scheduled for Monday, 07 July 2025. Future Releases --------------- @@ -67,17 +69,17 @@ Future Releases .. The following commented out dates are for when release candidates are planned to be tagged. -.. For the next scheduled release, release candidates were made on:: +For the next scheduled release, release candidates were made on:: -.. * U-Boot v2025.07-rc1 was released on Mon 21 April 2025. +* U-Boot |next_ver|-rc1 was released on Mon 28 April 2025. -.. * U-Boot v2025.07-rc2 was released on Mon 12 May 2025. +.. * U-Boot |next_ver|-rc2 was released on Mon 12 May 2025. -.. * U-Boot v2025.07-rc3 was released on Mon 26 May 2025. +.. * U-Boot |next_ver|-rc3 was released on Mon 26 May 2025. -.. * U-Boot v2025.07-rc4 was released on Mon 09 June 2025. +.. * U-Boot |next_ver|-rc4 was released on Mon 09 June 2025. -.. * U-Boot v2025.07-rc5 was released on Mon 23 June 2025. +.. * U-Boot |next_ver|-rc5 was released on Mon 23 June 2025. Please note that the following dates are planned only and may be deviated from as needed. diff --git a/doc/develop/tests_writing.rst b/doc/develop/tests_writing.rst index 7ea17081def..f6f852c297d 100644 --- a/doc/develop/tests_writing.rst +++ b/doc/develop/tests_writing.rst @@ -309,15 +309,15 @@ 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:: - obj-$(CONFIG_$(XPL_)CMDLINE) += wibble.o + obj-$(CONFIG_$(PHASE_)CMDLINE) += wibble.o 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. You can add an extra Kconfig check if needed:: - ifneq ($(CONFIG_$(XPL_)WIBBLE),) - obj-$(CONFIG_$(XPL_)CMDLINE) += wibble.o + ifneq ($(CONFIG_$(PHASE_)WIBBLE),) + obj-$(CONFIG_$(PHASE_)CMDLINE) += wibble.o endif Each suite can have an optional init and uninit function. These are run before diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index 48d6110b2ad..3ca22b572a9 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -597,21 +597,6 @@ and used by the steps highlighted below. [--fit | --raw | --guid <guid-string] \ <image_blob> <capsule_file_name> -4. Insert the signature list into a device tree in the following format:: - - { - signature { - capsule-key = [ <binary of signature list> ]; - } - ... - } - -You can perform step-4 through the Kconfig symbol -CONFIG_EFI_CAPSULE_CRT_FILE. This symbol points to the signing key -generated in step-2. As part of U-Boot build, the ESL certificate file will -be generated from the signing key and automatically get embedded into the -platform's dtb. - Anti-rollback Protection ************************ diff --git a/doc/git-mailrc b/doc/git-mailrc index 1177e42df2f..6214daeaecf 100644 --- a/doc/git-mailrc +++ b/doc/git-mailrc @@ -42,7 +42,7 @@ alias mbrugger Matthias Brugger <mbrugger@suse.com> alias monstr Michal Simek <monstr@monstr.eu> alias prom Minkyu Kang <mk7.kang@samsung.com> alias ptomsich Philipp Tomsich <philipp.tomsich@theobroma-systems.com> -alias sbabic Stefano Babic <sbabic@denx.de> +alias sbabic Stefano Babic <sbabic@nabladev.com> alias simongoldschmidt Simon Goldschmidt <simon.k.r.goldschmidt@gmail.com> alias sjg Simon Glass <sjg@chromium.org> alias smcnutt Scott McNutt <smcnutt@psyent.com> diff --git a/doc/usage/blkmap.rst b/doc/usage/blkmap.rst index 75f736c259f..4e9091e8ffa 100644 --- a/doc/usage/blkmap.rst +++ b/doc/usage/blkmap.rst @@ -39,7 +39,7 @@ network. Getting the image to the target is easy enough: dhcp ${ramdisk_addr_r} rootfs.ext4 -But now we are faced with a predicament: how to we extract the kernel +But now we are faced with a predicament: how do we extract the kernel image? Block maps to the rescue! We start by creating a new device: diff --git a/doc/usage/cmd/md.rst b/doc/usage/cmd/md.rst index 9a9919f9ad0..1eeaa824bf2 100644 --- a/doc/usage/cmd/md.rst +++ b/doc/usage/cmd/md.rst @@ -21,7 +21,7 @@ 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. +commands. address start address to display diff --git a/doc/usage/cmd/part.rst b/doc/usage/cmd/part.rst index e7faeccbb09..e7f6e54ecea 100644 --- a/doc/usage/cmd/part.rst +++ b/doc/usage/cmd/part.rst @@ -50,7 +50,7 @@ The 'part list' command prints or sets an environment variable to the list of pa 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), +The 'part start' command sets an environment variable to the start of the partition (in blocks), part can be either partition number or partition name. interface |