NXP IMX8M Plus

This guide provides an AudioReach architecture overview on the NXP IMX8M Plus platform and walks through the steps to create a Yocto image that integrates AudioReach, create a Zephyr image for the HiFi ADSP, set up the device, and run an AudioReach usecase.

Architecture Overview

../_images/nxp_imx8m_plus_evk_arch_diagram.png

The above architecture diagram illustrates the simulated playback usecase on the NXP IMX8M Plus using AudioReach. The platform has a heterogeneous multi-processor design: the AudioReach Engine (ARE) runs on the HiFi ADSP under Zephyr OS, while the rest of the AudioReach stack — AudioReach Graph Services (ARGS), Audio Graph Manager (AGM), and the ACDB — runs on the APPS processor under Linux.

When a graph open request is received by ARGS from the client (agmplay), ARGS retrieves the audio graph and calibration data from the Audio Calibration Database (ACDB) using the usecase handle and calibration handle. It then provides the graph definition and calibration data to ARE on the ADSP via the Generic Packet Router (GPR) protocol.

GPR messages are transported across the two processors using the RPMsg framework, which is built on top of Virtio rings (vrings) over shared memory. The control path (graph open, close, and parameter set commands) uses GPR over RPMsg, while audio data is exchanged between the APPS processor and the ADSP through a shared memory region mapped to both processors.

Upon receiving the graph definition, ARE on the ADSP forms an audio processing graph. In the current simulated playback usecase, the Rate-Adapted Timer module periodically signals the APPS processor to feed more data into the pipeline. There is not yet a hardware endpoint module for the NXP board, so no audio is rendered to a physical output device. The endpoint module is currently in development.

The graph topology can be visualized in real time during an active usecase using the PC-based GUI tool AudioReach Creator (ARC, also known as QACT).

../_images/nxp_playback_use_case_topology.png

The above diagram shows the usecase graph currently enabled for the NXP IMX8M Plus.

Step 1: Create a Yocto Image

To create a Yocto image, follow the guide at the official NXP GitHub page. AudioReach currently supports the scarthgap version of Yocto on NXP board.

Note

If there is an error in the repo init step, append the following flags to the repo init command:

--no-repo-verify --repo-url=http://android.googlesource.com/tools/repo

For the IMX 8M Plus, use the following setup command to create the build folder. Run this from the directory that will serve as <yocto_build_root> — the root directory containing the sources/ and build/ folders:

MACHINE=imx8mpevk DISTRO=fsl-imx-wayland source ./imx-setup-release.sh -b ./build

Once the build is synced and the setup is complete, run the following command to generate the full build:

bitbake imx-image-multimedia

Note

If the bitbake command gives a umask error, run umask 022 and try again.

Integrate AudioReach Components

Navigate to <yocto_build_root>/sources and clone the meta-audioreach repository:

git clone https://github.com/AudioReach/meta-audioreach.git -b scarthgap

Open <yocto_build_root>/build/conf/bblayers.conf and append the following line under the BBLAYERS ?= " \ section to integrate the AudioReach meta layer:

<yocto_build_root>/sources/meta-audioreach \

Open <yocto_build_root>/build/conf/local.conf and append the following lines to include the AudioReach components in the full Yocto build:

IMAGE_INSTALL:append = "audioreach-graphservices tinyalsa audioreach-graphmgr audioreach-conf audioreach-kernel"
PACKAGECONFIG:pn-audioreach-graphmgr = "use_default_acdb_path"
EXTRA_OECONF:append:pn-audioreach-conf = " --with-nxp"

Once the configuration is complete, run the following command to generate the full build with the integrated AudioReach components:

bitbake imx-image-multimedia

Step 2: Create a Zephyr Image

This step produces a Zephyr firmware image with the AudioReach Engine (ARE) integrated as the DSP component running on the HiFi ADSP. ARE is added to the Zephyr build as a west module, registered in the workspace manifest and built as part of the Zephyr build system. The zephyr/module.yml file in the audioreach-engine repository declares it as a Zephyr module, exposing its Kconfig options and CMake build targets to the Zephyr build system.

The audioreach-engine module provides the core Signal Processing Framework (SPF), the Platform & Operating System Abstraction Layer (POSAL), and the Generic Packet Router (GPR) as Zephyr-compatible libraries. A sample Zephyr application under audioreach-engine/app/ demonstrates the use of the module. This application initializes the three core components — POSAL, GPR, and the ARE framework — and serves as the entry point for the Zephyr firmware image that runs on the ADSP.

The steps below cover installing dependencies, setting up the west workspace, applying patches, and building the image.

Install Dependencies

Before setting up the workspace, install the required dependencies. Follow the relevant sections of the Zephyr getting started guide for your operating system:

Host Tool Dependencies

Follow the Install dependencies section of the Zephyr getting started guide to install the required host tools (CMake, Python, DTC) for your OS.

Python Dependencies and West

Follow the Get Zephyr and install Python dependencies section of the Zephyr getting started guide to set up a Python virtual environment and install west.

Note

Activate the virtual environment every time you start working:

source ~/zephyrproject/.venv/bin/activate

Zephyr SDK

Install the Zephyr SDK version 0.17.0, which is compatible with the Zephyr version used by AudioReach. Refer to the Install the Zephyr SDK section of the Zephyr getting started guide, and use the following command to install the specific version:

west sdk install --version 0.17.0

Note

Use west sdk install --help to see additional options such as specifying the installation destination or selecting specific architecture toolchains.

Setup the West Workspace

Create a directory to serve as the west workspace root and clone the audioreach-engine repository into it:

mkdir <workspace_dir> && cd <workspace_dir>
git clone https://github.com/AudioReach/audioreach-engine.git

The audioreach-engine repository contains a west.yml manifest file located under the zephyr/ subdirectory (zephyr/west.yml). This manifest defines all required dependencies, including the Zephyr RTOS. When west update is run, west fetches all projects defined in the manifest — including the Zephyr RTOS itself — as subdirectories of <workspace_dir>.

Initialize the west workspace using the cloned repository as the manifest source:

west init -l ./audioreach-engine/ --mf zephyr/west.yml

Then fetch all projects defined in the manifest, including Zephyr:

west update

Apply Patches

After running west init and west update, apply the required patches to the workspace:

west patch apply

To undo the patches and reset the workspace to the pinned state (e.g., reset zephyr/ to the pinned commit):

west patch clean

Build the Zephyr Image

To build the Zephyr image for the NXP IMX8M Plus ADSP target, run the following command:

west build -p always --build-dir <build_dir_path> -b imx8mp_evk/mimx8ml8/adsp ./audioreach-engine/app

The parameters used in the command are described below:

  • -p always — Enables a pristine build, cleaning the build directory before building to avoid stale artifacts from previous builds.

  • --build-dir <build_dir_path> — Specifies the output directory for build artifacts. Replace <build_dir_path> with the desired path.

  • -b imx8mp_evk/mimx8ml8/adsp — Specifies the target board. imx8mp_evk is the NXP IMX8M Plus Evaluation Kit, mimx8ml8 is the SoC variant, and adsp is the DSP core being targeted.

  • ./audioreach-engine/app — The path to the AudioReach application source to be built.

Build Output

If the build is successful, the build artifacts are generated under the <build_dir_path>/zephyr/ directory. The key output files are:

  • zephyr.elf — The compiled firmware image for the DSP. This is the file loaded onto the NXP board via remoteproc to start the AudioReach DSP component.

  • .config — The Kconfig configuration file generated during the build. This reflects all build-time options and enabled modules, and is useful for verifying the configuration used to produce the firmware.

Step 3: Setup the Device

Flash and Power On

Navigate to <yocto_build_root>/build/tmp/deploy/images/imx8mpevk and locate the file imx-image-multimedia-imx8mpevk.rootfs.wic.zst. This is the full Yocto image generated in Step 1.

Use Balena Etcher to flash this image onto a micro SD card. Once flashing is complete, insert the card into the NXP board.

Set the boot switches on the top left of the device to 0011 to select SD card boot. Connect a serial cable to the serial port, connect the board to power, and push the PWR switch to power on. For the location of the boot switches, serial port, and power connector on the board, refer to the Getting Started with the i.MX 8M Plus EVK.

Configure the Device Tree

While the board is powering on, the serial port will display a prompt to interrupt the boot. Press any key to interrupt, then run the following commands to set and persist the device tree:

=> editenv fdtfile
edit: imx8mp-evk-dsp.dtb
=> saveenv
=> boot

Note

saveenv writes the updated fdtfile variable to a dedicated environment partition on the eMMC. This persists across reboots so the DSP device tree is selected automatically on every boot without manual intervention. Note that running env default -a or re-flashing the eMMC will reset the saved environment, requiring this step to be repeated.

Connect to the Network

Once the board is booted, connect it to the internet using Ethernet or WiFi.

Note

For WiFi setup instructions, refer to the NXP community guide for connecting to WiFi on i.MX8MP.

Push Files to the Device

Copy the zephyr.elf image generated in Step 2 and a .wav audio file to a location on the device, such as /etc:

scp zephyr.elf root@<board_ip_address>:/etc/
scp <clip_name>.wav root@<board_ip_address>:/etc/

Step 4: Run an AudioReach Usecase

Start the DSP

Load the zephyr.elf firmware and start the AudioReach DSP using the remoteproc interface:

echo -n /etc/zephyr.elf > /sys/class/remoteproc/remoteproc0/firmware
echo start > /sys/class/remoteproc/remoteproc0/state

Note

To check the current DSP state, run cat /sys/class/remoteproc/remoteproc0/state. To stop the DSP, run echo stop > /sys/class/remoteproc/remoteproc0/state.

Enable Real-time Calibration Mode

ARC (AudioReach Creator) is a tool for creating and editing audio usecase graphs and editing audio configurations in real time during an active usecase. For more information on ARC, refer to the AudioReach Creator page.

Note

AudioReach Creator is only available on Windows at this time.

The steps below demonstrate how to connect ARC to the NXP board. Connecting to ARC is not required to run an AudioReach usecase.

On the NXP board:

  • Connect the NXP board to the internet using Ethernet or WiFi.

  • On the serial port or through SSH, run:

    ats_gateway <IP address> 5558

    Note

    The DSP must be running before starting ats_gateway. Refer to Start the DSP above if not already done.

On a local computer:

  • Install ARC (also known as QACT) on a Windows host machine using Steps to install ARC. QACT 8.1 or later is required.

  • Open ARC and click Connection configuration.

  • Add the NXP board as a device by entering <IP address>:5558 under the TCP/IP section.

  • Refresh the Available Devices list. The IP address of the NXP board should appear.

    Note

    If the board does not appear, verify that the ats_gateway command is still running on the board.

  • Select the entry and click Connect.

Start the Playback

Start the simulated playback using agmplay:

agmplay /<path_to_audio_file>/[clip_name].wav -D 100 -d 100 -i PCM_RT_PROXY-RX-2

Note

The -D 100 and -d 100 arguments specify the card index and device index respectively. Card ID 100 identifies the AGM virtual sound card (virtualsndcard) and device ID 100 refers to PCM100, the playback PCM device. The -i PCM_RT_PROXY-RX-2 argument specifies the RT proxy backend device (device ID 200). These IDs are defined for the NXP platform in card-defs.xml which is part of the audioreach-conf package installed on the device.

The playback is now running. If the NXP board is connected to ARC, the current usecase graph will appear in the graph view. System logs for the usecase are saved to /var/log/syslog.