[PATCH v5 9/9] doc: ti: am62: add falcon mode documentation
Anshul Dalal
anshuld at ti.com
Fri Apr 25 16:56:40 CEST 2025
This patch adds user documentation for falcon boot for am62 platforms.
The main section is added to am62x_sk.rst and other documents just
include the section. Steps to build falcon support, usage and the
modified R5 memory map have been documented.
Two svg images have also been added for reference, one for the modified
tispl_falcon.bin and other for the falcon specific fitImage format.
Signed-off-by: Anshul Dalal <anshuld at ti.com>
---
doc/board/ti/am62ax_sk.rst | 7 +
doc/board/ti/am62px_sk.rst | 7 +
doc/board/ti/am62x_sk.rst | 248 ++++++++++++++++++
doc/board/ti/img/fitImage_falcon.svg | Bin 0 -> 5511 bytes
.../ti/img/tifsstub_dm_tispl_falcon.bin.svg | Bin 0 -> 9466 bytes
5 files changed, 262 insertions(+)
create mode 100644 doc/board/ti/img/fitImage_falcon.svg
create mode 100644 doc/board/ti/img/tifsstub_dm_tispl_falcon.bin.svg
diff --git a/doc/board/ti/am62ax_sk.rst b/doc/board/ti/am62ax_sk.rst
index 262340ef59a..9830916e3e0 100644
--- a/doc/board/ti/am62ax_sk.rst
+++ b/doc/board/ti/am62ax_sk.rst
@@ -192,6 +192,13 @@ https://www.ti.com/lit/pdf/spruj16 under the `Boot Mode Pins` section.
For SW2 and SW1, the switch state in the "ON" position = 1.
+Falcon Mode
+-----------
+
+.. include:: am62x_sk.rst
+ :start-after: .. am62x_evm_falcon_mode_start
+ :end-before: .. am62x_evm_falcon_mode_end
+
Debugging U-Boot
----------------
diff --git a/doc/board/ti/am62px_sk.rst b/doc/board/ti/am62px_sk.rst
index 99bdc034869..74f6dafa238 100644
--- a/doc/board/ti/am62px_sk.rst
+++ b/doc/board/ti/am62px_sk.rst
@@ -290,6 +290,13 @@ https://www.ti.com/lit/pdf/spruj83 under the `Boot Mode Pins` section.
For SW2 and SW1, the switch state in the "ON" position = 1.
+Falcon Mode
+-----------
+
+.. include:: am62x_sk.rst
+ :start-after: .. am62x_evm_falcon_mode_start
+ :end-before: .. am62x_evm_falcon_mode_end
+
Debugging U-Boot
----------------
diff --git a/doc/board/ti/am62x_sk.rst b/doc/board/ti/am62x_sk.rst
index dab2970a85c..711aef3f3ab 100644
--- a/doc/board/ti/am62x_sk.rst
+++ b/doc/board/ti/am62x_sk.rst
@@ -526,6 +526,254 @@ Next, based on NET_VCI_STRING string mentioned in respective defconfig file `tib
fetches `tispl.bin` and then `tispl.bin` fetches `u-boot.img` from TFTP server which
completes Ethernet boot on the device.
+Falcon Mode
+-----------
+
+.. am62x_evm_falcon_mode_start
+
+Falcon boot flow on am62 platforms bypasses the A-core SPL and u-boot with the
+overall boot flow as below:
+
+**Normal boot flow:**
+
+* R5 SPL -> ATF -> OP-TEE -> Cortex-A SPL -> U-Boot -> Kernel
+
+**With falcon mode:**
+
+* R5 SPL -> ATF -> OP-TEE -> Kernel
+
+Build Process
+^^^^^^^^^^^^^
+
+Enabling falcon mode requires re-building ATF, R5 U-boot and the kernel fitImage
+as follows:
+
+0. Setup environment variables:
+"""""""""""""""""""""""""""""""
+
+Refer to the build procedure above for setting up the environment variables.
+
+1. Trusted Firmware-A:
+""""""""""""""""""""""
+
+.. prompt:: bash $
+
+ # Change load addresses for the kernel and DTB
+ export TFA_EXTRA_ARGS="PRELOADED_BL33_BASE=0x82000000 K3_HW_CONFIG_BASE=0x88000000"
+
+.. include:: ../ti/k3.rst
+ :start-after: .. k3_rst_include_start_build_steps_tfa
+ :end-before: .. k3_rst_include_end_build_steps_tfa
+
+2. R5 SPL:
+""""""""""
+
+.. prompt:: bash $
+
+ # use the common falcon config fragment for am62 platforms
+ export $UBOOT_FALCON_CFG_FRAGMENTR="am62x_r5_falcon.config"
+ export UBOOT_CFG_CORTEXR="${UBOOT_CFG_CORTEXR} ${UBOOT_FALCON_CFG_FRAGMENTR}"
+
+.. include:: ../ti/k3.rst
+ :start-after: .. k3_rst_include_start_build_steps_spl_r5
+ :end-before: .. k3_rst_include_end_build_steps_spl_r5
+
+3. fitImage:
+""""""""""""
+
+.. warning::
+
+ The ``fitImage`` available by default under ``boot/fitImage`` in rootfs of
+ the standard SDK release is not compatible with falcon mode.
+
+For secure boot in falcon mode, the compute heavy authentication required for
+the ``fitImage`` is offloaded from the slower R5 core to TIFS. This requires
+``fitImage`` to package the necessary binaries (kernel and dtb) with a
+pre-signed x509 certificate.
+
+**fitImage for falcon mode:**
+
+.. image:: img/fitImage_falcon.svg
+ :alt: fitImage for falcon boot image format
+
+Follow the steps below to create a falcon compatible ``fitImage``:
+
+* **Sources**
+
+ * **Core Secdev K3**
+
+ | **source:** https://git.ti.com/cgit/security-development-tools/core-secdev-k3
+ | **branch:** master
+
+**3.1 Environment setup**
+
+.. prompt:: bash $
+
+ export CORE_SECDEV_PATH=path/to/core-secdev-k3
+ export DTB_PATH=path/to/dtb
+ export IMAGE_PATH=path/to/kernel-image
+
+**3.2 fitImage creation**
+
+ Inside ``core-secdev-k3`` source directory, create a file ``fitImage.its``
+ with the following contents:
+
+.. code-block:: dts
+
+ /dts-v1/;
+
+ / {
+ description = "Kernel fitImage for falcon mode";
+ #address-cells = <1>;
+
+ images {
+ kernel-1 {
+ description = "Linux kernel";
+ data = /incbin/("Image.sec");
+ type = "kernel";
+ arch = "arm64";
+ os = "linux";
+ compression = "none";
+ load = <0x82000000>;
+ entry = <0x82000000>;
+ };
+ falcon.dtb {
+ description = "Flattened Device Tree blob";
+ data = /incbin/("falcon.dtb.sec");
+ type = "flat_dt";
+ arch = "arm64";
+ compression = "none";
+ load = <0x88000000>;
+ entry = <0x88000000>;
+ };
+ };
+
+ configurations {
+ default = "conf-falcon";
+ conf-falcon {
+ description = "Pre-signed Kernel and DTB";
+ kernel = "kernel-1";
+ fdt = "falcon.dtb";
+ };
+ };
+ };
+
+Create the signed binaries:
+
+.. prompt:: bash $
+
+ # copy the kernel and dtb to core-secdev-k3
+ cp $IMAGE_PATH $CORE_SECDEV_PATH/Image
+ cp $DTB_PATH $CORE_SECDEV_PATH/falcon.dtb
+ # inside core-secdev-k3 source
+ ./scripts/secure-binary-image.sh Image Image.sec
+ ./scripts/secure-binary-image.sh falcon.dtb falcon.dtb.sec
+
+Create ``fitImage`` using mkimage:
+
+.. prompt:: bash $
+
+ mkimage -f $CORE_SECDEV_PATH/fitImage.its $CORE_SECDEV_PATH/fitImage
+
+Usage
+^^^^^
+
+Falcon mode makes use of a cut down variant of the tispl binary called
+``tispl_falcon.bin`` with the Cortex-A SPL and it's corresponding DTBs removed.
+This file should be present alongside the existing ``tispl.bin`` after building
+U-Boot for the Cortex-A cores.
+
+- **tispl_falcon.bin**
+
+.. image:: img/tifsstub_dm_tispl_falcon.bin.svg
+ :alt: tispl_falcon.bin image format
+
+1. eMMC/SD Boot:
+""""""""""""""""
+
+Falcon mode for K3 devices only supports SD and eMMC in FS boot. The R5 SPL
+once loaded from the ``tiboot3.bin`` file from the boot partition looks for
+``tispl_falcon.bin``, the DTB and fitImage (or kernel image for unauthenticated
+boot) inside the boot directory of the second partition (rootfs).
+
+.. list-table::
+ :widths: 8 8 8 25
+ :header-rows: 1
+
+ * - File
+ - Copy path on SD/eMMC
+ - Partition
+ - Description
+
+ * - ``tiboot3.bin``
+ - ``/tiboot3.bin``
+ - boot (fat)
+ - R5 SPL with falcon support
+
+ * - ``tispl_falcon.bin``
+ - ``/boot/tispl_falcon.bin``
+ - rootfs (ext4)
+ - tispl binary without SPL for the A core and DTB
+
+ * - ``fitImage``
+ - ``/boot/fitImage``
+ - rootfs (ext4)
+ - kernel and dtb fitImage with pre-signed binaries
+
+2. OSPI Boot:
+"""""""""""""
+
+For OSPI boot, the ``tiboot3.bin`` and ``tispl_falcon.bin`` files should be
+flashed to the same addresses in flash as regular boot flow but the DTB and the
+fitImage (or kernel image for unauthenticated boot) are read from the rootfs's
+boot directory.
+
+Below commands can be used to download ``tiboot3.bin`` and ``tispl_falcon.bin``
+over tftp and then flash those to OSPI at their respective addresses.
+
+.. prompt:: bash =>
+
+ sf probe
+ tftp ${loadaddr} tiboot3.bin
+ sf update $loadaddr 0x0 $filesize
+ tftp ${loadaddr} tispl_falcon.bin
+ sf update $loadaddr 0x80000 $filesize
+
+R5 SPL Memory Map:
+^^^^^^^^^^^^^^^^^^
+
+.. 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)
+
+.. am62x_evm_falcon_mode_end
+
Debugging U-Boot
----------------
diff --git a/doc/board/ti/img/fitImage_falcon.svg b/doc/board/ti/img/fitImage_falcon.svg
new file mode 100644
index 0000000000000000000000000000000000000000..a22e0f6564eb527814c655ec6dd5c822c05edc38
GIT binary patch
literal 5511
zcmds5U2oeq6n)RH;FOmZC}n;~BBjJB&;(tJ6<D!mz}^Z)qHQ6vWKfEo^w;lF5=Gf@
z(yr)MU=9*X{J!U&d+ue<U*E4wv{kw(>T2#$pLj at BS)CWva_;?k{T53PHEmkuX<1il
z?p3w-`r_pL7mU%Tk5_-;4 at IV`M&b9ls at h^vD4n2RKYqZ>C%D$QOk1VV?|+~-pRO>+
zmt}g_D1`CFNx#Nry?M~Za at C?2moE_`EI`-lK5fwZs%iDz8WuIrS*<s<hP85p(W-4X
zO){J9c00c<{H$Kjh83Ib@&uu&In*-^yCQE_bC2=<b*0RX at Xkory)D%4O?^N2F!4jw
z{ehv#b{F~FgOvsA1~-7s27Z&g&Z=|`kSvP!{W at K$&x^Fo>dJ?)-N>T4ZL)Nuk_o(l
zPtl8*=PHsiC*qYcImCoxPF{ACz#UbS*r{{R7(3W%8~s`@XJ+eWlV+-!+4jkNd&qIV
zZSb4=PG at QXODMlm?d<CMYGymZ^1RL6GUIH6^p1D?GD67ATG$^J-ku$K0WLVVdnD%I
zxk21G1|b9P*d&5(bA&bkXI7WBo_nW@?lW}U)H+w%c17K1ud4=3iuR$W^00;VgITp%
zrFp#r-w(4ac!}v8CliQ+Ba^e0%5IgusZ$NdwnLg#y<2Ky2oRuAhZDcl^&0l`<HL>&
z7$><OF%muQGZt{_3l>ld%6QaWQGpG3U^R`YJY0GhVTn$Ocxnio!P;@SJ{;kxu624}
ztcx#dg2FgEyVDxN7DE3)f&Z4#Bd85v&-x-)&8_uuPR);pW*v=kwP+l1%p3De2QX|r
zzy{Q8qq4Txs(vU!Bm3Hi4MgnzP~KC%W22?YcJtXFgAznZ0HOfj1I9qv$smJKH;9-o
z3)lXbFP-u{zf^Z-o`Yl-%fbjT4ZB@~Xn$(}d}7`R%gi9r0n`a#A65qW0UHf)SS)&-
zBM}pE7+B&V1eQSjcg>6k(P-_coy4asj2sM>T#Ux1C$tPhNW&H!P at __EF)pNG2PS;Z
zxwMQxXi=0U#CRSmnOmNNyINh}f}c($yWx>L%cd?W$R}8BO<tILX<3fToA@(kPFHy-
zVUfIOHo!&D)Uv45nb|Qp&2Ln&2)Y+MM14Zf`hAmANu%h753hZkCB&Cfia4^Zc?wdZ
zH7r~~VzjN}S_5H$m#w;=VsAW4!!X`Mo`#Vh#KDka3=;=nKyBeO8o8(;uomgMC;`lO
zs@$r!$kP4p2I3M3#5VV1yEy_*t88TibzS6nX;rFcis_eFVu2&<&~Dlz_>F6hQBbBg
z3Ve7Uk{D%5x86nfcnObC4`h(E&u3<Xfr?MS;n)L~$<U7gk|ACHTsW{}{C at -pL=JZm
z0&oP(XAzeXAHn~5?7-o8i0_8uZPB84DuqP;JTn4cNFMJogOUj1(8c)A1mZ_P at te|>
zDp6NI?tw8?>;s at Xz3FAFmxp~BBcqHBy}hapG6oesp`oyP^)(f<NyDnE3kF+#2<itB
z=;BBVmlr at X<CwZBCM`t1h~t>-Ih9dA3YnN>kXENv14SwnPTixqM!diR0)tB#y#fhk
zTu>@rJ|VN~GU<wA$d+0)N^hOs4PbUkYNRrO-61FO&HY&~lV!2261ei{_H3t%7A`_~
zUFRw(HEwUt^1^rqE=x(->S0DFtizPvFZqqkWVY`YmtKzhg at SDkMZhX1K4*eRmqI}c
zs1T4ogm7VKTw_j7y^He}tgfujCS{MVO(rz?Z*<e3{APml5JE at y?WzN}Gt^>xT-}rO
z{{{3$W`Zze&L03hqk$iDIw^rH^iXGgC-hF|JLn(p+d=PkK7 at WK_r`*6lD?0}5M)-u
zSRBN!aO_7S3OIi`REY<*N`D{*B;+t*!W+XvDSZ)4NcdF20`1S2EW>~!MGHcGJRUDw
zjub99#8WsARI at MtCT2WSz+7Fw*(3ODd8CfELNe5oj|2W|LcAaFR$-k9gThMYM?pZS
z>#zz-1?c8@`Rn{8;65otJP{J`Rt&t28Ikt70FFMAUY=I2Z!+X~Mj7!Q&BIR41_L<*
zibY(wU>gmTa3PUoQUVxxlD^~=jIlar_!t4NBTksh2S3z8Aqan>@*j_3Ep%0yO_3q<
z13rxwYoCDsHxVM36LXUyA+#ie>)E)nF%WJ}VIV<!`it<7cHuuV5IZ&aRud-$?ZiX}
z6_^NDARz=W;omY*hU8m)=o~UNkP0}QWu5gQR5TGJbk{N17gIiI1p7cq8HMa22K&y9
Ms+^nurCpr-4WjVe&Hw-a
literal 0
HcmV?d00001
diff --git a/doc/board/ti/img/tifsstub_dm_tispl_falcon.bin.svg b/doc/board/ti/img/tifsstub_dm_tispl_falcon.bin.svg
new file mode 100644
index 0000000000000000000000000000000000000000..7e2793c2ed9ae855a07ed493d35df8af9a736d2e
GIT binary patch
literal 9466
zcmeHN+iu%95Pk1ga8)dj0->(HMX^)tHceZgixy4x@)pn%ZF3__szhJXuiqI;q$Jnz
z7ERIQA#NK-LvlECW_X4rHGa8WCS=WvQe^4G@@&^4JdLtgr1OdO=hX!rS)`OKjaibV
zd}5`U_44f5_!mma<;U}X=z9_IwB+<%%u^|5f)^oq^YK0PZI@;RO_<~b`S6MSetAv<
z`YK_ok`qeLo>e+tW%+F(<_k%VUcDf`>-WeN-?EatOG{a-mY@`WkFp}q3eXi3N)}S)
zW#~AY&Bm6(j<TgwYb at 9EXN0uf@hlW<L at XB*%MYr at 1;-iTdE~0*wcwlIv+cy9uH7f<
z2XrO6S;P|yG!K2%xdd!-_!q`ml(Hp20&bV3Turaz<+T)Lo?OpZ5 at o496{!sa)i9CX
zlo88$*uuJJd*tXOi1}bNirwKc`roH+Km+%M8U(RP%TN!USm=4}xE9)3F?Z08GG`Gl
z9W8H-*A|=cT40yis)+auRB$`x(mB66cXT7b5X-owW}AR+qXWU;1ZsBg<mALrtxfNJ
z{e0JT9gRoj8a#bt&+S4klYM=w*|F6+gIJHX{UL%9V`wo02*D^C(XgjXB_wBa9%V^Z
zOswZK^{E at CSrPL>Hx1OM)06?;Lf%$urk+B_7`2uQ7H1nsvU-#bOo)wUunP-r&){gm
zqZ?jKGgg4vx=XppHuC}<fdni0?!YfuwuJfYpg-{ZzV^_}8$p75!@k|$9T%Y!ea{Zu
zp~1zB+K3d~p!Ev!PJC_5ZV$bvJhxs|0J+AaRssgxH5yE~t7*x$Vky4x77#{pv?>aq
z2%wo;4k4TmzCs%@I~b0bmp3}hv4?*w;;2lD`K)Ym2cLYEVvuCUfE<`J=aCd^UUenJ
zB%r*_fgQSCgK9;ogw*J)^J_$ggv4`uKtS+aho}W1bV7_&Cl|joT-`oj6w4h}rECsj
zpl2}`NctWm1q|s8a9lGr0N!%Xz~Ueh3Lr(c)yhKTQ3lu)0Efn+;#Aii^xRRuKN=e4
z;0q9pYUua8p3cb at RYR-ij{-A7=a)Ym*}=(Rq$5p80kZ at EoD136^e<ovkPiJ}&}*EU
zi3C{WdEDotSg#NWnJls!h}H9vKMe*0GiRQO6zUh{Ypg>PizSI^!)1uBwzb?Qprle(
zt(XuBsvAJrsZ#1|bb3t~(cb1sFStP?(g?Ifl{+a^W at DG}1=tooM*c0n3>rJ@*b*WO
zmX=T=fLheASkaHLMjqpjs!pkN20Z4T&H^OjjgZkoXF`=GmCSSNTv7P~x}hGYAEy7d
z5(isKsqoC8V$PCm6Oy$k#WdlkMDneqEP+uWN%%~j8ZU9&uBRP%u!F|db${&))Bt<C
z4F&(a5(SShIFqY_LngE;aa{$kJ~@|vz41I}R&{#*dMjaPB&H&PGSPAvpi#vvjK#V^
z2kojIj&TpcZbLFl`1X`2KdF#>S%zelmTble?71K>PszWl5_TWA6m}ahnf$6<c?yfV
zKgvN<<sUraL(XE{<WZUBAsM(RTCxHNfg+;72H2}(_T7dX)2G>%mf{QO4M|l&DTq$V
z4D7=O4!ngkwF6lD(uoA35i`kXT(FJEz&|L_0K57QNim-uxyJ<mzBna2MjkTL7-}#U
zDQs&vohDgy)3MX@(NJahj4ee1 at p#LVHJ2h{r(~}oN|OQE_5tJ$frJpt<dkd{5KOA}
zYavNtWib%yET@}-K|pG;b$0RY3g%_77a2PyZ7QZkknnRy!(Q>&=`6QK(HKM0PDdbB
z&lLM=B4DUNLw6{v>2!x`R0~GD0&Zd%;5tDzNr5xv+fG}RAZfI~o!L^vandjxsz>(4
zKBF!|DAGQSor-PhvgFL`Uv}zKmw~+&xoVndi8Mp>8(#gv6zuix%fS#d1Hl0f2INe*
z$DO1wV!-){gMS(ad!zmn2|rE}zIu0YNiN~P_;ux;7Py~#cJ$`sF?oAQFD}*B<?9!F
zIT!irj)uMB`*O55I_YrfgOjv3u+9vGwr!7{d-L>3L%;`Uy0xGF!8Gmr_onHFfDdey
zeSpsJ at e@tsQc|CX+bVnR6HPzTy)v9u|F)M=F=g&(*ekv_1G|rmf&CsZutMkF%-jA?
z!2#-RZL5DU^#ZAz)0FQ!r3e~QJwUwyVD?14kLi at c>pdM)JW}fY at R44<e!Z7We>(a0
z9@!a10EeO)pL^4<4~M6kl^%wE;X+v5k3dQNKKh0DXktA;zrE%t8D at GqpitXh`0;Q%
zUq5)F-$zQnpZetd4|4JMqaa`(c21h2Fl!(D`~mi&XAMICOTpvnsJO#Tc-~wcrVjP-
zYQug%;Ce{oh4akeklj!$(=B`N;oM`|x`I>hV1$c;&#DV5{gO;|iK1SVftOaC8T*W{
zVNkw>cWNX>JZN5IaI>~7P2eQl1#x&s=6ag2^u~zMJ~n6_UEpYKB3u at tE_T<kefz*4
zsKh8G1TGu;oy$15YS_7j(<lCLJ$rTq(-2X at Er}#>=?3ovMJ&aK`dX)bz%+IkR-5KF
K0DfD;UBG`Rm_1wo
literal 0
HcmV?d00001
--
2.49.0
More information about the U-Boot
mailing list