Skip to content

docs(linux): U-Boot: Falcon-Mode: minor fixes for the 11.1 release #359

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
StaticRocket merged 6 commits into from
Jul 14, 2025
Merged

docs(linux): U-Boot: Falcon-Mode: minor fixes for the 11.1 release #359

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4451f6c
docs(linux): U-Boot: Falcon-Mode: Add entry for the DT
ArchUsr64 Jul 10, 2025
dbb6bfc
docs(linux): U-Boot: Falcon-Mode: add links to patches
ArchUsr64 Jul 11, 2025
09bbd02
docs(linux): U-Boot: Falcon-Mode: add non-yocto users section
ArchUsr64 Jul 11, 2025
cd4e299
docs(linux): U-Boot: Falcon-Mode: add R5 memory map
ArchUsr64 Jul 11, 2025
297ec60
docs(linux): AM62AX: add falcon mode to release notes
ArchUsr64 Jul 11, 2025
b2eb32e
docs(linux): U-Boot: Falcon-Mode: consistency fixes
ArchUsr64 Jul 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion source/devices/AM62AX/linux/Release_Specific_Release_Notes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,8 @@

**Processor SDK Linux AM62AX Release has following new features:**

- First 2025 LTS Reference Release Including RT combined branch model
- First 2025 LTS Reference Release Including RT combined branch model

Check warning on line 48 in source/devices/AM62AX/linux/Release_Specific_Release_Notes.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'LTS') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'LTS') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/devices/AM62AX/linux/Release_Specific_Release_Notes.rst", "range": {"start": {"line": 48, "column": 16}}}, "severity": "INFO"}
- Falcon mode through R5 SPL :ref:`U-Boot Falcon Mode <U-Boot-Falcon-Mode>`

Check warning on line 49 in source/devices/AM62AX/linux/Release_Specific_Release_Notes.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'SPL') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'SPL') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/devices/AM62AX/linux/Release_Specific_Release_Notes.rst", "range": {"start": {"line": 49, "column": 28}}}, "severity": "INFO"}
- Important Bug Fixes on top of Processor SDK 10.01.10.04 Release
- Review Issue Tracker Section for the new fixes.

Expand Down
151 changes: 121 additions & 30 deletions source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,12 @@
$ # build the SDK
$ MACHINE=<machine> bitbake -k tisdk-default-image

The following set of patches are also required since they are **not** part of the
``11.01`` SDK release:

* `meta-ti <https://patchwork.yoctoproject.org/project/ti/list/?series=36071>`__
* `U-Boot <https://git.ti.com/cgit/ti-u-boot/ti-u-boot/commit/?h=ti-u-boot-2025.01-next&id=80f8ea010e3ef61277b7ab94ac4aeb85499c3ca5>`__

*************************************
Changes made by *ti-falcon* override:
*************************************
Expand All @@ -41,30 +47,60 @@
=======

Falcon mode makes use of a cut down variant of the tispl binary called
``tifalcon.bin`` with the Cortex-A SPL and it's corresponding DTB removed.
This file is deployed to the boot directory inside rootfs so it can be picked by
the R5 SPL at boot time.
:file:`tifalcon.bin` with the Cortex-A SPL and its corresponding device-tree

Check warning on line 50 in source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'SPL') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'SPL') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst", "range": {"start": {"line": 50, "column": 40}}}, "severity": "INFO"}
removed. This file is deployed to the boot directory inside the root filesystem

Check warning on line 51 in source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.PassiveVoice] 'is deployed' is passive voice. In general, use active voice. Consult the style guide for acceptable use of passive voice.

Raw Output:
{"message": "[RedHat.PassiveVoice] 'is deployed' is passive voice. In general, use active voice. Consult the style guide for acceptable use of passive voice.", "location": {"path": "source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst", "range": {"start": {"line": 51, "column": 20}}}, "severity": "INFO"}
so it can be picked by the R5 SPL at boot time.

Check warning on line 52 in source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'SPL') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'SPL') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst", "range": {"start": {"line": 52, "column": 31}}}, "severity": "INFO"}

Check warning on line 52 in source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.PassiveVoice] 'be picked' is passive voice. In general, use active voice. Consult the style guide for acceptable use of passive voice.

Raw Output:
{"message": "[RedHat.PassiveVoice] 'be picked' is passive voice. In general, use active voice. Consult the style guide for acceptable use of passive voice.", "location": {"path": "source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst", "range": {"start": {"line": 52, "column": 11}}}, "severity": "INFO"}

R5 SPL:
=======

The R5 SPL is used for loading the kernel ``fitImage`` and ``tifalcon.bin``
file, though the ``fitImage`` for falcon boot is signed by using an x509
certificate with TIFS keys instead of making use of signature nodes and keys
present in the DT. This allows for faster authentication since TIFS uses the
security accelerator for authentication, which is much faster than doing the
same on R5 core.

This support depends on the U-Boot's ``k3_r5_falcon.config`` fragment, which is
built alongside the standard R5 defconfig when ``ti-falcon`` is enabled.
The R5 SPL loads the kernel :file:`fitImage` and :file:`tifalcon.bin` file. An

Check warning on line 57 in source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'SPL') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'SPL') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst", "range": {"start": {"line": 57, "column": 8}}}, "severity": "INFO"}
x509 certificate with TIFS keys verifies the :file:`fitImage` for falcon boot

Check warning on line 58 in source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'TIFS') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'TIFS') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst", "range": {"start": {"line": 58, "column": 23}}}, "severity": "INFO"}
instead of making use of signature nodes and keys present in the DT. This allows
for faster authentication since TIFS uses the security accelerator for

Check warning on line 60 in source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'TIFS') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'TIFS') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst", "range": {"start": {"line": 60, "column": 33}}}, "severity": "INFO"}
authentication, which is much faster than doing the same on R5 core.

This support is present alongside the standard R5 ``defconfig`` when ``ti-falcon``
is enabled due to U-Boot's :file:`k3_r5_falcon.config` fragment. This updates
the R5 memory map at U-Boot SPL stage to the following:

.. code-block::

0x80000000 +===============================+ Start of DDR
512KiB | ATF reserved memory space | CONFIG_K3_ATF_LOAD_ADDR
0x80080000 +-------------------------------+
31.5MiB | Unused |
0x82000000 +-------------------------------+ PRELOADED_BL33_BASE in ATF
| | CONFIG_SYS_LOAD_ADDR
57MiB | Kernel + initramfs Image | CONFIG_SPL_LOAD_FIT_ADDRESS
| |
0x85900000 +-------------------------------+
| |
| R5 U-Boot SPL Stack + Heap |
39MiB | (size defined by |
| SPL_STACK_R_MALLOC_SIMPLE_LEN)|
| |
0x88000000 +-------------------------------+ CONFIG_SPL_STACK_R_ADDR
| | K3_HW_CONFIG_BASE in ATF
16MiB | Kernel DTB | CONFIG_SPL_PAYLOAD_ARGS_ADDR
| |
0x89000000 +-------------------------------+
331MiB | Device Manager (DM) Load Addr |
0x9db00000 +-------------------------------+
12MiB | DM Reserved |
0x9e700000 +-------------------------------+
1MiB | Unused |
0x9e800000 +-------------------------------+ BL32_BASE in ATF
24MiB | OPTEE |
0xa0000000 +===============================+ End of DDR (512MiB)

fitImage:
=========

The resulting ``fitImage`` file in the boot directory of rootfs is produced
with the constituent binaries pre-signed with x509 certificates. This file is
authenticated from TIFS at boot time, which allows for a lower boot time than
authenticating on the R5 core.
The system produces the resulting :file:`fitImage` file in the boot directory
of the root filesystem. This file has its constituent binaries pre-signed with
x509 certificates. At boot time, TIFS authenticates this file, which allows for

Check warning on line 102 in source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'TIFS') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'TIFS') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/U-Boot/UG-Falcon-Mode.rst", "range": {"start": {"line": 102, "column": 34}}}, "severity": "INFO"}
a lower boot time compared to authenticating on the R5 core.

*******************
Extra Configuration
Expand All @@ -75,13 +111,13 @@

.. ifconfig:: CONFIG_part_variant not in ('AM62AX')

For OSPI boot, the ``tiboot3.bin`` and ``tifalcon.bin`` files should be
For OSPI boot, the :file:`tiboot3.bin` and :file:`tifalcon.bin` files should be
flashed to the same addresses in flash as regular boot flow but the
``fitImage`` is read from the rootfs's boot directory. The MMC device is
selected by the ``mmcdev`` env variable for R5 SPL.
:file:`fitImage` is read from the root filesystem's boot directory. The MMC
device is selected by the ``mmcdev`` env variable for R5 SPL.

Below U-Boot commands can be used to download ``tiboot3.bin`` and
``tifalcon.bin`` over tftp and then flash those to OSPI at their respective
Below U-Boot commands can be used to download :file:`tiboot3.bin` and
:file:`tifalcon.bin` over tftp and then flash those to OSPI at their respective
addresses.

.. code-block:: console
Expand All @@ -99,10 +135,11 @@
eMMC Boot:
==========

In eMMC boot mode, the ``tiboot3.bin`` file should be flashed to the hardware
boot partition whereas ``tifalcon.bin`` and the ``fitImage`` are read from
the rootfs inside UDA. Use the U-Boot commands below to set the correct boot
partition and write ``tiboot3.bin`` to the correct offset.
In eMMC boot mode, the :file:`tiboot3.bin` file should be flashed to the
hardware boot partition whereas :file:`tifalcon.bin` and the :file:`fitImage`
are read from the root filesystem inside UDA. Use the U-Boot commands below
to set the correct boot partition and write :file:`tiboot3.bin` to the correct
offset.

.. code-block:: console

Expand All @@ -117,6 +154,8 @@
For more information check: :ref:`How to flash eMMC and boot with eMMC Boot
<how-to-emmc-boot>`.

.. _u-boot_falcon_mode_fitImage_creation:

Custom fitImage creation:
=========================

Expand All @@ -126,10 +165,10 @@

$ git clone https://git.ti.com/cgit/security-development-tools/core-secdev-k3

Copy the required kernel image renamed to ``Image`` and the DTB renamed to
``falcon.dtb`` inside the core-secdev-k3 source directory.
Copy the required kernel image renamed to :file:`Image` and the device-tree
renamed to :file:`falcon.dtb` inside the `core-secdev-k3` source directory.

Copy the following contents to a file named ``fitImage.its`` inside
Copy the following contents to a file named :file:`fitImage.its` inside
core-secdev-k3 source:

.. code-block:: dts
Expand Down Expand Up @@ -158,6 +197,7 @@
arch = "arm64";
compression = "none";
load = <0x88000000>;
entry = <0x88000000>;
};
};

Expand All @@ -171,8 +211,8 @@
};
};

Sign the kernel and dtb with ``secure-binary-image.sh`` and create the
``fitImage`` by using mkimage:
Sign the kernel and device-tree with :file:`secure-binary-image.sh` and create the
:file:`fitImage` by using ``mkimage``:

.. code-block:: console

Expand All @@ -181,6 +221,57 @@
$ ./scripts/secure-binary-image.sh falcon.dtb falcon.dtb.sec
$ mkimage -f fitImage.its fitImage

****************
Non-Yocto Users:
****************

Following are the steps to build :file:`tiboot3.bin`, :file:`tifalcon.bin` and the
:file:`fitImage` required for falcon mode:

#. For :ref:`ATF build <foundational-components-atf>`, use the following
arguments to update the ATF's jump address for the kernel and the
device-tree: ``PRELOADED_BL33_BASE=0x82000000 K3_HW_CONFIG_BASE=0x88000000``.

#. For :ref:`R5 U-Boot build <Build-U-Boot-label>`, use the
:file:`k3_r5_falcon.config` fragment to enable flacon support at the R5 SPL
stage.

#. Refer to the :ref:`fitImage creation step
<u-boot_falcon_mode_fitImage_creation>` above for preparing a bootable
:file:`fitImage` with an appropriate kernel and device-tree.

#. Copy the files generated to correct path on SD/eMMC as in the table below:

.. list-table::
:widths: 8 8 8 25
:header-rows: 1

* - File
- Destination path on SD/eMMC
- Partition
- Description

* - :file:`tiboot3.bin`
- :file:`/tiboot3.bin`
- boot (fat)
- R5 SPL with falcon support

* - :file:`tifalcon.bin`
- :file:`/boot/tifalcon.bin`
- root filesystem (ext4)
- tispl binary without SPL for the A core and device-tree

* - :file:`fitImage`
- :file:`/boot/fitImage`
- root filesystem (ext4)
- :file:`fitImage` with pre-signed kernel and device-tree

.. note::

The :file:`tifalcon.bin` binary is generated by default for all falcon
supported platforms at the A-Core U-Boot build step and can be found
alongside the existing :file:`tispl.bin` file in U-Boot build's output directory.

**********************
Boot time comparisons:
**********************
Expand Down
Loading