Add documentation on how to use OpenOCD to debug U-Boot for TI K3 Generation boards.
Signed-off-by: Jason Kacines <j-kaci...@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-kaci...@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
