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
diff --git a/doc/board/nxp/imx8mp_evk.rst b/doc/board/nxp/imx8mp_evk.rst
index e7cc7b3..72175db 100644
--- a/doc/board/nxp/imx8mp_evk.rst
+++ b/doc/board/nxp/imx8mp_evk.rst
@@ -37,21 +37,22 @@
.. 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 ee4faec..3332d51 100644
--- a/doc/board/ti/am335x_evm.rst
+++ b/doc/board/ti/am335x_evm.rst
@@ -201,3 +201,65 @@
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 4646bc0f..5ed17c0 100644
--- a/doc/board/ti/am62x_sk.rst
+++ b/doc/board/ti/am62x_sk.rst
@@ -246,3 +246,27 @@
- 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 0129235..5f3c46c 100644
--- a/doc/board/ti/am65x_evm.rst
+++ b/doc/board/ti/am65x_evm.rst
@@ -287,3 +287,27 @@
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 0000000..afb6f74
--- /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 69abc55..2e60e22 100644
--- a/doc/board/ti/j7200_evm.rst
+++ b/doc/board/ti/j7200_evm.rst
@@ -201,3 +201,27 @@
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 f4b4c19..d2a214f 100644
--- a/doc/board/ti/j721e_evm.rst
+++ b/doc/board/ti/j721e_evm.rst
@@ -228,3 +228,27 @@
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 d2f86b0..f4576c5 100644
--- a/doc/board/ti/k3.rst
+++ b/doc/board/ti/k3.rst
@@ -468,3 +468,517 @@
=> 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 ac0e86b..36db149 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 @@
Output:
-.. code-block:: bash
+.. 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...
+ 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
+ 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 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)
+ 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 #
+ 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 439128a..cc39030 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 @@
.. 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 @@
Output:
-.. code-block:: bash
+.. 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 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)
+ 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 #
+ 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 482f693..bdc4d0c 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 @@
Output:
-.. code-block:: bash
+.. 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 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)
+ 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 #
+ 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 0000000..f44401e
--- /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 263d404..5b230d0 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -9,6 +9,7 @@
.. 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 da210bf..1381bdc 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 @@
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
