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`: 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`: 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 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + Cortex-R + + + + Cortex-R + + + + + + + + + + Cortex-A + + + + Cortex-A + + + + + + + + K3 SoC + + + + K3 SoC + + + + + + + + + + + + + Debug SS + + + + Debug SS + + + + + + + + + + + Jtag Interface +(XDS110, TUMPA..) + + + + Jtag Interface... + + + + + + + + + + + PC + + + + PC + + + + + + + + USB + + + + USB + + + + + + + + JTAG + + + + JTAG + + + + + + + + + OpenOCD + + + + OpenOCD + + + + + + + + + + + GDB + + + + GDB + + + + + + + + + + + IDE debugging code + + + + IDE debugging code + + + + 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`: 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`: 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 +`_ 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 + `_ 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 `_ +documentation to pick the installation steps appropriate to your +environment. Some references to OpenOCD documentation: + +* `OpenOCD User Guide `_ +* `OpenOCD Developer's Guide `_ + +Refer to the release notes corresponding to the `OpenOCD version +`_ 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 +`_ 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 `_ + 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 `_ +* `gef `_ +* `peda `_ +* `pwndbg `_ +* `voltron `_ +* `ddd `_ +* `vscode `_ +* `vim conque-gdb `_ +* `emacs realgud `_ +* `Lauterbach IDE `_ + +.. 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 +`_ 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 `_ or `XDS560 +`_. + +To debug on these boards, the following combinations is suggested: + +* `TUMPA `_ + or `equivalent dongles supported by OpenOCD. `_ +* Cable such as `Tag-connect ribbon cable `_ +* Adapter to convert cTI20 to ARM20 such as those from + `Segger `_ + or `Lauterbach LA-3780 `_ + Or optionally, if you have manufacturing capability then you could try + `BeagleBone JTAG Adapter `_ + +.. 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 `_. + +.. k3_rst_include_end_openocd_connect_cti20 + +.. k3_rst_include_start_openocd_connect_tag_connect + +**Tag-Connect**: `Tag-Connect `_ +pads on the boards which require special cable. Please check the documentation +to `identify `_ if "legged" +or "no-leg" version of the cable is appropriate for the board. + +To debug on these boards, you will need: + +* `TUMPA `_ + or `equivalent dongles supported by OpenOCD `_. +* Tag-Connect cable appropriate to the board such as + `TC2050-IDC-NL `_ +* In case of no-leg, version, a + `retaining clip `_ +* Tag-Connect to ARM20 + `adapter `_ + +.. note:: + You can optionally use a 3d printed solution such as + `Protective cap `_ or + `clip `_ 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 + `_ + 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 +`_ 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 `_ 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 +.. 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 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 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 +.. 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 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 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 +.. 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 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