Merge tag 'doc-2023-10-rc3' of https://source.denx.de/u-boot/custodians/u-boot-efi

Pull request for doc-2023-10-rc3

Documentation:

* Update examples for imx8mp_evk
* OpenOCD debugging guide for TI K3 boards
* Explain using gadget devices on TI boards
* Describe best practices for board ports

14 files changed, 1418 insertions, 123 deletions

diff --git a/doc/board/nxp/imx8mp_evk.rst b/doc/board/nxp/imx8mp_evk.rst
index e7cc7b396b..72175dbe78 100644
--- a/doc/board/nxp/imx8mp_evk.rst
+++ b/doc/board/nxp/imx8mp_evk.rst
@@ -37,21 +37,22 @@ Build U-Boot
 
 .. code-block:: bash
 
+Note: builddir is U-Boot build directory (source directory for in-tree builds).
+
    $ export CROSS_COMPILE=aarch64-poky-linux-
    $ make O=build imx8mp_evk_defconfig
-   $ cp ../imx-atf/build/imx8mp/release/bl31.bin ./build/bl31.bin
-   $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_1d_dmem_202006.bin ./build/
-   $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_1d_imem_202006.bin ./build/
-   $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_2d_dmem_202006.bin ./build/
-   $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_2d_imem_202006.bin ./build/
-   $ export ATF_LOAD_ADDR=0x970000
-   $ make O=build
+   $ cp ../imx-atf/build/imx8mp/release/bl31.bin $(builddir)
+   $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_1d_dmem_202006.bin $(builddir)
+   $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_1d_imem_202006.bin $(builddir)
+   $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_2d_dmem_202006.bin $(builddir)
+   $ cp ../firmware-imx-8.10/firmware/ddr/synopsys/lpddr4_pmu_train_2d_imem_202006.bin $(builddir)
+   $ make
 
 Burn the flash.bin to the MicroSD card at offset 32KB:
 
 .. code-block:: bash
 
-   $sudo dd if=build/flash.bin of=/dev/sd[x] bs=1K seek=32 conv=notrunc; sync
+   $ sudo dd if=flash.bin of=/dev/sd[x] bs=1K seek=32 conv=notrunc; sync
 
 Boot
 ----
diff --git a/doc/board/ti/am335x_evm.rst b/doc/board/ti/am335x_evm.rst
index ee4faec37c..3332d51b36 100644
--- a/doc/board/ti/am335x_evm.rst
+++ b/doc/board/ti/am335x_evm.rst
@@ -201,3 +201,65 @@ booting and mtdparts have been configured correctly for the board:
 	U-Boot # spl export fdt ${loadaddr} - ${fdtaddr}
 	U-Boot # nand erase.part u-boot-spl-os
 	U-Boot # nand write ${fdtaddr} u-boot-spl-os
+
+USB device
+----------
+
+The platform code for am33xx based designs is legacy in the sense that
+it is not fully compliant with the driver model in its management of the
+various resources. This is particularly true for the USB Ethernet gadget
+which will automatically be bound to the first USB Device Controller
+(UDC). This make the USB Ethernet gadget work out of the box on common
+boards like the Beagle Bone Blacks and by default will prevents other
+gadgets to be used.
+
+The output of the 'dm tree' command shows which driver is bound to which
+device, so the user can easily configure their platform differently from
+the command line:
+
+.. code-block:: text
+
+	=> dm tree
+	 Class     Index  Probed  Driver                Name
+	-----------------------------------------------------------
+	[...]
+	misc          0  [ + ]   ti-musb-wrapper       |   |-- usb@47400000
+	usb           0  [ + ]   ti-musb-peripheral    |   |   |-- usb@47401000
+	ethernet      1  [ + ]   usb_ether             |   |   |   `-- usb_ether
+	bootdev       3  [   ]   eth_bootdev           |   |   |       `-- usb_ether.bootdev
+	usb           0  [   ]   ti-musb-host          |   |   `-- usb@47401800
+
+Typically here any network command performed using the usb_ether
+interface would work, while using other gadgets would fail:
+
+.. code-block:: text
+
+	=> fastboot usb 0
+	All UDC in use (1 available), use the unbind command
+	g_dnl_register: failed!, error: -19
+	exit not allowed from main input shell.
+
+As hinted by the primary error message, the only controller available
+(usb@47401000) is currently bound to the usb_ether driver, which makes
+it impossible for the fastboot command to bind with this device (at
+least from a bootloader point of view). The solution here would be to
+use the unbind command specifying the class and index parameters (as
+shown above in the 'dm tree' output) to target the driver to unbind:
+
+.. code-block:: text
+
+	=> unbind ethernet 1
+
+The output of the 'dm tree' command now shows the availability of the
+first USB device controller, the fastboot gadget will now be able to
+bind with it:
+
+.. code-block:: text
+
+	=> dm tree
+	 Class     Index  Probed  Driver                Name
+	-----------------------------------------------------------
+	[...]
+	misc          0  [ + ]   ti-musb-wrapper       |   |-- usb@47400000
+	usb           0  [   ]   ti-musb-peripheral    |   |   |-- usb@47401000
+	usb           0  [   ]   ti-musb-host          |   |   `-- usb@47401800
diff --git a/doc/board/ti/am62x_sk.rst b/doc/board/ti/am62x_sk.rst
index 4646bc0f52..5ed17c0a3a 100644
--- a/doc/board/ti/am62x_sk.rst
+++ b/doc/board/ti/am62x_sk.rst
@@ -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 and connect to the board
+
+.. code-block:: bash
+
+  openocd -f board/ti_am625evm.cfg
diff --git a/doc/board/ti/am65x_evm.rst b/doc/board/ti/am65x_evm.rst
index 0129235c2b..5f3c46cf9f 100644
--- a/doc/board/ti/am65x_evm.rst
+++ b/doc/board/ti/am65x_evm.rst
@@ -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 and connect to the board
+
+.. code-block:: bash
+
+  openocd -f board/ti_am654evm.cfg
diff --git a/doc/board/ti/img/openocd-overview.svg b/doc/board/ti/img/openocd-overview.svg
new file mode 100644
index 0000000000..afb6f7472a
--- /dev/null
+++ b/doc/board/ti/img/openocd-overview.svg
@@ -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>
diff --git a/doc/board/ti/j7200_evm.rst b/doc/board/ti/j7200_evm.rst
index 69abc55a93..2e60e22ba1 100644
--- a/doc/board/ti/j7200_evm.rst
+++ b/doc/board/ti/j7200_evm.rst
@@ -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 and connect to the board
+
+.. code-block:: bash
+
+  openocd -f board/ti_j7200evm.cfg
diff --git a/doc/board/ti/j721e_evm.rst b/doc/board/ti/j721e_evm.rst
index f4b4c192d9..d2a214fb33 100644
--- a/doc/board/ti/j721e_evm.rst
+++ b/doc/board/ti/j721e_evm.rst
@@ -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 and connect to the board
+
+.. code-block:: bash
+
+  openocd -f board/ti_j721eevm.cfg
diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst
index d2f86b0a11..f4576c54cb 100644
--- a/doc/board/ti/k3.rst
+++ b/doc/board/ti/k3.rst
@@ -468,3 +468,517 @@ filesystem and then imported
 
   => fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
   => env import -t ${loadaddr} ${filesize}
+
+.. _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
+card, and use an OpenOCD environment. This section uses generic
+examples, though you can apply these instructions to any supported K3
+generation device.
+
+The overall structure of this setup is in the following figure.
+
+.. 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
+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
+
+* Processor support: In general, processor support shouldn't present
+  any difficulties since OpenOCD provides solid support for both ARMv8
+  and ARMv7.
+* 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
+  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 come with an onboard JTAG adapter that
+  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 out of the
+  box support by OpenOCD. The board-specific documentation will
+  cover the details and any adapter/dongle recommendations.
+
+.. code-block:: bash
+
+ openocd -v
+
+.. note::
+
+ OpenOCD version 0.12.0 is usually required to connect to most K3
+ devices. If your device is only supported by a newer version than the
+ one provided by your distribution, you may need to build it from the source.
+
+Building OpenOCD from source
+""""""""""""""""""""""""""""
+
+The dependency package installation instructions below are for Debian
+systems, but equivalent instructions should exist for systems with
+other package managers. Please refer to the `OpenOCD Documentation
+<https://openocd.org/>`_ for more recent installation steps.
+
+.. code-block:: bash
+
+  $ # Check the packages to be installed: needs deb-src in sources.list
+  $ sudo apt build-dep openocd
+  $ # The following list is NOT complete - please check the latest
+  $ sudo apt-get install libtool pkg-config texinfo libusb-dev \
+    libusb-1.0.0-dev libftdi-dev libhidapi-dev autoconf automake
+  $ 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::
+
+  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 not necessary if the distribution supports the OpenOCD, but
+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
+  # 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
+^^^^^^^^^^^^^^^^^
+
+Most systems come with gdb-multiarch package.
+
+.. 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
+may find a few of these interesting:
+
+* `gdb-dashboard <https://github.com/cyrus-and/gdb-dashboard>`_
+* `gef <https://github.com/hugsy/gef>`_
+* `peda <https://github.com/longld/peda>`_
+* `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.
+  Using GDB is probably the safest option at this point in time.
+
+Step 3: Connect board to PC
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+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 confirmed the silk screen label to ensure
+  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 have an onboard XDS110, cTI20 connector is usually
+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>`_
+* 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 an off the shelf adapter/dongle, 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 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.
+
+.. 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 a re-initialization
+without proper shutdown.
+
+To help narrow the debug down, it is usually simpler to use the
+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:
+
+* Modify the code adding a loop to allow the debugger to attach
+  near the point of interest. Boot up normally to stop at the loop.
+* Connect with OpenOCD and step out of the loop.
+* Step through the code to find the root of issue.
+
+Typical debugging involves a few iterations of the above sequence.
+Though most bootloader developers like to use printf to debug,
+debug with JTAG tends to be most efficient since it is possible to
+investigate the code flow and inspect hardware registers without
+repeated iterations.
+
+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 */
+       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 to the code we would like to debug.
+  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) {};
+      }
+      ...
+      /* Code to run on the ARMV8 (Main Domain) */
+      if (IS_ENABLED(CONFIG_CPU_ARM64)) {
+          volatile int x = 1;
+          while(x) {};
+      }
+      .
+      .
+  }
+
+Connecting with OpenOCD for a debug session
+"""""""""""""""""""""""""""""""""""""""""""
+
+Startup OpenOCD to debug the platform as follows:
+
+* **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
+
+.. 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
+  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:
+
+.. code-block:: bash
+
+  target extended-remote localhost:{port for desired core}
+
+To load symbols:
+
+.. warning::
+
+  SPL and U-Boot does a re-location of address compared to where it
+  is loaded originally. This step takes place after the DDR size is
+  determined from dt parsing. So, debugging can be split into either
+  "before re-location" or "after re-location". Please refer to the
+  file ''doc/README.arm-relocation'' to see how to grab the relocation
+  address.
+
+* Prior to relocation:
+
+.. code-block:: bash
+
+  symbol-file {path to elf file}
+
+* After relocation:
+
+.. code-block:: bash
+
+  # Drop old symbol file
+  symbol-file
+  # Pick up new relocaddr
+  add-symbol-file {path to elf file} {relocaddr}
+
+.. 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
+if using IDE, as appropriate to the IDE.
+
+Stepping through the code
+"""""""""""""""""""""""""
+
+`GDB TUI Commands
+<https://sourceware.org/gdb/onlinedocs/gdb/TUI-Commands.html>`_ can
+help set up the display more sensible for debug. Provide the name
+of the layout that can be used to debug. For example, use the GDB
+command ``layout src`` 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 to step out of the debug
+loop set in the ``board_init_f`` function.
+
+.. 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
+GDB <https://openocd.org/doc/html/GDB-and-OpenOCD.html>`_ for further
+information.
+
+.. warning::
+
+  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.
+
+Miscellaneous notes with OpenOCD
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Currently, OpenOCD does not support tracing for K3 platforms. 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.
diff --git a/doc/board/toradex/verdin-am62.rst b/doc/board/toradex/verdin-am62.rst
index ac0e86b300..36db149cda 100644
--- a/doc/board/toradex/verdin-am62.rst
+++ b/doc/board/toradex/verdin-am62.rst
@@ -4,6 +4,9 @@
 Verdin AM62 Module
 ==================
 
+- SoM: https://www.toradex.com/computer-on-modules/verdin-arm-family/ti-am62
+- Carrier board: https://www.toradex.com/products/carrier-board/verdin-development-board-kit
+
 Quick Start
 -----------
 
@@ -74,57 +77,57 @@ Boot
 
 Output:
 
-.. code-block:: bash
-
-U-Boot SPL 2023.10-rc1-00210-gb678170a34c (Aug 03 2023 - 00:09:14 +0200)
-SYSFW ABI: 3.1 (firmware rev 0x0009 '9.0.1--v09.00.01 (Kool Koala)')
-SPL initial stack usage: 13368 bytes
-Trying to boot from MMC1
-Authentication passed
-Authentication passed
-Authentication passed
-Authentication passed
-Authentication passed
-Starting ATF on ARM64 core...
-
-NOTICE:  BL31: v2.9(release):v2.9.0-73-g463655cc8
-NOTICE:  BL31: Built : 14:51:42, Jun  5 2023
-I/TC:
-I/TC: OP-TEE version: 3.21.0-168-g322cf9e33 (gcc version 12.2.1 20221205 (Arm GNU Toolchain 12.2.Rel1 (Build arm-12.24))) #2 Mon Jun  5 13:04:15 UTC 2023 aarch64
-I/TC: WARNING: This OP-TEE configuration might be insecure!
-I/TC: WARNING: Please check https://optee.readthedocs.io/en/latest/architecture/porting_guidelines.html
-I/TC: Primary CPU initializing
-I/TC: SYSFW ABI: 3.1 (firmware rev 0x0009 '9.0.1--v09.00.01 (Kool Koala)')
-I/TC: HUK Initialized
-I/TC: Primary CPU switching to normal world boot
-
-U-Boot SPL 2023.10-rc1-00210-gb678170a34c (Aug 03 2023 - 00:09:41 +0200)
-SYSFW ABI: 3.1 (firmware rev 0x0009 '9.0.1--v09.00.01 (Kool Koala)')
-SPL initial stack usage: 1840 bytes
-Trying to boot from MMC1
-Authentication passed
-Authentication passed
-
-
-U-Boot 2023.10-rc1-00210-gb678170a34c (Aug 03 2023 - 00:09:41 +0200)
-
-SoC:   AM62X SR1.0 HS-FS
-DRAM:  2 GiB
-Core:  136 devices, 28 uclasses, devicetree: separate
-MMC:   mmc@fa10000: 0, mmc@fa00000: 1
-Loading Environment from MMC... OK
-In:    serial@2800000
-Out:   serial@2800000
-Err:   serial@2800000
-Model: Toradex 0076 Verdin AM62 Quad 2GB WB IT V1.0A
-Serial#: 15037380
-Carrier: Toradex Verdin Development Board V1.1A, Serial# 10754333
-am65_cpsw_nuss ethernet@8000000: K3 CPSW: nuss_ver: 0x6BA01103 cpsw_ver: 0x6BA81103 ale_ver: 0x00290105 Ports:2 mdio_freq:1000000
-Setting variant to wifi
-Net:
-Warning: ethernet@8000000port@1 MAC addresses don't match:
-Address in ROM is		1c:63:49:22:5f:f9
-Address in environment is	00:14:2d:e5:73:c4
-eth0: ethernet@8000000port@1 [PRIME], eth1: ethernet@8000000port@2
-Hit any key to stop autoboot:  0
-Verdin AM62 #
+.. code-block:: none
+
+  U-Boot SPL 2023.10-rc1-00210-gb678170a34c (Aug 03 2023 - 00:09:14 +0200)
+  SYSFW ABI: 3.1 (firmware rev 0x0009 '9.0.1--v09.00.01 (Kool Koala)')
+  SPL initial stack usage: 13368 bytes
+  Trying to boot from MMC1
+  Authentication passed
+  Authentication passed
+  Authentication passed
+  Authentication passed
+  Authentication passed
+  Starting ATF on ARM64 core...
+
+  NOTICE:  BL31: v2.9(release):v2.9.0-73-g463655cc8
+  NOTICE:  BL31: Built : 14:51:42, Jun  5 2023
+  I/TC:
+  I/TC: OP-TEE version: 3.21.0-168-g322cf9e33 (gcc version 12.2.1 20221205 (Arm GNU Toolchain 12.2.Rel1 (Build arm-12.24))) #2 Mon Jun  5 13:04:15 UTC 2023 aarch64
+  I/TC: WARNING: This OP-TEE configuration might be insecure!
+  I/TC: WARNING: Please check https://optee.readthedocs.io/en/latest/architecture/porting_guidelines.html
+  I/TC: Primary CPU initializing
+  I/TC: SYSFW ABI: 3.1 (firmware rev 0x0009 '9.0.1--v09.00.01 (Kool Koala)')
+  I/TC: HUK Initialized
+  I/TC: Primary CPU switching to normal world boot
+
+  U-Boot SPL 2023.10-rc1-00210-gb678170a34c (Aug 03 2023 - 00:09:41 +0200)
+  SYSFW ABI: 3.1 (firmware rev 0x0009 '9.0.1--v09.00.01 (Kool Koala)')
+  SPL initial stack usage: 1840 bytes
+  Trying to boot from MMC1
+  Authentication passed
+  Authentication passed
+
+
+  U-Boot 2023.10-rc1-00210-gb678170a34c (Aug 03 2023 - 00:09:41 +0200)
+
+  SoC:   AM62X SR1.0 HS-FS
+  DRAM:  2 GiB
+  Core:  136 devices, 28 uclasses, devicetree: separate
+  MMC:   mmc@fa10000: 0, mmc@fa00000: 1
+  Loading Environment from MMC... OK
+  In:    serial@2800000
+  Out:   serial@2800000
+  Err:   serial@2800000
+  Model: Toradex 0076 Verdin AM62 Quad 2GB WB IT V1.0A
+  Serial#: 15037380
+  Carrier: Toradex Verdin Development Board V1.1A, Serial# 10754333
+  am65_cpsw_nuss ethernet@8000000: K3 CPSW: nuss_ver: 0x6BA01103 cpsw_ver: 0x6BA81103 ale_ver: 0x00290105 Ports:2 mdio_freq:1000000
+  Setting variant to wifi
+  Net:
+  Warning: ethernet@8000000port@1 MAC addresses don't match:
+  Address in ROM is		1c:63:49:22:5f:f9
+  Address in environment is	00:14:2d:e5:73:c4
+  eth0: ethernet@8000000port@1 [PRIME], eth1: ethernet@8000000port@2
+  Hit any key to stop autoboot:  0
+  Verdin AM62 #
diff --git a/doc/board/toradex/verdin-imx8mm.rst b/doc/board/toradex/verdin-imx8mm.rst
index 439128adce..cc39030450 100644
--- a/doc/board/toradex/verdin-imx8mm.rst
+++ b/doc/board/toradex/verdin-imx8mm.rst
@@ -1,8 +1,12 @@
-.. SPDX-License-Identifier: GPL-2.0+
+.. SPDX-License-Identifier: GPL-2.0-or-later
+.. sectionauthor:: Marcel Ziswiler <marcel.ziswiler@toradex.com>
 
 Verdin iMX8M Mini Module
 ========================
 
+- SoM: https://www.toradex.com/computer-on-modules/verdin-arm-family/nxp-imx-8m-mini-nano
+- Carrier board: https://www.toradex.com/products/carrier-board/verdin-development-board-kit
+
 Quick Start
 -----------
 
@@ -25,6 +29,7 @@ Then build ATF (TF-A):
 
 .. code-block:: bash
 
+    $ export CROSS_COMPILE=aarch64-linux-gnu-
     $ make PLAT=imx8mm IMX_BOOT_UART_BASE=0x30860000 bl31
     $ cp build/imx8mm/release/bl31.bin ../
 
@@ -75,30 +80,30 @@ Boot sequence is:
 
 Output:
 
-.. code-block:: bash
-
-U-Boot SPL 2021.10-rc2-00028-gee010ba1129 (Aug 23 2021 - 16:56:02 +0200)
-Normal Boot
-WDT:   Started with servicing (60s timeout)
-Trying to boot from MMC1
-NOTICE:  BL31: v2.2(release):rel_imx_5.4.70_2.3.2_rc1-5-g835a8f67b
-NOTICE:  BL31: Built : 18:02:12, Aug 16 2021
-
-
-U-Boot 2021.10-rc2-00028-gee010ba1129 (Aug 23 2021 - 16:56:02 +0200)
-
-CPU:   Freescale i.MX8MMQ rev1.0 at 1200 MHz
-Reset cause: POR
-DRAM:  2 GiB
-WDT:   Started with servicing (60s timeout)
-MMC:   FSL_SDHC: 0, FSL_SDHC: 1, FSL_SDHC: 2
-Loading Environment from MMC... OK
-In:    serial
-Out:   serial
-Err:   serial
-Model: Toradex Verdin iMX8M Mini Quad 2GB Wi-Fi / BT IT V1.1A, Serial# 06760554
-Carrier: Toradex Verdin Development Board V1.1A, Serial# 10754333
-Setting variant to wifi
-Net:   eth0: ethernet@30be0000
-Hit any key to stop autoboot:  0
-Verdin iMX8MM #
+.. code-block:: none
+
+  U-Boot SPL 2021.10-rc2-00028-gee010ba1129 (Aug 23 2021 - 16:56:02 +0200)
+  Normal Boot
+  WDT:   Started with servicing (60s timeout)
+  Trying to boot from MMC1
+  NOTICE:  BL31: v2.2(release):rel_imx_5.4.70_2.3.2_rc1-5-g835a8f67b
+  NOTICE:  BL31: Built : 18:02:12, Aug 16 2021
+
+
+  U-Boot 2021.10-rc2-00028-gee010ba1129 (Aug 23 2021 - 16:56:02 +0200)
+
+  CPU:   Freescale i.MX8MMQ rev1.0 at 1200 MHz
+  Reset cause: POR
+  DRAM:  2 GiB
+  WDT:   Started with servicing (60s timeout)
+  MMC:   FSL_SDHC: 0, FSL_SDHC: 1, FSL_SDHC: 2
+  Loading Environment from MMC... OK
+  In:    serial
+  Out:   serial
+  Err:   serial
+  Model: Toradex Verdin iMX8M Mini Quad 2GB Wi-Fi / BT IT V1.1A, Serial# 06760554
+  Carrier: Toradex Verdin Development Board V1.1A, Serial# 10754333
+  Setting variant to wifi
+  Net:   eth0: ethernet@30be0000
+  Hit any key to stop autoboot:  0
+  Verdin iMX8MM #
diff --git a/doc/board/toradex/verdin-imx8mp.rst b/doc/board/toradex/verdin-imx8mp.rst
index 482f693577..bdc4d0c2cb 100644
--- a/doc/board/toradex/verdin-imx8mp.rst
+++ b/doc/board/toradex/verdin-imx8mp.rst
@@ -1,8 +1,12 @@
 .. SPDX-License-Identifier: GPL-2.0-or-later
+.. sectionauthor:: Marcel Ziswiler <marcel.ziswiler@toradex.com>
 
 Verdin iMX8M Plus Module
 ========================
 
+- SoM: https://www.toradex.com/computer-on-modules/verdin-arm-family/nxp-imx-8m-plus
+- Carrier board: https://www.toradex.com/products/carrier-board/verdin-development-board-kit
+
 Quick Start
 -----------
 
@@ -76,36 +80,36 @@ Boot sequence is:
 
 Output:
 
-.. code-block:: bash
-
-U-Boot SPL 2022.04-rc1-00164-g21a0312611-dirty (Feb 07 2022 - 11:34:04 +0100)
-Quad die, dual rank failed, attempting dual die, single rank configuration.
-Normal Boot
-WDT:   Started watchdog@30280000 with servicing (60s timeout)
-Trying to boot from BOOTROM
-Find img info 0x&48025a00, size 872
-Need continue download 1024
-Download 779264, Total size 780424
-NOTICE:  BL31: v2.2(release):rel_imx_5.4.70_2.3.2_rc1-5-g835a8f67b
-NOTICE:  BL31: Built : 16:52:37, Aug 26 2021
-
-
-U-Boot 2022.04-rc1-00164-g21a0312611-dirty (Feb 07 2022 - 11:34:04 +0100)
-
-CPU:   Freescale i.MX8MP[8] rev1.1 at 1200 MHz
-Reset cause: POR
-DRAM:  8 GiB
-Core:  78 devices, 18 uclasses, devicetree: separate
-WDT:   Started watchdog@30280000 with servicing (60s timeout)
-MMC:   FSL_SDHC: 1, FSL_SDHC: 2
-Loading Environment from MMC... OK
-In:    serial
-Out:   serial
-Err:   serial
-Model: Toradex Verdin iMX8M Plus Quad 4GB Wi-Fi / BT IT V1.0B, Serial# 06817281
-Carrier: Toradex Verdin Development Board V1.1A, Serial# 10807609
-Setting variant to wifi
-Net:   Hard-coding pdata->enetaddr
-eth1: ethernet@30be0000, eth0: ethernet@30bf0000 [PRIME]
-Hit any key to stop autoboot:  0
-Verdin iMX8MP #
+.. code-block:: none
+
+  U-Boot SPL 2022.04-rc1-00164-g21a0312611-dirty (Feb 07 2022 - 11:34:04 +0100)
+  Quad die, dual rank failed, attempting dual die, single rank configuration.
+  Normal Boot
+  WDT:   Started watchdog@30280000 with servicing (60s timeout)
+  Trying to boot from BOOTROM
+  Find img info 0x&48025a00, size 872
+  Need continue download 1024
+  Download 779264, Total size 780424
+  NOTICE:  BL31: v2.2(release):rel_imx_5.4.70_2.3.2_rc1-5-g835a8f67b
+  NOTICE:  BL31: Built : 16:52:37, Aug 26 2021
+
+
+  U-Boot 2022.04-rc1-00164-g21a0312611-dirty (Feb 07 2022 - 11:34:04 +0100)
+
+  CPU:   Freescale i.MX8MP[8] rev1.1 at 1200 MHz
+  Reset cause: POR
+  DRAM:  8 GiB
+  Core:  78 devices, 18 uclasses, devicetree: separate
+  WDT:   Started watchdog@30280000 with servicing (60s timeout)
+  MMC:   FSL_SDHC: 1, FSL_SDHC: 2
+  Loading Environment from MMC... OK
+  In:    serial
+  Out:   serial
+  Err:   serial
+  Model: Toradex Verdin iMX8M Plus Quad 4GB Wi-Fi / BT IT V1.0B, Serial# 06817281
+  Carrier: Toradex Verdin Development Board V1.1A, Serial# 10807609
+  Setting variant to wifi
+  Net:   Hard-coding pdata->enetaddr
+  eth1: ethernet@30be0000, eth0: ethernet@30bf0000 [PRIME]
+  Hit any key to stop autoboot:  0
+  Verdin iMX8MP #
diff --git a/doc/develop/board_best_practices.rst b/doc/develop/board_best_practices.rst
new file mode 100644
index 0000000000..f44401eab7
--- /dev/null
+++ b/doc/develop/board_best_practices.rst
@@ -0,0 +1,26 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+Best Practices for Board Ports
+==============================
+
+In addition to the regular best practices such as using :doc:`checkpatch` and
+following the :doc:`docstyle` and the :doc:`codingstyle` there are some things
+which are specific to creating a new board port.
+
+* Implement :doc:`bootstd` to ensure that most operating systems will be
+  supported by the platform.
+
+* The platform defconfig file must be generated via `make savedefconfig`.
+
+* The Kconfig and Kbuild infrastructure supports using "fragments" that can be
+  used to apply changes on top of a defconfig file. These can be useful for
+  many things such as:
+
+  * Supporting different firmware locations (e.g. eMMC, SD, QSPI).
+
+  * Multiple board variants when runtime detection is not desired.
+
+  * Supporting different build types such as production and development.
+
+  Kconfig fragments should reside in the board directory itself rather than in
+  the top-level `configs/` directory.
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index 263d404b4c..5b230d0321 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -9,6 +9,7 @@ General
 .. toctree::
    :maxdepth: 1
 
+   board_best_practices
    codingstyle
    designprinciples
    docstyle
diff --git a/doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt b/doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt
index da210bfc86..1381bdcd16 100644
--- a/doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt
+++ b/doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt
@@ -41,3 +41,6 @@ Example: Bundles both peripheral bitstream and core bitstream into FIT image
 		resets = <&rst FPGAMGR_RESET>;
 		altr,bitstream = "fit_spl_fpga.itb";
 	};
+
+- The .its related documentations can be found here
+	- Appendix - Reducing Arria 10 Fabric Configuration Time - https://rocketboards.org/foswiki/Documentation/BuildingBootloaderCycloneVAndArria10