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-kaci...@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-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 > > 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
