boards/ti/am243x_evm/doc/index.rst - third_party/github/zephyrproject-rtos/zephyr - Git at Google

 .. 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`` occurrences 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
	.. 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`` occurrences 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