boards: ti: am243x_evm: add documentation

Add documentation for am243x_evm and while at it, add the openocd
configuration as well.

Co-authored-by: Mika Braunschweig <[email protected]>
Signed-off-by: Amneesh Singh <[email protected]>

Author: natto1784

boards/ti/am243x_evm/doc/img/tmds243evm-angled.webp

@@ -0,0 +1,280 @@
+.. zephyr:board:: am243x_evm
+
+Overview
+********
+
+The AM243x EVM is a development board that is based of a AM2434 SoC. The
+Cortex R5F cores in the SoC run at 800 MHz. The board also includes a flash
+region, DIP-Switches for the boot mode selection and 2 RJ45 Ethernet ports.
+
+See the `TI TMDS243EVM Product Page`_ for details.
+
+Hardware
+********
+
+The AM2434 SoC has 2 domains. A MAIN domain and a MCU domain. The MAIN domain
+consists of 4 R5F cores and the MCU domain of one M4F core.
+
+Zephyr currently supports the following cores:
+
+- R5F Subsystem 0 Core 0 (R5F0_0)
+- M4F Core (M4)
+
+The board physically contains:
+
+- Memory.
+
+   - 256KB of SRAM
+   - 2GB of DDR4
+
+- Debug
+
+   - XDS110 based JTAG
+
+Devices
+========
+System Clock
+------------
+
+This board configuration uses a system clock frequency of
+
+- 800MHz for R5F0_0
+- 400MHz for M4
+
+DDR RAM
+-------
+
+The board has 2GB of DDR RAM available. This board configuration allocates:
+
+- 4KB Resource Table at 0xa4100000 for M4
+- 4KB Resource Table at 0xa0100000 for R5F0_0
+- 8MB Shared Memory at 0xa5000000 for inter-processor communication
+
+Serial Port
+-----------
+
+This board configuration uses by default:
+
+- MAIN domain UART (UART0) for R5F0_0
+- MCU domain UART (MCU_UART0) for M4
+
+Supported Features
+==================
+
+.. zephyr:board-supported-hw::
+
+
+Flashing
+********
+The boot process of the AM2434 SoC requires the booting image to be in a
+specific format and to wait for the internal DMSC-L of the AM2434 to start up
+and configure memory firewalls. Since there exists no Zephyr support it's
+required to use one of the SBL bootloader examples from the TI MCU+ SDK.
+
+
+Prerequisites
+=============
+
+The following steps are from the time this documentation was written and might
+change in the future. They also target Linux with assumption some basic things
+(like python3 and openssl) are installed.
+
+You might also want to take a look at the `Bootflow Guide`_ for more details.
+
+To build these you need to install the TI MCU+ SDK. To do this you need to
+follow the steps described in the ``mcupsdk-core`` repository, which includes
+cloning the repositories with west.  It's recommended to use another Python venv
+for this since the MCU+ SDK has own Python dependencies that could conflict with
+Zephyr dependencies. You can replace ``all/dev.yml`` in the ``west init``
+command with ``am243x/dev.yml``, if you want to clone a few less repositories.
+
+You also need to follow the "Downloading And Installing Dependencies" section
+but you need to replace all ``am263x`` occurences in commands with ``am243x``.
+Please also take note of the ``tools`` and ``mcu_plus_sdk`` install path. The
+``tools`` install path will later be referred to as ``$TI_TOOLS`` and the MCU+
+SDK path as ``$MCUPSDK``. You can pass ``--skip_doxygen=true`` and
+``--skip_ccs=true`` to the install script since they aren't needed. You might
+encounter a error that a script can't be executed. To fix it you need to mark it
+as executable with ``chmod +x <path>`` and run the ``download_components.sh``
+again.
+
+Summarized you will most likely want to run the following commands or similar
+versions for setting up the MCU+ SDK:
+
+.. code-block:: console
+
+   python3 -m venv .venv
+   source .venv/bin/activate
+   pip3 install west
+   west init -m https://github.com/TexasInstruments/mcupsdk-manifests.git --mr mcupsdk_west --mf am243x/dev.yml
+   west update
+   ./mcupsdk_setup/am243x/download_components.sh --skip_doxygen=true --skip_ccs=true
+
+After the script finished successfully you want to switch into the
+``mcu_plus_sdk`` directory and edit the
+``source/drivers/bootloader/bootloader.c`` file to set the ``entryPoint`` to
+``0`` inside ``Bootloader_runCpu`` unconditionally. This is needed due to how
+Zephyr builds the image currently.
+
+Now you can build the internal libraries with the following commands:
+
+.. code-block:: console
+
+   make gen-buildfiles DEVICE=am243x PROFILE=release
+   make libs DEVICE=am243x PROFILE=release
+
+If you encounter compile errors you have to fix them. For that you might have to
+change parameter types, remove missing source files from makefiles or download
+missing headers from the TI online reference.
+
+Depending on whether you later want to boot from flash or by loading the image
+via UART either the ``sbl_ospi`` or the ``sbl_uart`` example is relevant for the
+next section.
+
+
+Building the bootloader itself
+==============================
+
+The example bootloader implementation is found in the
+``examples/drivers/boot/<example>/am243x-evm/r5fss0-0_nortos`` directory.
+
+You can either build the example by invoking ``make -C
+examples/drivers/boot/<example>/am243x-evm/r5fss0-0_nortos/ti-arm-clang/
+DEVICE=am243x PROFILE=release`` or use the prebuilt binaries in
+``tools/boot/sbl_prebuilt/am243x-evm``
+
+
+Converting the Zephyr application
+=================================
+
+Additionally for booting you need to convert your built Zephyr binary into a
+format that the TI example bootloader can boot. You can do this with the
+following commands, where ``$TI_TOOLS`` refers to the root of where your
+ti-tools (clang, sysconfig etc.) are installed (``$HOME/ti`` by default) and
+``$MCUPSDK`` to the root of the MCU+ SDK (directory called ``mcu_plus_sdk``).
+You might have to change version numbers in the commands. It's expected that the
+``zephyr.elf`` from the build output is in the current directory.
+
+.. code-block:: bash
+
+   export BOOTIMAGE_CORE_ID_r5fss0-0=4
+   export BOOTIMAGE_CORE_ID_m4=14
+   # set CORE_ID as per your target core
+   export BOOTIMAGE_CORE_ID=${BOOTIMAGE_CORE_ID_desired-core}
+   $TI_TOOLS/sysconfig_1.21.2/nodejs/node $MCUPSDK/tools/boot/out2rprc/elf2rprc.js ./zephyr.elf
+   $MCUPSDK/tools/boot/xipGen/xipGen.out -i ./zephyr.rprc -o ./zephyr.rprc_out -x ./zephyr.rprc_out_xip --flash-start-addr 0x60000000
+   $TI_TOOLS/sysconfig_1.21.2/nodejs/node $MCUPSDK/tools/boot/multicoreImageGen/multicoreImageGen.js --devID 55 --out ./zephyr.appimage ./zephyr.rprc_out@${BOOTIMAGE_CORE_ID}
+   $TI_TOOLS/sysconfig_1.21.2/nodejs/node $MCUPSDK/tools/boot/multicoreImageGen/multicoreImageGen.js --devID 55 --out ./zephyr.appimage_xip ./zephyr.rprc_out_xip@${BOOTIMAGE_CORE_ID}
+   python3 $MCUPSDK/source/security/security_common/tools/boot/signing/appimage_x509_cert_gen.py --bin ./zephyr.appimage --authtype 1 --key $MCUPSDK/source/security/security_common/tools/boot/signing/app_degenerateKey.pem --output ./zephyr.appimage.hs_fs
+
+All these steps are also present in various Makefiles in the ``examples/``
+directory of MCU+ SDK source.
+
+
+Running the Zephyr image
+========================
+
+After that you want to switch the bootmode to UART by switching the DIP-Switches
+into the following configuration:
+
+.. list-table:: UART Boot Mode
+   :header-rows: 1
+
+   * - SW2 [0:7]
+     - SW3 [8:15]
+   * - 11011100
+     - 10110000
+
+If you want to just run the image via UART you need to run
+
+.. code-block:: console
+
+ python3 uart_bootloader.py -p /dev/ttyUSB0 --bootloader=sbl_uart.release.hs_fs.tiimage --file=zephyr.appimage.hs_fs
+
+The ``uart_bootloader.py`` script is found in ``$MCUPSDK/tools/boot`` and the
+``sbl_uart.release.hs_fs.tiimage`` in
+``$MCUPSDK/tools/boot/sbl_prebuilt/am243x-evm``.  After sending the image your
+Zephyr application will run after a 2 second long delay.
+
+If you want to flash the image instead you have to take the OSPI example config
+file from the ``$MCUPSDK/tools/boot/sbl_prebuilt/am243x-evm`` directory and
+change the filepath according to your names. It should look approximately like:
+
+.. code-block::
+
+   --flash-writer=sbl_uart_uniflash.release.hs_fs.tiimage
+   --operation=flash-phy-tuning-data
+   --file=sbl_prebuilt/am243x-evm/sbl_ospi.release.hs_fs.tiimage --operation=flash --flash-offset=0x0
+   --file=zephyr.appimage.hs_fs --operation=flash --flash-offset=0x80000
+   --file=zephyr.appimage_xip --operation=flash-xip
+
+You then need to run ``python3 uart_uniflash.py -p /dev/ttyUSB0
+--cfg=<path/to/your-config-file>``. The scripts and images are in the same path
+as described in the UART section above.
+
+After flashing your image you can power off your board, switch the DIP-Switches
+into following configuration to boot in OSPI mode and your Zephyr application
+will boot immediately after powering on the board.
+
+.. list-table:: OSPI Boot Mode
+   :header-rows: 1
+
+   * - SW2 [0:7]
+     - SW3 [8:15]
+   * - 11001110
+     - 01000000
+
+Debugging
+*********
+
+OpenOCD
+=======
+
+The board is equipped with an XDS110 JTAG debugger. To debug a binary, utilize
+the ``debug`` build target:
+
+.. zephyr-app-commands::
+   :app: <my_app>
+   :board: am243x_evm/<soc>/<core>
+   :maybe-skip-config:
+   :goals: debug
+
+.. hint::
+   To utilize this feature, you'll need OpenOCD version 0.12 or higher. Due to the possibility of
+   older versions being available in package feeds, it's advisable to `build OpenOCD from source`_.
+
+Code Composer Studio
+====================
+
+Instead of using ``sbl_ospi`` from above, one may also flash ``sbl_null`` and load the
+application ELFs using Code Composer Studio IDE to individual cores and run/debug
+the application. Note that this does not require converting the Zephyr ELF to another
+forma, making development much easier.
+
+
+References
+**********
+
+AM64x/AM243x EVM Technical Reference Manual:
+   https://www.ti.com/lit/ug/spruj63a/spruj63a.pdf
+
+MCU+ SDK Github repository:
+   https://github.com/TexasInstruments/mcupsdk-core
+
+.. _Bootflow Guide:
+   https://software-dl.ti.com/mcu-plus-sdk/esd/AM64X/latest/exports/docs/api_guide_am64x/BOOTFLOW_GUIDE.html
+
+.. _TI TMDS243EVM Product Page:
+   https://www.ti.com/tool/TMDS243EVM
+
+.. _build OpenOCD from source:
+   https://docs.u-boot.org/en/latest/board/ti/k3.html#building-openocd-from-source
+
+License
+*******
+
+This document Copyright (c) Siemens Mobility GmbH
+
+This document Copyright (c) 2025 Texas Instruments
+
+SPDX-License-Identifier: Apache-2.0

boards/ti/am243x_evm/doc/index.rst

@@ -0,0 +1,7 @@
+# Texas Instruments AM243x EVM
+#
+# Copyright (c) 2025 Texas Instruments
+#
+# SPDX-License-Identifier: Apache-2.0
+
+source [find board/ti_am243_launchpad.cfg]