blob: eba0f0e3e4261961c384cc2bc8af454d29bccee0 [file] [log] [blame]
Bryan Brattlof6d138132022-12-19 14:29:50 -06001.. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
2.. sectionauthor:: Bryan Brattlof <bb@ti.com>
3
4K3 Generation
5=============
6
7Summary
8-------
9
10Texas Instrument's K3 family of SoCs utilize a heterogeneous multicore
11and highly integrated device architecture targeted to maximize
12performance and power efficiency for a wide range of industrial,
13automotive and other broad market segments.
14
15Typically the processing cores and the peripherals for these devices are
16partitioned into three functional domains to provide ultra-low power
17modes as well as accommodating application and industrial safety systems
18on the same SoC. These functional domains are typically called the:
19
20* Wakeup (WKUP) domain
21* Micro-controller (MCU) domain
22* Main domain
23
24For a more detailed view of what peripherals are attached to each
25domain, consult the device specific documentation.
26
27K3 Based SoCs
28-------------
29
30.. toctree::
31 :maxdepth: 1
32
Jai Luthrae526653e2023-11-13 08:51:49 -060033 am62ax_sk
Bryan Brattlof6d138132022-12-19 14:29:50 -060034 am62x_sk
Nishanth Menon1f2b6f92023-11-04 03:01:36 -050035 ../beagle/am62x_beagleplay
Wadim Egorov12722a42023-12-20 10:18:11 +010036 ../phytec/phycore-am62x
Marcel Ziswiler315deb32023-08-04 12:08:08 +020037 ../toradex/verdin-am62
Bryan Brattlofcf2e2b12024-03-12 15:20:30 -050038 am62px_sk
Roger Quadroscd87b1e2023-08-05 11:14:39 +030039 am64x_evm
Neha Malcom Francis507be122023-07-22 00:14:43 +053040 am65x_evm
Nishanth Menone83fe672023-07-27 13:59:01 -050041 j7200_evm
Nishanth Menon756b8782023-11-04 03:11:03 -050042 ../beagle/j721e_beagleboneai64
Nishanth Menone83fe672023-07-27 13:59:01 -050043 j721e_evm
Manorit Chawdhry670a22b2023-10-06 10:16:00 +053044 j721s2_evm
Jayesh Choudhary5e547a72024-06-12 14:41:23 +053045 j722s_evm
Apurva Nandan2b1c9ff2024-02-24 01:51:53 +053046 j784s4_evm
Bryan Brattlof6d138132022-12-19 14:29:50 -060047
48Boot Flow Overview
49------------------
50
51For all K3 SoCs the first core started will be inside the Security
52Management Subsystem (SMS) which will secure the device and start a core
53in the wakeup domain to run the ROM code. ROM will then initialize the
54boot media needed to load the binaries packaged inside `tiboot3.bin`,
55including a 32bit U-Boot SPL, (called the wakup SPL) that ROM will jump
56to after it has finished loading everything into internal SRAM.
57
Nishanth Menon7bdb2d52023-07-27 13:59:02 -050058.. image:: img/boot_flow_01.svg
Heinrich Schuchardtd0894b22023-08-22 11:40:55 -050059 :alt: Boot flow up to wakeup domain SPL
Bryan Brattlof6d138132022-12-19 14:29:50 -060060
61The wakeup SPL, running on a wakeup domain core, will initialize DDR and
62any peripherals needed load the larger binaries inside the `tispl.bin`
63into DDR. Once loaded the wakeup SPL will start one of the 'big'
64application cores inside the main domain to initialize the main domain,
Neha Malcom Francis507be122023-07-22 00:14:43 +053065starting with Trusted Firmware-A (TF-A), before moving on to start
66OP-TEE and the main domain's U-Boot SPL.
Bryan Brattlof6d138132022-12-19 14:29:50 -060067
Nishanth Menon7bdb2d52023-07-27 13:59:02 -050068.. image:: img/boot_flow_02.svg
Heinrich Schuchardtd0894b22023-08-22 11:40:55 -050069 :alt: Boot flow up to main domain SPL
Bryan Brattlof6d138132022-12-19 14:29:50 -060070
71The main domain's SPL, running on a 64bit application core, has
72virtually unlimited space (billions of bytes now that DDR is working) to
73initialize even more peripherals needed to load in the `u-boot.img`
74which loads more firmware into the micro-controller & wakeup domains and
75finally prepare the main domain to run Linux.
76
Nishanth Menon7bdb2d52023-07-27 13:59:02 -050077.. image:: img/boot_flow_03.svg
Heinrich Schuchardtd0894b22023-08-22 11:40:55 -050078 :alt: Complete boot flow up to Linux
Bryan Brattlof6d138132022-12-19 14:29:50 -060079
80This is the typical boot flow for all K3 based SoCs, however this flow
81offers quite a lot in the terms of flexibility, especially on High
82Security (HS) SoCs.
83
84Boot Flow Variations
85^^^^^^^^^^^^^^^^^^^^
86
87All K3 SoCs will generally use the above boot flow with two main
88differences depending on the capabilities of the boot ROM and the number
89of cores inside the device. These differences split the bootflow into
90essentially 4 unique but very similar flows:
91
92* Split binary with a combined firmware: (eg: AM65)
93* Combined binary with a combined firmware: (eg: AM64)
94* Split binary with a split firmware: (eg: J721E)
95* Combined binary with a split firmware: (eg: AM62)
96
97For devices that utilize the split binary approach, ROM is not capable
98of loading the firmware into the SoC requiring the wakeup domain's
99U-Boot SPL to load the firmware.
100
101Devices with a split firmware will have two firmwares loaded into the
102device at different times during the bootup process. TI's Foundational
103Security (TIFS), needed to operate the Security Management Subsystem,
104will either be loaded by ROM or the WKUP U-Boot SPL, then once the
105wakeup U-Boot SPL has completed, the second Device Management (DM)
106firmware can be loaded on the now free core in the wakeup domain.
107
108For more information on the bootup process of your SoC, consult the
109device specific boot flow documentation.
110
Manorit Chawdhry98346472023-12-29 16:16:33 +0530111Secure Boot
112-----------
113
114K3 HS-SE (High Security - Security Enforced) devices enforce an
115authenticated boot flow for secure boot. HS-FS (High Security - Field
116Securable) is the state of a K3 device before it has been eFused with
117customer security keys. In the HS-FS state the authentication still can
118function as in HS-SE but as there are no customer keys to verify the
119signatures against the authentication will pass for certificates signed
120with any key.
121
122Chain of trust
123^^^^^^^^^^^^^^
124
1251) Public ROM loads the tiboot3.bin (R5 SPL, TIFS)
1262) R5 SPL loads tispl.bin (ATF, OP-TEE, DM, SPL)
1273) SPL loads u-boot.img (U-Boot)
1284) U-Boot loads fitImage (Linux and DTBs)
129
130Steps 1-3 are all authenticated by either the Secure ROM or TIFS as the
131authenticating entity and step 4 uses U-boot standard mechanism for
132authenticating.
133
134All the authentication that are done for ROM/TIFS are done through x509
135certificates that are signed.
136
137Firewalls
138^^^^^^^^^
139
1401) Secure ROM comes up and sets up firewalls that are needed by itself
1412) TIFS will setup it's own firewalls to protect core system resources
1423) R5 SPL will remove any firewalls that are leftover from the Secure ROM stage
143 that are no longer required.
1444) Each stage beyond this: such as tispl.bin containing TFA/OPTEE uses OIDs to
145 set up firewalls to protect themselves (enforced by TIFS)
1465) TFA/OP-TEE can configure other firewalls at runtime if required as they
147 are already authenticated and firewalled off from illegal access.
1486) All later stages can setup or remove firewalls that have not been already
149 configured by previous stages, such as those created by TIFS, TFA, and OP-TEE.
150
151Futhur, firewalls have a lockdown bit in hardware that enforces the setting
152(and cannot be over-ridden) until the full system is reset.
153
Bryan Brattlof6d138132022-12-19 14:29:50 -0600154Software Sources
155----------------
156
157All scripts and code needed to build the `tiboot3.bin`, `tispl.bin` and
158`u-boot.img` for all K3 SoCs can be located at the following places
159online
160
Nishanth Menonee91e482023-07-27 13:58:44 -0500161.. k3_rst_include_start_boot_sources
162
Bryan Brattlof6d138132022-12-19 14:29:50 -0600163* **Das U-Boot**
164
165 | **source:** https://source.denx.de/u-boot/u-boot.git
166 | **branch:** master
167
Neha Malcom Francis507be122023-07-22 00:14:43 +0530168* **Trusted Firmware-A (TF-A)**
Bryan Brattlof6d138132022-12-19 14:29:50 -0600169
Neha Malcom Francis507be122023-07-22 00:14:43 +0530170 | **source:** https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/
Bryan Brattlof6d138132022-12-19 14:29:50 -0600171 | **branch:** master
172
Neha Malcom Francis507be122023-07-22 00:14:43 +0530173* **Open Portable Trusted Execution Environment (OP-TEE)**
Bryan Brattlof6d138132022-12-19 14:29:50 -0600174
175 | **source:** https://github.com/OP-TEE/optee_os.git
176 | **branch:** master
177
Nishanth Menone2a47452023-08-22 11:41:07 -0500178* **TI Firmware (TIFS, DM, SYSFW)**
Bryan Brattlof6d138132022-12-19 14:29:50 -0600179
180 | **source:** https://git.ti.com/git/processor-firmware/ti-linux-firmware.git
181 | **branch:** ti-linux-firmware
182
Nishanth Menone2a47452023-08-22 11:41:07 -0500183.. note::
184
185 The TI Firmware required for functionality of the system can be
186 one of the following combination (see platform specific boot diagram for
187 further information as to which component runs on which processor):
188
189 * **TIFS** - TI Foundational Security Firmware - Consists of purely firmware
190 meant to run on the security enclave.
191 * **DM** - Device Management firmware also called TI System Control Interface
192 server (TISCI Server) - This component purely plays the role of managing
193 device resources such as power, clock, interrupts, dma etc. This firmware
194 runs on a dedicated or multi-use microcontroller outside the security
195 enclave.
196
197 OR
198
199 * **SYSFW** - System firmware - consists of both TIFS and DM both running on
200 the security enclave.
201
Nishanth Menonee91e482023-07-27 13:58:44 -0500202.. k3_rst_include_end_boot_sources
203
Bryan Brattlof6d138132022-12-19 14:29:50 -0600204Build Procedure
205---------------
206
207Depending on the specifics of your device, you will need three or more
208binaries to boot your SoC.
209
210* `tiboot3.bin` (bootloader for the wakeup domain)
211* `tispl.bin` (bootloader for the main domain)
212* `u-boot.img`
213
214During the bootup process, both the 32bit wakeup domain and the 64bit
215main domains will be involved. This means everything inside the
216`tiboot3.bin` running in the wakeup domain will need to be compiled for
21732bit cores and most binaries in the `tispl.bin` will need to be
218compiled for 64bit main domain CPU cores.
219
220All of that to say you will need both a 32bit and 64bit cross compiler
221(assuming you're using an x86 desktop)
222
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500223.. k3_rst_include_start_common_env_vars_desc
224.. list-table:: Generic environment variables
225 :widths: 25 25 50
226 :header-rows: 1
227
228 * - S/w Component
229 - Env Variable
230 - Description
231 * - All Software
232 - CC32
233 - Cross compiler for ARMv7 (ARM 32bit), typically arm-linux-gnueabihf-
234 * - All Software
235 - CC64
236 - Cross compiler for ARMv8 (ARM 64bit), typically aarch64-linux-gnu-
237 * - All Software
238 - LNX_FW_PATH
239 - Path to TI Linux firmware repository
240 * - All Software
241 - TFA_PATH
242 - Path to source of Trusted Firmware-A
243 * - All Software
244 - OPTEE_PATH
245 - Path to source of OP-TEE
246.. k3_rst_include_end_common_env_vars_desc
247
248.. k3_rst_include_start_common_env_vars_defn
Nishanth Menon740c41c2023-11-02 23:40:25 -0500249.. prompt:: bash $
Bryan Brattlof6d138132022-12-19 14:29:50 -0600250
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500251 export CC32=arm-linux-gnueabihf-
252 export CC64=aarch64-linux-gnu-
253 export LNX_FW_PATH=path/to/ti-linux-firmware
254 export TFA_PATH=path/to/trusted-firmware-a
255 export OPTEE_PATH=path/to/optee_os
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500256.. k3_rst_include_end_common_env_vars_defn
257
258We will also need some common environment variables set up for the various
259other build sources. we shall use the following, in the build descriptions below:
260
261.. k3_rst_include_start_board_env_vars_desc
262.. list-table:: Board specific environment variables
263 :widths: 25 25 50
264 :header-rows: 1
265
266 * - S/w Component
267 - Env Variable
268 - Description
269 * - U-Boot
270 - UBOOT_CFG_CORTEXR
271 - Defconfig for Cortex-R (Boot processor).
272 * - U-Boot
273 - UBOOT_CFG_CORTEXA
274 - Defconfig for Cortex-A (MPU processor).
275 * - Trusted Firmware-A
276 - TFA_BOARD
277 - Platform name used for building TF-A for Cortex-A Processor.
278 * - Trusted Firmware-A
279 - TFA_EXTRA_ARGS
280 - Any extra arguments used for building TF-A.
281 * - OP-TEE
282 - OPTEE_PLATFORM
283 - Platform name used for building OP-TEE for Cortex-A Processor.
284 * - OP-TEE
285 - OPTEE_EXTRA_ARGS
286 - Any extra arguments used for building OP-TEE.
287.. k3_rst_include_end_board_env_vars_desc
Bryan Brattlof6d138132022-12-19 14:29:50 -0600288
289Building tiboot3.bin
Heinrich Schuchardtb72160b2023-10-28 11:59:32 +0200290^^^^^^^^^^^^^^^^^^^^
Bryan Brattlof6d138132022-12-19 14:29:50 -0600291
2921. To generate the U-Boot SPL for the wakeup domain, use the following
293 commands, substituting :code:`{SOC}` for the name of your device (eg:
Neha Malcom Francis507be122023-07-22 00:14:43 +0530294 am62x) to package the various firmware and the wakeup UBoot SPL into
295 the final `tiboot3.bin` binary. (or the `sysfw.itb` if your device
296 uses the split binary flow)
Bryan Brattlof6d138132022-12-19 14:29:50 -0600297
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530298.. _k3_rst_include_start_build_steps_spl_r5:
299
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500300.. k3_rst_include_start_build_steps_spl_r5
Nishanth Menon740c41c2023-11-02 23:40:25 -0500301.. prompt:: bash $
Bryan Brattlof6d138132022-12-19 14:29:50 -0600302
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500303 # inside u-boot source
304 make $UBOOT_CFG_CORTEXR
305 make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500306.. k3_rst_include_end_build_steps_spl_r5
Bryan Brattlof6d138132022-12-19 14:29:50 -0600307
308At this point you should have all the needed binaries to boot the wakeup
309domain of your K3 SoC.
310
311**Combined Binary Boot Flow** (eg: am62x, am64x, ... )
312
Neha Malcom Francis507be122023-07-22 00:14:43 +0530313 `tiboot3-{SOC}-{gp/hs-fs/hs}.bin`
Bryan Brattlof6d138132022-12-19 14:29:50 -0600314
315**Split Binary Boot Flow** (eg: j721e, am65x)
316
Neha Malcom Francis507be122023-07-22 00:14:43 +0530317 | `tiboot3-{SOC}-{gp/hs-fs/hs}.bin`
318 | `sysfw-{SOC}-{gp/hs-fs/hs}-evm.itb`
Bryan Brattlof6d138132022-12-19 14:29:50 -0600319
320.. note ::
321
322 It's important to rename the generated `tiboot3.bin` and `sysfw.itb`
323 to match exactly `tiboot3.bin` and `sysfw.itb` as ROM and the wakeup
324 UBoot SPL will only look for and load the files with these names.
325
326Building tispl.bin
Heinrich Schuchardtb72160b2023-10-28 11:59:32 +0200327^^^^^^^^^^^^^^^^^^
Bryan Brattlof6d138132022-12-19 14:29:50 -0600328
329The `tispl.bin` is a standard fitImage combining the firmware need for
330the main domain to function properly as well as Device Management (DM)
331firmware if your device using a split firmware.
332
Neha Malcom Francis507be122023-07-22 00:14:43 +05303332. We will first need TF-A, as it's the first thing to run on the 'big'
Bryan Brattlof6d138132022-12-19 14:29:50 -0600334 application cores on the main domain.
335
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500336.. k3_rst_include_start_build_steps_tfa
Nishanth Menon740c41c2023-11-02 23:40:25 -0500337.. prompt:: bash $
Bryan Brattlof6d138132022-12-19 14:29:50 -0600338
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500339 # inside trusted-firmware-a source
340 make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \
341 TARGET_BOARD=$TFA_BOARD
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500342.. k3_rst_include_end_build_steps_tfa
Bryan Brattlof6d138132022-12-19 14:29:50 -0600343
Neha Malcom Francis507be122023-07-22 00:14:43 +0530344Typically all `j7*` devices will use `TARGET_BOARD=generic` or `TARGET_BOARD
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500345=j784s4` (if it is a J784S4 device), while typical Sitara (`am6*`) devices
Neha Malcom Francis507be122023-07-22 00:14:43 +0530346use the `lite` option.
Bryan Brattlof6d138132022-12-19 14:29:50 -0600347
Neha Malcom Francis507be122023-07-22 00:14:43 +05303483. The Open Portable Trusted Execution Environment (OP-TEE) is designed
Bryan Brattlof6d138132022-12-19 14:29:50 -0600349 to run as a companion to a non-secure Linux kernel for Cortex-A cores
350 using the TrustZone technology built into the core.
351
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500352.. k3_rst_include_start_build_steps_optee
Nishanth Menon740c41c2023-11-02 23:40:25 -0500353.. prompt:: bash $
Bryan Brattlof6d138132022-12-19 14:29:50 -0600354
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500355 # inside optee_os source
356 make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \
357 PLATFORM=$OPTEE_PLATFORM
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500358.. k3_rst_include_end_build_steps_optee
Bryan Brattlof6d138132022-12-19 14:29:50 -0600359
Neha Malcom Francis507be122023-07-22 00:14:43 +05303604. Finally, after TF-A has initialized the main domain and OP-TEE has
Bryan Brattlof6d138132022-12-19 14:29:50 -0600361 finished, we can jump back into U-Boot again, this time running on a
362 64bit core in the main domain.
363
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530364.. _k3_rst_include_start_build_steps_uboot:
365
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500366.. k3_rst_include_start_build_steps_uboot
Nishanth Menon740c41c2023-11-02 23:40:25 -0500367.. prompt:: bash $
Bryan Brattlof6d138132022-12-19 14:29:50 -0600368
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500369 # inside u-boot source
370 make $UBOOT_CFG_CORTEXA
371 make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500372 BL31=$TFA_PATH/build/k3/$TFA_BOARD/release/bl31.bin \
373 TEE=$OPTEE_PATH/out/arm-plat-k3/core/tee-raw.bin
Neha Malcom Francis2b259f02023-12-05 15:12:20 +0530374
375.. note::
376 It is also possible to pick up a custom DM binary by adding TI_DM argument
377 pointing to the file. If not provided, it defaults to picking up the DM
378 binary from BINMAN_INDIRS. This is only applicable to devices that utilize
379 split firmware.
380
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500381.. k3_rst_include_end_build_steps_uboot
Bryan Brattlof6d138132022-12-19 14:29:50 -0600382
383At this point you should have every binary needed initialize both the
384wakeup and main domain and to boot to the U-Boot prompt
385
386**Main Domain Bootloader**
387
Neha Malcom Francis507be122023-07-22 00:14:43 +0530388 | `tispl.bin` for HS devices or `tispl.bin_unsigned` for GP devices
389 | `u-boot.img` for HS devices or `u-boot.img_unsigned` for GP devices
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530390
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530391FIT signature signing
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530392---------------------
393
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530394K3 platforms have FIT signature signing enabled by default on their primary
395platforms. Here we'll take an example for creating FIT Image for J721E platform
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530396and the same can be extended to other platforms
397
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530398Pre-requisites:
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530399
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530400* U-boot build (:ref:`U-boot build <k3_rst_include_start_build_steps_spl_r5>`)
401* Linux Image and Linux DTB prebuilt
402
403Describing FIT source
404^^^^^^^^^^^^^^^^^^^^^
405
406FIT Image is a packed structure containing binary blobs and configurations.
407The Kernel FIT Image that we have has Kernel Image, DTB and the DTBOs. It
408supports packing multiple images and configurations that allow you to
409choose any configuration at runtime to boot from.
410
411.. code-block::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530412
413 /dts-v1/;
414
415 / {
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530416 description = "FIT Image description";
417 #address-cells = <1>;
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530418
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530419 images {
420 [image-1]
421 [image-2]
422 [fdt-1]
423 [fdt-2]
424 }
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530425
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530426 configurations {
427 default = <conf-1>
428 [conf-1: image-1,fdt-1]
429 [conf-2: image-2,fdt-1]
430 }
431 }
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530432
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530433* Sample Images
434
435.. code-block::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530436
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530437 kernel-1 {
438 description = "Linux kernel";
439 data = /incbin/("linux.bin");
440 type = "kernel";
441 arch = "arm64";
442 os = "linux";
443 compression = "gzip";
444 load = <0x81000000>;
445 entry = <0x81000000>;
446 hash-1 {
447 algo = "sha512";
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530448 };
449 };
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530450 fdt-ti_k3-j721e-common-proc-board.dtb {
451 description = "Flattened Device Tree blob";
452 data = /incbin/("arch/arm64/boot/dts/ti/k3-j721e-common-proc-board.dtb");
453 type = "flat_dt";
454 arch = "arm64";
455 compression = "none";
456 load = <0x83000000>;
457 hash-1 {
458 algo = "sha512";
459 };
460 };
461 # Optional images
462 fdt-ti_k3-j721e-evm-virt-mac-client.dtbo {
463 description = "Flattened Device Tree blob";
464 data = /incbin/("arch/arm64/boot/dts/ti/k3-j721e-evm-virt-mac-client.dtbo");
465 type = "flat_dt";
466 arch = "arm64";
467 compression = "none";
468 load = <0x83080000>;
469 hash-1 {
470 algo = "sha512";
471 };
472 };
473
474.. note::
475
476 Change the path in data variables to point to the respective files in your
477 local machine. For e.g change "linux.bin" to "<path-to-kernel-image>".
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530478
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530479For enabling usage of FIT signature, add the signature node to the
480corresponding configuration node as follows.
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530481
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530482* Sample Configurations
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530483
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530484.. code-block::
485
486 conf-ti_k3-j721e-common-proc-board.dtb {
487 description = "Linux kernel, FDT blob";
488 fdt = "fdt-ti_k3-j721e-common-proc-board.dtb";
489 kernel = "kernel-1";
490 signature-1 {
491 algo = "sha512,rsa4096";
492 key-name-hint = "custMpk";
493 sign-images = "kernel", "fdt";
494 };
495 };
496 # Optional configurations
497 conf-ti_k3-j721e-evm-virt-mac-client.dtbo {
498 description = "FDTO blob";
499 fdt = "fdt-ti_k3-j721e-evm-virt-mac-client.dtbo";
500
501 signature-1 {
502 algo = "sha512,rsa4096";
503 key-name-hint = "custMpk";
504 sign-images = "fdt";
505 };
506 };
507
508Specify all images you need the signature to authenticate as a part of
509sign-images. The key-name-hint needs to be changed if you are using some
510other key other than the TI dummy key that we are using for this example.
511It should be the name of the file containing the keys.
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530512
Nishanth Menonb7ee22f2023-07-27 13:58:48 -0500513.. note::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530514
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530515 Generating new set of keys:
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530516
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530517 .. prompt:: bash $
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530518
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530519 mkdir keys
520 openssl genpkey -algorithm RSA -out keys/dev.key \
521 -pkeyopt rsa_keygen_bits:4096 -pkeyopt rsa_keygen_pubexp:65537
522 openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530523
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530524Generating the fitImage
525^^^^^^^^^^^^^^^^^^^^^^^
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530526
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530527.. note::
528
529 For signing a secondary platform like SK boards, you'll require
530 additional steps
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530531
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530532 - Change the CONFIG_DEFAULT_DEVICE_TREE
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530533
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530534 For e.g
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530535
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530536 .. code-block::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530537
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530538 diff --git a/configs/j721e_evm_a72_defconfig b/configs/j721e_evm_a72_defconfig
539 index a5c1df7e0054..6d0126d955ef 100644
540 --- a/configs/j721e_evm_a72_defconfig
541 +++ b/configs/j721e_evm_a72_defconfig
542 @@ -13,7 +13,7 @@ CONFIG_CUSTOM_SYS_INIT_SP_ADDR=0x80480000
543 CONFIG_ENV_SIZE=0x20000
544 CONFIG_DM_GPIO=y
545 CONFIG_SPL_DM_SPI=y
546 -CONFIG_DEFAULT_DEVICE_TREE="k3-j721e-common-proc-board"
547 +CONFIG_DEFAULT_DEVICE_TREE="k3-j721e-sk"
548 CONFIG_SPL_TEXT_BASE=0x80080000
549 CONFIG_DM_RESET=y
550 CONFIG_SPL_MMC=y
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530551
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530552 - Change the binman nodes to package u-boot.dtb for the correct set of platform
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530553
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530554 For e.g
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530555
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530556 .. code-block::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530557
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530558 diff --git a/arch/arm/dts/k3-j721e-binman.dtsi b/arch/arm/dts/k3-j721e-binman.dtsi
559 index 673be646b1e3..752fa805fe8d 100644
560 --- a/arch/arm/dts/k3-j721e-binman.dtsi
561 +++ b/arch/arm/dts/k3-j721e-binman.dtsi
562 @@ -299,8 +299,8 @@
563 #define SPL_J721E_SK_DTB "spl/dts/k3-j721e-sk.dtb"
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530564
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530565 #define UBOOT_NODTB "u-boot-nodtb.bin"
566 -#define J721E_EVM_DTB "u-boot.dtb"
567 -#define J721E_SK_DTB "arch/arm/dts/k3-j721e-sk.dtb"
568 +#define J721E_EVM_DTB "arch/arm/dts/k3-j721e-common-proc-board.dtb"
569 +#define J721E_SK_DTB "u-boot.dtb"
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530570
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530571This step will embed the public key in the u-boot.dtb file that was already
572built during the initial u-boot build.
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530573
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530574.. prompt:: bash $
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530575
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530576 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 +0530577
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530578.. note::
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530579
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530580 If you have another set of keys then change the -k argument to point to
581 the folder where your keys are present, the build requires the presence
582 of both .key and .crt file.
583
584Build u-boot again
585^^^^^^^^^^^^^^^^^^
586
587The updated u-boot.dtb needs to be packed in u-boot.img for authentication
588so rebuild U-boot ARMV8 without changing any parameters.
589Refer (:ref:`U-boot ARMV8 build <k3_rst_include_start_build_steps_uboot>`)
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530590
591.. note::
592
Manorit Chawdhryf64b3bd2023-12-29 16:16:32 +0530593 The devices now also have distroboot enabled so if the FIT image doesn't
594 work then the fallback to normal distroboot will be there on HS devices.
595 This will need to be explicitly disabled by changing the boot_targets to
596 disallow fallback during testing.
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530597
598Saving environment
599------------------
600
601SAVEENV is disabled by default and for the new flow uses Uenv.txt as the default
602way for saving the environments. This has been done as Uenv.txt is more granular
603then the saveenv command and can be used across various bootmodes too.
604
605**Writing to MMC/EMMC**
606
Nishanth Menon740c41c2023-11-02 23:40:25 -0500607.. prompt:: bash =>
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530608
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500609 env export -t $loadaddr <list of variables>
610 fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530611
612**Reading from MMC/EMMC**
613
614By default run envboot will read it from the MMC/EMMC partition ( based on
615mmcdev) and set the environments.
616
617If manually needs to be done then the environment can be read from the
618filesystem and then imported
619
Nishanth Menon740c41c2023-11-02 23:40:25 -0500620.. prompt:: bash =>
Manorit Chawdhryce7a62f2023-07-14 11:22:29 +0530621
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500622 fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
623 env import -t ${loadaddr} ${filesize}
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500624
625.. _k3_rst_refer_openocd:
626
627Common Debugging environment - OpenOCD
628--------------------------------------
629
630This section will show you how to connect a board to `OpenOCD
631<https://openocd.org/>`_ and load the SPL symbols for debugging with
632a K3 generation device. To follow this guide, you must build custom
633u-boot binaries, start your board from a boot media such as an SD
634card, and use an OpenOCD environment. This section uses generic
635examples, though you can apply these instructions to any supported K3
636generation device.
637
638The overall structure of this setup is in the following figure.
639
640.. image:: img/openocd-overview.svg
Nishanth Menon5746e032023-08-22 11:40:56 -0500641 :alt: Overview of OpenOCD setup.
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500642
643.. note::
644
645 If you find these instructions useful, please consider `donating
646 <https://openocd.org/pages/donations.html>`_ to OpenOCD.
647
648Step 1: Download and install OpenOCD
649^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
650
651To get started, it is more convenient if the distribution you
652use supports OpenOCD by default. Follow the instructions in the
653`getting OpenOCD <https://openocd.org/pages/getting-openocd.html>`_
654documentation to pick the installation steps appropriate to your
655environment. Some references to OpenOCD documentation:
656
657* `OpenOCD User Guide <https://openocd.org/doc/html/index.html>`_
658* `OpenOCD Developer's Guide <https://openocd.org/doc/doxygen/html/index.html>`_
659
660Refer to the release notes corresponding to the `OpenOCD version
661<https://github.com/openocd-org/openocd/releases>`_ to ensure
662
663* Processor support: In general, processor support shouldn't present
664 any difficulties since OpenOCD provides solid support for both ARMv8
665 and ARMv7.
666* SoC support: When working with System-on-a-Chip (SoC), the support
667 usually comes as a TCL config file. It is vital to ensure the correct
668 version of OpenOCD or to use the TCL files from the latest release or
669 the one mentioned.
670* Board or the JTAG adapter support: In most cases, board support is
671 a relatively easy problem if the board has a JTAG pin header. All
672 you need to do is ensure that the adapter you select is compatible
673 with OpenOCD. Some boards come with an onboard JTAG adapter that
674 requires a USB cable to be plugged into the board, in which case, it
675 is vital to ensure that the JTAG adapter is supported. Fortunately,
676 almost all TI K3 SK/EVMs come with TI's XDS110, which has out of the
677 box support by OpenOCD. The board-specific documentation will
678 cover the details and any adapter/dongle recommendations.
679
Nishanth Menon740c41c2023-11-02 23:40:25 -0500680.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500681
682 openocd -v
683
684.. note::
685
686 OpenOCD version 0.12.0 is usually required to connect to most K3
687 devices. If your device is only supported by a newer version than the
688 one provided by your distribution, you may need to build it from the source.
689
690Building OpenOCD from source
691""""""""""""""""""""""""""""
692
693The dependency package installation instructions below are for Debian
694systems, but equivalent instructions should exist for systems with
695other package managers. Please refer to the `OpenOCD Documentation
696<https://openocd.org/>`_ for more recent installation steps.
697
Nishanth Menon740c41c2023-11-02 23:40:25 -0500698.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500699
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500700 # Check the packages to be installed: needs deb-src in sources.list
701 sudo apt build-dep openocd
702 # The following list is NOT complete - please check the latest
703 sudo apt-get install libtool pkg-config texinfo libusb-dev \
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500704 libusb-1.0.0-dev libftdi-dev libhidapi-dev autoconf automake
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500705 git clone https://github.com/openocd-org/openocd.git openocd
706 cd openocd
707 git submodule init
708 git submodule update
709 ./bootstrap
710 ./configure --prefix=/usr/local/
711 make -j`nproc`
712 sudo make install
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500713
714.. note::
715
716 The example above uses the GitHub mirror site. See
717 `git repo information <https://openocd.org/doc/html/Developers.html#OpenOCD-Git-Repository>`_
718 information to pick the official git repo.
719 If a specific version is desired, select the version using `git checkout tag`.
720
721Installing OpenOCD udev rules
722"""""""""""""""""""""""""""""
723
724The step is not necessary if the distribution supports the OpenOCD, but
725if building from a source, ensure that the udev rules are installed
726correctly to ensure a sane system.
727
Nishanth Menon740c41c2023-11-02 23:40:25 -0500728.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500729
730 # Go to the OpenOCD source directory
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500731 cd openocd
732 Copy the udev rules to the correct system location
733 sudo cp ./contrib/60-openocd.rules \
Jonathan Humphreys27fd4982023-08-22 13:49:03 -0500734 ./src/jtag/drivers/libjaylink/contrib/99-libjaylink.rules \
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500735 /etc/udev/rules.d/
736 # Get Udev to load the new rules up
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500737 sudo udevadm control --reload-rules
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500738 # Use the new rules on existing connected devices
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500739 sudo udevadm trigger
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500740
741Step 2: Setup GDB
742^^^^^^^^^^^^^^^^^
743
744Most systems come with gdb-multiarch package.
745
Nishanth Menon740c41c2023-11-02 23:40:25 -0500746.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500747
748 # Install gdb-multiarch package
Nishanth Menon55fbcae2023-08-24 10:40:36 -0500749 sudo apt-get install gdb-multiarch
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500750
751Though using GDB natively is normal, developers with interest in using IDE
752may find a few of these interesting:
753
754* `gdb-dashboard <https://github.com/cyrus-and/gdb-dashboard>`_
755* `gef <https://github.com/hugsy/gef>`_
756* `peda <https://github.com/longld/peda>`_
757* `pwndbg <https://github.com/pwndbg/pwndbg>`_
758* `voltron <https://github.com/snare/voltron>`_
759* `ddd <https://www.gnu.org/software/ddd/>`_
760* `vscode <https://www.justinmklam.com/posts/2017/10/vscode-debugger-setup/>`_
761* `vim conque-gdb <https://github.com/vim-scripts/Conque-GDB>`_
762* `emacs realgud <https://github.com/realgud/realgud/wiki/gdb-notes>`_
763* `Lauterbach IDE <https://www2.lauterbach.com/pdf/backend_gdb.pdf>`_
764
765.. warning::
766 LLDB support for OpenOCD is still a work in progress as of this writing.
767 Using GDB is probably the safest option at this point in time.
768
769Step 3: Connect board to PC
770^^^^^^^^^^^^^^^^^^^^^^^^^^^
771There are few patterns of boards in the ecosystem
772
773.. k3_rst_include_start_openocd_connect_XDS110
774
775**Integrated JTAG adapter/dongle**: The board has a micro-USB connector labelled
776XDS110 USB or JTAG. Connect a USB cable to the board to the mentioned port.
777
778.. note::
779
780 There are multiple USB ports on a typical board, So, ensure you have read
781 the user guide for the board and confirmed the silk screen label to ensure
782 connecting to the correct port.
783
784.. k3_rst_include_end_openocd_connect_XDS110
785
786.. k3_rst_include_start_openocd_connect_cti20
787
788**cTI20 connector**: The TI's `cTI20
789<https://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_JTAG_connectors.html#cti-20-pin-header-information>`_ connector
790is probably the most prevelant on TI platforms. Though many
791TI boards have an onboard XDS110, cTI20 connector is usually
792provided as an alternate scheme to connect alternatives such
793as `Lauterbach <https://www.lauterbach.com/>`_ or `XDS560
794<https://www.ti.com/tool/TMDSEMU560V2STM-U>`_.
795
796To debug on these boards, the following combinations is suggested:
797
798* `TUMPA <https://www.diygadget.com/JTAG-cables-and-microcontroller-programmers/tiao-usb-multi-protocol-adapter-JTAG-spi-i2c-serial>`_
799 or `equivalent dongles supported by OpenOCD. <https://openocd.org/doc/html/Debug-Adapter-Hardware.html#Debug-Adapter-Hardware>`_
800* Cable such as `Tag-connect ribbon cable <https://www.tag-connect.com/product/20-pin-cortex-ribbon-cable-4-length-with-50-mil-connectors>`_
801* Adapter to convert cTI20 to ARM20 such as those from
802 `Segger <https://www.segger.com/products/debug-probes/j-link/accessories/adapters/ti-cti-20-adapter/>`_
803 or `Lauterbach LA-3780 <https://www.lauterbach.com/ad3780.html>`_
804 Or optionally, if you have manufacturing capability then you could try
805 `BeagleBone JTAG Adapter <https://github.com/mmorawiec/BeagleBone-Black-JTAG-Adapters>`_
806
807.. warning::
808 XDS560 and Lauterbach are proprietary solutions and is not supported by
809 OpenOCD.
810 When purchasing an off the shelf adapter/dongle, you do want to be careful
811 about the signalling though. Please
812 `read for additional info <https://software-dl.ti.com/ccs/esd/xdsdebugprobes/emu_JTAG_connectors.html>`_.
813
814.. k3_rst_include_end_openocd_connect_cti20
815
816.. k3_rst_include_start_openocd_connect_tag_connect
817
818**Tag-Connect**: `Tag-Connect <https://www.tag-connect.com/>`_
819pads on the boards which require special cable. Please check the documentation
820to `identify <https://www.tag-connect.com/info/legs-or-no-legs>`_ if "legged"
821or "no-leg" version of the cable is appropriate for the board.
822
823To debug on these boards, you will need:
824
825* `TUMPA <https://www.diygadget.com/JTAG-cables-and-microcontroller-programmers/tiao-usb-multi-protocol-adapter-JTAG-spi-i2c-serial>`_
826 or `equivalent dongles supported by OpenOCD <https://openocd.org/doc/html/Debug-Adapter-Hardware.html#Debug-Adapter-Hardware>`_.
827* Tag-Connect cable appropriate to the board such as
828 `TC2050-IDC-NL <https://www.tag-connect.com/product/TC2050-IDC-NL-10-pin-no-legs-cable-with-ribbon-connector>`_
829* In case of no-leg, version, a
830 `retaining clip <https://www.tag-connect.com/product/tc2050-clip-3pack-retaining-clip>`_
831* Tag-Connect to ARM20
832 `adapter <https://www.tag-connect.com/product/tc2050-arm2010-arm-20-pin-to-tc2050-adapter>`_
833
834.. note::
835 You can optionally use a 3d printed solution such as
836 `Protective cap <https://www.thingiverse.com/thing:3025584>`_ or
837 `clip <https://www.thingiverse.com/thing:3035278>`_ to replace
838 the retaining clip.
839
840.. warning::
841 With the Tag-Connect to ARM20 adapter, Please solder the "Trst" signal for
842 connection to work.
843
844.. k3_rst_include_end_openocd_connect_tag_connect
845
846Debugging with OpenOCD
847^^^^^^^^^^^^^^^^^^^^^^
848
849Debugging U-Boot is different from debugging regular user space
850applications. The bootloader initialization process involves many boot
851media and hardware configuration operations. For K3 devices, there
852are also interactions with security firmware. While reloading the
853"elf" file works through GDB, developers must be mindful of cascading
854initialization's potential consequences.
855
856Consider the following code change:
857
858.. code-block:: diff
859
860 --- a/file.c 2023-07-29 10:55:29.647928811 -0500
861 +++ b/file.c 2023-07-29 10:55:46.091856816 -0500
862 @@ -1,3 +1,3 @@
863 val = readl(reg);
864 -val |= 0x2;
865 +val |= 0x1;
866 writel(val, reg);
867
868Re-running the elf file with the above change will result in the
869register setting 0x3 instead of the intended 0x1. There are other
870hardware blocks which may not behave very well with a re-initialization
871without proper shutdown.
872
873To help narrow the debug down, it is usually simpler to use the
874standard boot media to get to the bootloader and debug only in the area
875of interest.
876
877In general, to debug u-boot spl/u-boot with OpenOCD there are three steps:
878
879* Modify the code adding a loop to allow the debugger to attach
880 near the point of interest. Boot up normally to stop at the loop.
881* Connect with OpenOCD and step out of the loop.
882* Step through the code to find the root of issue.
883
884Typical debugging involves a few iterations of the above sequence.
885Though most bootloader developers like to use printf to debug,
886debug with JTAG tends to be most efficient since it is possible to
887investigate the code flow and inspect hardware registers without
888repeated iterations.
889
890Code modification
891"""""""""""""""""
892
893* **start.S**: Adding an infinite while loop at the very entry of
894 U-Boot. For this, look for the corresponding start.S entry file.
895 This is usually only required when debugging some core SoC or
896 processor related function. For example: arch/arm/cpu/armv8/start.S or
897 arch/arm/cpu/armv7/start.S
898
899.. code-block:: diff
900
901 diff --git a/arch/arm/cpu/armv7/start.S b/arch/arm/cpu/armv7/start.S
902 index 69e281b086..744929e825 100644
903 --- a/arch/arm/cpu/armv7/start.S
904 +++ b/arch/arm/cpu/armv7/start.S
905 @@ -37,6 +37,8 @@
906 #endif
907
908 reset:
909 +dead_loop:
910 + b dead_loop
911 /* Allow the board to save important registers */
912 b save_boot_params
913 save_boot_params_ret:
914
915* **board_init_f**: Adding an infinite while loop at the board entry
916 function. In many cases, it is important to debug the boot process if
917 any changes are made for board-specific applications. Below is a step
918 by step process for debugging the boot SPL or Armv8 SPL:
919
920 To debug the boot process in either domain, we will first
921 add a modification to the code we would like to debug.
922 In this example, we will debug ``board_init_f`` inside
923 ``arch/arm/mach-k3/{soc}_init.c``. Since some sections of U-Boot
924 will be executed multiple times during the bootup process of K3
Jonathan Humphreys27fd4982023-08-22 13:49:03 -0500925 devices, we will need to include either ``CONFIG_ARM64`` or
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500926 ``CONFIG_CPU_V7R`` to catch the CPU at the desired place during the
927 bootup process (Main or Wakeup domains). For example, modify the
928 file as follows (depending on need):
929
930.. code-block:: c
931
932 void board_init_f(ulong dummy)
933 {
934 .
935 .
936 /* Code to run on the R5F (Wakeup/Boot Domain) */
937 if (IS_ENABLED(CONFIG_CPU_V7R)) {
938 volatile int x = 1;
939 while(x) {};
940 }
941 ...
942 /* Code to run on the ARMV8 (Main Domain) */
Jonathan Humphreys27fd4982023-08-22 13:49:03 -0500943 if (IS_ENABLED(CONFIG_ARM64)) {
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500944 volatile int x = 1;
945 while(x) {};
946 }
947 .
948 .
949 }
950
951Connecting with OpenOCD for a debug session
952"""""""""""""""""""""""""""""""""""""""""""
953
954Startup OpenOCD to debug the platform as follows:
955
956* **Integrated JTAG interface**: If the evm has a debugger such as
957 XDS110 inbuilt, there is typically an evm board support added and a
958 cfg file will be available.
959
960.. k3_rst_include_start_openocd_cfg_XDS110
961
Nishanth Menon740c41c2023-11-02 23:40:25 -0500962.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500963
964 openocd -f board/{board_of_choice}.cfg
965
966.. k3_rst_include_end_openocd_cfg_XDS110
967
968.. k3_rst_include_start_openocd_cfg_external_intro
969
970* **External JTAG adapter/interface**: In other cases, where an
971 adapter/dongle is used, a simple cfg file can be created to integrate the
972 SoC and adapter information. See `supported TI K3 SoCs
973 <https://github.com/openocd-org/openocd/blob/master/tcl/target/ti_k3.cfg#L59>`_
974 to decide if the SoC is supported or not.
975
Nishanth Menon740c41c2023-11-02 23:40:25 -0500976.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -0500977
978 openocd -f openocd_connect.cfg
979
980.. k3_rst_include_end_openocd_cfg_external_intro
981
982 For example, with BeaglePlay (AM62X platform), the openocd_connect.cfg:
983
984.. code-block:: tcl
985
986 # TUMPA example:
987 # http://www.tiaowiki.com/w/TIAO_USB_Multi_Protocol_Adapter_User's_Manual
988 source [find interface/ftdi/tumpa.cfg]
989
990 transport select jtag
991
992 # default JTAG configuration has only SRST and no TRST
993 reset_config srst_only srst_push_pull
994
995 # delay after SRST goes inactive
996 adapter srst delay 20
997
998 if { ![info exists SOC] } {
999 # Set the SoC of interest
1000 set SOC am625
1001 }
1002
1003 source [find target/ti_k3.cfg]
1004
1005 ftdi tdo_sample_edge falling
1006
1007 # Speeds for FT2232H are in multiples of 2, and 32MHz is tops
1008 # max speed we seem to achieve is ~20MHz.. so we pick 16MHz
1009 adapter speed 16000
1010
1011Below is an example of the output of this command:
1012
1013.. code-block:: console
1014
1015 Info : Listening on port 6666 for tcl connections
1016 Info : Listening on port 4444 for telnet connections
1017 Info : XDS110: connected
1018 Info : XDS110: vid/pid = 0451/bef3
1019 Info : XDS110: firmware version = 3.0.0.20
1020 Info : XDS110: hardware version = 0x002f
1021 Info : XDS110: connected to target via JTAG
1022 Info : XDS110: TCK set to 2500 kHz
1023 Info : clock speed 2500 kHz
1024 Info : JTAG tap: am625.cpu tap/device found: 0x0bb7e02f (mfg: 0x017 (Texas Instruments), part: 0xbb7e, ver: 0x0)
1025 Info : starting gdb server for am625.cpu.sysctrl on 3333
1026 Info : Listening on port 3333 for gdb connections
1027 Info : starting gdb server for am625.cpu.a53.0 on 3334
1028 Info : Listening on port 3334 for gdb connections
1029 Info : starting gdb server for am625.cpu.a53.1 on 3335
1030 Info : Listening on port 3335 for gdb connections
1031 Info : starting gdb server for am625.cpu.a53.2 on 3336
1032 Info : Listening on port 3336 for gdb connections
1033 Info : starting gdb server for am625.cpu.a53.3 on 3337
1034 Info : Listening on port 3337 for gdb connections
1035 Info : starting gdb server for am625.cpu.main0_r5.0 on 3338
1036 Info : Listening on port 3338 for gdb connections
1037 Info : starting gdb server for am625.cpu.gp_mcu on 3339
1038 Info : Listening on port 3339 for gdb connections
1039
1040.. note::
1041 Notice the default configuration is non-SMP configuration allowing
1042 for each of the core to be attached and debugged simultaneously.
1043 ARMv8 SPL/U-Boot starts up on cpu0 of a53/a72.
1044
1045.. k3_rst_include_start_openocd_cfg_external_gdb
1046
1047To debug using this server, use GDB directly or your preferred
1048GDB-based IDE. To start up GDB in the terminal, run the following
1049command.
1050
Nishanth Menon740c41c2023-11-02 23:40:25 -05001051.. prompt:: bash $
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001052
1053 gdb-multiarch
1054
1055To connect to your desired core, run the following command within GDB:
1056
Nishanth Menon740c41c2023-11-02 23:40:25 -05001057.. prompt:: bash (gdb)
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001058
1059 target extended-remote localhost:{port for desired core}
1060
1061To load symbols:
1062
1063.. warning::
1064
1065 SPL and U-Boot does a re-location of address compared to where it
1066 is loaded originally. This step takes place after the DDR size is
1067 determined from dt parsing. So, debugging can be split into either
1068 "before re-location" or "after re-location". Please refer to the
1069 file ''doc/README.arm-relocation'' to see how to grab the relocation
1070 address.
1071
1072* Prior to relocation:
1073
Nishanth Menon740c41c2023-11-02 23:40:25 -05001074.. prompt:: bash (gdb)
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001075
1076 symbol-file {path to elf file}
1077
1078* After relocation:
1079
Nishanth Menon740c41c2023-11-02 23:40:25 -05001080.. prompt:: bash (gdb)
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001081
1082 # Drop old symbol file
1083 symbol-file
1084 # Pick up new relocaddr
1085 add-symbol-file {path to elf file} {relocaddr}
1086
1087.. k3_rst_include_end_openocd_cfg_external_gdb
1088
1089In the above example of AM625,
1090
Nishanth Menon740c41c2023-11-02 23:40:25 -05001091.. prompt:: bash (gdb)
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001092
1093 target extended-remote localhost:3338 <- R5F (Wakeup Domain)
1094 target extended-remote localhost:3334 <- A53 (Main Domain)
1095
1096The core can now be debugged directly within GDB using GDB commands or
1097if using IDE, as appropriate to the IDE.
1098
1099Stepping through the code
1100"""""""""""""""""""""""""
1101
1102`GDB TUI Commands
1103<https://sourceware.org/gdb/onlinedocs/gdb/TUI-Commands.html>`_ can
1104help set up the display more sensible for debug. Provide the name
1105of the layout that can be used to debug. For example, use the GDB
1106command ``layout src`` after loading the symbols to see the code and
1107breakpoints. To exit the debug loop added above, add any breakpoints
1108needed and run the following GDB commands to step out of the debug
1109loop set in the ``board_init_f`` function.
1110
Nishanth Menon740c41c2023-11-02 23:40:25 -05001111.. prompt:: bash (gdb)
Jason Kacinesb0fdee92023-08-03 01:29:22 -05001112
1113 set x = 0
1114 continue
1115
1116The platform has now been successfully setup to debug with OpenOCD
1117using GDB commands or a GDB-based IDE. See `OpenOCD documentation for
1118GDB <https://openocd.org/doc/html/GDB-and-OpenOCD.html>`_ for further
1119information.
1120
1121.. warning::
1122
1123 On the K3 family of devices, a watchdog timer within the DMSC is
1124 enabled by default by the ROM bootcode with a timeout of 3 minutes.
1125 The watchdog timer is serviced by System Firmware (SYSFW) or TI
1126 Foundational Security (TIFS) during normal operation. If debugging
1127 the SPL before the SYSFW is loaded, the watchdog timer will not get
1128 serviced automatically and the debug session will reset after 3
1129 minutes. It is recommended to start debugging SPL code only after
1130 the startup of SYSFW to avoid running into the watchdog timer reset.
1131
1132Miscellaneous notes with OpenOCD
1133^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1134
1135Currently, OpenOCD does not support tracing for K3 platforms. Tracing
1136function could be beneficial if the bug in code occurs deep within
1137nested function and can optionally save developers major trouble of
1138stepping through a large quantity of code.