From effe50854a6964b6cf0f30e2716bec052a770d10 Mon Sep 17 00:00:00 2001 From: Jason Kacines Date: Thu, 3 Aug 2023 01:29:22 -0500 Subject: [PATCH 1/7] doc: board: ti: k3: Add a guide to debugging with OpenOCD Bootloader debug usually tends to be a bit dicey prior to DDR and serial port getting active in the system. JTAG typically remains the only practical debug option during the initial bringup. OpenOCD is one of the most popular environment for providing debug capability via a GDB compatible interface for developers to work with. Debugging U-Boot and bootloaders on K3 platform does have a bit of tribal knowledge that is better documented in our common platform documentation. Signed-off-by: Jason Kacines Signed-off-by: Nishanth Menon --- doc/board/ti/am62x_sk.rst | 24 ++ doc/board/ti/am65x_evm.rst | 24 ++ doc/board/ti/img/openocd-overview.svg | 580 ++++++++++++++++++++++++++ doc/board/ti/j7200_evm.rst | 24 ++ doc/board/ti/j721e_evm.rst | 24 ++ doc/board/ti/k3.rst | 514 +++++++++++++++++++++++ 6 files changed, 1190 insertions(+) create mode 100644 doc/board/ti/img/openocd-overview.svg diff --git a/doc/board/ti/am62x_sk.rst b/doc/board/ti/am62x_sk.rst index 4646bc0f525..5ed17c0a3a5 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 0129235c2b2..5f3c46cf9f9 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 00000000000..afb6f7472a4 --- /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 69abc55a93c..2e60e22ba15 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 f4b4c192d9d..d2a214fb33f 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 d2f86b0a11a..f4576c54cb3 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. From b8531ac4d11b274c50803f90a0ffc5a9064f9836 Mon Sep 17 00:00:00 2001 From: Jit Loon Lim Date: Fri, 4 Aug 2023 10:28:39 +0800 Subject: [PATCH 2/7] doc: Add the link for the documentation of the .its Provide the link for the .its related documentation for Arria10. Signed-off-by: Jit Loon Lim --- doc/device-tree-bindings/fpga/altera-socfpga-a10-fpga-mgr.txt | 3 +++ 1 file changed, 3 insertions(+) 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 da210bfc86b..1381bdcd164 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 From 636acb40223ecb287c4c8a971daafccd521b4e77 Mon Sep 17 00:00:00 2001 From: Marcel Ziswiler Date: Mon, 7 Aug 2023 01:44:46 +0200 Subject: [PATCH 3/7] doc: board: toradex: fix verdin module output Fix the Verdin module output which was missing white space for correct rendering. While at it also leave product links, add section author also for the Verdin iMX8M Mini and Plus, and add a missing CROSS_COMPILE export for the Verdin iMX8M Mini. Signed-off-by: Marcel Ziswiler Reviewed-by: Nishanth Menon #verdin-am62 Reviewed-by: Tom Rini --- doc/board/toradex/verdin-am62.rst | 99 +++++++++++++++-------------- doc/board/toradex/verdin-imx8mm.rst | 53 ++++++++------- doc/board/toradex/verdin-imx8mp.rst | 62 +++++++++--------- 3 files changed, 113 insertions(+), 101 deletions(-) diff --git a/doc/board/toradex/verdin-am62.rst b/doc/board/toradex/verdin-am62.rst index ac0e86b3001..36db149cda0 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 439128adceb..cc39030450f 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 482f6935779..bdc4d0c2cb5 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 # From c631cf84dba9204ca1167b613b72847b6b18e7e4 Mon Sep 17 00:00:00 2001 From: Miquel Raynal Date: Mon, 7 Aug 2023 08:42:41 +0200 Subject: [PATCH 4/7] doc: ti: Explain how the various gadget devices can be used Describe the current situation wrt the handling of USB devices on AM33xx based boards, taking the example of a common board (the Beagle Bone Black) and explaining how the different USB gadgets can be used. Signed-off-by: Miquel Raynal --- doc/board/ti/am335x_evm.rst | 62 +++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/doc/board/ti/am335x_evm.rst b/doc/board/ti/am335x_evm.rst index ee4faec37c2..3332d51b365 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 From 961519b58d1c578f88a8a1f8c6ed78344cb47c96 Mon Sep 17 00:00:00 2001 From: Fabio Estevam Date: Mon, 7 Aug 2023 10:42:46 -0300 Subject: [PATCH 5/7] doc: imx8mp_evk: Remove unneeded export ATF_LOAD_ADDR line Originally, exporting the ATF_LOAD_ADDR was required, but since binman has been used to generate the flash.bin, it is no longer needed to do such manual export. The ATF address is now passed via binman in imx8mp-u-boot.dtsi: atf { description = "ARM Trusted Firmware"; type = "firmware"; arch = "arm64"; compression = "none"; load = <0x970000>; entry = <0x970000>; atf_blob: atf-blob { filename = "bl31.bin"; type = "atf-bl31"; }; }; Remove the unneeded export ATF_LOAD_ADDR line. Signed-off-by: Fabio Estevam Reviewed-by: Peng Fan --- doc/board/nxp/imx8mp_evk.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/board/nxp/imx8mp_evk.rst b/doc/board/nxp/imx8mp_evk.rst index e7cc7b396b5..e106c3c7187 100644 --- a/doc/board/nxp/imx8mp_evk.rst +++ b/doc/board/nxp/imx8mp_evk.rst @@ -44,7 +44,6 @@ Build U-Boot $ 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 Burn the flash.bin to the MicroSD card at offset 32KB: From 8134043dada24a1879d85a9218c24c617ee4ae1e Mon Sep 17 00:00:00 2001 From: Fabio Estevam Date: Mon, 7 Aug 2023 10:42:47 -0300 Subject: [PATCH 6/7] doc: imx8mp_evk: Use in-tree build in the example To make it consistent with the instructions from other NXP imx8m boards, such as imx8mm-evk and imx8mn-evk, use U-Boot in-tree build in the examples. Signed-off-by: Fabio Estevam Reviewed-by: Peng Fan --- doc/board/nxp/imx8mp_evk.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/doc/board/nxp/imx8mp_evk.rst b/doc/board/nxp/imx8mp_evk.rst index e106c3c7187..72175dbe78f 100644 --- a/doc/board/nxp/imx8mp_evk.rst +++ b/doc/board/nxp/imx8mp_evk.rst @@ -37,20 +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/ - $ 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 ---- From fa43709b8d7aa30b6d1039dce854c5eea86f122f Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Tue, 8 Aug 2023 16:36:16 -0400 Subject: [PATCH 7/7] doc: Begin adding a best practices document for board ports To help guide developers down the right path, begin a document that lists some best practices to follow when creating a new board port. Signed-off-by: Tom Rini Reviewed-by: Simon Glass --- doc/develop/board_best_practices.rst | 26 ++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 2 files changed, 27 insertions(+) create mode 100644 doc/develop/board_best_practices.rst diff --git a/doc/develop/board_best_practices.rst b/doc/develop/board_best_practices.rst new file mode 100644 index 00000000000..f44401eab7d --- /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 263d404b4ca..5b230d0321f 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