Pull request for doc-2023-10-rc4

Documentation:
 
 * Fix documentation for TI boards
 * Describe running on VirtualBox
 * List build dependencies for building documenation
 * Add references to U-Boot talks
 
 Other:
 
 * Fix error handling in the setexpr command (printf_str)
 -----BEGIN PGP SIGNATURE-----
 
 iQIzBAABCAAdFiEEbcT5xx8ppvoGt20zxIHbvCwFGsQFAmTlrkIACgkQxIHbvCwF
 GsQZew/8CBzzL3LzxRh4GZLVfXjgdYT5gQ068G9+ZWBg6UFwM58RruuAdjU+UDc4
 jDM2I2V+4g3Yc8b3+eJzOlbw5DXaSrfwswERTkjq7HRGBr573LFwY7S5eXc2qefj
 /+2dy4lF+7GZjfcH0EKSThye0AT+/xkvjBFjbJGlfmgE6oUP+rCbKVQXwKSwq66T
 x18z6Qi8pM18bGjRSqzR3M14NEHwmnybG+qgziBecc0ruaLbLsW05wEprQzZZNRJ
 Ywr95Bd32R/3iR/BDcsS0Z79S9SmcKrj3nTpJb800dY2hmhVGX3JRTN1wz5YBf4O
 9nMVNEyaYAH5816Wp+cw2/Jr0QmwTjChs4kXMtOfKv/SwJxEd0boMWIjodwGNQpe
 HY13NiKMh3fe9omq+WoN0+zbGA2OtLIfdRiE00STdFrCzHIIQNF9KEwaAMcmSy89
 WiR+WyBdHvpDbNVVaHoWfo6GsxXkqpFbPHSY8Lf0juwA4JMZ6htKTC4wuxLpK/WD
 nYxpsOL7+I0iKmOpiusvbwON1GaiZp0IQgZsHm5e1OVDaJmT2S2CsLj0lP1fHdcT
 FzBbkrCTmAeWGTgg0MyqJCC3+QGv/ES7r76tA5DgKJ/+04+BlIQxc2MS6fRRckGc
 OUXMVdaNAY6WuW0LzUABejOKX8URmaZEEQDUvASFngDEuzks4d0=
 =E6SF
 -----END PGP SIGNATURE-----

Merge tag 'doc-2023-10-rc4' of https://source.denx.de/u-boot/custodians/u-boot-efi

Pull request for doc-2023-10-rc4

Documentation:

* Fix documentation for TI boards
* Describe running on VirtualBox
* List build dependencies for building documenation
* Add references to U-Boot talks

Other:

* Fix error handling in the setexpr command (printf_str)
This commit is contained in:
Tom Rini 2023-08-23 11:03:46 -04:00
commit 291055efee
9 changed files with 180 additions and 36 deletions

View file

@ -144,10 +144,10 @@ static void printf_str(struct print_inf *inf, char *format, ...)
i = vsnprintf(inf->str + inf->offset, remaining, format, args);
va_end(args);
if (i >= remaining)
inf->error |= PRINT_TRUNCATED_ERROR;
else if (i < 0)
if (i < 0)
inf->error |= PRINT_CONVERSION_ERROR;
else if ((unsigned int)i >= remaining)
inf->error |= PRINT_TRUNCATED_ERROR;
else
inf->offset += i;
}

View file

@ -47,6 +47,7 @@ Boot Flow:
Below is the pictorial representation of boot flow:
.. image:: img/boot_diagram_k3_current.svg
:alt: Boot flow diagram
- Here TIFS acts as master and provides all the critical services. R5/A53
requests TIFS to get these services done as shown in the above diagram.
@ -102,13 +103,13 @@ Set the variables corresponding to this platform:
3. U-Boot:
* 4.1 R5:
* 3.1 R5:
.. include:: ../ti/k3.rst
:start-after: .. k3_rst_include_start_build_steps_spl_r5
:end-before: .. k3_rst_include_end_build_steps_spl_r5
* 4.2 A53:
* 3.2 A53:
.. include:: ../ti/k3.rst
:start-after: .. k3_rst_include_start_build_steps_uboot
@ -141,10 +142,12 @@ Image formats:
- tiboot3.bin
.. image:: img/multi_cert_tiboot3.bin.svg
:alt: tiboot3.bin image format
- tispl.bin
.. image:: img/dm_tispl.bin.svg
:alt: tispl.bin image format
A53 SPL DDR Memory Layout
-------------------------

View file

@ -46,6 +46,7 @@ applications. This should happen before running Linux.
instead use Falcon boot flow to reduce boot time.
.. image:: img/boot_diagram_am65.svg
:alt: Boot flow diagram
- Here DMSC acts as master and provides all the critical services. R5/A53
requests DMSC to get these services done as shown in the above diagram.
@ -102,13 +103,13 @@ Set the variables corresponding to this platform:
3. U-Boot:
* 4.1 R5:
* 3.1 R5:
.. include:: k3.rst
:start-after: .. k3_rst_include_start_build_steps_spl_r5
:end-before: .. k3_rst_include_end_build_steps_spl_r5
* 4.2 A53:
* 3.2 A53:
.. include:: k3.rst
:start-after: .. k3_rst_include_start_build_steps_uboot
@ -122,13 +123,13 @@ Each SoC variant (GP and HS) requires a different source for these files.
- GP
* tiboot3-am65x_sr2-gp-evm.bin, sysfw-am65x_sr2-gp-evm.itb from step 4.1
* tispl.bin_unsigned, u-boot.img_unsigned from step 4.2
* tiboot3-am65x_sr2-gp-evm.bin, sysfw-am65x_sr2-gp-evm.itb from step 3.1
* tispl.bin_unsigned, u-boot.img_unsigned from step 3.2
- HS
* tiboot3-am65x_sr2-hs-evm.bin, sysfw-am65x_sr2-hs-evm.itb from step 4.1
* tispl.bin, u-boot.img from step 4.2
* tiboot3-am65x_sr2-hs-evm.bin, sysfw-am65x_sr2-hs-evm.itb from step 3.1
* tispl.bin, u-boot.img from step 3.2
Image formats:
--------------
@ -136,14 +137,17 @@ Image formats:
- tiboot3.bin
.. image:: img/no_multi_cert_tiboot3.bin.svg
:alt: tiboot3.bin image format
- tispl.bin
.. image:: img/nodm_tispl.bin.svg
:alt: tispl.bin image format
- sysfw.itb
.. image:: img/sysfw.itb.svg
:alt: sysfw.itb image format
eMMC:
-----
@ -185,6 +189,7 @@ used:
eMMC layout:
.. image:: img/emmc_am65x_evm_boot0.svg
:alt: emmc boot partition layout
Kernel image and DT are expected to be present in the /boot folder of rootfs.
To boot kernel from eMMC, use the following commands:
@ -220,6 +225,7 @@ addresses.
Flash layout for OSPI:
.. image:: img/ospi_sysfw.svg
:alt: OSPI flash partition layout
Kernel Image and DT are expected to be present in the /boot folder of UBIFS
ospi.rootfs just like in SD card case. U-Boot looks for UBI volume named

View file

@ -35,6 +35,7 @@ Boot Flow:
Below is the pictorial representation of boot flow:
.. image:: img/boot_diagram_k3_current.svg
:alt: Boot flow diagram
- Here DMSC acts as master and provides all the critical services. R5/A72
requests DMSC to get these services done as shown in the above diagram.
@ -91,13 +92,13 @@ Set the variables corresponding to this platform:
3. U-Boot:
* 4.1 R5:
* 3.1 R5:
.. include:: k3.rst
:start-after: .. k3_rst_include_start_build_steps_spl_r5
:end-before: .. k3_rst_include_end_build_steps_spl_r5
* 4.2 A72:
* 3.2 A72:
.. include:: k3.rst
:start-after: .. k3_rst_include_start_build_steps_uboot
@ -111,18 +112,18 @@ variant (GP, HS-FS, HS-SE) requires a different source for these files.
- GP
* tiboot3-j7200-gp-evm.bin from step 4.1
* tispl.bin_unsigned, u-boot.img_unsigned from step 4.2
* tiboot3-j7200-gp-evm.bin from step 3.1
* tispl.bin_unsigned, u-boot.img_unsigned from step 3.2
- HS-FS
* tiboot3-j7200_sr2-hs-fs-evm.bin from step 4.1
* tispl.bin, u-boot.img from step 4.2
* tiboot3-j7200_sr2-hs-fs-evm.bin from step 3.1
* tispl.bin, u-boot.img from step 3.2
- HS-SE
* tiboot3-j7200_sr2-hs-evm.bin from step 4.1
* tispl.bin, u-boot.img from step 4.2
* tiboot3-j7200_sr2-hs-evm.bin from step 3.1
* tispl.bin, u-boot.img from step 3.2
Image formats:
--------------
@ -130,12 +131,12 @@ Image formats:
- tiboot3.bin
.. image:: img/j7200_tiboot3.bin.svg
:alt: tiboot3.bin image format
- tispl.bin
.. image:: img/dm_tispl.bin.svg
:alt: tispl.bin image format
Switch Setting for Boot Mode
----------------------------
@ -191,6 +192,7 @@ Size of u-boot.img is taken 4MB for refernece,
But this is subject to change depending upon atf, optee size
.. image:: img/emmc_j7200_evm_boot01.svg
:alt: Traditional eMMC boot partition layout
In case of UDA FS mode booting, following is layout.
@ -198,6 +200,7 @@ All boot images tiboot3.bin, tispl and u-boot should be written to
fat formatted UDA FS as file.
.. image:: img/emmc_j7200_evm_udafs.svg
:alt: eMMC UDA boot partition layout
In case of booting from eMMC, write above images into raw or UDA FS.
and set mmc partconf accordingly.

View file

@ -40,6 +40,7 @@ Boot flow is similar to that of AM65x SoC and extending it with remoteproc
support. Below is the pictorial representation of boot flow:
.. image:: img/boot_diagram_j721e.svg
:alt: Boot flow diagram
- Here DMSC acts as master and provides all the critical services. R5/A72
requests DMSC to get these services done as shown in the above diagram.
@ -96,13 +97,13 @@ Set the variables corresponding to this platform:
3. U-Boot:
* 4.1 R5:
* 3.1 R5:
.. include:: k3.rst
:start-after: .. k3_rst_include_start_build_steps_spl_r5
:end-before: .. k3_rst_include_end_build_steps_spl_r5
* 4.2 A72:
* 3.2 A72:
.. include:: k3.rst
:start-after: .. k3_rst_include_start_build_steps_uboot
@ -117,18 +118,18 @@ files.
- GP
* tiboot3-j721e-gp-evm.bin, sysfw-j721e-gp-evm.itb from step 4.1
* tispl.bin_unsigned, u-boot.img_unsigned from step 4.2
* tiboot3-j721e-gp-evm.bin, sysfw-j721e-gp-evm.itb from step 3.1
* tispl.bin_unsigned, u-boot.img_unsigned from step 3.2
- HS-FS
* tiboot3-j721e_sr2-hs-fs-evm.bin, sysfw-j721e_sr2-hs-fs-evm.itb from step 4.1
* tispl.bin, u-boot.img from step 4.2
* tiboot3-j721e_sr2-hs-fs-evm.bin, sysfw-j721e_sr2-hs-fs-evm.itb from step 3.1
* tispl.bin, u-boot.img from step 3.2
- HS-SE
* tiboot3-j721e_sr2-hs-evm.bin, sysfw-j721e_sr2-hs-evm.itb from step 4.1
* tispl.bin, u-boot.img from step 4.2
* tiboot3-j721e_sr2-hs-evm.bin, sysfw-j721e_sr2-hs-evm.itb from step 3.1
* tispl.bin, u-boot.img from step 3.2
Image formats:
--------------
@ -136,14 +137,17 @@ Image formats:
- tiboot3.bin
.. image:: img/no_multi_cert_tiboot3.bin.svg
:alt: tiboot3.bin image format
- tispl.bin
.. image:: img/dm_tispl.bin.svg
:alt: tispl.bin image format
- sysfw.itb
.. image:: img/sysfw.itb.svg
:alt: sysfw.itb image format
R5 Memory Map:
--------------
@ -213,6 +217,7 @@ addresses.
Flash layout for OSPI:
.. image:: img/ospi_sysfw.svg
:alt: OSPI flash partition layout
Firmwares:
----------

View file

@ -47,6 +47,7 @@ including a 32bit U-Boot SPL, (called the wakup SPL) that ROM will jump
to after it has finished loading everything into internal SRAM.
.. image:: img/boot_flow_01.svg
:alt: Boot flow up to wakeup domain SPL
The wakeup SPL, running on a wakeup domain core, will initialize DDR and
any peripherals needed load the larger binaries inside the `tispl.bin`
@ -56,6 +57,7 @@ starting with Trusted Firmware-A (TF-A), before moving on to start
OP-TEE and the main domain's U-Boot SPL.
.. image:: img/boot_flow_02.svg
:alt: Boot flow up to main domain SPL
The main domain's SPL, running on a 64bit application core, has
virtually unlimited space (billions of bytes now that DDR is working) to
@ -64,6 +66,7 @@ which loads more firmware into the micro-controller & wakeup domains and
finally prepare the main domain to run Linux.
.. image:: img/boot_flow_03.svg
:alt: Complete boot flow up to Linux
This is the typical boot flow for all K3 based SoCs, however this flow
offers quite a lot in the terms of flexibility, especially on High
@ -120,11 +123,30 @@ online
| **source:** https://github.com/OP-TEE/optee_os.git
| **branch:** master
* **TI Firmware (TIFS, DM, DSMC)**
* **TI Firmware (TIFS, DM, SYSFW)**
| **source:** https://git.ti.com/git/processor-firmware/ti-linux-firmware.git
| **branch:** ti-linux-firmware
.. note::
The TI Firmware required for functionality of the system can be
one of the following combination (see platform specific boot diagram for
further information as to which component runs on which processor):
* **TIFS** - TI Foundational Security Firmware - Consists of purely firmware
meant to run on the security enclave.
* **DM** - Device Management firmware also called TI System Control Interface
server (TISCI Server) - This component purely plays the role of managing
device resources such as power, clock, interrupts, dma etc. This firmware
runs on a dedicated or multi-use microcontroller outside the security
enclave.
OR
* **SYSFW** - System firmware - consists of both TIFS and DM both running on
the security enclave.
.. k3_rst_include_end_boot_sources
Build Procedure
@ -485,6 +507,7 @@ generation device.
The overall structure of this setup is in the following figure.
.. image:: img/openocd-overview.svg
:alt: Overview of OpenOCD setup.
.. note::
@ -577,7 +600,7 @@ correctly to ensure a sane system.
$ cd openocd
# Copy the udev rules to the correct system location
$ sudo cp ./contrib/60-openocd.rules \
./src/JTAG/drivers/libjaylink/contrib/99-libjaylink.rules \
./src/jtag/drivers/libjaylink/contrib/99-libjaylink.rules \
/etc/udev/rules.d/
# Get Udev to load the new rules up
$ sudo udevadm control --reload-rules
@ -768,7 +791,7 @@ Code modification
In this example, we will debug ``board_init_f`` inside
``arch/arm/mach-k3/{soc}_init.c``. Since some sections of U-Boot
will be executed multiple times during the bootup process of K3
devices, we will need to include either ``CONFIG_CPU_ARM64`` or
devices, we will need to include either ``CONFIG_ARM64`` or
``CONFIG_CPU_V7R`` to catch the CPU at the desired place during the
bootup process (Main or Wakeup domains). For example, modify the
file as follows (depending on need):
@ -786,7 +809,7 @@ Code modification
}
...
/* Code to run on the ARMV8 (Main Domain) */
if (IS_ENABLED(CONFIG_CPU_ARM64)) {
if (IS_ENABLED(CONFIG_ARM64)) {
volatile int x = 1;
while(x) {};
}

View file

@ -5,6 +5,17 @@ Building documentation
The U-Boot documentation is based on the Sphinx documentation generator.
In addition to the Python packages listed in ``doc/sphinx/requirements.txt``,
the following dependencies are needed to build the documentation:
* fontconfig
* graphviz
* imagemagick
* texinfo (if building the `Infodoc documentation`_)
HTML documentation
------------------

View file

@ -254,6 +254,90 @@ This shows running with serial enabled (see `include/configs/efi-x86_app.h`)::
=> QEMU: Terminated
Run on VirtualBox (x86_64)
--------------------------
Enable EFI
~~~~~~~~~~
At settings for virtual machine the flag at **System->Motherboard->Enable EFI
(special OSes only)** has to be enabled.
Installation
~~~~~~~~~~~~
Provide the preinstalled Linux system as a Virtual Disk Image (VDI) and assign
it to a SATA controller (type AHCI) using the settings for the virtual machine
at menu item **System->Storage->Controller:SATA**.
For the following description three GPT partitions are assumed:
- Partition 1: formatted as FAT file-system and marked as EFI system partition
(partition type 0xEF00) used for the U-Boot EFI binary. (If VirtualBox is UEFI
compliant, it should recognize the ESP as the boot partition.)
- Partition 2: formatted as **ext4**, used for root file system
Create an extlinux.conf or a boot script
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Following files are assumed to be located at system for boot configuration::
Partition File Comment
1 EFI/BOOT/BOOTX64.efi # renamed U-Boot EFI image
1 Image # Linux image
1 Initrd # Initramfs of Linux
**EFI/BOOT/BOOTX64.efi** is a renamed build result **u-boot-payload.efi**, built with
**efi-x86_payload64_defconfig** configuration.
Boot script
~~~~~~~~~~~
The boot script **boot.scr** is assumed to be located at::
Partition File Comment
1 boot.scr # Boot script, generated with mkimage from template
Content of **boot.scr**:
.. code-block:: bash
ext4load ${devtype} ${devnum}:${distro_bootpart} ${kernel_addr_r} ${prefix}Image
setenv kernel_size ${filesize}
ext4load ${devtype} ${devnum}:${distro_bootpart} ${ramdisk_addr_r} ${prefix}Initrd
setenv initrd_size ${filesize}
zboot ${kernel_addr_r} ${kernel_size} ${ramdisk_addr_r} ${initrd_size}
Extlinux configuration
~~~~~~~~~~~~~~~~~~~~~~
Alternatively a configuration **extlinux.conf** can be used. **extlinux.conf**
is assumed to be located at::
Partition File Comment
1 extlinux/extlinux.conf # Extlinux boot configuration
Content of **extlinux.conf**:
.. code-block:: bash
default l0
menu title U-Boot menu
prompt 0
timeout 50
label l0
menu label Linux
linux /Image
initrd /Initrd
Additionally something like (sda is assumed as disk device):
.. code-block:: bash
append root=/dev/sda2 console=tty0 console=ttyS0,115200n8 rootwait rw
Future work
-----------

View file

@ -3,9 +3,18 @@
U-Boot Talks
============
U-Boot is a topic at various conferences each year. These talkes might help you
learn a bit about U-Boot.
U-Boot is a topic at various conferences each year. These talks might help you
learn a bit about U-Boot:
See elinux_talks_ for a list.
* `Tutorial: Introduction to the Embedded Boot Loader U-boot - Behan Webster,
Converse in Code <https://www.youtube.com/watch?v=INWghYZH3hI>`__
from Embedded Linux Conference 2020
(`slides <https://cm.e-ale.org/2020/ELC2020/intro-to-u-boot/intro-to-u-boot-2020.pdf>`__).
* `Recent Advances in U-Boot - Simon Glass, Google Inc.
<https://www.youtube.com/watch?v=YlJBsVZJkDI>`__
from Embedded Linux Conference 2023.
See elinux_talks_ for a more comprehensive list.
.. _elinux_talks: https://elinux.org/Boot_Loaders#U-Boot