diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/board/nxp/imx8mp_evk.rst | 17 | ||||
-rw-r--r-- | doc/board/ti/am335x_evm.rst | 62 | ||||
-rw-r--r-- | doc/board/ti/am62x_sk.rst | 24 | ||||
-rw-r--r-- | doc/board/ti/am65x_evm.rst | 24 | ||||
-rw-r--r-- | doc/board/ti/img/openocd-overview.svg | 580 | ||||
-rw-r--r-- | doc/board/ti/j7200_evm.rst | 24 | ||||
-rw-r--r-- | doc/board/ti/j721e_evm.rst | 24 | ||||
-rw-r--r-- | doc/board/ti/k3.rst | 514 | ||||
-rw-r--r-- | doc/board/toradex/verdin-am62.rst | 111 | ||||
-rw-r--r-- | doc/board/toradex/verdin-imx8mm.rst | 61 | ||||
-rw-r--r-- | doc/board/toradex/verdin-imx8mp.rst | 70 | ||||
-rw-r--r-- | doc/develop/board_best_practices.rst | 26 | ||||
-rw-r--r-- | doc/develop/index.rst | 1 | ||||
-rw-r--r-- | doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt | 3 |
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 |