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