[PATCH] docs: boards: ti: add openocd spl debugging docs
Heinrich Schuchardt
xypron.glpk at gmx.de
Fri Jul 28 08:52:52 CEST 2023
On 7/21/23 21:19, Jason Kacines wrote:
> 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>
Thank you for providing OpenOCD usage guidance.
This patch cannot be applied to origin/master. Please, rebase it.
Please, remove trailing spaces.
Please, try to avoid lines over 80 characters. See below.
> ---
> 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
Users don't like scrolling horizontally. Please, put the comments above
or below the output lines.
> + [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``
Please void lines above 80 characters.
Best regards
Heinrich
> +#. 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
More information about the U-Boot
mailing list