Skip to contentSkip to conversation

doc: board: ti: k3: Add a guide to debugging with OpenOCD

PATCH Superseded Nishanth Menon 2 participants 2 messages Aug 1, 2023 – Aug 2, 2023

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

PATCH v3 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 V2:
* Review comments and further grammatical fixes
* Added openOCD version supported in each of the board documentation

V2: https://lore.kernel.org/all/[email protected]/
V1: https://lore.kernel.org/u-boot/[email protected]/

 doc/board/ti/am62x_sk.rst             |  24 ++
 doc/board/ti/am65x_evm.rst            |  24 ++
 doc/board/ti/img/openocd-overview.svg | 580 ++++++++++++++++++++++++++
 doc/board/ti/j7200_evm.rst            |  24 ++
 doc/board/ti/j721e_evm.rst            |  24 ++
 doc/board/ti/k3.rst                   | 481 +++++++++++++++++++++
 6 files changed, 1157 insertions(+)
 create mode 100644 doc/board/ti/img/openocd-overview.svg
doc/board/ti/am62x_sk.rst +24 -0
index 637985cb096e..9f577fe0f430 100644
@@ -246,3 +246,27 @@ 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.
+
+.. warning::
+
+  **OpenOCD support since**: v0.12.0
+
+  If the default package version of OpenOCD in your development
+  environment's distribution needs to be updated, it might be necessary to
+  build OpenOCD from the source.
+
+.. 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 +24 -0
index 0129235c2b29..60d18390959f 100644
@@ -287,3 +287,27 @@ 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.
+
+.. warning::
+
+  **OpenOCD support since**: v0.12.0
+
+  If the default package version of OpenOCD in your development
+  environment's distribution needs to be updated, it might be necessary to
+  build OpenOCD from the source.
+
+.. 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 +24 -0
index 69abc55a93ce..d5d5c10b2870 100644
@@ -201,3 +201,27 @@ 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.
+
+.. warning::
+
+  **OpenOCD support since**: v0.12.0
+
+  If the default package version of OpenOCD in your development
+  environment's distribution needs to be updated, it might be necessary to
+  build OpenOCD from the source.
+
+.. 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 +24 -0
index f4b4c192d9da..a9f441087938 100644
@@ -228,3 +228,27 @@ 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.
+
+.. warning::
+
+  **OpenOCD support since**: v0.12.0
+
+  If the default package version of OpenOCD in your development
+  environment's distribution needs to be updated, it might be necessary to
+  build OpenOCD from the source.
+
+.. 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 +481 -0

484 lines not on this page · raw message

Signature · 1 line
2.40.0
#1 lore raw
Quoted 8 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.

Thanks for documenting the usage of OpenOCD. I only have some nits:

%s/gdb/GDB/

Quoted 30 lines

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 V2:
* Review comments and further grammatical fixes
* Added openOCD version supported in each of the board documentation

V2: https://lore.kernel.org/all/[email protected]/
V1: https://lore.kernel.org/u-boot/[email protected]/

  doc/board/ti/am62x_sk.rst             |  24 ++
  doc/board/ti/am65x_evm.rst            |  24 ++
  doc/board/ti/img/openocd-overview.svg | 580 ++++++++++++++++++++++++++
  doc/board/ti/j7200_evm.rst            |  24 ++
  doc/board/ti/j721e_evm.rst            |  24 ++
  doc/board/ti/k3.rst                   | 481 +++++++++++++++++++++
  6 files changed, 1157 insertions(+)

create mode 100644 doc/board/ti/img/openocd-overview.svg

doc/board/ti/am62x_sk.rst +0 -0
index 637985cb096e..9f577fe0f430 100644

doc/board/ti/am62x_sk.rst https://www.ti.com/lit/pdf/spruiv7 under the `Boot Mode Pins` section. · line 250

Quoted 5 lines
doc/board/ti/am62x_sk.rst +2 -0
@@ -246,3 +246,27 @@ 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

%s/U-boot/U-Boot/

Quoted 8 lines
doc/board/ti/am62x_sk.rst +8 -0
+----------------
+
+See :ref:`Common Debugging environment - openOCD<k3_rst_refer_openocd>`: for
+detailed setup information.
+
+.. warning::
+
+  **OpenOCD support since**: v0.12.0

doc/board/ti/am62x_sk.rst https://www.ti.com/lit/pdf/spruiv7 under the `Boot Mode Pins` section. · line 268

Quoted 10 lines
doc/board/ti/am62x_sk.rst +10 -0
+
+  If the default package version of OpenOCD in your development
+  environment's distribution needs to be updated, it might be necessary to
+  build OpenOCD from the source.
+
+.. 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

Do you mean:

To start OpenOCD and connect to the board

Quoted 9 lines
doc/board/ti/am62x_sk.rst +4 -0
+
+.. code-block:: bash
+
+  openocd -f board/ti_am625evm.cfg
doc/board/ti/am65x_evm.rst +0 -0
index 0129235c2b29..60d18390959f 100644

doc/board/ti/am65x_evm.rst artifacts needed to the device: · line 291

Quoted 5 lines
doc/board/ti/am65x_evm.rst +2 -0
@@ -287,3 +287,27 @@ 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

%s/U-boot/U-Boot/

Quoted 8 lines
doc/board/ti/am65x_evm.rst +8 -0
+----------------
+
+See :ref:`Common Debugging environment - openOCD<k3_rst_refer_openocd>`: for
+detailed setup information.
+
+.. warning::
+
+  **OpenOCD support since**: v0.12.0

doc/board/ti/am65x_evm.rst artifacts needed to the device: · line 309

Quoted 10 lines
doc/board/ti/am65x_evm.rst +10 -0
+
+  If the default package version of OpenOCD in your development
+  environment's distribution needs to be updated, it might be necessary to
+  build OpenOCD from the source.
+
+.. 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

see above

Quoted 627 lines
doc/board/ti/am65x_evm.rst +4 -0
+
+.. code-block:: bash
+
+  openocd -f board/ti_am654evm.cfg
doc/board/ti/img/openocd-overview.svg new file +580 -0
new file mode 100644
index 000000000000..13a817132a45
@@ -0,0 +1,580 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!--SPDX-License-Identifier: GPL-2.0-or-later OR BSD-3-Clause-->
+
+<!--Copyright (C) 2023 Texas Instruments Incorporated - https://www.ti.com/-->
+
+<svg
+   xmlns:xhtml="http://www.w3.org/1999/xhtml"
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   version="1.1"
+   width="281px"
+   height="671px"
+   viewBox="-0.5 -0.5 281 671"
+   id="svg128"
+   sodipodi:docname="openocd-overview.svg"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)">
+  <metadata
+     id="metadata132">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <sodipodi:namedview
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="3440"
+     inkscape:window-height="1391"
+     id="namedview130"
+     showgrid="false"
+     inkscape:zoom="1.4068554"
+     inkscape:cx="283.8637"
+     inkscape:cy="385.05999"
+     inkscape:window-x="0"
+     inkscape:window-y="25"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="svg128" />
+  <defs
+     id="defs2" />
+  <g
+     id="g118">
+    <path
+       d="M 0 510 L 0 510 L 280 510 L 280 510"
+       fill="rgb(255, 255, 255)"
+       stroke="#ff0a1b"
+       stroke-miterlimit="10"
+       pointer-events="all"
+       id="path4" />
+    <path
+       d="M 0 510 L 0 670 L 280 670 L 280 510"
+       fill="none"
+       stroke="#ff0a1b"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path6" />
+    <rect
+       x="10"
+       y="590"
+       width="100"
+       height="70"
+       fill="#f8cecc"
+       stroke="#b85450"
+       pointer-events="none"
+       id="rect8" />
+    <path
+       d="M 20 590 L 20 660 M 100 590 L 100 660"
+       fill="none"
+       stroke="#b85450"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path10" />
+    <g
+       transform="translate(-0.5 -0.5)"
+       id="g16">
+      <switch
+         id="switch14">
+        <foreignObject
+           style="overflow: visible; text-align: left;"
+           pointer-events="none"
+           width="100%"
+           height="100%"
+           requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+          <xhtml:div
+             style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 625px; margin-left: 21px;">
+            <xhtml:div
+               style="box-sizing: border-box; font-size: 0px; text-align: center;"
+               data-drawio-colors="color: rgb(0, 0, 0); ">
+              <xhtml:div
+                 style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Cortex-R</xhtml:div>
+            </xhtml:div>
+          </xhtml:div>
+        </foreignObject>
+        <text
+           x="60"
+           y="629"
+           fill="rgb(0, 0, 0)"
+           font-family="Helvetica"
+           font-size="12px"
+           text-anchor="middle"
+           id="text12">Cortex-R</text>
+      </switch>
+    </g>
+    <rect
+       x="170"
+       y="590"
+       width="100"
+       height="70"
+       fill="#f8cecc"
+       stroke="#b85450"
+       pointer-events="none"
+       id="rect18" />
+    <path
+       d="M 180 590 L 180 660 M 260 590 L 260 660"
+       fill="none"
+       stroke="#b85450"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path20" />
+    <g
+       transform="translate(-0.5 -0.5)"
+       id="g26">
+      <switch
+         id="switch24">
+        <foreignObject
+           style="overflow: visible; text-align: left;"
+           pointer-events="none"
+           width="100%"
+           height="100%"
+           requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+          <xhtml:div
+             style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 625px; margin-left: 181px;">
+            <xhtml:div
+               style="box-sizing: border-box; font-size: 0px; text-align: center;"
+               data-drawio-colors="color: rgb(0, 0, 0); ">
+              <xhtml:div
+                 style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Cortex-A</xhtml:div>
+            </xhtml:div>
+          </xhtml:div>
+        </foreignObject>
+        <text
+           x="220"
+           y="629"
+           fill="rgb(0, 0, 0)"
+           font-family="Helvetica"
+           font-size="12px"
+           text-anchor="middle"
+           id="text22">Cortex-A</text>
+      </switch>
+    </g>
+    <g
+       transform="translate(-0.5 -0.5)"
+       id="g32">
+      <switch
+         id="switch30">
+        <foreignObject
+           style="overflow: visible; text-align: left;"
+           pointer-events="none"
+           width="100%"
+           height="100%"
+           requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+          <xhtml:div
+             style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 58px; height: 1px; padding-top: 530px; margin-left: 221px;">
+            <xhtml:div
+               style="box-sizing: border-box; font-size: 0px; text-align: center;"
+               data-drawio-colors="color: rgb(0, 0, 0); ">
+              <xhtml:div
+                 style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">K3 SoC</xhtml:div>
+            </xhtml:div>
+          </xhtml:div>
+        </foreignObject>
+        <text
+           x="250"
+           y="534"
+           fill="rgb(0, 0, 0)"
+           font-family="Helvetica"
+           font-size="12px"
+           text-anchor="middle"
+           id="text28">K3 SoC</text>
+      </switch>
+    </g>
+    <path
+       d="M 140 550 L 140 570 L 60 570 L 60 583.63"
+       fill="none"
+       stroke="rgb(0, 0, 0)"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path34" />
+    <path
+       d="M 60 588.88 L 56.5 581.88 L 60 583.63 L 63.5 581.88 Z"
+       fill="rgb(0, 0, 0)"
+       stroke="rgb(0, 0, 0)"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path36" />
+    <path
+       d="M 140 550 L 140 570 L 220 570 L 220 583.63"
+       fill="none"
+       stroke="rgb(0, 0, 0)"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path38" />
+    <path
+       d="M 220 588.88 L 216.5 581.88 L 220 583.63 L 223.5 581.88 Z"
+       fill="rgb(0, 0, 0)"
+       stroke="rgb(0, 0, 0)"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path40" />
+    <rect
+       x="90"
+       y="520"
+       width="100"
+       height="30"
+       fill="#f8cecc"
+       stroke="#b85450"
+       pointer-events="none"
+       id="rect42" />
+    <g
+       transform="translate(-0.5 -0.5)"
+       id="g48">
+      <switch
+         id="switch46">
+        <foreignObject
+           style="overflow: visible; text-align: left;"
+           pointer-events="none"
+           width="100%"
+           height="100%"
+           requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+          <xhtml:div
+             style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 98px; height: 1px; padding-top: 535px; margin-left: 91px;">
+            <xhtml:div
+               style="box-sizing: border-box; font-size: 0px; text-align: center;"
+               data-drawio-colors="color: rgb(0, 0, 0); ">
+              <xhtml:div
+                 style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Debug SS</xhtml:div>
+            </xhtml:div>
+          </xhtml:div>
+        </foreignObject>
+        <text
+           x="140"
+           y="539"
+           fill="rgb(0, 0, 0)"
+           font-family="Helvetica"
+           font-size="12px"
+           text-anchor="middle"
+           id="text44">Debug SS</text>
+      </switch>
+    </g>
+    <path
+       d="M 140 470 L 140 503.63"
+       fill="none"
+       stroke="rgb(0, 0, 0)"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path50" />
+    <path
+       d="M 140 508.88 L 136.5 501.88 L 140 503.63 L 143.5 501.88 Z"
+       fill="rgb(0, 0, 0)"
+       stroke="rgb(0, 0, 0)"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path52" />
+    <rect
+       x="80"
+       y="410"
+       width="120"
+       height="60"
+       rx="9"
+       ry="9"
+       fill="#ffe6cc"
+       stroke="#d79b00"
+       pointer-events="none"
+       id="rect54" />
+    <g
+       transform="translate(-0.5 -0.5)"
+       id="g60">
+      <switch
+         id="switch58">
+        <foreignObject
+           style="overflow: visible; text-align: left;"
+           pointer-events="none"
+           width="100%"
+           height="100%"
+           requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+          <xhtml:div
+             style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 440px; margin-left: 81px;">
+            <xhtml:div
+               style="box-sizing: border-box; font-size: 0px; text-align: center;"
+               data-drawio-colors="color: rgb(0, 0, 0); ">
+              <xhtml:div
+                 style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">Jtag Interface<xhtml:br />
+(XDS110, TUMPA..)</xhtml:div>
+            </xhtml:div>
+          </xhtml:div>
+        </foreignObject>
+        <text
+           x="140"
+           y="444"
+           fill="rgb(0, 0, 0)"
+           font-family="Helvetica"
+           font-size="12px"
+           text-anchor="middle"
+           id="text56">Jtag Interface...</text>
+      </switch>
+    </g>
+    <path
+       d="M 140 370 L 140 403.63"
+       fill="none"
+       stroke="rgb(0, 0, 0)"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path62" />
+    <path
+       d="M 140 408.88 L 136.5 401.88 L 140 403.63 L 143.5 401.88 Z"
+       fill="rgb(0, 0, 0)"
+       stroke="rgb(0, 0, 0)"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path64" />
+    <rect
+       x="80"
+       y="310"
+       width="120"
+       height="60"
+       fill="#f5f5f5"
+       stroke="#666666"
+       pointer-events="none"
+       id="rect66" />
+    <g
+       transform="translate(-0.5 -0.5)"
+       id="g72">
+      <switch
+         id="switch70">
+        <foreignObject
+           style="overflow: visible; text-align: left;"
+           pointer-events="none"
+           width="100%"
+           height="100%"
+           requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+          <xhtml:div
+             style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 340px; margin-left: 81px;">
+            <xhtml:div
+               style="box-sizing: border-box; font-size: 0px; text-align: center;"
+               data-drawio-colors="color: #333333; ">
+              <xhtml:div
+                 style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(51, 51, 51); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">PC</xhtml:div>
+            </xhtml:div>
+          </xhtml:div>
+        </foreignObject>
+        <text
+           x="140"
+           y="344"
+           fill="#333333"
+           font-family="Helvetica"
+           font-size="12px"
+           text-anchor="middle"
+           id="text68">PC</text>
+      </switch>
+    </g>
+    <g
+       transform="translate(-0.5 -0.5)"
+       id="g78">
+      <switch
+         id="switch76">
+        <foreignObject
+           style="overflow: visible; text-align: left;"
+           pointer-events="none"
+           width="100%"
+           height="100%"
+           requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+          <xhtml:div
+             style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 58px; height: 1px; padding-top: 385px; margin-left: 141px;">
+            <xhtml:div
+               style="box-sizing: border-box; font-size: 0px; text-align: center;"
+               data-drawio-colors="color: rgb(0, 0, 0); ">
+              <xhtml:div
+                 style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">USB</xhtml:div>
+            </xhtml:div>
+          </xhtml:div>
+        </foreignObject>
+        <text
+           x="170"
+           y="389"
+           fill="rgb(0, 0, 0)"
+           font-family="Helvetica"
+           font-size="12px"
+           text-anchor="middle"
+           id="text74">USB</text>
+      </switch>
+    </g>
+    <g
+       transform="translate(-0.5 -0.5)"
+       id="g84">
+      <switch
+         id="switch82">
+        <foreignObject
+           style="overflow: visible; text-align: left;"
+           pointer-events="none"
+           width="100%"
+           height="100%"
+           requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+          <xhtml:div
+             style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 58px; height: 1px; padding-top: 485px; margin-left: 141px;">
+            <xhtml:div
+               style="box-sizing: border-box; font-size: 0px; text-align: center;"
+               data-drawio-colors="color: rgb(0, 0, 0); ">
+              <xhtml:div
+                 style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">JTAG</xhtml:div>
+            </xhtml:div>
+          </xhtml:div>
+        </foreignObject>
+        <text
+           x="170"
+           y="489"
+           fill="rgb(0, 0, 0)"
+           font-family="Helvetica"
+           font-size="12px"
+           text-anchor="middle"
+           id="text80">JTAG</text>
+      </switch>
+    </g>
+    <path
+       d="M 100 230 L 180 230 L 200 270 L 180 310 L 100 310 L 80 270 Z"
+       fill="#e1d5e7"
+       stroke="#9673a6"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path86" />
+    <g
+       transform="translate(-0.5 -0.5)"
+       id="g92">
+      <switch
+         id="switch90">
+        <foreignObject
+           style="overflow: visible; text-align: left;"
+           pointer-events="none"
+           width="100%"
+           height="100%"
+           requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+          <xhtml:div
+             style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 270px; margin-left: 81px;">
+            <xhtml:div
+               style="box-sizing: border-box; font-size: 0px; text-align: center;"
+               data-drawio-colors="color: rgb(0, 0, 0); ">
+              <xhtml:div
+                 style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">OpenOCD</xhtml:div>
+            </xhtml:div>
+          </xhtml:div>
+        </foreignObject>
+        <text
+           x="140"
+           y="274"
+           fill="rgb(0, 0, 0)"
+           font-family="Helvetica"
+           font-size="12px"
+           text-anchor="middle"
+           id="text88">OpenOCD</text>
+      </switch>
+    </g>
+    <path
+       d="M 140 200 L 140 220 L 140 210 L 140 223.63"
+       fill="none"
+       stroke="rgb(0, 0, 0)"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path94" />
+    <path
+       d="M 140 228.88 L 136.5 221.88 L 140 223.63 L 143.5 221.88 Z"
+       fill="rgb(0, 0, 0)"
+       stroke="rgb(0, 0, 0)"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path96" />
+    <path
+       d="M 100 120 L 180 120 L 200 160 L 180 200 L 100 200 L 80 160 Z"
+       fill="#e1d5e7"
+       stroke="#9673a6"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path98" />
+    <g
+       transform="translate(-0.5 -0.5)"
+       id="g104">
+      <switch
+         id="switch102">
+        <foreignObject
+           style="overflow: visible; text-align: left;"
+           pointer-events="none"
+           width="100%"
+           height="100%"
+           requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+          <xhtml:div
+             style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 160px; margin-left: 81px;">
+            <xhtml:div
+               style="box-sizing: border-box; font-size: 0px; text-align: center;"
+               data-drawio-colors="color: rgb(0, 0, 0); ">
+              <xhtml:div
+                 style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">gdb</xhtml:div>
+            </xhtml:div>
+          </xhtml:div>
+        </foreignObject>
+        <text
+           x="140"
+           y="164"
+           fill="rgb(0, 0, 0)"
+           font-family="Helvetica"
+           font-size="12px"
+           text-anchor="middle"
+           id="text100">gdb</text>
+      </switch>
+    </g>
+    <path
+       d="M 140 80 L 140 113.63"
+       fill="none"
+       stroke="rgb(0, 0, 0)"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path106" />
+    <path
+       d="M 140 118.88 L 136.5 111.88 L 140 113.63 L 143.5 111.88 Z"
+       fill="rgb(0, 0, 0)"
+       stroke="rgb(0, 0, 0)"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path108" />
+    <path
+       d="M 80 0 L 200 0 L 200 68 Q 170 46.4 140 68 Q 110 89.6 80 68 L 80 12 Z"
+       fill="#e1d5e7"
+       stroke="#9673a6"
+       stroke-miterlimit="10"
+       pointer-events="none"
+       id="path110" />
+    <g
+       transform="translate(-0.5 -0.5)"
+       id="g116">
+      <switch
+         id="switch114">
+        <foreignObject
+           style="overflow: visible; text-align: left;"
+           pointer-events="none"
+           width="100%"
+           height="100%"
+           requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+          <xhtml:div
+             style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 28px; margin-left: 81px;">
+            <xhtml:div
+               style="box-sizing: border-box; font-size: 0px; text-align: center;"
+               data-drawio-colors="color: rgb(0, 0, 0); ">
+              <xhtml:div
+                 style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: none; white-space: normal; overflow-wrap: normal;">IDE debugging code</xhtml:div>
+            </xhtml:div>
+          </xhtml:div>
+        </foreignObject>
+        <text
+           x="140"
+           y="32"
+           fill="rgb(0, 0, 0)"
+           font-family="Helvetica"
+           font-size="12px"
+           text-anchor="middle"
+           id="text112">IDE debugging code</text>
+      </switch>
+    </g>
+  </g>
+</svg>
doc/board/ti/j7200_evm.rst +24 -0
index 69abc55a93ce..d5d5c10b2870 100644
@@ -201,3 +201,27 @@ 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.
+
+.. warning::
+
+  **OpenOCD support since**: v0.12.0
+
+  If the default package version of OpenOCD in your development
+  environment's distribution needs to be updated, it might be necessary to
+  build OpenOCD from the source.
+
+.. 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 +0 -0
index f4b4c192d9da..a9f441087938 100644

doc/board/ti/j721e_evm.rst J721E common processor board can be attached to a Ethernet QSGMII card and the · line 232

Quoted 5 lines
doc/board/ti/j721e_evm.rst +2 -0
@@ -228,3 +228,27 @@ 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

%s/U-boot/U-Boot/

Quoted 8 lines
doc/board/ti/j721e_evm.rst +8 -0
+----------------
+
+See :ref:`Common Debugging environment - openOCD<k3_rst_refer_openocd>`: for
+detailed setup information.
+
+.. warning::
+
+  **OpenOCD support since**: v0.12.0

doc/board/ti/j721e_evm.rst J721E common processor board can be attached to a Ethernet QSGMII card and the · line 250

Quoted 10 lines
doc/board/ti/j721e_evm.rst +10 -0
+
+  If the default package version of OpenOCD in your development
+  environment's distribution needs to be updated, it might be necessary to
+  build OpenOCD from the source.
+
+.. 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

see above

Quoted 12 lines
doc/board/ti/j721e_evm.rst +4 -0
+
+.. code-block:: bash
+
+  openocd -f board/ti_j721eevm.cfg
doc/board/ti/k3.rst +0 -0
index 2034002af7cb..ea96fe502f35 100644
@@ -468,3 +468,484 @@ filesystem and then imported
 
    => fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
    => env import -t ${loadaddr} ${filesize}

doc/board/ti/k3.rst filesystem and then imported · line 480

Quoted 10 lines
doc/board/ti/k3.rst +10 -0
+
+.. _k3_rst_refer_openocd:
+
+Common Debugging environment - OpenOCD
+--------------------------------------
+
+This section will show you how to connect a board to `OpenOCD
+<https://openocd.org/>`_ and load the SPL symbols for debugging with
+a K3 generation device. To follow this guide, you must build custom
+u-boot binaries, start your board from a boot media such as an SD

%s/u-boot/U-Boot/

doc/board/ti/k3.rst filesystem and then imported · line 485

Quoted 5 lines
doc/board/ti/k3.rst +5 -0
+card, and use an OpenOCD environment. This section uses generic
+examples, though you can apply these instructions to any supported K3
+generation device.
+
+Overall structure of this setup is in the following figure.

The overall

Quoted 12 lines
doc/board/ti/k3.rst +12 -0
+
+.. image:: img/openocd-overview.svg
+
+.. note::
+
+  If you find these instructions useful, please consider `donating
+  <https://openocd.org/pages/donations.html>`_ to OpenOCD.
+
+Step 1: Download and install OpenOCD
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To get started, it is more convenient if the distribution you

doc/board/ti/k3.rst filesystem and then imported · line 507

Quoted 10 lines
doc/board/ti/k3.rst +10 -0
+use supports OpenOCD by default. Follow the instructions in the
+`getting OpenOCD <https://openocd.org/pages/getting-openocd.html>`_
+documentation to pick the installation steps appropriate to your
+environment. Some references to OpenOCD documentation:
+
+* `OpenOCD User Guide <https://openocd.org/doc/html/index.html>`_
+* `OpenOCD Developer's Guide <https://openocd.org/doc/doxygen/html/index.html>`_
+
+Refer to the release notes corresponding to the `OpenOCD version
+<https://github.com/openocd-org/openocd/releases>`_ to ensure that:

%s/ that:/:/

doc/board/ti/k3.rst filesystem and then imported · line 511

Quoted 4 lines
doc/board/ti/k3.rst +4 -0
+
+* Processor support: In general, processor support shouldn't present
+  any difficulties since OpenOCD provides solid support for both armv8
+  and armv7.

ARMv8 and ARMv7

or

Armv8 and Armv7

ARM themselves use either of these.

doc/board/ti/k3.rst filesystem and then imported · line 514

Quoted 3 lines
doc/board/ti/k3.rst +3 -0
+* SoC support: When working with System-on-a-Chip (SoC), the support
+  usually comes as a tcl config file. It is vital to ensure the correct
+  version of OpenOCD or to use the tcl files from the latest release or

%s/tcl/Tcl/

doc/board/ti/k3.rst filesystem and then imported · line 519

Quoted 5 lines
doc/board/ti/k3.rst +5 -0
+  the one mentioned.
+* Board or the JTAG adapter support: In most cases, board support is
+  a relatively easy problem 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 an onboard JTAG adapter that

%s/do come/come/

doc/board/ti/k3.rst filesystem and then imported · line 522

Quoted 3 lines
doc/board/ti/k3.rst +3 -0
+  requires a USB cable to be plugged into the board, in which case, it
+  is vital to ensure that the JTAG adapter is supported. Fortunately,
+  almost all TI K3 SK/EVMs come with TI's XDS110, which has support

which has out of the box support by OpenOCD

doc/board/ti/k3.rst filesystem and then imported · line 533

Quoted 11 lines
doc/board/ti/k3.rst +11 -0
+  out of the box with OpenOCD. The board-specific documentation will
+  cover the details and any adapter recommendations.
+
+.. code-block:: bash
+
+ openocd -v
+
+.. note::
+
+ OpenOCD version 0.12.0 is usually required to connect to most K3
+ devices. If the support is on a newer version than what is in your

If your device is only supported by a newer version than the one provided by your distribution,

doc/board/ti/k3.rst filesystem and then imported · line 539

Quoted 6 lines
doc/board/ti/k3.rst +6 -0
+ distribution, you may need to build it from the source.
+
+Building OpenOCD from source
+""""""""""""""""""""""""""""
+
+Dependency package installation instructions are for Debian

The dependency package installation instructions below are

doc/board/ti/k3.rst filesystem and then imported · line 540

Quoted 1 line
doc/board/ti/k3.rst +1 -0
+systems, but equivalent instructions should exist on systems with

%s/on/for/

doc/board/ti/k3.rst filesystem and then imported · line 541

Quoted 1 line
doc/board/ti/k3.rst +1 -0
+other package managers. Please refer to `OpenOCD Documentation

%s/to/to the/

doc/board/ti/k3.rst filesystem and then imported · line 547

Quoted 6 lines
doc/board/ti/k3.rst +6 -0
+<https://openocd.org/>`_ for more recent installation steps.
+
+.. code-block:: bash
+
+  $ sudo apt-get install libtool pkg-config texinfo libusb-dev \
+    libusb-1.0.0-dev libftdi-dev libhidapi-dev autoconf automake

This list might be incomplete:

sudo apt build-dep openocd
will install all dependecies used by Debian or Ubuntu.

My computer curently would install:

libcapstone-dev libcapstone4 libftdi1-dev libgpiod-dev libgpiod2
libhidapi-dev libhidapi-hidraw0 libhidapi-libusb0
libjaylink-dev libjaylink0 libjim-dev libjim0.81 libusb-1.0-0-dev texlive

Quoted 10 lines
doc/board/ti/k3.rst +10 -0
+  $ git clone https://github.com/openocd-org/openocd.git openocd
+  $ cd openocd
+  $ git submodule init
+  $ git submodule update
+  $ ./bootstrap
+  $ ./configure --prefix=/usr/local/
+  $ make -j`nproc`
+  $ sudo make install
+
+.. note::

doc/board/ti/k3.rst filesystem and then imported · line 567

Quoted 10 lines
doc/board/ti/k3.rst +10 -0
+
+  The example above uses the GitHub mirror site. See
+  `git repo information <https://openocd.org/doc/html/Developers.html#OpenOCD-Git-Repository>`_
+  information to pick the official git repo.
+  If a specific version is desired, select the version using `git checkout tag`.
+
+Installing OpenOCD udev rules
+"""""""""""""""""""""""""""""
+
+The step is unnecessary if the distribution supports the OpenOCD, but

This step is not required

Quoted 7 lines
doc/board/ti/k3.rst +7 -0
+if building from a source, ensure that the udev rules are installed
+correctly to ensure a sane system.
+
+.. code-block:: bash
+
+  # Go to the OpenOCD source directory
+  $ cd openocd

doc/board/ti/k3.rst filesystem and then imported · line 584

Quoted 10 lines
doc/board/ti/k3.rst +10 -0
+  # Copy the udev rules to the correct system location
+  $ sudo cp ./contrib/60-openocd.rules \
+      ./src/JTAG/drivers/libjaylink/contrib/99-libjaylink.rules \
+      /etc/udev/rules.d/
+  # Get Udev to load the new rules up
+  $ sudo udevadm control --reload-rules
+  # Use the new rules on existing connected devices
+  $ sudo udevadm trigger
+
+Step 2: Setup gdb

%s/gdb/GDB/

doc/board/ti/k3.rst filesystem and then imported · line 587

Quoted 3 lines
doc/board/ti/k3.rst +3 -0
+^^^^^^^^^^^^^^^^^
+
+Most systems come with gdb-multiarch package.

%s/with/with the/

doc/board/ti/k3.rst filesystem and then imported · line 594

Quoted 7 lines
doc/board/ti/k3.rst +7 -0
+
+.. code-block:: bash
+
+  # Install gdb-multiarch package
+  $ sudo apt-get install gdb-multiarch
+
+Though using gdb natively is normal, developers with interest in using IDE

%s/gdb/GDB/

doc/board/ti/k3.rst filesystem and then imported · line 595

Quoted 1 line
doc/board/ti/k3.rst +1 -0
+will find few of these interesting:

%s/will/may/

%s/few/a few/

Quoted 4 lines
doc/board/ti/k3.rst +4 -0
+
+* `gdb-dashboard <https://github.com/cyrus-and/gdb-dashboard>`_
+* `gef <https://github.com/hugsy/gef>`_
+* `peda <https://github.com/longld/peda>`_

doc/board/ti/k3.rst filesystem and then imported · line 609

Quoted 10 lines
doc/board/ti/k3.rst +10 -0
+* `pwndbg <https://github.com/pwndbg/pwndbg>`_
+* `voltron <https://github.com/snare/voltron>`_
+* `ddd <https://www.gnu.org/software/ddd/>`_
+* `vscode <https://www.justinmklam.com/posts/2017/10/vscode-debugger-setup/>`_
+* `vim conque-gdb <https://github.com/vim-scripts/Conque-GDB>`_
+* `emacs realgud <https://github.com/realgud/realgud/wiki/gdb-notes>`_
+* `Lauterbach IDE <https://www2.lauterbach.com/pdf/backend_gdb.pdf>`_
+
+.. warning::
+  lldb support for OpenOCD is still a work in progress as of this writing.

%s/lldb/LLDB/

doc/board/ti/k3.rst filesystem and then imported · line 610

Quoted 1 line
doc/board/ti/k3.rst +1 -0
+  Using gdb is probably the safest option at this point in time.

%s/gdb/GDB/

doc/board/ti/k3.rst filesystem and then imported · line 612

Quoted 2 lines
doc/board/ti/k3.rst +2 -0
+
+Step 3: Setup of board to PC

Connect board to host

doc/board/ti/k3.rst filesystem and then imported · line 624

Quoted 12 lines
doc/board/ti/k3.rst +12 -0
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+There are few patterns of boards in the ecosystem
+
+.. k3_rst_include_start_openocd_connect_XDS110
+
+**Integrated JTAG adapter/dongle**: The board has a micro-USB connector labelled
+XDS110 USB or JTAG. Connect a USB cable to the board to the mentioned port.
+
+.. note::
+
+  There are multiple USB ports on a typical board, So, ensure you have read
+  the user guide for the board and confirm the silk screen label to ensure

%s/confirm/confirmed/

doc/board/ti/k3.rst filesystem and then imported · line 634

Quoted 10 lines
doc/board/ti/k3.rst +10 -0
+  connecting to the correct port.
+
+.. k3_rst_include_end_openocd_connect_XDS110
+
+.. k3_rst_include_start_openocd_connect_cti20
+
+**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/do have/have an/

Quoted 9 lines
doc/board/ti/k3.rst +9 -0
+provided as an alternate scheme to connect alternatives such
+as `Lauterbach <https://www.lauterbach.com/>`_ or `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 dongles supported by OpenOCD. <https://openocd.org/doc/html/Debug-Adapter-Hardware.html#Debug-Adapter-Hardware>`_
+* Cable such as `Tag-connect ribbon cable <https://www.tag-connect.com/product/20-pin-cortex-ribbon-cable-4-length-with-50-mil-connectors>`_

doc/board/ti/k3.rst filesystem and then imported · line 653

Quoted 10 lines
doc/board/ti/k3.rst +10 -0
+* 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/>`_
+  or `Lauterbach LA-3780 <https://www.lauterbach.com/ad3780.html>`_
+  Or optionally, if you have manufacturing capability then you could try
+  `BeagleBone JTAG Adapter <https://github.com/mmorawiec/BeagleBone-Black-JTAG-Adapters>`_
+
+.. warning::
+  XDS560 and Lauterbach are proprietary solutions and is not supported by
+  OpenOCD.
+  When purchasing off the shelf adapter/dongle, you do want to be careful

%s/off/an off/

Quoted 29 lines
doc/board/ti/k3.rst +29 -0
+  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 dongles supported by OpenOCD <https://openocd.org/doc/html/Debug-Adapter-Hardware.html#Debug-Adapter-Hardware>`_.
+* 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>`_
+* 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.
+

doc/board/ti/k3.rst filesystem and then imported · line 692

Quoted 10 lines
doc/board/ti/k3.rst +10 -0
+.. 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

%s/U-boot/U-Boot/

doc/board/ti/k3.rst filesystem and then imported · line 696

Quoted 4 lines
doc/board/ti/k3.rst +4 -0
+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

%s/gdb/GDB/

Quoted 7 lines
doc/board/ti/k3.rst +7 -0
+initialization's potential consequences.
+
+Consider the following code change:
+
+.. code-block:: diff
+
+  --- a/file.c	2023-07-29 10:55:29.647928811 -0500

doc/board/ti/k3.rst filesystem and then imported · line 713

Quoted 10 lines
doc/board/ti/k3.rst +10 -0
+  +++ 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

%s/wit re-initialization sequence/with a re-initialization/

doc/board/ti/k3.rst filesystem and then imported · line 716

Quoted 3 lines
doc/board/ti/k3.rst +3 -0
+sequence without proper shutdown.
+
+To help narrow the debug down, it is usually more simpler to use the

%s/more simpler/simpler/

(simpler is already a comparative)

doc/board/ti/k3.rst filesystem and then imported · line 720

Quoted 4 lines
doc/board/ti/k3.rst +4 -0
+standard boot media to get to the bootloader and debug only in the area
+of interest.
+
+In general, to debug u-boot spl/u-boot with OpenOCD there are three steps:

%s/u-boot/U-Boot/

doc/board/ti/k3.rst filesystem and then imported · line 722

Quoted 2 lines
doc/board/ti/k3.rst +2 -0
+
+* Modify the code to put a loop to allow debugger to attach near the point

%s/to put a loop to allow debugger/adding a loop to allow the debugger/

doc/board/ti/k3.rst filesystem and then imported · line 725

Quoted 3 lines
doc/board/ti/k3.rst +3 -0
+  of interest. Boot up normally to stop at the loop.
+* Connect with OpenOCD and step out of the loop
+* Step through code to find the root of issue

%s/code/the code/

doc/board/ti/k3.rst filesystem and then imported · line 727

Quoted 2 lines
doc/board/ti/k3.rst +2 -0
+
+Typical debug involves a few iterations of the above sequence. Though

%s/debug/debugging/

doc/board/ti/k3.rst filesystem and then imported · line 730

Quoted 3 lines
doc/board/ti/k3.rst +3 -0
+most bootloader developers like to use printf to debug, debug with
+JTAG tends to be most efficient since it is possible to investigate
+code flow and inspect hardware registers without repeated iterations.

%s/code/the code/

Quoted 23 lines
doc/board/ti/k3.rst +23 -0
+
+Code modification
+"""""""""""""""""
+
+* **start.S**: Adding an infinite while loop at the very entry of
+  U-Boot. For this, look for the corresponding start.S entry file.
+  This is usually only required when debugging some core SoC or
+  processor related function. For example: arch/arm/cpu/armv8/start.S or
+  arch/arm/cpu/armv7/start.S
+
+.. code-block:: diff
+
+  diff --git a/arch/arm/cpu/armv7/start.S b/arch/arm/cpu/armv7/start.S
+  index 69e281b086..744929e825 100644
+  --- a/arch/arm/cpu/armv7/start.S
+  +++ b/arch/arm/cpu/armv7/start.S
+  @@ -37,6 +37,8 @@
+   #endif
+
+   reset:
+  +dead_loop:
+  +    b dead_loop
+       /* Allow the board to save important registers */

doc/board/ti/k3.rst filesystem and then imported · line 763

Quoted 10 lines
doc/board/ti/k3.rst +10 -0
+       b    save_boot_params
+   save_boot_params_ret:
+
+* **board_init_f**: Adding an infinite while loop at the board entry
+  function. 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 boot SPL or Armv8 SPL:
+
+  To debug the boot process in either domain, we will first
+  add a modification in the code we would like to debug.

%s/in the code/to the code/

Quoted 20 lines
doc/board/ti/k3.rst +20 -0
+  In this example, we will debug ``board_init_f`` inside
+  ``arch/arm/mach-k3/{soc}_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). For example, modify the
+  file as follows (depending on need):
+
+.. code-block:: c
+
+  void board_init_f(ulong dummy)
+  {
+      .
+      .
+      /* Code to run on the R5F (Wakeup/Boot Domain) */
+      if (IS_ENABLED(CONFIG_CPU_V7R)) {
+          volatile int x = 1;
+          while(x) {};
+      }
+      ...

doc/board/ti/k3.rst filesystem and then imported · line 793

Quoted 10 lines
doc/board/ti/k3.rst +10 -0
+      /* Code to run on the ARMV8 (Main Domain) */
+      if (IS_ENABLED(CONFIG_CPU_ARM64)) {
+          volatile int x = 1;
+          while(x) {};
+      }
+      .
+      .
+  }
+
+Connecting with OpenOCD for debug session

%s/for/for a/

doc/board/ti/k3.rst filesystem and then imported · line 796

Quoted 3 lines
doc/board/ti/k3.rst +3 -0
+"""""""""""""""""""""""""""""""""""""""""
+
+Startup openocd to debug the platform as follows:

%s/openocd/OpenOCD/

Quoted 7 lines
doc/board/ti/k3.rst +7 -0
+
+* **Integrated JTAG interface**: If the evm has a debugger such as
+  XDS110 inbuilt, there is typically an evm board support added and a
+  cfg file will be available.
+
+.. k3_rst_include_start_openocd_cfg_XDS110
+

doc/board/ti/k3.rst filesystem and then imported · line 813

Quoted 10 lines
doc/board/ti/k3.rst +10 -0
+.. code-block:: bash
+
+  openocd -f board/{board_of_choice}.cfg
+
+.. k3_rst_include_end_openocd_cfg_XDS110
+
+.. k3_rst_include_start_openocd_cfg_external_intro
+
+* **External JTAG adapter/interface**: In other cases, where an
+  adapter/dongle  is used, a simple cfg file can be created to integrate the

%s/ / /

Quoted 91 lines
doc/board/ti/k3.rst +91 -0
+  SoC and adapter information. See `supported TI K3 SoCs
+  <https://github.com/openocd-org/openocd/blob/master/tcl/target/ti_k3.cfg#L59>`_
+  to decide if the SoC is supported or not.
+
+.. code-block:: bash
+
+  openocd -f openocd_connect.cfg
+
+.. k3_rst_include_end_openocd_cfg_external_intro
+
+  For example, with BeaglePlay (AM62X platform), the openocd_connect.cfg:
+
+.. code-block:: tcl
+
+  # TUMPA example:
+  # http://www.tiaowiki.com/w/TIAO_USB_Multi_Protocol_Adapter_User's_Manual
+  source [find interface/ftdi/tumpa.cfg]
+
+  transport select jtag
+
+  # default JTAG configuration has only SRST and no TRST
+  reset_config srst_only srst_push_pull
+
+  # delay after SRST goes inactive
+  adapter srst delay 20
+
+  if { ![info exists SOC] } {
+    # Set the SoC of interest
+    set SOC am625
+  }
+
+  source [find target/ti_k3.cfg]
+
+  ftdi tdo_sample_edge falling
+
+  # Speeds for FT2232H are in multiples of 2, and 32MHz is tops
+  # max speed we seem to achieve is ~20MHz.. so we pick 16MHz
+  adapter speed 16000
+
+Below is an example of the output of this command:
+
+.. code-block:: console
+
+  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
+
+.. note::
+  Notice the default configuration is non-SMP configuration allowing
+  for each of the core to be attached and debugged simultaneously.
+  armv8 SPL/U-boot starts up on cpu0 of a53/a72.
+
+.. k3_rst_include_start_openocd_cfg_external_gdb
+
+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
+
+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}
+

doc/board/ti/k3.rst filesystem and then imported · line 914

Quoted 10 lines
doc/board/ti/k3.rst +10 -0
+.. k3_rst_include_end_openocd_cfg_external_gdb
+
+In the above example of AM625,
+
+.. code-block:: bash
+
+  target extended-remote localhost:3338     <- R5F (Wakeup Domain)
+  target extended-remote localhost:3334     <- A53 (Main Domain)
+
+The core can now be debugged directly within gdb using gdb commands or

%s/gdb/GDB/

doc/board/ti/k3.rst filesystem and then imported · line 920

Quoted 6 lines
doc/board/ti/k3.rst +6 -0
+if using IDE, as appropriate to the IDE.
+
+Stepping through the code
+"""""""""""""""""""""""""
+
+Use the gdb command ``lay next`` after loading the symbols to see the

%s/lay next/lay src/ ?

Please, provide the name of the layout.
Cf. https://sourceware.org/gdb/onlinedocs/gdb/TUI-Commands.html

doc/board/ti/k3.rst filesystem and then imported · line 930

Quoted 10 lines
doc/board/ti/k3.rst +10 -0
+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 platform has now been successfully setup to debug with OpenOCD
+using gdb commands or a gdb-based IDE. See `OpenOCD documentation for

%s/gdb/GDB/

Quoted 5 lines
doc/board/ti/k3.rst +5 -0
+gdb <https://openocd.org/doc/html/GDB-and-OpenOCD.html>`_ for further
+information.
+
+.. warning::
+

doc/board/ti/k3.rst filesystem and then imported · line 945

Quoted 10 lines
doc/board/ti/k3.rst +10 -0
+  On the K3 family of devices, 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) or TI
+  Foundational Security (TIFS) 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.
+
+Misc notes with openOCD

%s/Misc/Miscellaneous/

doc/board/ti/k3.rst filesystem and then imported · line 948

Quoted 3 lines
doc/board/ti/k3.rst +3 -0
+^^^^^^^^^^^^^^^^^^^^^^^
+
+At this time, OpenOCD does not support tracing for K3 platforms.

Currently

Best regards

Heinrich

Quoted 3 lines
doc/board/ti/k3.rst +3 -0
+Tracing function could be beneficial if the bug in code occurs deep
+within nested function and can optionally save developers major
+trouble of stepping through a large quantity of code.