diff --git a/boards/ti/am243x_evm/doc/img/tmds243evm-angled.webp b/boards/ti/am243x_evm/doc/img/tmds243evm-angled.webp new file mode 100644 index 00000000000..87e99a11039 Binary files /dev/null and b/boards/ti/am243x_evm/doc/img/tmds243evm-angled.webp differ diff --git a/boards/ti/am243x_evm/doc/index.rst b/boards/ti/am243x_evm/doc/index.rst new file mode 100644 index 00000000000..9689e094f9c --- /dev/null +++ b/boards/ti/am243x_evm/doc/index.rst @@ -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 `` 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//am243x-evm/r5fss0-0_nortos`` directory. + +You can either build the example by invoking ``make -C +examples/drivers/boot//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=``. 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: + :board: am243x_evm// + :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 diff --git a/boards/ti/am243x_evm/support/openocd.cfg b/boards/ti/am243x_evm/support/openocd.cfg new file mode 100644 index 00000000000..61a4d85b4c3 --- /dev/null +++ b/boards/ti/am243x_evm/support/openocd.cfg @@ -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]