blob: 67b066a07d3ac36d9479edf180686b216a83912e [file] [log] [blame]
Bryan Brattlof6d138132022-12-19 14:29:50 -06001.. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
2.. sectionauthor:: Bryan Brattlof <bb@ti.com>
3
4K3 Generation
5=============
6
7Summary
8-------
9
10Texas Instrument's K3 family of SoCs utilize a heterogeneous multicore
11and highly integrated device architecture targeted to maximize
12performance and power efficiency for a wide range of industrial,
13automotive and other broad market segments.
14
15Typically the processing cores and the peripherals for these devices are
16partitioned into three functional domains to provide ultra-low power
17modes as well as accommodating application and industrial safety systems
18on the same SoC. These functional domains are typically called the:
19
20* Wakeup (WKUP) domain
21* Micro-controller (MCU) domain
22* Main domain
23
24For a more detailed view of what peripherals are attached to each
25domain, consult the device specific documentation.
26
27K3 Based SoCs
28-------------
29
30.. toctree::
31 :maxdepth: 1
32
Jai Luthrae526653e2023-11-13 08:51:49 -060033 am62ax_sk
Bryan Brattlof6d138132022-12-19 14:29:50 -060034 am62x_sk
Nishanth Menon1f2b6f92023-11-04 03:01:36 -050035 ../beagle/am62x_beagleplay
Wadim Egorov12722a42023-12-20 10:18:11 +010036 ../phytec/phycore-am62x
Marcel Ziswiler315deb32023-08-04 12:08:08 +020037 ../toradex/verdin-am62
Bryan Brattlofcf2e2b12024-03-12 15:20:30 -050038 am62px_sk
Roger Quadroscd87b1e2023-08-05 11:14:39 +030039 am64x_evm
Neha Malcom Francis507be122023-07-22 00:14:43 +053040 am65x_evm
Nishanth Menone83fe672023-07-27 13:59:01 -050041 j7200_evm
Nishanth Menon756b8782023-11-04 03:11:03 -050042 ../beagle/j721e_beagleboneai64
Nishanth Menone83fe672023-07-27 13:59:01 -050043 j721e_evm
Manorit Chawdhry670a22b2023-10-06 10:16:00 +053044 j721s2_evm
Jayesh Choudhary5e547a72024-06-12 14:41:23 +053045 j722s_evm
Apurva Nandan2b1c9ff2024-02-24 01:51:53 +053046 j784s4_evm
Bryan Brattlof6d138132022-12-19 14:29:50 -060047
48Boot Flow Overview
49------------------
50
51For all K3 SoCs the first core started will be inside the Security
52Management Subsystem (SMS) which will secure the device and start a core
53in the wakeup domain to run the ROM code. ROM will then initialize the
54boot media needed to load the binaries packaged inside `tiboot3.bin`,
Jonathan Humphreys97fa76a2024-06-14 11:35:29 -050055including a 32bit U-Boot SPL, (called the wakeup SPL) that ROM will jump
Bryan Brattlof6d138132022-12-19 14:29:50 -060056to after it has finished loading everything into internal SRAM.
57
Nishanth Menon7bdb2d52023-07-27 13:59:02 -050058.. image:: img/boot_flow_01.svg
Heinrich Schuchardtd0894b22023-08-22 11:40:55 -050059 :alt: Boot flow up to wakeup domain SPL
Bryan Brattlof6d138132022-12-19 14:29:50 -060060
61The wakeup SPL, running on a wakeup domain core, will initialize DDR and
Jonathan Humphreys97fa76a2024-06-14 11:35:29 -050062any peripherals needed to load the larger binaries inside the `tispl.bin`
Bryan Brattlof6d138132022-12-19 14:29:50 -060063into DDR. Once loaded the wakeup SPL will start one of the 'big'
64application cores inside the main domain to initialize the main domain,
Neha Malcom Francis507be122023-07-22 00:14:43 +053065starting with Trusted Firmware-A (TF-A), before moving on to start
66OP-TEE and the main domain's U-Boot SPL.
Bryan Brattlof6d138132022-12-19 14:29:50 -060067
Nishanth Menon7bdb2d52023-07-27 13:59:02 -050068.. image:: img/boot_flow_02.svg
Heinrich Schuchardtd0894b22023-08-22 11:40:55 -050069 :alt: Boot flow up to main domain SPL
Bryan Brattlof6d138132022-12-19 14:29:50 -060070
71The main domain's SPL, running on a 64bit application core, has
72virtually unlimited space (billions of bytes now that DDR is working) to
73initialize even more peripherals needed to load in the `u-boot.img`
74which loads more firmware into the micro-controller & wakeup domains and
75finally prepare the main domain to run Linux.
76
Nishanth Menon7bdb2d52023-07-27 13:59:02 -050077.. image:: img/boot_flow_03.svg
Heinrich Schuchardtd0894b22023-08-22 11:40:55 -050078 :alt: Complete boot flow up to Linux
Bryan Brattlof6d138132022-12-19 14:29:50 -060079
80This is the typical boot flow for all K3 based SoCs, however this flow
81offers quite a lot in the terms of flexibility, especially on High
82Security (HS) SoCs.
83
84Boot Flow Variations
85^^^^^^^^^^^^^^^^^^^^
86
87All K3 SoCs will generally use the above boot flow with two main
88differences depending on the capabilities of the boot ROM and the number
89of cores inside the device. These differences split the bootflow into
90essentially 4 unique but very similar flows:
91
92* Split binary with a combined firmware: (eg: AM65)
93* Combined binary with a combined firmware: (eg: AM64)
94* Split binary with a split firmware: (eg: J721E)
95* Combined binary with a split firmware: (eg: AM62)
96
97For devices that utilize the split binary approach, ROM is not capable
Jonathan Humphreys97fa76a2024-06-14 11:35:29 -050098of loading the firmware into the SoC, requiring the wakeup domain's
Bryan Brattlof6d138132022-12-19 14:29:50 -060099U-Boot SPL to load the firmware.
100
101Devices with a split firmware will have two firmwares loaded into the
102device at different times during the bootup process. TI's Foundational
103Security (TIFS), needed to operate the Security Management Subsystem,
104will either be loaded by ROM or the WKUP U-Boot SPL, then once the
105wakeup U-Boot SPL has completed, the second Device Management (DM)
106firmware can be loaded on the now free core in the wakeup domain.
107
108For more information on the bootup process of your SoC, consult the
109device specific boot flow documentation.
110
Manorit Chawdhry98346472023-12-29 16:16:33 +0530111Secure Boot
112-----------
113
114K3 HS-SE (High Security - Security Enforced) devices enforce an
115authenticated boot flow for secure boot. HS-FS (High Security - Field
116Securable) is the state of a K3 device before it has been eFused with
117customer security keys. In the HS-FS state the authentication still can
Jonathan Humphreys97fa76a2024-06-14 11:35:29 -0500118function as in HS-SE, but as there are no customer keys to verify the
119signatures against, the authentication will pass for certificates signed
Manorit Chawdhry98346472023-12-29 16:16:33 +0530120with any key.
121
122Chain of trust
123^^^^^^^^^^^^^^
124
1251) Public ROM loads the tiboot3.bin (R5 SPL, TIFS)
1262) R5 SPL loads tispl.bin (ATF, OP-TEE, DM, SPL)
1273) SPL loads u-boot.img (U-Boot)
1284) U-Boot loads fitImage (Linux and DTBs)
129
130Steps 1-3 are all authenticated by either the Secure ROM or TIFS as the
131authenticating entity and step 4 uses U-boot standard mechanism for
132authenticating.
133
134All the authentication that are done for ROM/TIFS are done through x509
135certificates that are signed.
136
137Firewalls
138^^^^^^^^^
139
1401) Secure ROM comes up and sets up firewalls that are needed by itself
1412) TIFS will setup it's own firewalls to protect core system resources
1423) R5 SPL will remove any firewalls that are leftover from the Secure ROM stage
143 that are no longer required.
1444) Each stage beyond this: such as tispl.bin containing TFA/OPTEE uses OIDs to
145 set up firewalls to protect themselves (enforced by TIFS)
1465) TFA/OP-TEE can configure other firewalls at runtime if required as they
147 are already authenticated and firewalled off from illegal access.
1486) All later stages can setup or remove firewalls that have not been already
149 configured by previous stages, such as those created by TIFS, TFA, and OP-TEE.
150
151Futhur, firewalls have a lockdown bit in hardware that enforces the setting
152(and cannot be over-ridden) until the full system is reset.
153
Bryan Brattlof6d138132022-12-19 14:29:50 -0600154Software Sources
155----------------
156
157All scripts and code needed to build the `tiboot3.bin`, `tispl.bin` and
158`u-boot.img` for all K3 SoCs can be located at the following places
159online
160
Nishanth Menonee91e482023-07-27 13:58:44 -0500161.. k3_rst_include_start_boot_sources
162
Bryan Brattlof6d138132022-12-19 14:29:50 -0600163* **Das U-Boot**
164
165 | **source:** https://source.denx.de/u-boot/u-boot.git
166 | **branch:** master
167
Neha Malcom Francis507be122023-07-22 00:14:43 +0530168* **Trusted Firmware-A (TF-A)**
Bryan Brattlof6d138132022-12-19 14:29:50 -0600169
Neha Malcom Francis507be122023-07-22 00:14:43 +0530170 | **source:** https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/
Bryan Brattlof6d138132022-12-19 14:29:50 -0600171 | **branch:** master
172
Neha Malcom Francis507be122023-07-22 00:14:43 +0530173* **Open Portable Trusted Execution Environment (OP-TEE)**
Bryan Brattlof6d138132022-12-19 14:29:50 -0600174
175 | **source:** https://github.com/OP-TEE/optee_os.git
176 | **branch:** master
177
Nishanth Menone2a47452023-08-22 11:41:07 -0500178* **TI Firmware (TIFS, DM, SYSFW)**
Bryan Brattlof6d138132022-12-19 14:29:50 -0600179
180 | **source:** https://git.ti.com/git/processor-firmware/ti-linux-firmware.git
181 | **branch:** ti-linux-firmware
182
Nishanth Menone2a47452023-08-22 11:41:07 -0500183.. note::
184
185 The TI Firmware required for functionality of the system can be
186 one of the following combination (see platform specific boot diagram for
187 further information as to which component runs on which processor):
188
189 * **TIFS** - TI Foundational Security Firmware - Consists of purely firmware
190 meant to run on the security enclave.
191 * **DM** - Device Management firmware also called TI System Control Interface
192 server (TISCI Server) - This component purely plays the role of managing
193 device resources such as power, clock, interrupts, dma etc. This firmware
194 runs on a dedicated or multi-use microcontroller outside the security
195 enclave.
196
197 OR
198
199 * **SYSFW** - System firmware - consists of both TIFS and DM both running on
200 the security enclave.
201
Nishanth Menonee91e482023-07-27 13:58:44 -0500202.. k3_rst_include_end_boot_sources
203
Bryan Brattlof6d138132022-12-19 14:29:50 -0600204Build Procedure
205---------------
206
Jonathan Humphreys43d44fa2024-06-21 15:17:06 -0500207.. note ::
208
209 Make sure you have installed all necessary host package dependencies
210 before proceeding. See :ref:`build/gcc:Building with GCC`.
211
Bryan Brattlof6d138132022-12-19 14:29:50 -0600212Depending on the specifics of your device, you will need three or more
213binaries to boot your SoC.
214
215* `tiboot3.bin` (bootloader for the wakeup domain)
216* `tispl.bin` (bootloader for the main domain)
217* `u-boot.img`
218
219During the bootup process, both the 32bit wakeup domain and the 64bit
220main domains will be involved. This means everything inside the
221`tiboot3.bin` running in the wakeup domain will need to be compiled for
22232bit cores and most binaries in the `tispl.bin` will need to be
223compiled for 64bit main domain CPU cores.
224
225All of that to say you will need both a 32bit and 64bit cross compiler
226(assuming you're using an x86 desktop)
227
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500228.. k3_rst_include_start_common_env_vars_desc
229.. list-table:: Generic environment variables
230 :widths: 25 25 50
231 :header-rows: 1
232
233 * - S/w Component
234 - Env Variable
235 - Description
236 * - All Software
237 - CC32
238 - Cross compiler for ARMv7 (ARM 32bit), typically arm-linux-gnueabihf-
239 * - All Software
240 - CC64
241 - Cross compiler for ARMv8 (ARM 64bit), typically aarch64-linux-gnu-
242 * - All Software
243 - LNX_FW_PATH
244 - Path to TI Linux firmware repository
245 * - All Software
246 - TFA_PATH
247 - Path to source of Trusted Firmware-A
248 * - All Software
249 - OPTEE_PATH
250 - Path to source of OP-TEE
251.. k3_rst_include_end_common_env_vars_desc
252
253.. k3_rst_include_start_common_env_vars_defn
Nishanth Menon740c41c2023-11-02 23:40:25 -0500254.. prompt:: bash $
Bryan Brattlof6d138132022-12-19 14:29:50 -0600255
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500256 export CC32=arm-linux-gnueabihf-
257 export CC64=aarch64-linux-gnu-
258 export LNX_FW_PATH=path/to/ti-linux-firmware
259 export TFA_PATH=path/to/trusted-firmware-a
260 export OPTEE_PATH=path/to/optee_os
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500261.. k3_rst_include_end_common_env_vars_defn
262
263We will also need some common environment variables set up for the various
264other build sources. we shall use the following, in the build descriptions below:
265
266.. k3_rst_include_start_board_env_vars_desc
267.. list-table:: Board specific environment variables
268 :widths: 25 25 50
269 :header-rows: 1
270
271 * - S/w Component
272 - Env Variable
273 - Description
274 * - U-Boot
275 - UBOOT_CFG_CORTEXR
276 - Defconfig for Cortex-R (Boot processor).
277 * - U-Boot
278 - UBOOT_CFG_CORTEXA
279 - Defconfig for Cortex-A (MPU processor).
280 * - Trusted Firmware-A
281 - TFA_BOARD
282 - Platform name used for building TF-A for Cortex-A Processor.
283 * - Trusted Firmware-A
284 - TFA_EXTRA_ARGS
285 - Any extra arguments used for building TF-A.
286 * - OP-TEE
287 - OPTEE_PLATFORM
288 - Platform name used for building OP-TEE for Cortex-A Processor.
289 * - OP-TEE
290 - OPTEE_EXTRA_ARGS
291 - Any extra arguments used for building OP-TEE.
292.. k3_rst_include_end_board_env_vars_desc
Bryan Brattlof6d138132022-12-19 14:29:50 -0600293
294Building tiboot3.bin
Heinrich Schuchardtb72160b2023-10-28 11:59:32 +0200295^^^^^^^^^^^^^^^^^^^^
Bryan Brattlof6d138132022-12-19 14:29:50 -0600296
2971. To generate the U-Boot SPL for the wakeup domain, use the following
298 commands, substituting :code:`{SOC}` for the name of your device (eg:
Neha Malcom Francis507be122023-07-22 00:14:43 +0530299 am62x) to package the various firmware and the wakeup UBoot SPL into
300 the final `tiboot3.bin` binary. (or the `sysfw.itb` if your device
301 uses the split binary flow)
Bryan Brattlof6d138132022-12-19 14:29:50 -0600302
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530303.. _k3_rst_include_start_build_steps_spl_r5:
304
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500305.. k3_rst_include_start_build_steps_spl_r5
Nishanth Menon740c41c2023-11-02 23:40:25 -0500306.. prompt:: bash $
Bryan Brattlof6d138132022-12-19 14:29:50 -0600307
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500308 # inside u-boot source
309 make $UBOOT_CFG_CORTEXR
310 make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500311.. k3_rst_include_end_build_steps_spl_r5
Bryan Brattlof6d138132022-12-19 14:29:50 -0600312
313At this point you should have all the needed binaries to boot the wakeup
314domain of your K3 SoC.
315
316**Combined Binary Boot Flow** (eg: am62x, am64x, ... )
317
Neha Malcom Francis507be122023-07-22 00:14:43 +0530318 `tiboot3-{SOC}-{gp/hs-fs/hs}.bin`
Bryan Brattlof6d138132022-12-19 14:29:50 -0600319
320**Split Binary Boot Flow** (eg: j721e, am65x)
321
Neha Malcom Francis507be122023-07-22 00:14:43 +0530322 | `tiboot3-{SOC}-{gp/hs-fs/hs}.bin`
323 | `sysfw-{SOC}-{gp/hs-fs/hs}-evm.itb`
Bryan Brattlof6d138132022-12-19 14:29:50 -0600324
325.. note ::
326
327 It's important to rename the generated `tiboot3.bin` and `sysfw.itb`
328 to match exactly `tiboot3.bin` and `sysfw.itb` as ROM and the wakeup
329 UBoot SPL will only look for and load the files with these names.
330
331Building tispl.bin
Heinrich Schuchardtb72160b2023-10-28 11:59:32 +0200332^^^^^^^^^^^^^^^^^^
Bryan Brattlof6d138132022-12-19 14:29:50 -0600333
334The `tispl.bin` is a standard fitImage combining the firmware need for
335the main domain to function properly as well as Device Management (DM)
336firmware if your device using a split firmware.
337
Neha Malcom Francis507be122023-07-22 00:14:43 +05303382. We will first need TF-A, as it's the first thing to run on the 'big'
Bryan Brattlof6d138132022-12-19 14:29:50 -0600339 application cores on the main domain.
340
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500341.. k3_rst_include_start_build_steps_tfa
Nishanth Menon740c41c2023-11-02 23:40:25 -0500342.. prompt:: bash $
Bryan Brattlof6d138132022-12-19 14:29:50 -0600343
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500344 # inside trusted-firmware-a source
345 make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \
346 TARGET_BOARD=$TFA_BOARD
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500347.. k3_rst_include_end_build_steps_tfa
Bryan Brattlof6d138132022-12-19 14:29:50 -0600348
Neha Malcom Francis507be122023-07-22 00:14:43 +0530349Typically all `j7*` devices will use `TARGET_BOARD=generic` or `TARGET_BOARD
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500350=j784s4` (if it is a J784S4 device), while typical Sitara (`am6*`) devices
Neha Malcom Francis507be122023-07-22 00:14:43 +0530351use the `lite` option.
Bryan Brattlof6d138132022-12-19 14:29:50 -0600352
Neha Malcom Francis507be122023-07-22 00:14:43 +05303533. The Open Portable Trusted Execution Environment (OP-TEE) is designed
Bryan Brattlof6d138132022-12-19 14:29:50 -0600354 to run as a companion to a non-secure Linux kernel for Cortex-A cores
355 using the TrustZone technology built into the core.
356
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500357.. k3_rst_include_start_build_steps_optee
Nishanth Menon740c41c2023-11-02 23:40:25 -0500358.. prompt:: bash $
Bryan Brattlof6d138132022-12-19 14:29:50 -0600359
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500360 # inside optee_os source
361 make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \
362 PLATFORM=$OPTEE_PLATFORM
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500363.. k3_rst_include_end_build_steps_optee
Bryan Brattlof6d138132022-12-19 14:29:50 -0600364
Neha Malcom Francis507be122023-07-22 00:14:43 +05303654. Finally, after TF-A has initialized the main domain and OP-TEE has
Bryan Brattlof6d138132022-12-19 14:29:50 -0600366 finished, we can jump back into U-Boot again, this time running on a
367 64bit core in the main domain.
368
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530369.. _k3_rst_include_start_build_steps_uboot:
370
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500371.. k3_rst_include_start_build_steps_uboot
Nishanth Menon740c41c2023-11-02 23:40:25 -0500372.. prompt:: bash $
Bryan Brattlof6d138132022-12-19 14:29:50 -0600373
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500374 # inside u-boot source
375 make $UBOOT_CFG_CORTEXA
376 make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500377 BL31=$TFA_PATH/build/k3/$TFA_BOARD/release/bl31.bin \
378 TEE=$OPTEE_PATH/out/arm-plat-k3/core/tee-raw.bin
Neha Malcom Francis2b259f02023-12-05 15:12:20 +0530379
380.. note::
381 It is also possible to pick up a custom DM binary by adding TI_DM argument
382 pointing to the file. If not provided, it defaults to picking up the DM
383 binary from BINMAN_INDIRS. This is only applicable to devices that utilize
384 split firmware.
385
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500386.. k3_rst_include_end_build_steps_uboot
Bryan Brattlof6d138132022-12-19 14:29:50 -0600387
388At this point you should have every binary needed initialize both the
389wakeup and main domain and to boot to the U-Boot prompt
390
391**Main Domain Bootloader**
392
Neha Malcom Francis507be122023-07-22 00:14:43 +0530393 | `tispl.bin` for HS devices or `tispl.bin_unsigned` for GP devices
394 | `u-boot.img` for HS devices or `u-boot.img_unsigned` for GP devices
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530395
Jonathan Humphreys43d44fa2024-06-21 15:17:06 -0500396Capsules
397--------
398
399Most K3 boards have support for UEFI capsule update via capsule-on-disk
400functionality. Check the ``CONFIG_EFI_CAPSULE_ON_DISK`` config option for
401the board under question to verify. If configured, capsules for each of the
402binaries above are automatically generated as part of the binary's build.
403They are named `<binary>-capsule.bin`. For example, the capsule for
404`u-boot.img` would be called `uboot-capsule.bin`.
405
406See :ref:`uefi_capsule_update_ref` for more information on U-Boot's support
407for capsule update and how they are applied.
408
409Each board defines the capsules generated, including where those capsules
410are applied. See the ``update_info`` definition for a board, typically
411found at `board/ti/<board>/evm.c`. For example, `board/ti/am62x/evm.c`.
412Usually, if the board has OSPI flash, the capsules will be applied there,
413else the boot partition of the eMMC device.
414
415Once applied, the board will have U-Boot binaries in on-board non-volatile
416storage. To start booting from that storage, set the bootmode pins
417accordingly. Future updates can be performed by using the capsules
418generated from the corresponding U-Boot builds.
419
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530420FIT signature signing
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530421---------------------
422
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530423K3 platforms have FIT signature signing enabled by default on their primary
424platforms. Here we'll take an example for creating FIT Image for J721E platform
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530425and the same can be extended to other platforms
426
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530427Pre-requisites:
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530428
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530429* U-boot build (:ref:`U-boot build <k3_rst_include_start_build_steps_spl_r5>`)
430* Linux Image and Linux DTB prebuilt
431
432Describing FIT source
433^^^^^^^^^^^^^^^^^^^^^
434
435FIT Image is a packed structure containing binary blobs and configurations.
436The Kernel FIT Image that we have has Kernel Image, DTB and the DTBOs. It
437supports packing multiple images and configurations that allow you to
438choose any configuration at runtime to boot from.
439
440.. code-block::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530441
442 /dts-v1/;
443
444 / {
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530445 description = "FIT Image description";
446 #address-cells = <1>;
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530447
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530448 images {
449 [image-1]
450 [image-2]
451 [fdt-1]
452 [fdt-2]
453 }
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530454
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530455 configurations {
456 default = <conf-1>
457 [conf-1: image-1,fdt-1]
458 [conf-2: image-2,fdt-1]
459 }
460 }
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530461
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530462* Sample Images
463
464.. code-block::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530465
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530466 kernel-1 {
467 description = "Linux kernel";
468 data = /incbin/("linux.bin");
469 type = "kernel";
470 arch = "arm64";
471 os = "linux";
472 compression = "gzip";
473 load = <0x81000000>;
474 entry = <0x81000000>;
475 hash-1 {
476 algo = "sha512";
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530477 };
478 };
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530479 fdt-ti_k3-j721e-common-proc-board.dtb {
480 description = "Flattened Device Tree blob";
481 data = /incbin/("arch/arm64/boot/dts/ti/k3-j721e-common-proc-board.dtb");
482 type = "flat_dt";
483 arch = "arm64";
484 compression = "none";
485 load = <0x83000000>;
486 hash-1 {
487 algo = "sha512";
488 };
489 };
490 # Optional images
491 fdt-ti_k3-j721e-evm-virt-mac-client.dtbo {
492 description = "Flattened Device Tree blob";
493 data = /incbin/("arch/arm64/boot/dts/ti/k3-j721e-evm-virt-mac-client.dtbo");
494 type = "flat_dt";
495 arch = "arm64";
496 compression = "none";
497 load = <0x83080000>;
498 hash-1 {
499 algo = "sha512";
500 };
501 };
502
503.. note::
504
505 Change the path in data variables to point to the respective files in your
506 local machine. For e.g change "linux.bin" to "<path-to-kernel-image>".
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530507
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530508For enabling usage of FIT signature, add the signature node to the
509corresponding configuration node as follows.
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530510
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530511* Sample Configurations
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530512
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530513.. code-block::
514
515 conf-ti_k3-j721e-common-proc-board.dtb {
516 description = "Linux kernel, FDT blob";
517 fdt = "fdt-ti_k3-j721e-common-proc-board.dtb";
518 kernel = "kernel-1";
519 signature-1 {
520 algo = "sha512,rsa4096";
521 key-name-hint = "custMpk";
522 sign-images = "kernel", "fdt";
523 };
524 };
525 # Optional configurations
526 conf-ti_k3-j721e-evm-virt-mac-client.dtbo {
527 description = "FDTO blob";
528 fdt = "fdt-ti_k3-j721e-evm-virt-mac-client.dtbo";
529
530 signature-1 {
531 algo = "sha512,rsa4096";
532 key-name-hint = "custMpk";
533 sign-images = "fdt";
534 };
535 };
536
537Specify all images you need the signature to authenticate as a part of
538sign-images. The key-name-hint needs to be changed if you are using some
539other key other than the TI dummy key that we are using for this example.
540It should be the name of the file containing the keys.
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530541
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500542.. note::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530543
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530544 Generating new set of keys:
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530545
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530546 .. prompt:: bash $
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530547
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530548 mkdir keys
549 openssl genpkey -algorithm RSA -out keys/dev.key \
550 -pkeyopt rsa_keygen_bits:4096 -pkeyopt rsa_keygen_pubexp:65537
551 openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530552
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530553Generating the fitImage
554^^^^^^^^^^^^^^^^^^^^^^^
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530555
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530556.. note::
557
558 For signing a secondary platform like SK boards, you'll require
559 additional steps
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530560
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530561 - Change the CONFIG_DEFAULT_DEVICE_TREE
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530562
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530563 For e.g
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530564
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530565 .. code-block::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530566
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530567 diff --git a/configs/j721e_evm_a72_defconfig b/configs/j721e_evm_a72_defconfig
568 index a5c1df7e0054..6d0126d955ef 100644
569 --- a/configs/j721e_evm_a72_defconfig
570 +++ b/configs/j721e_evm_a72_defconfig
571 @@ -13,7 +13,7 @@ CONFIG_CUSTOM_SYS_INIT_SP_ADDR=0x80480000
572 CONFIG_ENV_SIZE=0x20000
573 CONFIG_DM_GPIO=y
574 CONFIG_SPL_DM_SPI=y
575 -CONFIG_DEFAULT_DEVICE_TREE="k3-j721e-common-proc-board"
576 +CONFIG_DEFAULT_DEVICE_TREE="k3-j721e-sk"
577 CONFIG_SPL_TEXT_BASE=0x80080000
578 CONFIG_DM_RESET=y
579 CONFIG_SPL_MMC=y
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530580
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530581 - Change the binman nodes to package u-boot.dtb for the correct set of platform
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530582
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530583 For e.g
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530584
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530585 .. code-block::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530586
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530587 diff --git a/arch/arm/dts/k3-j721e-binman.dtsi b/arch/arm/dts/k3-j721e-binman.dtsi
588 index 673be646b1e3..752fa805fe8d 100644
589 --- a/arch/arm/dts/k3-j721e-binman.dtsi
590 +++ b/arch/arm/dts/k3-j721e-binman.dtsi
591 @@ -299,8 +299,8 @@
592 #define SPL_J721E_SK_DTB "spl/dts/k3-j721e-sk.dtb"
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530593
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530594 #define UBOOT_NODTB "u-boot-nodtb.bin"
595 -#define J721E_EVM_DTB "u-boot.dtb"
596 -#define J721E_SK_DTB "arch/arm/dts/k3-j721e-sk.dtb"
597 +#define J721E_EVM_DTB "arch/arm/dts/k3-j721e-common-proc-board.dtb"
598 +#define J721E_SK_DTB "u-boot.dtb"
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530599
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530600This step will embed the public key in the u-boot.dtb file that was already
601built during the initial u-boot build.
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530602
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530603.. prompt:: bash $
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530604
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530605 mkimage -r -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K $UBOOT_PATH/build/$ARMV8/dts/dt.dtb fitImage
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530606
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530607.. note::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530608
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530609 If you have another set of keys then change the -k argument to point to
610 the folder where your keys are present, the build requires the presence
611 of both .key and .crt file.
612
613Build u-boot again
614^^^^^^^^^^^^^^^^^^
615
616The updated u-boot.dtb needs to be packed in u-boot.img for authentication
617so rebuild U-boot ARMV8 without changing any parameters.
618Refer (:ref:`U-boot ARMV8 build <k3_rst_include_start_build_steps_uboot>`)
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530619
620.. note::
621
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530622 The devices now also have distroboot enabled so if the FIT image doesn't
623 work then the fallback to normal distroboot will be there on HS devices.
624 This will need to be explicitly disabled by changing the boot_targets to
625 disallow fallback during testing.
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530626
627Saving environment
628------------------
629
630SAVEENV is disabled by default and for the new flow uses Uenv.txt as the default
631way for saving the environments. This has been done as Uenv.txt is more granular
632then the saveenv command and can be used across various bootmodes too.
633
634**Writing to MMC/EMMC**
635
Nishanth Menon740c41c2023-11-02 23:40:25 -0500636.. prompt:: bash =>
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530637
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500638 env export -t $loadaddr <list of variables>
639 fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530640
641**Reading from MMC/EMMC**
642
643By default run envboot will read it from the MMC/EMMC partition ( based on
644mmcdev) and set the environments.
645
646If manually needs to be done then the environment can be read from the
647filesystem and then imported
648
Nishanth Menon740c41c2023-11-02 23:40:25 -0500649.. prompt:: bash =>
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530650
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500651 fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
652 env import -t ${loadaddr} ${filesize}
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500653
654.. _k3_rst_refer_openocd:
655
656Common Debugging environment - OpenOCD
657--------------------------------------
658
659This section will show you how to connect a board to `OpenOCD
660<https://openocd.org/>`_ and load the SPL symbols for debugging with
661a K3 generation device. To follow this guide, you must build custom
662u-boot binaries, start your board from a boot media such as an SD
663card, and use an OpenOCD environment. This section uses generic
664examples, though you can apply these instructions to any supported K3
665generation device.
666
667The overall structure of this setup is in the following figure.
668
669.. image:: img/openocd-overview.svg
Nishanth Menon5746e032023-08-22 11:40:56 -0500670 :alt: Overview of OpenOCD setup.
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500671
672.. note::
673
674 If you find these instructions useful, please consider `donating
675 <https://openocd.org/pages/donations.html>`_ to OpenOCD.
676
677Step 1: Download and install OpenOCD
678^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
679
680To get started, it is more convenient if the distribution you
681use supports OpenOCD by default. Follow the instructions in the
682`getting OpenOCD <https://openocd.org/pages/getting-openocd.html>`_
683documentation to pick the installation steps appropriate to your
684environment. Some references to OpenOCD documentation:
685
686* `OpenOCD User Guide <https://openocd.org/doc/html/index.html>`_
687* `OpenOCD Developer's Guide <https://openocd.org/doc/doxygen/html/index.html>`_
688
689Refer to the release notes corresponding to the `OpenOCD version
690<https://github.com/openocd-org/openocd/releases>`_ to ensure
691
692* Processor support: In general, processor support shouldn't present
693 any difficulties since OpenOCD provides solid support for both ARMv8
694 and ARMv7.
695* SoC support: When working with System-on-a-Chip (SoC), the support
696 usually comes as a TCL config file. It is vital to ensure the correct
697 version of OpenOCD or to use the TCL files from the latest release or
698 the one mentioned.
699* Board or the JTAG adapter support: In most cases, board support is
700 a relatively easy problem if the board has a JTAG pin header. All
701 you need to do is ensure that the adapter you select is compatible
702 with OpenOCD. Some boards come with an onboard JTAG adapter that
703 requires a USB cable to be plugged into the board, in which case, it
704 is vital to ensure that the JTAG adapter is supported. Fortunately,
705 almost all TI K3 SK/EVMs come with TI's XDS110, which has out of the
706 box support by OpenOCD. The board-specific documentation will
707 cover the details and any adapter/dongle recommendations.
708
Nishanth Menon740c41c2023-11-02 23:40:25 -0500709.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500710
711 openocd -v
712
713.. note::
714
715 OpenOCD version 0.12.0 is usually required to connect to most K3
716 devices. If your device is only supported by a newer version than the
717 one provided by your distribution, you may need to build it from the source.
718
719Building OpenOCD from source
720""""""""""""""""""""""""""""
721
722The dependency package installation instructions below are for Debian
723systems, but equivalent instructions should exist for systems with
724other package managers. Please refer to the `OpenOCD Documentation
725<https://openocd.org/>`_ for more recent installation steps.
726
Nishanth Menon740c41c2023-11-02 23:40:25 -0500727.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500728
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500729 # Check the packages to be installed: needs deb-src in sources.list
730 sudo apt build-dep openocd
731 # The following list is NOT complete - please check the latest
732 sudo apt-get install libtool pkg-config texinfo libusb-dev \
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500733 libusb-1.0.0-dev libftdi-dev libhidapi-dev autoconf automake
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500734 git clone https://github.com/openocd-org/openocd.git openocd
735 cd openocd
736 git submodule init
737 git submodule update
738 ./bootstrap
739 ./configure --prefix=/usr/local/
740 make -j`nproc`
741 sudo make install
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500742
743.. note::
744
745 The example above uses the GitHub mirror site. See
746 `git repo information <https://openocd.org/doc/html/Developers.html#OpenOCD-Git-Repository>`_
747 information to pick the official git repo.
748 If a specific version is desired, select the version using `git checkout tag`.
749
750Installing OpenOCD udev rules
751"""""""""""""""""""""""""""""
752
753The step is not necessary if the distribution supports the OpenOCD, but
754if building from a source, ensure that the udev rules are installed
755correctly to ensure a sane system.
756
Nishanth Menon740c41c2023-11-02 23:40:25 -0500757.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500758
759 # Go to the OpenOCD source directory
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500760 cd openocd
761 Copy the udev rules to the correct system location
762 sudo cp ./contrib/60-openocd.rules \
Jonathan Humphreys27fd4982023-08-22 13:49:03 -0500763 ./src/jtag/drivers/libjaylink/contrib/99-libjaylink.rules \
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500764 /etc/udev/rules.d/
765 # Get Udev to load the new rules up
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500766 sudo udevadm control --reload-rules
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500767 # Use the new rules on existing connected devices
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500768 sudo udevadm trigger
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500769
770Step 2: Setup GDB
771^^^^^^^^^^^^^^^^^
772
773Most systems come with gdb-multiarch package.
774
Nishanth Menon740c41c2023-11-02 23:40:25 -0500775.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500776
777 # Install gdb-multiarch package
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500778 sudo apt-get install gdb-multiarch
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500779
780Though using GDB natively is normal, developers with interest in using IDE
781may find a few of these interesting:
782
783* `gdb-dashboard <https://github.com/cyrus-and/gdb-dashboard>`_
784* `gef <https://github.com/hugsy/gef>`_
785* `peda <https://github.com/longld/peda>`_
786* `pwndbg <https://github.com/pwndbg/pwndbg>`_
787* `voltron <https://github.com/snare/voltron>`_
788* `ddd <https://www.gnu.org/software/ddd/>`_
789* `vscode <https://www.justinmklam.com/posts/2017/10/vscode-debugger-setup/>`_
790* `vim conque-gdb <https://github.com/vim-scripts/Conque-GDB>`_
791* `emacs realgud <https://github.com/realgud/realgud/wiki/gdb-notes>`_
792* `Lauterbach IDE <https://www2.lauterbach.com/pdf/backend_gdb.pdf>`_
793
794.. warning::
795 LLDB support for OpenOCD is still a work in progress as of this writing.
796 Using GDB is probably the safest option at this point in time.
797
798Step 3: Connect board to PC
799^^^^^^^^^^^^^^^^^^^^^^^^^^^
800There are few patterns of boards in the ecosystem
801
802.. k3_rst_include_start_openocd_connect_XDS110
803
804**Integrated JTAG adapter/dongle**: The board has a micro-USB connector labelled
805XDS110 USB or JTAG. Connect a USB cable to the board to the mentioned port.
806
807.. note::
808
809 There are multiple USB ports on a typical board, So, ensure you have read
810 the user guide for the board and confirmed the silk screen label to ensure
811 connecting to the correct port.
812
813.. k3_rst_include_end_openocd_connect_XDS110
814
815.. k3_rst_include_start_openocd_connect_cti20
816
817**cTI20 connector**: The TI's `cTI20
818<https://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_JTAG_connectors.html#cti-20-pin-header-information>`_ connector
819is probably the most prevelant on TI platforms. Though many
820TI boards have an onboard XDS110, cTI20 connector is usually
821provided as an alternate scheme to connect alternatives such
822as `Lauterbach <https://www.lauterbach.com/>`_ or `XDS560
823<https://www.ti.com/tool/TMDSEMU560V2STM-U>`_.
824
825To debug on these boards, the following combinations is suggested:
826
827* `TUMPA <https://www.diygadget.com/JTAG-cables-and-microcontroller-programmers/tiao-usb-multi-protocol-adapter-JTAG-spi-i2c-serial>`_
828 or `equivalent dongles supported by OpenOCD. <https://openocd.org/doc/html/Debug-Adapter-Hardware.html#Debug-Adapter-Hardware>`_
829* Cable such as `Tag-connect ribbon cable <https://www.tag-connect.com/product/20-pin-cortex-ribbon-cable-4-length-with-50-mil-connectors>`_
830* Adapter to convert cTI20 to ARM20 such as those from
831 `Segger <https://www.segger.com/products/debug-probes/j-link/accessories/adapters/ti-cti-20-adapter/>`_
832 or `Lauterbach LA-3780 <https://www.lauterbach.com/ad3780.html>`_
833 Or optionally, if you have manufacturing capability then you could try
834 `BeagleBone JTAG Adapter <https://github.com/mmorawiec/BeagleBone-Black-JTAG-Adapters>`_
835
836.. warning::
837 XDS560 and Lauterbach are proprietary solutions and is not supported by
838 OpenOCD.
839 When purchasing an off the shelf adapter/dongle, you do want to be careful
840 about the signalling though. Please
841 `read for additional info <https://software-dl.ti.com/ccs/esd/xdsdebugprobes/emu_JTAG_connectors.html>`_.
842
843.. k3_rst_include_end_openocd_connect_cti20
844
845.. k3_rst_include_start_openocd_connect_tag_connect
846
847**Tag-Connect**: `Tag-Connect <https://www.tag-connect.com/>`_
848pads on the boards which require special cable. Please check the documentation
849to `identify <https://www.tag-connect.com/info/legs-or-no-legs>`_ if "legged"
850or "no-leg" version of the cable is appropriate for the board.
851
852To debug on these boards, you will need:
853
854* `TUMPA <https://www.diygadget.com/JTAG-cables-and-microcontroller-programmers/tiao-usb-multi-protocol-adapter-JTAG-spi-i2c-serial>`_
855 or `equivalent dongles supported by OpenOCD <https://openocd.org/doc/html/Debug-Adapter-Hardware.html#Debug-Adapter-Hardware>`_.
856* Tag-Connect cable appropriate to the board such as
857 `TC2050-IDC-NL <https://www.tag-connect.com/product/TC2050-IDC-NL-10-pin-no-legs-cable-with-ribbon-connector>`_
858* In case of no-leg, version, a
859 `retaining clip <https://www.tag-connect.com/product/tc2050-clip-3pack-retaining-clip>`_
860* Tag-Connect to ARM20
861 `adapter <https://www.tag-connect.com/product/tc2050-arm2010-arm-20-pin-to-tc2050-adapter>`_
862
863.. note::
864 You can optionally use a 3d printed solution such as
865 `Protective cap <https://www.thingiverse.com/thing:3025584>`_ or
866 `clip <https://www.thingiverse.com/thing:3035278>`_ to replace
867 the retaining clip.
868
869.. warning::
870 With the Tag-Connect to ARM20 adapter, Please solder the "Trst" signal for
871 connection to work.
872
873.. k3_rst_include_end_openocd_connect_tag_connect
874
875Debugging with OpenOCD
876^^^^^^^^^^^^^^^^^^^^^^
877
878Debugging U-Boot is different from debugging regular user space
879applications. The bootloader initialization process involves many boot
880media and hardware configuration operations. For K3 devices, there
881are also interactions with security firmware. While reloading the
882"elf" file works through GDB, developers must be mindful of cascading
883initialization's potential consequences.
884
885Consider the following code change:
886
887.. code-block:: diff
888
889 --- a/file.c 2023-07-29 10:55:29.647928811 -0500
890 +++ b/file.c 2023-07-29 10:55:46.091856816 -0500
891 @@ -1,3 +1,3 @@
892 val = readl(reg);
893 -val |= 0x2;
894 +val |= 0x1;
895 writel(val, reg);
896
897Re-running the elf file with the above change will result in the
898register setting 0x3 instead of the intended 0x1. There are other
899hardware blocks which may not behave very well with a re-initialization
900without proper shutdown.
901
902To help narrow the debug down, it is usually simpler to use the
903standard boot media to get to the bootloader and debug only in the area
904of interest.
905
906In general, to debug u-boot spl/u-boot with OpenOCD there are three steps:
907
908* Modify the code adding a loop to allow the debugger to attach
909 near the point of interest. Boot up normally to stop at the loop.
910* Connect with OpenOCD and step out of the loop.
911* Step through the code to find the root of issue.
912
913Typical debugging involves a few iterations of the above sequence.
914Though most bootloader developers like to use printf to debug,
915debug with JTAG tends to be most efficient since it is possible to
916investigate the code flow and inspect hardware registers without
917repeated iterations.
918
919Code modification
920"""""""""""""""""
921
922* **start.S**: Adding an infinite while loop at the very entry of
923 U-Boot. For this, look for the corresponding start.S entry file.
924 This is usually only required when debugging some core SoC or
925 processor related function. For example: arch/arm/cpu/armv8/start.S or
926 arch/arm/cpu/armv7/start.S
927
928.. code-block:: diff
929
930 diff --git a/arch/arm/cpu/armv7/start.S b/arch/arm/cpu/armv7/start.S
931 index 69e281b086..744929e825 100644
932 --- a/arch/arm/cpu/armv7/start.S
933 +++ b/arch/arm/cpu/armv7/start.S
934 @@ -37,6 +37,8 @@
935 #endif
936
937 reset:
938 +dead_loop:
939 + b dead_loop
940 /* Allow the board to save important registers */
941 b save_boot_params
942 save_boot_params_ret:
943
944* **board_init_f**: Adding an infinite while loop at the board entry
945 function. In many cases, it is important to debug the boot process if
946 any changes are made for board-specific applications. Below is a step
947 by step process for debugging the boot SPL or Armv8 SPL:
948
949 To debug the boot process in either domain, we will first
950 add a modification to the code we would like to debug.
951 In this example, we will debug ``board_init_f`` inside
952 ``arch/arm/mach-k3/{soc}_init.c``. Since some sections of U-Boot
953 will be executed multiple times during the bootup process of K3
Jonathan Humphreys27fd4982023-08-22 13:49:03 -0500954 devices, we will need to include either ``CONFIG_ARM64`` or
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500955 ``CONFIG_CPU_V7R`` to catch the CPU at the desired place during the
956 bootup process (Main or Wakeup domains). For example, modify the
957 file as follows (depending on need):
958
959.. code-block:: c
960
961 void board_init_f(ulong dummy)
962 {
963 .
964 .
965 /* Code to run on the R5F (Wakeup/Boot Domain) */
966 if (IS_ENABLED(CONFIG_CPU_V7R)) {
967 volatile int x = 1;
968 while(x) {};
969 }
970 ...
971 /* Code to run on the ARMV8 (Main Domain) */
Jonathan Humphreys27fd4982023-08-22 13:49:03 -0500972 if (IS_ENABLED(CONFIG_ARM64)) {
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500973 volatile int x = 1;
974 while(x) {};
975 }
976 .
977 .
978 }
979
980Connecting with OpenOCD for a debug session
981"""""""""""""""""""""""""""""""""""""""""""
982
983Startup OpenOCD to debug the platform as follows:
984
985* **Integrated JTAG interface**: If the evm has a debugger such as
986 XDS110 inbuilt, there is typically an evm board support added and a
987 cfg file will be available.
988
989.. k3_rst_include_start_openocd_cfg_XDS110
990
Nishanth Menon740c41c2023-11-02 23:40:25 -0500991.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500992
993 openocd -f board/{board_of_choice}.cfg
994
995.. k3_rst_include_end_openocd_cfg_XDS110
996
997.. k3_rst_include_start_openocd_cfg_external_intro
998
999* **External JTAG adapter/interface**: In other cases, where an
1000 adapter/dongle is used, a simple cfg file can be created to integrate the
1001 SoC and adapter information. See `supported TI K3 SoCs
1002 <https://github.com/openocd-org/openocd/blob/master/tcl/target/ti_k3.cfg#L59>`_
1003 to decide if the SoC is supported or not.
1004
Nishanth Menon740c41c2023-11-02 23:40:25 -05001005.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001006
1007 openocd -f openocd_connect.cfg
1008
1009.. k3_rst_include_end_openocd_cfg_external_intro
1010
1011 For example, with BeaglePlay (AM62X platform), the openocd_connect.cfg:
1012
1013.. code-block:: tcl
1014
1015 # TUMPA example:
1016 # http://www.tiaowiki.com/w/TIAO_USB_Multi_Protocol_Adapter_User's_Manual
1017 source [find interface/ftdi/tumpa.cfg]
1018
1019 transport select jtag
1020
1021 # default JTAG configuration has only SRST and no TRST
1022 reset_config srst_only srst_push_pull
1023
1024 # delay after SRST goes inactive
1025 adapter srst delay 20
1026
1027 if { ![info exists SOC] } {
1028 # Set the SoC of interest
1029 set SOC am625
1030 }
1031
1032 source [find target/ti_k3.cfg]
1033
1034 ftdi tdo_sample_edge falling
1035
1036 # Speeds for FT2232H are in multiples of 2, and 32MHz is tops
1037 # max speed we seem to achieve is ~20MHz.. so we pick 16MHz
1038 adapter speed 16000
1039
1040Below is an example of the output of this command:
1041
1042.. code-block:: console
1043
1044 Info : Listening on port 6666 for tcl connections
1045 Info : Listening on port 4444 for telnet connections
1046 Info : XDS110: connected
1047 Info : XDS110: vid/pid = 0451/bef3
1048 Info : XDS110: firmware version = 3.0.0.20
1049 Info : XDS110: hardware version = 0x002f
1050 Info : XDS110: connected to target via JTAG
1051 Info : XDS110: TCK set to 2500 kHz
1052 Info : clock speed 2500 kHz
1053 Info : JTAG tap: am625.cpu tap/device found: 0x0bb7e02f (mfg: 0x017 (Texas Instruments), part: 0xbb7e, ver: 0x0)
1054 Info : starting gdb server for am625.cpu.sysctrl on 3333
1055 Info : Listening on port 3333 for gdb connections
1056 Info : starting gdb server for am625.cpu.a53.0 on 3334
1057 Info : Listening on port 3334 for gdb connections
1058 Info : starting gdb server for am625.cpu.a53.1 on 3335
1059 Info : Listening on port 3335 for gdb connections
1060 Info : starting gdb server for am625.cpu.a53.2 on 3336
1061 Info : Listening on port 3336 for gdb connections
1062 Info : starting gdb server for am625.cpu.a53.3 on 3337
1063 Info : Listening on port 3337 for gdb connections
1064 Info : starting gdb server for am625.cpu.main0_r5.0 on 3338
1065 Info : Listening on port 3338 for gdb connections
1066 Info : starting gdb server for am625.cpu.gp_mcu on 3339
1067 Info : Listening on port 3339 for gdb connections
1068
1069.. note::
1070 Notice the default configuration is non-SMP configuration allowing
1071 for each of the core to be attached and debugged simultaneously.
1072 ARMv8 SPL/U-Boot starts up on cpu0 of a53/a72.
1073
1074.. k3_rst_include_start_openocd_cfg_external_gdb
1075
1076To debug using this server, use GDB directly or your preferred
1077GDB-based IDE. To start up GDB in the terminal, run the following
1078command.
1079
Nishanth Menon740c41c2023-11-02 23:40:25 -05001080.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001081
1082 gdb-multiarch
1083
1084To connect to your desired core, run the following command within GDB:
1085
Nishanth Menon740c41c2023-11-02 23:40:25 -05001086.. prompt:: bash (gdb)
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001087
1088 target extended-remote localhost:{port for desired core}
1089
1090To load symbols:
1091
1092.. warning::
1093
1094 SPL and U-Boot does a re-location of address compared to where it
1095 is loaded originally. This step takes place after the DDR size is
1096 determined from dt parsing. So, debugging can be split into either
1097 "before re-location" or "after re-location". Please refer to the
1098 file ''doc/README.arm-relocation'' to see how to grab the relocation
1099 address.
1100
1101* Prior to relocation:
1102
Nishanth Menon740c41c2023-11-02 23:40:25 -05001103.. prompt:: bash (gdb)
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001104
1105 symbol-file {path to elf file}
1106
1107* After relocation:
1108
Nishanth Menon740c41c2023-11-02 23:40:25 -05001109.. prompt:: bash (gdb)
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001110
1111 # Drop old symbol file
1112 symbol-file
1113 # Pick up new relocaddr
1114 add-symbol-file {path to elf file} {relocaddr}
1115
1116.. k3_rst_include_end_openocd_cfg_external_gdb
1117
1118In the above example of AM625,
1119
Nishanth Menon740c41c2023-11-02 23:40:25 -05001120.. prompt:: bash (gdb)
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001121
1122 target extended-remote localhost:3338 <- R5F (Wakeup Domain)
1123 target extended-remote localhost:3334 <- A53 (Main Domain)
1124
1125The core can now be debugged directly within GDB using GDB commands or
1126if using IDE, as appropriate to the IDE.
1127
1128Stepping through the code
1129"""""""""""""""""""""""""
1130
1131`GDB TUI Commands
1132<https://sourceware.org/gdb/onlinedocs/gdb/TUI-Commands.html>`_ can
1133help set up the display more sensible for debug. Provide the name
1134of the layout that can be used to debug. For example, use the GDB
1135command ``layout src`` after loading the symbols to see the code and
1136breakpoints. To exit the debug loop added above, add any breakpoints
1137needed and run the following GDB commands to step out of the debug
1138loop set in the ``board_init_f`` function.
1139
Nishanth Menon740c41c2023-11-02 23:40:25 -05001140.. prompt:: bash (gdb)
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001141
1142 set x = 0
1143 continue
1144
1145The platform has now been successfully setup to debug with OpenOCD
1146using GDB commands or a GDB-based IDE. See `OpenOCD documentation for
1147GDB <https://openocd.org/doc/html/GDB-and-OpenOCD.html>`_ for further
1148information.
1149
1150.. warning::
1151
1152 On the K3 family of devices, a watchdog timer within the DMSC is
1153 enabled by default by the ROM bootcode with a timeout of 3 minutes.
1154 The watchdog timer is serviced by System Firmware (SYSFW) or TI
1155 Foundational Security (TIFS) during normal operation. If debugging
1156 the SPL before the SYSFW is loaded, the watchdog timer will not get
1157 serviced automatically and the debug session will reset after 3
1158 minutes. It is recommended to start debugging SPL code only after
1159 the startup of SYSFW to avoid running into the watchdog timer reset.
1160
1161Miscellaneous notes with OpenOCD
1162^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1163
1164Currently, OpenOCD does not support tracing for K3 platforms. Tracing
1165function could be beneficial if the bug in code occurs deep within
1166nested function and can optionally save developers major trouble of
1167stepping through a large quantity of code.