blob: 15e1ed232bf094e36d30941e684b0b6dd2d65efd [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
Roger Quadroscd87b1e2023-08-05 11:14:39 +030038 am64x_evm
Neha Malcom Francis507be122023-07-22 00:14:43 +053039 am65x_evm
Nishanth Menone83fe672023-07-27 13:59:01 -050040 j7200_evm
Nishanth Menon756b8782023-11-04 03:11:03 -050041 ../beagle/j721e_beagleboneai64
Nishanth Menone83fe672023-07-27 13:59:01 -050042 j721e_evm
Manorit Chawdhry670a22b2023-10-06 10:16:00 +053043 j721s2_evm
Apurva Nandan2b1c9ff2024-02-24 01:51:53 +053044 j784s4_evm
Bryan Brattlof6d138132022-12-19 14:29:50 -060045
46Boot Flow Overview
47------------------
48
49For all K3 SoCs the first core started will be inside the Security
50Management Subsystem (SMS) which will secure the device and start a core
51in the wakeup domain to run the ROM code. ROM will then initialize the
52boot media needed to load the binaries packaged inside `tiboot3.bin`,
53including a 32bit U-Boot SPL, (called the wakup SPL) that ROM will jump
54to after it has finished loading everything into internal SRAM.
55
Nishanth Menon7bdb2d52023-07-27 13:59:02 -050056.. image:: img/boot_flow_01.svg
Heinrich Schuchardtd0894b22023-08-22 11:40:55 -050057 :alt: Boot flow up to wakeup domain SPL
Bryan Brattlof6d138132022-12-19 14:29:50 -060058
59The wakeup SPL, running on a wakeup domain core, will initialize DDR and
60any peripherals needed load the larger binaries inside the `tispl.bin`
61into DDR. Once loaded the wakeup SPL will start one of the 'big'
62application cores inside the main domain to initialize the main domain,
Neha Malcom Francis507be122023-07-22 00:14:43 +053063starting with Trusted Firmware-A (TF-A), before moving on to start
64OP-TEE and the main domain's U-Boot SPL.
Bryan Brattlof6d138132022-12-19 14:29:50 -060065
Nishanth Menon7bdb2d52023-07-27 13:59:02 -050066.. image:: img/boot_flow_02.svg
Heinrich Schuchardtd0894b22023-08-22 11:40:55 -050067 :alt: Boot flow up to main domain SPL
Bryan Brattlof6d138132022-12-19 14:29:50 -060068
69The main domain's SPL, running on a 64bit application core, has
70virtually unlimited space (billions of bytes now that DDR is working) to
71initialize even more peripherals needed to load in the `u-boot.img`
72which loads more firmware into the micro-controller & wakeup domains and
73finally prepare the main domain to run Linux.
74
Nishanth Menon7bdb2d52023-07-27 13:59:02 -050075.. image:: img/boot_flow_03.svg
Heinrich Schuchardtd0894b22023-08-22 11:40:55 -050076 :alt: Complete boot flow up to Linux
Bryan Brattlof6d138132022-12-19 14:29:50 -060077
78This is the typical boot flow for all K3 based SoCs, however this flow
79offers quite a lot in the terms of flexibility, especially on High
80Security (HS) SoCs.
81
82Boot Flow Variations
83^^^^^^^^^^^^^^^^^^^^
84
85All K3 SoCs will generally use the above boot flow with two main
86differences depending on the capabilities of the boot ROM and the number
87of cores inside the device. These differences split the bootflow into
88essentially 4 unique but very similar flows:
89
90* Split binary with a combined firmware: (eg: AM65)
91* Combined binary with a combined firmware: (eg: AM64)
92* Split binary with a split firmware: (eg: J721E)
93* Combined binary with a split firmware: (eg: AM62)
94
95For devices that utilize the split binary approach, ROM is not capable
96of loading the firmware into the SoC requiring the wakeup domain's
97U-Boot SPL to load the firmware.
98
99Devices with a split firmware will have two firmwares loaded into the
100device at different times during the bootup process. TI's Foundational
101Security (TIFS), needed to operate the Security Management Subsystem,
102will either be loaded by ROM or the WKUP U-Boot SPL, then once the
103wakeup U-Boot SPL has completed, the second Device Management (DM)
104firmware can be loaded on the now free core in the wakeup domain.
105
106For more information on the bootup process of your SoC, consult the
107device specific boot flow documentation.
108
Manorit Chawdhry98346472023-12-29 16:16:33 +0530109Secure Boot
110-----------
111
112K3 HS-SE (High Security - Security Enforced) devices enforce an
113authenticated boot flow for secure boot. HS-FS (High Security - Field
114Securable) is the state of a K3 device before it has been eFused with
115customer security keys. In the HS-FS state the authentication still can
116function as in HS-SE but as there are no customer keys to verify the
117signatures against the authentication will pass for certificates signed
118with any key.
119
120Chain of trust
121^^^^^^^^^^^^^^
122
1231) Public ROM loads the tiboot3.bin (R5 SPL, TIFS)
1242) R5 SPL loads tispl.bin (ATF, OP-TEE, DM, SPL)
1253) SPL loads u-boot.img (U-Boot)
1264) U-Boot loads fitImage (Linux and DTBs)
127
128Steps 1-3 are all authenticated by either the Secure ROM or TIFS as the
129authenticating entity and step 4 uses U-boot standard mechanism for
130authenticating.
131
132All the authentication that are done for ROM/TIFS are done through x509
133certificates that are signed.
134
135Firewalls
136^^^^^^^^^
137
1381) Secure ROM comes up and sets up firewalls that are needed by itself
1392) TIFS will setup it's own firewalls to protect core system resources
1403) R5 SPL will remove any firewalls that are leftover from the Secure ROM stage
141 that are no longer required.
1424) Each stage beyond this: such as tispl.bin containing TFA/OPTEE uses OIDs to
143 set up firewalls to protect themselves (enforced by TIFS)
1445) TFA/OP-TEE can configure other firewalls at runtime if required as they
145 are already authenticated and firewalled off from illegal access.
1466) All later stages can setup or remove firewalls that have not been already
147 configured by previous stages, such as those created by TIFS, TFA, and OP-TEE.
148
149Futhur, firewalls have a lockdown bit in hardware that enforces the setting
150(and cannot be over-ridden) until the full system is reset.
151
Bryan Brattlof6d138132022-12-19 14:29:50 -0600152Software Sources
153----------------
154
155All scripts and code needed to build the `tiboot3.bin`, `tispl.bin` and
156`u-boot.img` for all K3 SoCs can be located at the following places
157online
158
Nishanth Menonee91e482023-07-27 13:58:44 -0500159.. k3_rst_include_start_boot_sources
160
Bryan Brattlof6d138132022-12-19 14:29:50 -0600161* **Das U-Boot**
162
163 | **source:** https://source.denx.de/u-boot/u-boot.git
164 | **branch:** master
165
Neha Malcom Francis507be122023-07-22 00:14:43 +0530166* **Trusted Firmware-A (TF-A)**
Bryan Brattlof6d138132022-12-19 14:29:50 -0600167
Neha Malcom Francis507be122023-07-22 00:14:43 +0530168 | **source:** https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/
Bryan Brattlof6d138132022-12-19 14:29:50 -0600169 | **branch:** master
170
Neha Malcom Francis507be122023-07-22 00:14:43 +0530171* **Open Portable Trusted Execution Environment (OP-TEE)**
Bryan Brattlof6d138132022-12-19 14:29:50 -0600172
173 | **source:** https://github.com/OP-TEE/optee_os.git
174 | **branch:** master
175
Nishanth Menone2a47452023-08-22 11:41:07 -0500176* **TI Firmware (TIFS, DM, SYSFW)**
Bryan Brattlof6d138132022-12-19 14:29:50 -0600177
178 | **source:** https://git.ti.com/git/processor-firmware/ti-linux-firmware.git
179 | **branch:** ti-linux-firmware
180
Nishanth Menone2a47452023-08-22 11:41:07 -0500181.. note::
182
183 The TI Firmware required for functionality of the system can be
184 one of the following combination (see platform specific boot diagram for
185 further information as to which component runs on which processor):
186
187 * **TIFS** - TI Foundational Security Firmware - Consists of purely firmware
188 meant to run on the security enclave.
189 * **DM** - Device Management firmware also called TI System Control Interface
190 server (TISCI Server) - This component purely plays the role of managing
191 device resources such as power, clock, interrupts, dma etc. This firmware
192 runs on a dedicated or multi-use microcontroller outside the security
193 enclave.
194
195 OR
196
197 * **SYSFW** - System firmware - consists of both TIFS and DM both running on
198 the security enclave.
199
Nishanth Menonee91e482023-07-27 13:58:44 -0500200.. k3_rst_include_end_boot_sources
201
Bryan Brattlof6d138132022-12-19 14:29:50 -0600202Build Procedure
203---------------
204
205Depending on the specifics of your device, you will need three or more
206binaries to boot your SoC.
207
208* `tiboot3.bin` (bootloader for the wakeup domain)
209* `tispl.bin` (bootloader for the main domain)
210* `u-boot.img`
211
212During the bootup process, both the 32bit wakeup domain and the 64bit
213main domains will be involved. This means everything inside the
214`tiboot3.bin` running in the wakeup domain will need to be compiled for
21532bit cores and most binaries in the `tispl.bin` will need to be
216compiled for 64bit main domain CPU cores.
217
218All of that to say you will need both a 32bit and 64bit cross compiler
219(assuming you're using an x86 desktop)
220
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500221.. k3_rst_include_start_common_env_vars_desc
222.. list-table:: Generic environment variables
223 :widths: 25 25 50
224 :header-rows: 1
225
226 * - S/w Component
227 - Env Variable
228 - Description
229 * - All Software
230 - CC32
231 - Cross compiler for ARMv7 (ARM 32bit), typically arm-linux-gnueabihf-
232 * - All Software
233 - CC64
234 - Cross compiler for ARMv8 (ARM 64bit), typically aarch64-linux-gnu-
235 * - All Software
236 - LNX_FW_PATH
237 - Path to TI Linux firmware repository
238 * - All Software
239 - TFA_PATH
240 - Path to source of Trusted Firmware-A
241 * - All Software
242 - OPTEE_PATH
243 - Path to source of OP-TEE
244.. k3_rst_include_end_common_env_vars_desc
245
246.. k3_rst_include_start_common_env_vars_defn
Nishanth Menon740c41c2023-11-02 23:40:25 -0500247.. prompt:: bash $
Bryan Brattlof6d138132022-12-19 14:29:50 -0600248
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500249 export CC32=arm-linux-gnueabihf-
250 export CC64=aarch64-linux-gnu-
251 export LNX_FW_PATH=path/to/ti-linux-firmware
252 export TFA_PATH=path/to/trusted-firmware-a
253 export OPTEE_PATH=path/to/optee_os
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500254.. k3_rst_include_end_common_env_vars_defn
255
256We will also need some common environment variables set up for the various
257other build sources. we shall use the following, in the build descriptions below:
258
259.. k3_rst_include_start_board_env_vars_desc
260.. list-table:: Board specific environment variables
261 :widths: 25 25 50
262 :header-rows: 1
263
264 * - S/w Component
265 - Env Variable
266 - Description
267 * - U-Boot
268 - UBOOT_CFG_CORTEXR
269 - Defconfig for Cortex-R (Boot processor).
270 * - U-Boot
271 - UBOOT_CFG_CORTEXA
272 - Defconfig for Cortex-A (MPU processor).
273 * - Trusted Firmware-A
274 - TFA_BOARD
275 - Platform name used for building TF-A for Cortex-A Processor.
276 * - Trusted Firmware-A
277 - TFA_EXTRA_ARGS
278 - Any extra arguments used for building TF-A.
279 * - OP-TEE
280 - OPTEE_PLATFORM
281 - Platform name used for building OP-TEE for Cortex-A Processor.
282 * - OP-TEE
283 - OPTEE_EXTRA_ARGS
284 - Any extra arguments used for building OP-TEE.
285.. k3_rst_include_end_board_env_vars_desc
Bryan Brattlof6d138132022-12-19 14:29:50 -0600286
287Building tiboot3.bin
Heinrich Schuchardtb72160b2023-10-28 11:59:32 +0200288^^^^^^^^^^^^^^^^^^^^
Bryan Brattlof6d138132022-12-19 14:29:50 -0600289
2901. To generate the U-Boot SPL for the wakeup domain, use the following
291 commands, substituting :code:`{SOC}` for the name of your device (eg:
Neha Malcom Francis507be122023-07-22 00:14:43 +0530292 am62x) to package the various firmware and the wakeup UBoot SPL into
293 the final `tiboot3.bin` binary. (or the `sysfw.itb` if your device
294 uses the split binary flow)
Bryan Brattlof6d138132022-12-19 14:29:50 -0600295
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530296.. _k3_rst_include_start_build_steps_spl_r5:
297
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500298.. k3_rst_include_start_build_steps_spl_r5
Nishanth Menon740c41c2023-11-02 23:40:25 -0500299.. prompt:: bash $
Bryan Brattlof6d138132022-12-19 14:29:50 -0600300
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500301 # inside u-boot source
302 make $UBOOT_CFG_CORTEXR
303 make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500304.. k3_rst_include_end_build_steps_spl_r5
Bryan Brattlof6d138132022-12-19 14:29:50 -0600305
306At this point you should have all the needed binaries to boot the wakeup
307domain of your K3 SoC.
308
309**Combined Binary Boot Flow** (eg: am62x, am64x, ... )
310
Neha Malcom Francis507be122023-07-22 00:14:43 +0530311 `tiboot3-{SOC}-{gp/hs-fs/hs}.bin`
Bryan Brattlof6d138132022-12-19 14:29:50 -0600312
313**Split Binary Boot Flow** (eg: j721e, am65x)
314
Neha Malcom Francis507be122023-07-22 00:14:43 +0530315 | `tiboot3-{SOC}-{gp/hs-fs/hs}.bin`
316 | `sysfw-{SOC}-{gp/hs-fs/hs}-evm.itb`
Bryan Brattlof6d138132022-12-19 14:29:50 -0600317
318.. note ::
319
320 It's important to rename the generated `tiboot3.bin` and `sysfw.itb`
321 to match exactly `tiboot3.bin` and `sysfw.itb` as ROM and the wakeup
322 UBoot SPL will only look for and load the files with these names.
323
324Building tispl.bin
Heinrich Schuchardtb72160b2023-10-28 11:59:32 +0200325^^^^^^^^^^^^^^^^^^
Bryan Brattlof6d138132022-12-19 14:29:50 -0600326
327The `tispl.bin` is a standard fitImage combining the firmware need for
328the main domain to function properly as well as Device Management (DM)
329firmware if your device using a split firmware.
330
Neha Malcom Francis507be122023-07-22 00:14:43 +05303312. We will first need TF-A, as it's the first thing to run on the 'big'
Bryan Brattlof6d138132022-12-19 14:29:50 -0600332 application cores on the main domain.
333
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500334.. k3_rst_include_start_build_steps_tfa
Nishanth Menon740c41c2023-11-02 23:40:25 -0500335.. prompt:: bash $
Bryan Brattlof6d138132022-12-19 14:29:50 -0600336
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500337 # inside trusted-firmware-a source
338 make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \
339 TARGET_BOARD=$TFA_BOARD
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500340.. k3_rst_include_end_build_steps_tfa
Bryan Brattlof6d138132022-12-19 14:29:50 -0600341
Neha Malcom Francis507be122023-07-22 00:14:43 +0530342Typically all `j7*` devices will use `TARGET_BOARD=generic` or `TARGET_BOARD
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500343=j784s4` (if it is a J784S4 device), while typical Sitara (`am6*`) devices
Neha Malcom Francis507be122023-07-22 00:14:43 +0530344use the `lite` option.
Bryan Brattlof6d138132022-12-19 14:29:50 -0600345
Neha Malcom Francis507be122023-07-22 00:14:43 +05303463. The Open Portable Trusted Execution Environment (OP-TEE) is designed
Bryan Brattlof6d138132022-12-19 14:29:50 -0600347 to run as a companion to a non-secure Linux kernel for Cortex-A cores
348 using the TrustZone technology built into the core.
349
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500350.. k3_rst_include_start_build_steps_optee
Nishanth Menon740c41c2023-11-02 23:40:25 -0500351.. prompt:: bash $
Bryan Brattlof6d138132022-12-19 14:29:50 -0600352
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500353 # inside optee_os source
354 make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \
355 PLATFORM=$OPTEE_PLATFORM
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500356.. k3_rst_include_end_build_steps_optee
Bryan Brattlof6d138132022-12-19 14:29:50 -0600357
Neha Malcom Francis507be122023-07-22 00:14:43 +05303584. Finally, after TF-A has initialized the main domain and OP-TEE has
Bryan Brattlof6d138132022-12-19 14:29:50 -0600359 finished, we can jump back into U-Boot again, this time running on a
360 64bit core in the main domain.
361
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530362.. _k3_rst_include_start_build_steps_uboot:
363
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500364.. k3_rst_include_start_build_steps_uboot
Nishanth Menon740c41c2023-11-02 23:40:25 -0500365.. prompt:: bash $
Bryan Brattlof6d138132022-12-19 14:29:50 -0600366
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500367 # inside u-boot source
368 make $UBOOT_CFG_CORTEXA
369 make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500370 BL31=$TFA_PATH/build/k3/$TFA_BOARD/release/bl31.bin \
371 TEE=$OPTEE_PATH/out/arm-plat-k3/core/tee-raw.bin
Neha Malcom Francis2b259f02023-12-05 15:12:20 +0530372
373.. note::
374 It is also possible to pick up a custom DM binary by adding TI_DM argument
375 pointing to the file. If not provided, it defaults to picking up the DM
376 binary from BINMAN_INDIRS. This is only applicable to devices that utilize
377 split firmware.
378
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500379.. k3_rst_include_end_build_steps_uboot
Bryan Brattlof6d138132022-12-19 14:29:50 -0600380
381At this point you should have every binary needed initialize both the
382wakeup and main domain and to boot to the U-Boot prompt
383
384**Main Domain Bootloader**
385
Neha Malcom Francis507be122023-07-22 00:14:43 +0530386 | `tispl.bin` for HS devices or `tispl.bin_unsigned` for GP devices
387 | `u-boot.img` for HS devices or `u-boot.img_unsigned` for GP devices
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530388
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530389FIT signature signing
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530390---------------------
391
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530392K3 platforms have FIT signature signing enabled by default on their primary
393platforms. Here we'll take an example for creating FIT Image for J721E platform
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530394and the same can be extended to other platforms
395
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530396Pre-requisites:
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530397
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530398* U-boot build (:ref:`U-boot build <k3_rst_include_start_build_steps_spl_r5>`)
399* Linux Image and Linux DTB prebuilt
400
401Describing FIT source
402^^^^^^^^^^^^^^^^^^^^^
403
404FIT Image is a packed structure containing binary blobs and configurations.
405The Kernel FIT Image that we have has Kernel Image, DTB and the DTBOs. It
406supports packing multiple images and configurations that allow you to
407choose any configuration at runtime to boot from.
408
409.. code-block::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530410
411 /dts-v1/;
412
413 / {
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530414 description = "FIT Image description";
415 #address-cells = <1>;
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530416
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530417 images {
418 [image-1]
419 [image-2]
420 [fdt-1]
421 [fdt-2]
422 }
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530423
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530424 configurations {
425 default = <conf-1>
426 [conf-1: image-1,fdt-1]
427 [conf-2: image-2,fdt-1]
428 }
429 }
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530430
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530431* Sample Images
432
433.. code-block::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530434
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530435 kernel-1 {
436 description = "Linux kernel";
437 data = /incbin/("linux.bin");
438 type = "kernel";
439 arch = "arm64";
440 os = "linux";
441 compression = "gzip";
442 load = <0x81000000>;
443 entry = <0x81000000>;
444 hash-1 {
445 algo = "sha512";
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530446 };
447 };
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530448 fdt-ti_k3-j721e-common-proc-board.dtb {
449 description = "Flattened Device Tree blob";
450 data = /incbin/("arch/arm64/boot/dts/ti/k3-j721e-common-proc-board.dtb");
451 type = "flat_dt";
452 arch = "arm64";
453 compression = "none";
454 load = <0x83000000>;
455 hash-1 {
456 algo = "sha512";
457 };
458 };
459 # Optional images
460 fdt-ti_k3-j721e-evm-virt-mac-client.dtbo {
461 description = "Flattened Device Tree blob";
462 data = /incbin/("arch/arm64/boot/dts/ti/k3-j721e-evm-virt-mac-client.dtbo");
463 type = "flat_dt";
464 arch = "arm64";
465 compression = "none";
466 load = <0x83080000>;
467 hash-1 {
468 algo = "sha512";
469 };
470 };
471
472.. note::
473
474 Change the path in data variables to point to the respective files in your
475 local machine. For e.g change "linux.bin" to "<path-to-kernel-image>".
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530476
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530477For enabling usage of FIT signature, add the signature node to the
478corresponding configuration node as follows.
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530479
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530480* Sample Configurations
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530481
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530482.. code-block::
483
484 conf-ti_k3-j721e-common-proc-board.dtb {
485 description = "Linux kernel, FDT blob";
486 fdt = "fdt-ti_k3-j721e-common-proc-board.dtb";
487 kernel = "kernel-1";
488 signature-1 {
489 algo = "sha512,rsa4096";
490 key-name-hint = "custMpk";
491 sign-images = "kernel", "fdt";
492 };
493 };
494 # Optional configurations
495 conf-ti_k3-j721e-evm-virt-mac-client.dtbo {
496 description = "FDTO blob";
497 fdt = "fdt-ti_k3-j721e-evm-virt-mac-client.dtbo";
498
499 signature-1 {
500 algo = "sha512,rsa4096";
501 key-name-hint = "custMpk";
502 sign-images = "fdt";
503 };
504 };
505
506Specify all images you need the signature to authenticate as a part of
507sign-images. The key-name-hint needs to be changed if you are using some
508other key other than the TI dummy key that we are using for this example.
509It should be the name of the file containing the keys.
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530510
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500511.. note::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530512
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530513 Generating new set of keys:
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530514
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530515 .. prompt:: bash $
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530516
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530517 mkdir keys
518 openssl genpkey -algorithm RSA -out keys/dev.key \
519 -pkeyopt rsa_keygen_bits:4096 -pkeyopt rsa_keygen_pubexp:65537
520 openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530521
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530522Generating the fitImage
523^^^^^^^^^^^^^^^^^^^^^^^
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530524
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530525.. note::
526
527 For signing a secondary platform like SK boards, you'll require
528 additional steps
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530529
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530530 - Change the CONFIG_DEFAULT_DEVICE_TREE
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530531
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530532 For e.g
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530533
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530534 .. code-block::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530535
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530536 diff --git a/configs/j721e_evm_a72_defconfig b/configs/j721e_evm_a72_defconfig
537 index a5c1df7e0054..6d0126d955ef 100644
538 --- a/configs/j721e_evm_a72_defconfig
539 +++ b/configs/j721e_evm_a72_defconfig
540 @@ -13,7 +13,7 @@ CONFIG_CUSTOM_SYS_INIT_SP_ADDR=0x80480000
541 CONFIG_ENV_SIZE=0x20000
542 CONFIG_DM_GPIO=y
543 CONFIG_SPL_DM_SPI=y
544 -CONFIG_DEFAULT_DEVICE_TREE="k3-j721e-common-proc-board"
545 +CONFIG_DEFAULT_DEVICE_TREE="k3-j721e-sk"
546 CONFIG_SPL_TEXT_BASE=0x80080000
547 CONFIG_DM_RESET=y
548 CONFIG_SPL_MMC=y
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530549
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530550 - Change the binman nodes to package u-boot.dtb for the correct set of platform
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530551
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530552 For e.g
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530553
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530554 .. code-block::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530555
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530556 diff --git a/arch/arm/dts/k3-j721e-binman.dtsi b/arch/arm/dts/k3-j721e-binman.dtsi
557 index 673be646b1e3..752fa805fe8d 100644
558 --- a/arch/arm/dts/k3-j721e-binman.dtsi
559 +++ b/arch/arm/dts/k3-j721e-binman.dtsi
560 @@ -299,8 +299,8 @@
561 #define SPL_J721E_SK_DTB "spl/dts/k3-j721e-sk.dtb"
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530562
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530563 #define UBOOT_NODTB "u-boot-nodtb.bin"
564 -#define J721E_EVM_DTB "u-boot.dtb"
565 -#define J721E_SK_DTB "arch/arm/dts/k3-j721e-sk.dtb"
566 +#define J721E_EVM_DTB "arch/arm/dts/k3-j721e-common-proc-board.dtb"
567 +#define J721E_SK_DTB "u-boot.dtb"
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530568
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530569This step will embed the public key in the u-boot.dtb file that was already
570built during the initial u-boot build.
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530571
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530572.. prompt:: bash $
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530573
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530574 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 +0530575
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530576.. note::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530577
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530578 If you have another set of keys then change the -k argument to point to
579 the folder where your keys are present, the build requires the presence
580 of both .key and .crt file.
581
582Build u-boot again
583^^^^^^^^^^^^^^^^^^
584
585The updated u-boot.dtb needs to be packed in u-boot.img for authentication
586so rebuild U-boot ARMV8 without changing any parameters.
587Refer (:ref:`U-boot ARMV8 build <k3_rst_include_start_build_steps_uboot>`)
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530588
589.. note::
590
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530591 The devices now also have distroboot enabled so if the FIT image doesn't
592 work then the fallback to normal distroboot will be there on HS devices.
593 This will need to be explicitly disabled by changing the boot_targets to
594 disallow fallback during testing.
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530595
596Saving environment
597------------------
598
599SAVEENV is disabled by default and for the new flow uses Uenv.txt as the default
600way for saving the environments. This has been done as Uenv.txt is more granular
601then the saveenv command and can be used across various bootmodes too.
602
603**Writing to MMC/EMMC**
604
Nishanth Menon740c41c2023-11-02 23:40:25 -0500605.. prompt:: bash =>
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530606
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500607 env export -t $loadaddr <list of variables>
608 fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530609
610**Reading from MMC/EMMC**
611
612By default run envboot will read it from the MMC/EMMC partition ( based on
613mmcdev) and set the environments.
614
615If manually needs to be done then the environment can be read from the
616filesystem and then imported
617
Nishanth Menon740c41c2023-11-02 23:40:25 -0500618.. prompt:: bash =>
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530619
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500620 fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
621 env import -t ${loadaddr} ${filesize}
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500622
623.. _k3_rst_refer_openocd:
624
625Common Debugging environment - OpenOCD
626--------------------------------------
627
628This section will show you how to connect a board to `OpenOCD
629<https://openocd.org/>`_ and load the SPL symbols for debugging with
630a K3 generation device. To follow this guide, you must build custom
631u-boot binaries, start your board from a boot media such as an SD
632card, and use an OpenOCD environment. This section uses generic
633examples, though you can apply these instructions to any supported K3
634generation device.
635
636The overall structure of this setup is in the following figure.
637
638.. image:: img/openocd-overview.svg
Nishanth Menon5746e032023-08-22 11:40:56 -0500639 :alt: Overview of OpenOCD setup.
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500640
641.. note::
642
643 If you find these instructions useful, please consider `donating
644 <https://openocd.org/pages/donations.html>`_ to OpenOCD.
645
646Step 1: Download and install OpenOCD
647^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
648
649To get started, it is more convenient if the distribution you
650use supports OpenOCD by default. Follow the instructions in the
651`getting OpenOCD <https://openocd.org/pages/getting-openocd.html>`_
652documentation to pick the installation steps appropriate to your
653environment. Some references to OpenOCD documentation:
654
655* `OpenOCD User Guide <https://openocd.org/doc/html/index.html>`_
656* `OpenOCD Developer's Guide <https://openocd.org/doc/doxygen/html/index.html>`_
657
658Refer to the release notes corresponding to the `OpenOCD version
659<https://github.com/openocd-org/openocd/releases>`_ to ensure
660
661* Processor support: In general, processor support shouldn't present
662 any difficulties since OpenOCD provides solid support for both ARMv8
663 and ARMv7.
664* SoC support: When working with System-on-a-Chip (SoC), the support
665 usually comes as a TCL config file. It is vital to ensure the correct
666 version of OpenOCD or to use the TCL files from the latest release or
667 the one mentioned.
668* Board or the JTAG adapter support: In most cases, board support is
669 a relatively easy problem if the board has a JTAG pin header. All
670 you need to do is ensure that the adapter you select is compatible
671 with OpenOCD. Some boards come with an onboard JTAG adapter that
672 requires a USB cable to be plugged into the board, in which case, it
673 is vital to ensure that the JTAG adapter is supported. Fortunately,
674 almost all TI K3 SK/EVMs come with TI's XDS110, which has out of the
675 box support by OpenOCD. The board-specific documentation will
676 cover the details and any adapter/dongle recommendations.
677
Nishanth Menon740c41c2023-11-02 23:40:25 -0500678.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500679
680 openocd -v
681
682.. note::
683
684 OpenOCD version 0.12.0 is usually required to connect to most K3
685 devices. If your device is only supported by a newer version than the
686 one provided by your distribution, you may need to build it from the source.
687
688Building OpenOCD from source
689""""""""""""""""""""""""""""
690
691The dependency package installation instructions below are for Debian
692systems, but equivalent instructions should exist for systems with
693other package managers. Please refer to the `OpenOCD Documentation
694<https://openocd.org/>`_ for more recent installation steps.
695
Nishanth Menon740c41c2023-11-02 23:40:25 -0500696.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500697
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500698 # Check the packages to be installed: needs deb-src in sources.list
699 sudo apt build-dep openocd
700 # The following list is NOT complete - please check the latest
701 sudo apt-get install libtool pkg-config texinfo libusb-dev \
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500702 libusb-1.0.0-dev libftdi-dev libhidapi-dev autoconf automake
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500703 git clone https://github.com/openocd-org/openocd.git openocd
704 cd openocd
705 git submodule init
706 git submodule update
707 ./bootstrap
708 ./configure --prefix=/usr/local/
709 make -j`nproc`
710 sudo make install
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500711
712.. note::
713
714 The example above uses the GitHub mirror site. See
715 `git repo information <https://openocd.org/doc/html/Developers.html#OpenOCD-Git-Repository>`_
716 information to pick the official git repo.
717 If a specific version is desired, select the version using `git checkout tag`.
718
719Installing OpenOCD udev rules
720"""""""""""""""""""""""""""""
721
722The step is not necessary if the distribution supports the OpenOCD, but
723if building from a source, ensure that the udev rules are installed
724correctly to ensure a sane system.
725
Nishanth Menon740c41c2023-11-02 23:40:25 -0500726.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500727
728 # Go to the OpenOCD source directory
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500729 cd openocd
730 Copy the udev rules to the correct system location
731 sudo cp ./contrib/60-openocd.rules \
Jonathan Humphreys27fd4982023-08-22 13:49:03 -0500732 ./src/jtag/drivers/libjaylink/contrib/99-libjaylink.rules \
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500733 /etc/udev/rules.d/
734 # Get Udev to load the new rules up
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500735 sudo udevadm control --reload-rules
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500736 # Use the new rules on existing connected devices
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500737 sudo udevadm trigger
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500738
739Step 2: Setup GDB
740^^^^^^^^^^^^^^^^^
741
742Most systems come with gdb-multiarch package.
743
Nishanth Menon740c41c2023-11-02 23:40:25 -0500744.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500745
746 # Install gdb-multiarch package
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500747 sudo apt-get install gdb-multiarch
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500748
749Though using GDB natively is normal, developers with interest in using IDE
750may find a few of these interesting:
751
752* `gdb-dashboard <https://github.com/cyrus-and/gdb-dashboard>`_
753* `gef <https://github.com/hugsy/gef>`_
754* `peda <https://github.com/longld/peda>`_
755* `pwndbg <https://github.com/pwndbg/pwndbg>`_
756* `voltron <https://github.com/snare/voltron>`_
757* `ddd <https://www.gnu.org/software/ddd/>`_
758* `vscode <https://www.justinmklam.com/posts/2017/10/vscode-debugger-setup/>`_
759* `vim conque-gdb <https://github.com/vim-scripts/Conque-GDB>`_
760* `emacs realgud <https://github.com/realgud/realgud/wiki/gdb-notes>`_
761* `Lauterbach IDE <https://www2.lauterbach.com/pdf/backend_gdb.pdf>`_
762
763.. warning::
764 LLDB support for OpenOCD is still a work in progress as of this writing.
765 Using GDB is probably the safest option at this point in time.
766
767Step 3: Connect board to PC
768^^^^^^^^^^^^^^^^^^^^^^^^^^^
769There are few patterns of boards in the ecosystem
770
771.. k3_rst_include_start_openocd_connect_XDS110
772
773**Integrated JTAG adapter/dongle**: The board has a micro-USB connector labelled
774XDS110 USB or JTAG. Connect a USB cable to the board to the mentioned port.
775
776.. note::
777
778 There are multiple USB ports on a typical board, So, ensure you have read
779 the user guide for the board and confirmed the silk screen label to ensure
780 connecting to the correct port.
781
782.. k3_rst_include_end_openocd_connect_XDS110
783
784.. k3_rst_include_start_openocd_connect_cti20
785
786**cTI20 connector**: The TI's `cTI20
787<https://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_JTAG_connectors.html#cti-20-pin-header-information>`_ connector
788is probably the most prevelant on TI platforms. Though many
789TI boards have an onboard XDS110, cTI20 connector is usually
790provided as an alternate scheme to connect alternatives such
791as `Lauterbach <https://www.lauterbach.com/>`_ or `XDS560
792<https://www.ti.com/tool/TMDSEMU560V2STM-U>`_.
793
794To debug on these boards, the following combinations is suggested:
795
796* `TUMPA <https://www.diygadget.com/JTAG-cables-and-microcontroller-programmers/tiao-usb-multi-protocol-adapter-JTAG-spi-i2c-serial>`_
797 or `equivalent dongles supported by OpenOCD. <https://openocd.org/doc/html/Debug-Adapter-Hardware.html#Debug-Adapter-Hardware>`_
798* Cable such as `Tag-connect ribbon cable <https://www.tag-connect.com/product/20-pin-cortex-ribbon-cable-4-length-with-50-mil-connectors>`_
799* Adapter to convert cTI20 to ARM20 such as those from
800 `Segger <https://www.segger.com/products/debug-probes/j-link/accessories/adapters/ti-cti-20-adapter/>`_
801 or `Lauterbach LA-3780 <https://www.lauterbach.com/ad3780.html>`_
802 Or optionally, if you have manufacturing capability then you could try
803 `BeagleBone JTAG Adapter <https://github.com/mmorawiec/BeagleBone-Black-JTAG-Adapters>`_
804
805.. warning::
806 XDS560 and Lauterbach are proprietary solutions and is not supported by
807 OpenOCD.
808 When purchasing an off the shelf adapter/dongle, you do want to be careful
809 about the signalling though. Please
810 `read for additional info <https://software-dl.ti.com/ccs/esd/xdsdebugprobes/emu_JTAG_connectors.html>`_.
811
812.. k3_rst_include_end_openocd_connect_cti20
813
814.. k3_rst_include_start_openocd_connect_tag_connect
815
816**Tag-Connect**: `Tag-Connect <https://www.tag-connect.com/>`_
817pads on the boards which require special cable. Please check the documentation
818to `identify <https://www.tag-connect.com/info/legs-or-no-legs>`_ if "legged"
819or "no-leg" version of the cable is appropriate for the board.
820
821To debug on these boards, you will need:
822
823* `TUMPA <https://www.diygadget.com/JTAG-cables-and-microcontroller-programmers/tiao-usb-multi-protocol-adapter-JTAG-spi-i2c-serial>`_
824 or `equivalent dongles supported by OpenOCD <https://openocd.org/doc/html/Debug-Adapter-Hardware.html#Debug-Adapter-Hardware>`_.
825* Tag-Connect cable appropriate to the board such as
826 `TC2050-IDC-NL <https://www.tag-connect.com/product/TC2050-IDC-NL-10-pin-no-legs-cable-with-ribbon-connector>`_
827* In case of no-leg, version, a
828 `retaining clip <https://www.tag-connect.com/product/tc2050-clip-3pack-retaining-clip>`_
829* Tag-Connect to ARM20
830 `adapter <https://www.tag-connect.com/product/tc2050-arm2010-arm-20-pin-to-tc2050-adapter>`_
831
832.. note::
833 You can optionally use a 3d printed solution such as
834 `Protective cap <https://www.thingiverse.com/thing:3025584>`_ or
835 `clip <https://www.thingiverse.com/thing:3035278>`_ to replace
836 the retaining clip.
837
838.. warning::
839 With the Tag-Connect to ARM20 adapter, Please solder the "Trst" signal for
840 connection to work.
841
842.. k3_rst_include_end_openocd_connect_tag_connect
843
844Debugging with OpenOCD
845^^^^^^^^^^^^^^^^^^^^^^
846
847Debugging U-Boot is different from debugging regular user space
848applications. The bootloader initialization process involves many boot
849media and hardware configuration operations. For K3 devices, there
850are also interactions with security firmware. While reloading the
851"elf" file works through GDB, developers must be mindful of cascading
852initialization's potential consequences.
853
854Consider the following code change:
855
856.. code-block:: diff
857
858 --- a/file.c 2023-07-29 10:55:29.647928811 -0500
859 +++ b/file.c 2023-07-29 10:55:46.091856816 -0500
860 @@ -1,3 +1,3 @@
861 val = readl(reg);
862 -val |= 0x2;
863 +val |= 0x1;
864 writel(val, reg);
865
866Re-running the elf file with the above change will result in the
867register setting 0x3 instead of the intended 0x1. There are other
868hardware blocks which may not behave very well with a re-initialization
869without proper shutdown.
870
871To help narrow the debug down, it is usually simpler to use the
872standard boot media to get to the bootloader and debug only in the area
873of interest.
874
875In general, to debug u-boot spl/u-boot with OpenOCD there are three steps:
876
877* Modify the code adding a loop to allow the debugger to attach
878 near the point of interest. Boot up normally to stop at the loop.
879* Connect with OpenOCD and step out of the loop.
880* Step through the code to find the root of issue.
881
882Typical debugging involves a few iterations of the above sequence.
883Though most bootloader developers like to use printf to debug,
884debug with JTAG tends to be most efficient since it is possible to
885investigate the code flow and inspect hardware registers without
886repeated iterations.
887
888Code modification
889"""""""""""""""""
890
891* **start.S**: Adding an infinite while loop at the very entry of
892 U-Boot. For this, look for the corresponding start.S entry file.
893 This is usually only required when debugging some core SoC or
894 processor related function. For example: arch/arm/cpu/armv8/start.S or
895 arch/arm/cpu/armv7/start.S
896
897.. code-block:: diff
898
899 diff --git a/arch/arm/cpu/armv7/start.S b/arch/arm/cpu/armv7/start.S
900 index 69e281b086..744929e825 100644
901 --- a/arch/arm/cpu/armv7/start.S
902 +++ b/arch/arm/cpu/armv7/start.S
903 @@ -37,6 +37,8 @@
904 #endif
905
906 reset:
907 +dead_loop:
908 + b dead_loop
909 /* Allow the board to save important registers */
910 b save_boot_params
911 save_boot_params_ret:
912
913* **board_init_f**: Adding an infinite while loop at the board entry
914 function. In many cases, it is important to debug the boot process if
915 any changes are made for board-specific applications. Below is a step
916 by step process for debugging the boot SPL or Armv8 SPL:
917
918 To debug the boot process in either domain, we will first
919 add a modification to the code we would like to debug.
920 In this example, we will debug ``board_init_f`` inside
921 ``arch/arm/mach-k3/{soc}_init.c``. Since some sections of U-Boot
922 will be executed multiple times during the bootup process of K3
Jonathan Humphreys27fd4982023-08-22 13:49:03 -0500923 devices, we will need to include either ``CONFIG_ARM64`` or
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500924 ``CONFIG_CPU_V7R`` to catch the CPU at the desired place during the
925 bootup process (Main or Wakeup domains). For example, modify the
926 file as follows (depending on need):
927
928.. code-block:: c
929
930 void board_init_f(ulong dummy)
931 {
932 .
933 .
934 /* Code to run on the R5F (Wakeup/Boot Domain) */
935 if (IS_ENABLED(CONFIG_CPU_V7R)) {
936 volatile int x = 1;
937 while(x) {};
938 }
939 ...
940 /* Code to run on the ARMV8 (Main Domain) */
Jonathan Humphreys27fd4982023-08-22 13:49:03 -0500941 if (IS_ENABLED(CONFIG_ARM64)) {
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500942 volatile int x = 1;
943 while(x) {};
944 }
945 .
946 .
947 }
948
949Connecting with OpenOCD for a debug session
950"""""""""""""""""""""""""""""""""""""""""""
951
952Startup OpenOCD to debug the platform as follows:
953
954* **Integrated JTAG interface**: If the evm has a debugger such as
955 XDS110 inbuilt, there is typically an evm board support added and a
956 cfg file will be available.
957
958.. k3_rst_include_start_openocd_cfg_XDS110
959
Nishanth Menon740c41c2023-11-02 23:40:25 -0500960.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500961
962 openocd -f board/{board_of_choice}.cfg
963
964.. k3_rst_include_end_openocd_cfg_XDS110
965
966.. k3_rst_include_start_openocd_cfg_external_intro
967
968* **External JTAG adapter/interface**: In other cases, where an
969 adapter/dongle is used, a simple cfg file can be created to integrate the
970 SoC and adapter information. See `supported TI K3 SoCs
971 <https://github.com/openocd-org/openocd/blob/master/tcl/target/ti_k3.cfg#L59>`_
972 to decide if the SoC is supported or not.
973
Nishanth Menon740c41c2023-11-02 23:40:25 -0500974.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500975
976 openocd -f openocd_connect.cfg
977
978.. k3_rst_include_end_openocd_cfg_external_intro
979
980 For example, with BeaglePlay (AM62X platform), the openocd_connect.cfg:
981
982.. code-block:: tcl
983
984 # TUMPA example:
985 # http://www.tiaowiki.com/w/TIAO_USB_Multi_Protocol_Adapter_User's_Manual
986 source [find interface/ftdi/tumpa.cfg]
987
988 transport select jtag
989
990 # default JTAG configuration has only SRST and no TRST
991 reset_config srst_only srst_push_pull
992
993 # delay after SRST goes inactive
994 adapter srst delay 20
995
996 if { ![info exists SOC] } {
997 # Set the SoC of interest
998 set SOC am625
999 }
1000
1001 source [find target/ti_k3.cfg]
1002
1003 ftdi tdo_sample_edge falling
1004
1005 # Speeds for FT2232H are in multiples of 2, and 32MHz is tops
1006 # max speed we seem to achieve is ~20MHz.. so we pick 16MHz
1007 adapter speed 16000
1008
1009Below is an example of the output of this command:
1010
1011.. code-block:: console
1012
1013 Info : Listening on port 6666 for tcl connections
1014 Info : Listening on port 4444 for telnet connections
1015 Info : XDS110: connected
1016 Info : XDS110: vid/pid = 0451/bef3
1017 Info : XDS110: firmware version = 3.0.0.20
1018 Info : XDS110: hardware version = 0x002f
1019 Info : XDS110: connected to target via JTAG
1020 Info : XDS110: TCK set to 2500 kHz
1021 Info : clock speed 2500 kHz
1022 Info : JTAG tap: am625.cpu tap/device found: 0x0bb7e02f (mfg: 0x017 (Texas Instruments), part: 0xbb7e, ver: 0x0)
1023 Info : starting gdb server for am625.cpu.sysctrl on 3333
1024 Info : Listening on port 3333 for gdb connections
1025 Info : starting gdb server for am625.cpu.a53.0 on 3334
1026 Info : Listening on port 3334 for gdb connections
1027 Info : starting gdb server for am625.cpu.a53.1 on 3335
1028 Info : Listening on port 3335 for gdb connections
1029 Info : starting gdb server for am625.cpu.a53.2 on 3336
1030 Info : Listening on port 3336 for gdb connections
1031 Info : starting gdb server for am625.cpu.a53.3 on 3337
1032 Info : Listening on port 3337 for gdb connections
1033 Info : starting gdb server for am625.cpu.main0_r5.0 on 3338
1034 Info : Listening on port 3338 for gdb connections
1035 Info : starting gdb server for am625.cpu.gp_mcu on 3339
1036 Info : Listening on port 3339 for gdb connections
1037
1038.. note::
1039 Notice the default configuration is non-SMP configuration allowing
1040 for each of the core to be attached and debugged simultaneously.
1041 ARMv8 SPL/U-Boot starts up on cpu0 of a53/a72.
1042
1043.. k3_rst_include_start_openocd_cfg_external_gdb
1044
1045To debug using this server, use GDB directly or your preferred
1046GDB-based IDE. To start up GDB in the terminal, run the following
1047command.
1048
Nishanth Menon740c41c2023-11-02 23:40:25 -05001049.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001050
1051 gdb-multiarch
1052
1053To connect to your desired core, run the following command within GDB:
1054
Nishanth Menon740c41c2023-11-02 23:40:25 -05001055.. prompt:: bash (gdb)
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001056
1057 target extended-remote localhost:{port for desired core}
1058
1059To load symbols:
1060
1061.. warning::
1062
1063 SPL and U-Boot does a re-location of address compared to where it
1064 is loaded originally. This step takes place after the DDR size is
1065 determined from dt parsing. So, debugging can be split into either
1066 "before re-location" or "after re-location". Please refer to the
1067 file ''doc/README.arm-relocation'' to see how to grab the relocation
1068 address.
1069
1070* Prior to relocation:
1071
Nishanth Menon740c41c2023-11-02 23:40:25 -05001072.. prompt:: bash (gdb)
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001073
1074 symbol-file {path to elf file}
1075
1076* After relocation:
1077
Nishanth Menon740c41c2023-11-02 23:40:25 -05001078.. prompt:: bash (gdb)
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001079
1080 # Drop old symbol file
1081 symbol-file
1082 # Pick up new relocaddr
1083 add-symbol-file {path to elf file} {relocaddr}
1084
1085.. k3_rst_include_end_openocd_cfg_external_gdb
1086
1087In the above example of AM625,
1088
Nishanth Menon740c41c2023-11-02 23:40:25 -05001089.. prompt:: bash (gdb)
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001090
1091 target extended-remote localhost:3338 <- R5F (Wakeup Domain)
1092 target extended-remote localhost:3334 <- A53 (Main Domain)
1093
1094The core can now be debugged directly within GDB using GDB commands or
1095if using IDE, as appropriate to the IDE.
1096
1097Stepping through the code
1098"""""""""""""""""""""""""
1099
1100`GDB TUI Commands
1101<https://sourceware.org/gdb/onlinedocs/gdb/TUI-Commands.html>`_ can
1102help set up the display more sensible for debug. Provide the name
1103of the layout that can be used to debug. For example, use the GDB
1104command ``layout src`` after loading the symbols to see the code and
1105breakpoints. To exit the debug loop added above, add any breakpoints
1106needed and run the following GDB commands to step out of the debug
1107loop set in the ``board_init_f`` function.
1108
Nishanth Menon740c41c2023-11-02 23:40:25 -05001109.. prompt:: bash (gdb)
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001110
1111 set x = 0
1112 continue
1113
1114The platform has now been successfully setup to debug with OpenOCD
1115using GDB commands or a GDB-based IDE. See `OpenOCD documentation for
1116GDB <https://openocd.org/doc/html/GDB-and-OpenOCD.html>`_ for further
1117information.
1118
1119.. warning::
1120
1121 On the K3 family of devices, a watchdog timer within the DMSC is
1122 enabled by default by the ROM bootcode with a timeout of 3 minutes.
1123 The watchdog timer is serviced by System Firmware (SYSFW) or TI
1124 Foundational Security (TIFS) during normal operation. If debugging
1125 the SPL before the SYSFW is loaded, the watchdog timer will not get
1126 serviced automatically and the debug session will reset after 3
1127 minutes. It is recommended to start debugging SPL code only after
1128 the startup of SYSFW to avoid running into the watchdog timer reset.
1129
1130Miscellaneous notes with OpenOCD
1131^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1132
1133Currently, OpenOCD does not support tracing for K3 platforms. Tracing
1134function could be beneficial if the bug in code occurs deep within
1135nested function and can optionally save developers major trouble of
1136stepping through a large quantity of code.