Skip to main content

FreeRTOS Porting Guide for EDM-IMX95

Applicable Platforms​

This guide applies to the following build targets:

Build targetPlatform
edm-imx95EDM-IMX95
edm-imx95-rEDM-IMX95-R

Introduction​

This guide describes how to build and flash FreeRTOS demo applications for the Cortex-M7 core of the NXP i.MX95 platform. The BSP is based on NXP MCUXpresso SDK SDK_25_09_00_MIMX9596xxxxN and uses a Docker build environment.

The build script generates three M7 boot images: Hello World, RPMsg-Lite String Echo, and RPMsg-Lite Ping Pong. Each image can be flashed to eMMC using NXP Universal Update Utility (uuu).

The RPMsg examples also require a compatible Linux image with the appropriate remoteproc, RPMsg, and device tree configuration. Flashing an M7 boot image alone does not configure the Linux side of the communication link.

Part 1: Set Up the Environment​

1.1 Host Requirements​

Prepare a Linux host with the following tools:

  • Git
  • The repo tool
  • Docker
  • NXP Universal Update Utility (uuu)

Ensure Docker is running and your user account has permission to run Docker commands. The ARM GCC toolchain and CMake are provided by the Docker build environment and do not need to be installed separately on the host.

1.2 Download the Source Code​

Create a workspace, initialize the manifest, and synchronize the repositories:

mkdir -p tn_demo
cd tn_demo

repo init \
-u https://github.com/TechNexion/freertos-tn.git \
-b freertos_25.09.x_imx95 \
-m uboot-manifest/tn-imx_6.18.37_2.1.0_manifest.xml

repo sync

Run the following build steps in the same terminal session.

1.3 Build the Docker Image​

From the tn_demo workspace root:

cd sources/freertos-tn/build-tools/
./build_docker.sh

After the Docker image has been built, return to the workspace root:

cd ../../../

Part 2: Build the Demo Applications​

2.1 Start the Build​

From the tn_demo workspace root, run:

./build_flash_bin.sh -b

The -b / --build option is required to start compilation. To explicitly select the target platform, use one of the following commands.

For edm-imx95:

./build_flash_bin.sh -p edm-imx95 -b

For edm-imx95-r:

./build_flash_bin.sh --set-project-type edm-imx95-r --build

2.2 Build Options​

OptionDescription
-h, --helpShow the help message and exit.
-c, --cleanClean previous build artifacts and exit.
-p, --set-project-type <TYPE>Specify the build project type: edm-imx95 or edm-imx95-r.
-b, --buildStart the build process.

Display the available options:

./build_flash_bin.sh --help

Clean previous build artifacts:

./build_flash_bin.sh -c

The clean command exits after cleaning. Run a build command afterward to generate new images.

2.3 Build Output​

After a successful build, the script creates an output/ directory under the tn_demo workspace root with the following files:

FileDemo application
m7_hello_world_flash.binHello World
m7_rpmsg_lite_str_echo_flash.binRPMsg-Lite String Echo
m7_rpmsg_lite_pingpong_flash.binRPMsg-Lite Ping Pong

Check the generated images:

ls -lh output/m7_*_flash.bin

Part 3: Prepare the Board for Flashing​

  1. Set the EDM-IMX95 or EDM-IMX95-R board to Serial Download Mode using the boot mode settings for your board and carrier.
  2. Connect the board's USB download port to the Linux host.
  3. Power on or reset the board so that it enters Serial Download Mode.
  4. Flash the image for the example you want to run, as described below.
  5. After flashing completes successfully, switch the board to eMMC boot mode and power-cycle or reset it.

Connect a serial terminal to the board's Cortex-M7 debug console to observe application output. Use the UART connection and serial settings specified for your board and BSP.

The general flashing command is:

uuu -b emmc <flash.bin_file_name>

All host-side flashing examples below run from the tn_demo workspace root. Flash one demo image at a time; repeat the Serial Download Mode procedure when switching examples.

Part 4: Run the Hello World Example​

4.1 Flash the Image​

With the board in Serial Download Mode, run on the host:

uuu -b emmc output/m7_hello_world_flash.bin

4.2 Verify the Application​

After flashing completes, switch the board to eMMC boot mode and restart it.

Check the Cortex-M7 debug console for the Hello World startup message. If the application prompts for input, type text in the serial terminal to verify console interaction. The exact startup text depends on the application revision.

Part 5: Run the RPMsg-Lite String Echo Example​

5.1 Linux Requirements​

Use a Linux BSP configured to communicate with the M7 firmware. Its remoteproc configuration, shared memory regions, vrings, mailbox configuration, and RPMsg channel must match the firmware.

For a TTY-based echo test, Linux must include the imx_rpmsg_tty driver, and the M7 firmware must announce a channel supported by that driver. A firmware image announcing a different endpoint requires the corresponding Linux driver or userspace client.

5.2 Flash the Image​

With the board in Serial Download Mode, run on the host:

uuu -b emmc output/m7_rpmsg_lite_str_echo_flash.bin

Switch the board to eMMC boot mode, restart it, and allow Linux to boot.

On the board's Linux console, inspect the RPMsg devices and kernel messages:

ls /sys/bus/rpmsg/devices/
dmesg | grep -iE 'remoteproc|rpmsg|virtio'

If the TTY driver is built as a module, load it:

modprobe imx_rpmsg_tty

Find the TTY device created by the driver:

ls /dev/ttyRPMSG*

Use the actual device name reported by your system. For example, if /dev/ttyRPMSG30 is present:

echo "this is a test" > /dev/ttyRPMSG30

Observe the M7 debug console and the Linux-side receive interface to verify message handling. The RPMsg TTY device number and console output depend on the Linux BSP and firmware revision.

Part 6: Run the RPMsg-Lite Ping Pong Example​

6.1 Linux Requirements​

Use a Linux BSP with a matching RPMsg configuration and an imx_rpmsg_pingpong driver that supports the channel announced by the M7 firmware.

6.2 Flash the Image​

With the board in Serial Download Mode, run on the host:

uuu -b emmc output/m7_rpmsg_lite_pingpong_flash.bin

Switch the board to eMMC boot mode, restart it, and allow Linux to boot.

6.3 Verify Message Exchange​

If the Linux Ping Pong driver is built as a module, load it:

modprobe imx_rpmsg_pingpong

Inspect the Linux kernel log:

dmesg | grep -iE 'remoteproc|rpmsg|virtio|pingpong'

Observe the M7 debug console and Linux kernel log for message exchange. The exact messages depend on the example and driver revisions.

Troubleshooting​

Docker Image Build Fails​

  • Check that Docker is running and your user can run Docker commands.
  • Check network access required by the Docker build.
  • Review the first error reported by build_docker.sh.

No Build Images Are Generated​

  • Include -b or --build in the build command.
  • Run build_flash_bin.sh from the tn_demo workspace root.
  • Select the correct project type with -p.
  • Review the build log for errors before checking output/.

UUU Cannot Detect the Board​

  • Verify that the board is in Serial Download Mode and has been reset after changing its boot settings.
  • Use the board's USB download port and a USB data cable.
  • Check USB device access permissions on the host.

No M7 Console Output After Flashing​

  • Confirm that uuu completed successfully.
  • Confirm that the image was built for the correct platform.
  • Switch to eMMC boot mode and restart the board.
  • Verify the M7 debug UART connection and serial terminal settings.
  • Confirm that a compatible Linux image has booted.
  • Check Linux remoteproc, virtio, and RPMsg initialization messages.
  • Check that the Linux device tree and M7 firmware use matching shared memory, vring, and mailbox settings.
ls /sys/class/remoteproc/
ls /sys/bus/virtio/devices/
ls /sys/bus/rpmsg/devices/
dmesg | grep -iE 'remoteproc|rpmsg|virtio'

No RPMsg TTY Device Is Created​

  • Confirm that Linux includes CONFIG_IMX_RPMSG_TTY and load imx_rpmsg_tty if it is a module.
  • Check that the M7 firmware announces a channel supported by the TTY driver.
  • Check /sys/bus/rpmsg/devices/ and the kernel log for channel creation and driver binding.
  • Use the actual /dev/ttyRPMSG* device name reported by the system.

References​