[PATCH] docs: boards: ti: add openocd spl debugging docs
Nishanth Menon
nm at ti.com
Fri Jul 28 14:48:18 CEST 2023
On 08:52-20230728, Heinrich Schuchardt wrote:
> 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.
Jason,
I will pick this patch up if you don't mind as part of my documentation
cleanup series. I think we will need to structure it a bit so that it is
re-usable across multiple platforms. I'd rather do that in a single shot
than have to deal with refactoring later.
>
> > ---
> > 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
>
--
Regards,
Nishanth Menon
Key (0xDDB5849D1736249D) / Fingerprint: F8A2 8693 54EB 8232 17A3 1A34 DDB5 849D 1736 249D
More information about the U-Boot
mailing list