[PATCH V2] doc: board: ti: k3: Add a guide to debugging with OpenOCD

[Neha Malcom Francis]

Hi Nishanth

On 30/07/23 02:15, Nishanth Menon wrote:
> From: Jason Kacines <j-kacines at ti.com>
> 
> Bootloader debug usually tends to be a bit dicey prior to DDR and
> serial port getting active in the system. JTAG typically remains the
> only practical debug option during the initial bringup.
> 
> OpenOCD is one of the most popular environment for providing debug
> capability via a gdb compatible interface for developers to work with.
> 
> Debugging U-boot and bootloaders on K3 platform does have a bit of
> tribal knowledge that is better documented in our common platform
> documentation.
> 
> Signed-off-by: Jason Kacines <j-kacines at ti.com>
> Signed-off-by: Nishanth Menon <nm at ti.com>
> ---

[...]

> +* Board or the jtag adapter is supported: In most cases, board support
> +  is a relatively easy problem to solve if the board has a jtag pin header.
> +  All you need to do is ensure that the adapter you select is compatible
> +  with OpenOCD. Some boards do come with onboard JTAG adapter that just
> +  needs a USB cable to be plugged into the board, in which case, it is
> +  important to ensure that the jtag adapter is supported. Fortunately,
> +  almost all TI K3 SK/EVMs come with TI's xds110 which is supported out

s/xds110/XDS110

> +  of box with OpenOCD. The board specific documentation will cover the
> +  details and any adapter recommendations.
> +
> +.. code-block:: bash
> +
> + openocd -v

[...]

> +
> +**cTI20 connector**: The TI's `cTI20
> +<https://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_jtag_connectors.html#cti-20-pin-header-information>`_ connector
> +is probably the most prevelant on TI platforms. Though many
> +TI boards do have onboard xds110, cTI20 connector is usually

s/xds110/XDS110

> +provided as an alternate scheme to connect alternatives such
> +as `Lauterbach <https://www.lauterbach.com/>`_ or `xds560

s/xds560/XDS560

> +<https://www.ti.com/tool/TMDSEMU560V2STM-U>`_.
> +
> +To debug on these boards, the following combinations is suggested:
> +
> +* `TUMPA <https://www.diygadget.com/jtag-cables-and-microcontroller-programmers/tiao-usb-multi-protocol-adapter-jtag-spi-i2c-serial>`_
> +  or equivalent supported by OpenOCD
> +* Cable such as `Tag-connect ribbon cable <https://www.tag-connect.com/product/20-pin-cortex-ribbon-cable-4-length-with-50-mil-connectors>`_
> +* Adapter to convert cTI20 to ARM20 such as those from
> +  `Segger <https://www.segger.com/products/debug-probes/j-link/accessories/adapters/ti-cti-20-adapter/>`_
> +  `Lauterbach LA-3780 <https://www.lauterbach.com/ad3780.html>`_
> +  Or optionally, if you have manufacturing capability then you could try
> +  `beagle bone jtag adapter <https://github.com/mmorawiec/BeagleBone-Black-JTAG-Adapters>`_

s/beagle bone jtag adapter/BeagleBone JTAG Adapter

> +
> +.. warning::
> +  XDS560 and Lauterbach are proprietary solutions and is not supported by
> +  OpenOCD.
> +  When purchasing off the shelf adapters, you do want to be careful about the
> +  signalling though. Please `read for additional info <https://software-dl.ti.com/ccs/esd/xdsdebugprobes/emu_jtag_connectors.html>`_
> +
> +.. k3_rst_include_end_openocd_connect_cti20
> +
> +.. k3_rst_include_start_openocd_connect_tag_connect
> +
> +**Tag-Connect**: `Tag-Connect <https://www.tag-connect.com/>`_
> +pads on the boards which require special cable. Please check the documentation
> +to `identify <https://www.tag-connect.com/info/legs-or-no-legs>`_ if "legged"
> +or "no-leg" version of the cable is appropriate for the board.
> +
> +To debug on these boards, you will need:
> +
> +* `TUMPA <https://www.diygadget.com/jtag-cables-and-microcontroller-programmers/tiao-usb-multi-protocol-adapter-jtag-spi-i2c-serial>`_
> +  or equivalent supported by OpenOCD
> +* Tag-Connect cable appropriate to the board such as
> +  `tc2050-idc-nl <https://www.tag-connect.com/product/tc2050-idc-nl-10-pin-no-legs-cable-with-ribbon-connector>`_

s/tc2050-idc-nl/TC2050-IDC-NL

There's few more instances of these below as well.

> +* In case of no-leg, version, a
> +  `retaining clip <https://www.tag-connect.com/product/tc2050-clip-3pack-retaining-clip>`_
> +* Tag-Connect to ARM20
> +  `adapter <https://www.tag-connect.com/product/tc2050-arm2010-arm-20-pin-to-tc2050-adapter>`_
> +
> +.. note::
> +  You can optionally use a 3d printed solution such as
> +  `Protective cap <https://www.thingiverse.com/thing:3025584>`_ or
> +  `clip <https://www.thingiverse.com/thing:3035278>`_ to replace
> +  the retaining clip.
> +
> +.. warning::
> +  With the Tag-Connect to ARM20 adapter, Please solder the "Trst" signal for
> +  connection to work.
> +
> +.. k3_rst_include_end_openocd_connect_tag_connect
> +
> +Debugging with OpenOCD
> +^^^^^^^^^^^^^^^^^^^^^^
> +
> +Debugging U-boot is different from debugging regular user space
> +applications. The bootloader initialization process involves many boot
> +media and hardware configuration operations. For K3 devices, there
> +are also interactions with security firmware. While reloading the
> +"elf" file works through gdb, developers must be mindful of cascading
> +initialization's potential consequences.
> +
> +Consider the following code change:
> +
> +.. code-block:: diff
> +
> +  --- a/file.c	2023-07-29 10:55:29.647928811 -0500
> +  +++ b/file.c	2023-07-29 10:55:46.091856816 -0500
> +  @@ -1,3 +1,3 @@
> +   val = readl(reg);
> +  -val |= 0x2;
> +  +val |= 0x1;
> +   writel(val, reg);
> +
> +Re-running the elf file with the above change will result in the
> +register setting 0x3 instead of the intended 0x1. There are other
> +hardware blocks which may not behave very well with re-initialization
> +sequence without proper shutdown.
> +
> +To help narrow the debug down, it is usually more simpler to use the
> +standard boot media to get to the booloader and debug only in the area

s/booloader/bootloader

> +of interest.
> +
> +In general, to debug u-boot spl/u-boot with OpenOCD there are three steps:
> +

[...]

> +Connecting with OpenOCD for debug session
> +"""""""""""""""""""""""""""""""""""""""""
> +
> +Startup openocd to debug the platform as follows:
> +
> +* **integrated jtag interface**: If the evm has a debugger such as

s/integrated/Integrated

> +  xds110 inbuilt, there is typically an evm board support added and a
> +  cfg file will be available.

[...]

> +
> +At the time of this writing openOCD does not support tracing for K3
> +platforms. Tracing function could be very useful if the bug in code
> +occurs deep within nested function and can optionally save developers
> +major trouble of stepping through large quantity of code.

But overall this patch is looking extremely helpful! Thanks!

-- 
Thanking You
Neha Malcom Francis