[PATCH] docs: boards: ti: add openocd spl debugging docs
Jason Kacines
j-kacines at ti.com
Fri Jul 21 21:19:34 CEST 2023
Add documentation on how to use OpenOCD to debug U-Boot for TI K3
Generation boards.
Signed-off-by: Jason Kacines <j-kacines at ti.com>
---
doc/board/ti/am62x_openocd.rst | 248 +++++++++++++++++++++++++++++++++
doc/board/ti/k3.rst | 20 ++-
2 files changed, 265 insertions(+), 3 deletions(-)
create mode 100644 doc/board/ti/am62x_openocd.rst
diff --git a/doc/board/ti/am62x_openocd.rst b/doc/board/ti/am62x_openocd.rst
new file mode 100644
index 0000000000..4e33bd6f58
--- /dev/null
+++ b/doc/board/ti/am62x_openocd.rst
@@ -0,0 +1,248 @@
+.. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
+.. sectionauthor:: Jason Kacines <j-kacines at ti.com>
+
+Debugging SPL in OpenOCD
+========================
+
+The following section demonstrates how to connect a board to OpenOCD and
+load the SPL symbols for debugging with a K3 generation device. For the
+guide below, users are expected to generate custom binaries, boot their
+board from an SD card and work with OpenOCD in a Linux environment. This
+guide uses the AM625-SK for device specific examples but can be extended
+to any K3 generation device.
+
+Step 1: Downloading OpenOCD
+---------------------------
+
+Download OpenOCD using the following command.
+
+.. code-block:: bash
+
+ sudo apt-get install openocd
+
+.. note::
+
+ OpenOCD version 0.12.0 is required to connect to the AM625-SK. Some
+ major GNU/Linux distros do not support version 0.12.0. Check the
+ version of OpenOCD with ``openocd -v``
+
+**For OpenOCD installations prior to version 0.12.0:**
+
+Clone the OpenOCD source code (https://openocd.org/).
+
+.. code-block:: bash
+
+ git clone https://git.code.sf.net/p/openocd/code openocd-code
+
+Move the required config files to the package installation of OpenOCD.
+
+.. code-block:: bash
+
+ cd {OpenOCD Source}
+ cp tcl/board/ti_am625evm.cfg /usr/local/share/openocd/scripts/board
+ cp tcl/target/ti_k3.cfg /usr/local/share/openocd/scripts/target
+
+Now you can move on to SK/EVM Setup to prepare your SK/EVM for debugging.
+
+Step 2: SK/EVM Setup
+--------------------
+
+Make the appropriate board cable connections.
+
+.. note::
+
+ Ensure that the BOOT MODE switches are set appropriately for an SD
+ Card boot (refer to the TRM for boot mode switch settings). For
+ AM62x devices, refer to :doc:`/board/ti/am62x_sk`.
+
+After connecting each of the cables from the figure above, run the
+following command to ensure that each connection is established.
+
+.. code-block:: bash
+
+ sudo dmesg | grep tty
+
+An output similar to the figure below should appear.
+
+::
+
+ [XXXXXX.XXXXXX] usb 1-5.3.2.2: FTDI USB Serial Device converter now attached to ttyUSB0 <- Used for UART Flashing, UART boot, Linux Kernel, U-Boot
+ [XXXXXX.XXXXXX] usb 1-5.3.2.2: FTDI USB Serial Device converter now attached to ttyUSB1
+ [XXXXXX.XXXXXX] usb 1-5.3.2.2: FTDI USB Serial Device converter now attached to ttyUSB2 <- Used for Console for DM R5F (WKUP R5F)
+ [XXXXXX.XXXXXX] usb 1-5.3.2.2: FTDI USB Serial Device converter now attached to ttyUSB3 <- Used for Console on MCU M4F
+ [XXXXXX.XXXXXX] cdc_acm 1-5.3.1:1.0: ttyACM0: USB ACM device
+ [XXXXXX.XXXXXX] cdc_acm 1-5.3.1:1.3: ttyACM1: USB ACM device
+
+Open a serial connection with a baud rate of 115200 to view the kernel
+and U-Boot logs. Use the following command or a serial monitor of your
+choice.
+
+.. code-block:: bash
+
+ sudo picocom -b 115200 /dev/ttyUSB0
+
+Step 3: OpenOCD Debugging
+-------------------------
+
+Now that OpenOCD has been configured, launch an OpenOCD server with the
+following command.
+
+.. code-block:: bash
+
+ openocd -f board/ti_am625evm.cfg
+
+Below is an example of what the output of this command will print.
+
+::
+
+ Info : Listening on port 6666 for tcl connections
+ Info : Listening on port 4444 for telnet connections
+ Info : XDS110: connected
+ Info : XDS110: vid/pid = 0451/bef3
+ Info : XDS110: firmware version = 3.0.0.20
+ Info : XDS110: hardware version = 0x002f
+ Info : XDS110: connected to target via JTAG
+ Info : XDS110: TCK set to 2500 kHz
+ Info : clock speed 2500 kHz
+ Info : JTAG tap: am625.cpu tap/device found: 0x0bb7e02f (mfg: 0x017 (Texas Instruments), part: 0xbb7e, ver: 0x0)
+ Info : starting gdb server for am625.cpu.sysctrl on 3333
+ Info : Listening on port 3333 for gdb connections
+ Info : starting gdb server for am625.cpu.a53.0 on 3334
+ Info : Listening on port 3334 for gdb connections
+ Info : starting gdb server for am625.cpu.a53.1 on 3335
+ Info : Listening on port 3335 for gdb connections
+ Info : starting gdb server for am625.cpu.a53.2 on 3336
+ Info : Listening on port 3336 for gdb connections
+ Info : starting gdb server for am625.cpu.a53.3 on 3337
+ Info : Listening on port 3337 for gdb connections
+ Info : starting gdb server for am625.cpu.main0_r5.0 on 3338
+ Info : Listening on port 3338 for gdb connections
+ Info : starting gdb server for am625.cpu.gp_mcu on 3339
+ Info : Listening on port 3339 for gdb connections
+
+To debug using this server, use gdb directly or your preferred gdb-based
+IDE. To start up gdb in the terminal, run the following command.
+
+.. code-block:: bash
+
+ gdb-multiarch
+
+.. note::
+
+ This requires the use of the gdb-multiarch package to access shared
+ libraries. Use ``sudo apt-get install gdb-multiarch`` if necessary.
+
+To connect to your desired core, run the following command within gdb and
+load the symbols from the corresponding elf file.
+
+.. code-block:: bash
+
+ target extended-remote localhost:{port for desired core}
+ symbol-file {path to elf file}
+
+The core can now be debugged directly within gdb using gdb commands.
+
+Example: Debugging the Boot Process (Main and Wakeup Domains)
+-------------------------------------------------------------
+
+In many cases, it is important to debug the boot process if any changes
+are made for board-specific applications. Below is a step by step process
+for debugging the key domains for the boot process of AM62x devices.
+
+To debug the boot process in either domain, we will first add a
+modification in the code we would like to debug. In this example, we will
+debug ``board_init_f`` inside ``am625_init.c``. Since some sections of
+U-Boot will be executed multiple times during the bootup process of K3
+devices, we will need to include either ``CONFIG_CPU_ARM64`` or
+``CONFIG_CPU_V7R`` to catch the CPU at the desired place during the
+bootup process (Main or Wakeup domains).
+
+**Example: Main Domain Debugging (A53)**
+
+.. code-block:: c
+
+ void board_init_f(ulong dummy)
+ {
+ .
+ .
+ // Code to run on the A53 (Main Domain)
+ if (IS_ENABLED(CONFIG_CPU_ARM64)) {
+ volatile int x = 1;
+ while(x) {};
+ }
+ .
+ .
+ }
+
+Since this initialization is done within the SPL, it will run on the A53
+and R5F in both domains. In order to only run the new code in the Main
+Domain (A53), the ``CONFIG_CPU_ARM64`` conditional is used.
+
+**Example: Wakeup Domain Debugging (R5F)**
+
+.. code-block:: c
+
+ void board_init_f(ulong dummy)
+ {
+ .
+ .
+ // Code to run on the R5F (Wakeup Domain)
+ if (IS_ENABLED(CONFIG_CPU_V7R)) {
+ volatile int x = 1;
+ while(x) {};
+ }
+ .
+ .
+ }
+
+Since this initialization in done within the SPL, it will run on the A53
+and R5F in both domains. In order to only run our new code in the Wakeup
+Domain (R5F), the ``CONFIG_CPU_V7R`` conditional is used.
+
+**Building the Binaries and ELF Files**
+
+Build each of the required binaries (tiboot3.bin, tispl.bin, u-boot.img)
+to boot from an SD Card and locate the ELF of the SPL for the domain to
+debug.
+
+#. The SPL ELF for the Wakeup Domain (R5F) is located at ``u-boot/build/wkup/spl/u-boot-spl``
+#. The SPL ELF for the Main Domain (A53) is located at ``u-boot/build/main/spl/u-boot-spl``
+
+Boot the board using the SD Card with the custom binaries. The board
+should not boot to the kernel, since it has been stopped the debug code.
+
+Debugging
+---------
+
+Follow Step 3 to connect OpenOCD to the board using the port of the core
+you wish to debug.
+
+.. code-block:: bash
+
+ target extended-remote localhost:3338 <- R5F (Wakeup Domain)
+ target extended-remote localhost:3334 <- A53 (Main Domain)
+
+
+Use the gdb command ``lay next`` after loading the symbols to see the
+code and breakpoints. To exit the debug loop added above, add any
+breakpoints needed and run the following gdb commands.
+
+.. code-block:: bash
+
+ set x = 0
+ continue
+
+The SK/EVM has now been successfully setup to debug with OpenOCD using
+gdb commands or a gdb-based IDE.
+
+.. note::
+
+ On the K3 family of devices such as the AM62x, a watchdog timer
+ within the DMSC is enabled by default by the ROM bootcode with a
+ timeout of 3 minutes. The watchdog timer is serviced by System
+ Firmware (SYSFW) during normal operation. If debugging the SPL
+ before the SYSFW is loaded, the watchdog timer will not get serviced
+ automatically and the debug session will reset after 3 minutes. It
+ is recommended to start debugging SPL code only after the startup of
+ SYSFW to avoid running into the watchdog timer reset.
+
diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst
index b49a60caf1..b22ff82615 100644
--- a/doc/board/ti/k3.rst
+++ b/doc/board/ti/k3.rst
@@ -209,7 +209,7 @@ domain of your K3 SoC.
| `u-boot/build/wkup/tiboot3.bin`
| `k3-image-gen/sysfw-{SOC}-evm.bin`
-.. note ::
+.. note::
It's important to rename the generated `tiboot3.bin` and `sysfw.itb`
to match exactly `tiboot3.bin` and `sysfw.itb` as ROM and the wakeup
@@ -259,16 +259,30 @@ Sitara (`am6*`) devices use the `lite` option.
If your device uses a split firmware, you will also need to supply the
path to the Device Management (DM) Firmware to be included in the final
-`tispl.bin` binary
+`tispl.bin` binary.
.. code-block:: bash
DM=<path/to/ti-linux-firmware/ti-dm/ipc_echo_testb_mcu1_0_release_strip.xer5f>
At this point you should have every binary needed initialize both the
-wakeup and main domain and to boot to the U-Boot prompt
+wakeup and main domain and to boot to the U-Boot prompt.
**Main Domain Bootloader**
| `u-boot/build/main/tispl.bin`
| `u-boot/build/main/u-boot.img`
+
+.. note::
+
+ When generating the Main Domain binaries for secure devices, use
+ `tispl.bin_HS` and `u-boot.img_HS` and rename these files to match
+ exactly `tispl.bin` and `u-boot.img` to boot the device.
+
+Troubleshooting
+---------------
+
+.. toctree::
+ :maxdepth: 1
+
+ am62x_openocd
--
2.34.1
More information about the U-Boot
mailing list