FreeRTOS Porting Guide for EDM-IMX95
Applicable Platforms
This guide applies to the following build targets:
| Build target | Platform |
|---|---|
edm-imx95 | EDM-IMX95 |
edm-imx95-r | EDM-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
repotool - 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
| Option | Description |
|---|---|
-h, --help | Show the help message and exit. |
-c, --clean | Clean previous build artifacts and exit. |
-p, --set-project-type <TYPE> | Specify the build project type: edm-imx95 or edm-imx95-r. |
-b, --build | Start 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:
| File | Demo application |
|---|---|
m7_hello_world_flash.bin | Hello World |
m7_rpmsg_lite_str_echo_flash.bin | RPMsg-Lite String Echo |
m7_rpmsg_lite_pingpong_flash.bin | RPMsg-Lite Ping Pong |
Check the generated images:
ls -lh output/m7_*_flash.bin
Part 3: Prepare the Board for Flashing
- Set the EDM-IMX95 or EDM-IMX95-R board to Serial Download Mode using the boot mode settings for your board and carrier.
- Connect the board's USB download port to the Linux host.
- Power on or reset the board so that it enters Serial Download Mode.
- Flash the image for the example you want to run, as described below.
- 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.
5.3 Verify the RPMsg Link
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
-bor--buildin the build command. - Run
build_flash_bin.shfrom thetn_demoworkspace 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
uuucompleted 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.
M7 Waits for the RPMsg Link
- 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_TTYand loadimx_rpmsg_ttyif 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.