doc: board: ti: k3: Add a guide to debugging with OpenOCD
PATCH v2 1/1 doc: board: ti: k3: Add a guide to debugging with OpenOCD
From: Jason Kacines <[email protected]>
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.
---
Changes since V1:
* Merged into k3.rst and added anchors for include, reference to other files
* Added documentation for other board documentation.
V1: https://lore.kernel.org/u-boot/[email protected]/
doc/board/ti/am62x_sk.rst | 16 + doc/board/ti/am65x_evm.rst | 16 + doc/board/ti/img/openocd-overview.svg | 580 ++++++++++++++++++++++++++ doc/board/ti/j7200_evm.rst | 16 + doc/board/ti/j721e_evm.rst | 16 + doc/board/ti/k3.rst | 468 +++++++++++++++++++++ 6 files changed, 1112 insertions(+) create mode 100644 doc/board/ti/img/openocd-overview.svg
doc/board/ti/am62x_sk.rst +16 -0
@@ -246,3 +246,19 @@ https://www.ti.com/lit/pdf/spruiv7 under the `Boot Mode Pins` section. - 11001010 For SW2 and SW1, the switch state in the "ON" position = 1. + +Debugging U-boot +---------------- + +See :ref:`Common Debugging environment - openOCD<k3_rst_refer_openocd>`: for +detailed setup information. + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_openocd_connect_xds110 + :end-before: .. k3_rst_include_end_openocd_connect_xds110 + +To start OpenOCD to connect to the board + +.. code-block:: bash + + openocd -f board/ti_am625evm.cfg
doc/board/ti/am65x_evm.rst +16 -0
@@ -287,3 +287,19 @@ artifacts needed to the device: sb --ymodem tispl.bin > $MAIN_DEV < $MAIN_DEV sleep 1 sb --xmodem u-boot.img > $MAIN_DEV < $MAIN_DEV + +Debugging U-boot +---------------- + +See :ref:`Common Debugging environment - openOCD<k3_rst_refer_openocd>`: for +detailed setup information. + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_openocd_connect_xds110 + :end-before: .. k3_rst_include_end_openocd_connect_xds110 + +To start OpenOCD to connect to the board + +.. code-block:: bash + + openocd -f board/ti_am654evm.cfg
doc/board/ti/img/openocd-overview.svg new file +580 -0
580 lines not on this page · raw message
doc/board/ti/j7200_evm.rst +16 -0
@@ -201,3 +201,19 @@ fat formatted UDA FS as file. In case of booting from eMMC, write above images into raw or UDA FS. and set mmc partconf accordingly. + +Debugging U-boot +---------------- + +See :ref:`Common Debugging environment - openOCD<k3_rst_refer_openocd>`: for +detailed setup information. + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_openocd_connect_xds110 + :end-before: .. k3_rst_include_end_openocd_connect_xds110 + +To start OpenOCD to connect to the board + +.. code-block:: bash + + openocd -f board/ti_j7200evm.cfg
doc/board/ti/j721e_evm.rst +16 -0
@@ -228,3 +228,19 @@ J721E common processor board can be attached to a Ethernet QSGMII card and the PHY in the card has to be reset before it can be used for data transfer. "do_main_cpsw0_qsgmii_phyinit" env variable has to be set for the U-BOOT to configure this PHY. + +Debugging U-boot +---------------- + +See :ref:`Common Debugging environment - openOCD<k3_rst_refer_openocd>`: for +detailed setup information. + +.. include:: k3.rst + :start-after: .. k3_rst_include_start_openocd_connect_xds110 + :end-before: .. k3_rst_include_end_openocd_connect_xds110 + +To start OpenOCD to connect to the board + +.. code-block:: bash + + openocd -f board/ti_j721eevm.cfg
doc/board/ti/k3.rst +468 -0
471 lines not on this page · raw message
Signature · 1 line
2.37.2
Hi Nishanth
Quoted 16 lines · Nishanth Menon
From: Jason Kacines <[email protected]>
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 <[email protected]>Signed-off-by Nishanth Menon <[email protected]>---
[...]
doc/board/ti/k3.rst filesystem and then imported · line 521
Quoted 7 lines
doc/board/ti/k3.rst +7
-0+* 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
Quoted 6 lines
doc/board/ti/k3.rst +6
-0+ of box with OpenOCD. The board specific documentation will cover the + details and any adapter recommendations. + +.. code-block:: bash + + openocd -v
[...]
doc/board/ti/k3.rst filesystem and then imported · line 633
Quoted 5 lines
doc/board/ti/k3.rst +5
-0+ +**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
doc/board/ti/k3.rst filesystem and then imported · line 635
Quoted 2 lines
doc/board/ti/k3.rst +2
-0+provided as an alternate scheme to connect alternatives such +as `Lauterbach <https://www.lauterbach.com/>`_ or `xds560
s/xds560/XDS560
doc/board/ti/k3.rst filesystem and then imported · line 647
Quoted 12 lines
+<https://www.ti.com/tool/TMDSEMU560V2STM-U>`_.
doc/board/ti/k3.rst +11
-0+ +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
Quoted 12 lines
doc/board/ti/k3.rst +12
-0+ +.. 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/>`_
doc/board/ti/k3.rst filesystem and then imported · line 669
Quoted 10 lines
doc/board/ti/k3.rst +10
-0+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.
Quoted 36 lines
doc/board/ti/k3.rst +36
-0+* 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;
doc/board/ti/k3.rst filesystem and then imported · line 715
Quoted 10 lines
doc/board/ti/k3.rst +10
-0+ +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
Quoted 4 lines
doc/board/ti/k3.rst +4
-0+of interest. + +In general, to debug u-boot spl/u-boot with OpenOCD there are three steps: +
[...]
doc/board/ti/k3.rst filesystem and then imported · line 796
Quoted 6 lines
doc/board/ti/k3.rst +6
-0+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
Quoted 2 lines
doc/board/ti/k3.rst +2
-0+ xds110 inbuilt, there is typically an evm board support added and a + cfg file will be available.
[...]
doc/board/ti/k3.rst filesystem and then imported · line 937
Quoted 5 lines
doc/board/ti/k3.rst +5
-0+ +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!
Signature · 2 lines
Thanking You Neha Malcom Francis