How To Use RemoteProc
Introduction
This article describes how to configure and use the Remote Processor Framework, also known as RemoteProc, to manage firmware running on alternative cores from Linux using the MCUXpresso SDK.
This article complies with the Typographic Conventions for Toradex Documentation.
Prerequisites
- The MCUXpresso SDK and all required tools configured. Refer to the Setting Up the MCUXpresso SDK and Toolchain for HMP Development article for more information about the installation process
- A
hello_worldexample firmware binary compiled for the alternative core, as described in How To Compile Firmware for Alternative Cores (NXP) article
Firmware binaries built with the NXP MCUXpresso SDK fail to load through the Linux RemoteProc framework when the binary size is close to or larger than 128 KiB.
For firmware images exceeding this size, refer to the How To Load and Run Firmware on Alternative Cores (NXP) article, which describes how to load firmware from U-Boot instead of Linux environment.
RemoteProc Overview
The Remote Processor Framework, commonly referred to as RemoteProc, is a Linux kernel subsystem used to manage remote processors in heterogeneous multiprocessing environments. This framework provides a standard interface for loading firmware, starting, and stopping remote processors, and monitoring their state from Linux.
RemoteProc abstracts platform-specific details such as reset control, clocks, memory regions, and firmware loading. When the remote firmware exposes virtio devices, RemoteProc can also register those devices in Linux. For RPMsg-based applications, this allows the Linux RPMsg infrastructure to exchange messages with firmware running on the remote processor.
For more information, refer to the Linux kernel RemoteProc documentation.
Set Up and Enable the RemoteProc Framework
Toradex provides device tree overlays that configure the RemoteProc framework for the alternative cores. For instructions on adding and enabling device tree overlays, refer to First Steps with Device Tree Overlays.
The following table lists the HMP-related device tree overlays available for supported Toradex modules:
| Overlay | Status | Device Tree Overlays Repository Branch |
|---|---|---|
verdin-imx8mp_hmp_overlay.dts | Available | toradex_6.6-2.2.x-imx |
verdin-imx8mp_hmp_overlay.dts | Coming soon | master |
verdin-imx8mm_hmp_overlay.dts | Available | toradex_6.6-2.2.x-imx |
verdin-imx8mm_hmp_overlay.dts | Available | master |
verdin-am62_uart4-mcu_overlay.dts¹ | Available | toradex_ti-linux-6.6.y |
verdin-am62p_uart4-mcu_overlay.dts¹ | Available | toradex_ti-linux-6.6.y |
apalis-imx8_hmp_overlay.dts | Not Available | N/A |
colibri-imx8x_hmp_overlay.dts | Available | toradex_6.6-2.2.x-imx |
colibri-imx7_hmp_overlay.dts | Not Available | N/A |
¹ In the latest Kernel, the remoteproc and memory nodes are defined directly in the base device tree. The overlay only reserves the Cortex-M UART, which remains available for debugging.
Available overlays are precompiled as *.dtbo files in Torizon OS and Toradex BSP reference images for the corresponding branch. The overlay source files are available in the Toradex device-tree-overlays.git repository.
For overlays marked as Coming soon, contact Toradex through the Support channels.
RemoteProc Framework Usage with i.MX 95 Modules
The RemoteProc framework is enabled by default on i.MX 95 modules, so no additional configuration is required to use the remoteproc with these modules.
RemoteProc Framework Usage with i.MX 8M Plus and i.MX 8M Mini Modules
To be able to use the RemoteProc framework with i.MX 8M Plus and i.MX 8M Mini modules, a Kernel command line argument is required. It is possible to update the Kernel environment variables from the Linux user space using the fw_setenv command.
# fw_setenv tdxargs "clk-imx8mp.mcore_booted=1"
# fw_setenv tdxargs "clk-imx8mm.mcore_booted=1"
After running the command, reboot the module for the changes to take effect.
After the device tree overlay is enabled, the RemoteProc driver should load automatically, which can be confirmed through the dmesg logs:
# dmesg | grep -E "remote|rproc"
[ 1.629455] remoteproc remoteproc0: imx-rproc is available
Usage of RemoteProc From Sysfs
The RemoteProc framework provides a sysfs interface that allows users to manage remote processors from the Linux user space. This interface enables users to load firmware, start, and stop remote processors, and check their status.
The RemoteProc driver expects the firmware image to be in the *.elf format. To load and run *.bin firmware binaries, refer to the How To Load and Run Firmware on Alternative Cores (NXP) documentation.
The sysfs interface is organized under the /sys/class/remoteproc/ directory:
# ls /sys/class/remoteproc/
remoteproc0
# ls /sys/class/remoteproc/remoteproc0/
consumers device firmware name power state subsystem suppliers uevent
By default, RemoteProc expects that the firmware image be stored under the /lib/firmware directory. If the firmware is not stored at the default location, update the path parameter with the directory path containing the firmware:
# echo -n </path/to/firmware> > /sys/module/firmware_class/parameters/path
Torizon OS uses a read-only root filesystem. For this reason, the firmware cannot be stored in /lib/firmware by default. Copy the firmware to a writable location, and update the firmware search path accordingly.
Before loading the firmware, it is necessary to make sure that the remote processor is offline. To check the state of the remote processor, read the content of the state file:
# echo stop > /sys/class/remoteproc/remoteproc0/state
# cat /sys/class/remoteproc/remoteproc0/state
offline
After stopping the remote processor, update the firmware parameter with the firmware filename:
# echo <firmware>.elf > /sys/class/remoteproc/remoteproc0/firmware
If the processor has more than one remote core, load the firmware through the RemoteProc instance that corresponds to the target core. For example, use remoteproc1 instead of remoteproc0 when the firmware targets the second remote core.
Finally, start the remote processor with the new firmware by writing start to the state file:
# echo start > /sys/class/remoteproc/remoteproc0/state
[ 1459.598770] remoteproc remoteproc0: powering up imx-rproc
[ 1459.604504] remoteproc remoteproc0: Booting fw image hello_world.elf, size 240736
[ 1459.612841] remoteproc remoteproc0: no dtb rsrc-table
[ 1459.668208] remoteproc remoteproc0: remote processor imx-rproc is now up
# cat /sys/class/remoteproc/remoteproc0/state
running
Next Steps
Follow the Cortex-M Shared Memory Guide article to learn how to exchange data between the Linux environment and the firmware running on the alternative cores using shared memory.