diff --git a/.github/workflows/pull.yml b/.github/workflows/pull.yml index ddad7eebf61..4d263dfbe3c 100644 --- a/.github/workflows/pull.yml +++ b/.github/workflows/pull.yml @@ -1701,3 +1701,22 @@ jobs: echo "Neutron backend library not found!" exit 1 fi + + nxp-mcuxpresso-test: + name: nxp-mcuxpresso-test + uses: pytorch/test-infra/.github/workflows/linux_job_v2.yml@main + permissions: + id-token: write + contents: read + with: + runner: linux.2xlarge + docker-image: ci-image:executorch-ubuntu-22.04-arm-sdk + submodules: 'recursive' + ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }} + timeout: 180 + script: | + # The generic Linux job chooses to use base env, not the one setup by the image + CONDA_ENV=$(conda env list --json | jq -r ".envs | .[-1]") + conda activate "${CONDA_ENV}" + + ./examples/nxp/mcuxpresso/imxrt700/executorch_cifarnet/test_build_from_scratch.sh \ No newline at end of file diff --git a/docs/source/backends/nxp/nxp-mcuxpresso-example.md b/docs/source/backends/nxp/nxp-mcuxpresso-example.md new file mode 100644 index 00000000000..688a5fdfb2c --- /dev/null +++ b/docs/source/backends/nxp/nxp-mcuxpresso-example.md @@ -0,0 +1,120 @@ +# Using the MCUXpresso Example + +This example demonstrates how to build and run the ExecuTorch CIFARNet application for the NXP RT700 platform using the MCUXpresso SDK and the GNU Arm Embedded Toolchain. Before building the project, make sure that all required dependencies are installed and that the necessary environment variables are configured correctly. + +## 1. Install the Arm GNU Toolchain + +First, download the Arm GCC cross-compilation toolchain that is supported by the RT700 platform: + +```text +https://developer.arm.com/-/media/Files/downloads/gnu/15.2.rel1/binrel/arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi.tar.xz +``` + +After extracting the archive, create an environment variable called `ARMGCC_DIR` that points to the root directory of the toolchain installation. The build scripts use this variable to locate the compiler, linker, and other required tools. + +Example on Linux: + +```bash +export ARMGCC_DIR=/path/to/arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi +``` + +To verify the installation, you can run: + +```bash +$ARMGCC_DIR/bin/arm-none-eabi-gcc --version +``` + +The command should print the installed compiler version. + +## 2. Download the MCUXpresso SDK + +Next, download MCUXpresso SDK version **26.06** for the RT700 device family: + +```text +https://mcuxpresso.nxp.com/builder?hw=MIMXRT700-EVK +``` + +When generating the SDK package, make sure that you select: + +- **Toolchain:** ARMGCC +- **SDK Layout:** Classic Layout +- **Target Board:** MIMXRT700-EVK + +After extracting the SDK package, configure the `SdkRootDirPath` environment variable to point to the SDK root directory. + +Example on Linux: + +```bash +export SdkRootDirPath=/path/to/SDK_26_06 +``` + +The build system relies on this variable to locate board support packages, middleware components, startup code, linker scripts, and device-specific libraries. + +## 3. Prepare the Model Header File + +Before building the application, a compiled model must be provided as a C header file named `model_pte.h` and placed alongside the build script. The `prepare_model.sh` script automates this process. It installs the required Python packages, compiles the CIFARNet model using the NXP ExecuTorch backend, and generates the `model_pte.h` header from the resulting `.pte` file. + +> **Important:** The MCUXpresso SDK package includes a pre-built CIFARNet model and a set of Neutron libraries, but this build flow deliberately does **not** use either of them. Instead, the `prepare_model.sh` script installs the exact eiq-neutron-sdk version that was verified with the current ExecuTorch release, recompiles the CIFARNet model from scratch using that SDK, and later the linker picks the matching Neutron libraries from the same installation. This ensures that the ExecuTorch AoT, the model bytecode, the Neutron driver, the Neutron firmware, and the ExecuTorch runtime are all in sync. + +## 4. Build the Application + +Once the environment variables have been configured and `model_pte.h` is present in the project directory, set the `NEUTRON_LIB_DIR` variable to the directory that contains the Neutron static libraries shipped with the eiq-neutron-sdk: + +```bash +export NEUTRON_LIB_DIR=/path/to/eiq_neutron_sdk/libs +``` + +The build script expects the following libraries to exist in that directory: + +- `libNeutronDriver.a` +- `libNeutronFirmware.a` + +Then build the project by executing the provided script: + +```bash +cd examples/nxp/mcuxpresso/imxrt700/executorch_cifarnet +./build_example.sh +``` + +The script validates all required inputs, configures CMake, compiles the source code, links the application, and generates the executable image: + +```text +executorch_cifarnet.elf +``` + +If the build completes successfully, the ELF file will be available in the `cmake-out` build output directory and ready for programming onto the target board. + +## 5. Flash the Application + +The generated application can be programmed onto the RT700 device using SEGGER J-Link tools. + +### Linux + +```bash +echo "loadfile executorch_cifarnet.elf" | \ +/opt/SEGGER/JLink_V796k/JLinkExe \ + -IF SWD \ + -speed auto \ + -Device MIMXRT798S_M33_0 +``` + +Before flashing, ensure that: + +- The board is powered on. +- The J-Link debugger is connected to the target. +- The SWD interface is available and correctly wired. +- No other debugging application is currently using the J-Link connection. + +The programming process typically takes only a few seconds. Once the image has been loaded successfully, the application can be started directly from flash memory. + +## 6. Running the Example + +After the firmware is programmed, reset the board and open a serial terminal connected to the device's debug UART interface. The application will initialize the hardware, load the embedded CIFARNet model, and begin performing image inference. + +During execution, inference results and diagnostic messages are printed to the terminal. The included demonstration image contains a cat, and the model is expected to classify the image accordingly. + +A successful run produces output similar to the following: + +![example](terminal.png "Example") + +This example serves as a basic validation that the ExecuTorch runtime, model integration, SDK configuration, and hardware platform are all functioning correctly. It can also be used as a starting point for evaluating custom neural network models and experimenting with on-device machine learning workloads on the RT700 platform. diff --git a/docs/source/backends/nxp/nxp-overview.md b/docs/source/backends/nxp/nxp-overview.md index b636af291ab..5517cac124d 100644 --- a/docs/source/backends/nxp/nxp-overview.md +++ b/docs/source/backends/nxp/nxp-overview.md @@ -52,6 +52,11 @@ For more finegrained tutorial, visit [this manual page](https://mcuxpresso.nxp.c For guideline how to update the eIQ Neutron Runtime on MCUXpresso SDK, follow the instructions from the eIQ Neutron SDK package `docs/NeutronSDKUserGuide.md` available here https://www.nxp.com/design/design-center/software/eiq-ai-development-environment/eiq-toolkit-for-end-to-end-model-development-and-deployment:EIQ-TOOLKIT. +## Using the MCUXpresso Example + +[This page](nxp-mcuxpresso-example.md) demonstrates how to build and run the ExecuTorch CIFARNet example from MCUXpresso SDK. + + ## Reference **→{doc}`nxp-partitioner` — Partitioner options.** diff --git a/docs/source/backends/nxp/terminal.png b/docs/source/backends/nxp/terminal.png new file mode 100644 index 00000000000..9a4f1d70ee8 Binary files /dev/null and b/docs/source/backends/nxp/terminal.png differ diff --git a/examples/nxp/mcuxpresso/imxrt700/executorch_cifarnet/CMakeLists.txt b/examples/nxp/mcuxpresso/imxrt700/executorch_cifarnet/CMakeLists.txt new file mode 100644 index 00000000000..367516b9064 --- /dev/null +++ b/examples/nxp/mcuxpresso/imxrt700/executorch_cifarnet/CMakeLists.txt @@ -0,0 +1,151 @@ +# Copyright 2026 NXP +# +# This source code is licensed under the BSD-style license found in the +# LICENSE file in the root directory of this source tree. + +cmake_minimum_required(VERSION 3.10.0) + +# THE VERSION NUMBER +set(MCUXPRESSO_CMAKE_FORMAT_MAJOR_VERSION 2) +set(MCUXPRESSO_CMAKE_FORMAT_MINOR_VERSION 0) + +set(CMAKE_EXECUTABLE_LIBRARY_PREFIX) +set(CMAKE_EXECUTABLE_LIBRARY_SUFFIX) + +# CURRENT DIRECTORY +set(ProjDirPath ${CMAKE_CURRENT_SOURCE_DIR}) + +set(EXECUTABLE_OUTPUT_PATH ${ProjDirPath}/${CMAKE_BUILD_TYPE}) +set(LIBRARY_OUTPUT_PATH ${ProjDirPath}/${CMAKE_BUILD_TYPE}) + +# Skip link step during compiler check (bare-metal cross-compilation). +set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY) + +project(executorch_cifarnet) + +enable_language(ASM) + +set(MCUX_BUILD_TYPES flash_debug flash_release) + +set(MCUX_SDK_PROJECT_NAME executorch_cifarnet.elf) + +set(EXECUTORCH_ROOT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../../../..) + +# CPU and FPU flags required for Cortex-M33 with single-precision FPU. +set(CPU_FLAGS "-mcpu=cortex-m33 -mthumb -mfloat-abi=hard -mfpu=fpv5-sp-d16") +set(CPU_DEFINES + "-DCPU_MIMXRT798SGFOA_cm33_core0 -DCPU_MIMXRT798SGFOB_cm33_core0 \ + -DMIMXRT798S_cm33_core0_SERIES -DMCUXPRESSO_SDK \ + -D__STARTUP_INITIALIZE_NONCACHEDATA -D__STARTUP_CLEAR_BSS \ + -DDSP_IMAGE_COPY_TO_RAM=1 -DBOOT_HEADER_ENABLE=1 \ + -DEIQ_EXAMPLE_HSRUN_CLOCK -DMCUX_META_BUILD \ + -DPRINTF_ADVANCED_ENABLE=1 -DPRINTF_FLOAT_ENABLE=1 -DNO_HEAP_USAGE=1 \ + -DSDK_DEBUGCONSOLE=1 -DSDK_I2C_BASED_COMPONENT_USED=1" +) +set(CMAKE_C_FLAGS + "${CMAKE_C_FLAGS} ${CPU_FLAGS} ${CPU_DEFINES} -fno-common -ffunction-sections -fdata-sections -fno-builtin -mapcs -std=gnu99" +) +set(CMAKE_CXX_FLAGS + "${CMAKE_CXX_FLAGS} ${CPU_FLAGS} ${CPU_DEFINES} -fno-common -ffunction-sections -fdata-sections -fno-builtin -mapcs -fno-rtti -fno-exceptions" +) +set(CMAKE_ASM_FLAGS "${CMAKE_ASM_FLAGS} ${CPU_FLAGS} ${CPU_DEFINES}") +set(CMAKE_EXE_LINKER_FLAGS + "${CMAKE_EXE_LINKER_FLAGS} ${CPU_FLAGS} -fno-common -ffunction-sections -fdata-sections -fno-builtin -mapcs -Wl,--gc-sections -Wl,-static -specs=nano.specs -specs=nosys.specs -T\"${SdkRootDirPath}/examples/_boards/mimxrt700evk/eiq_examples/executorch_cifarnet/cm33_core0/gcc/MIMXRT798Sxxxx_cm33_core0_flash.ld\" -static" +) + +add_executable( + ${MCUX_SDK_PROJECT_NAME} + ${SdkRootDirPath}/examples/_boards/mimxrt700evk/flash_config/flash_config.c + ${SdkRootDirPath}/examples/_boards/mimxrt700evk/eiq_examples/executorch_cifarnet/cm33_core0/hardware_init.c + ${SdkRootDirPath}/examples/_boards/mimxrt700evk/eiq_examples/executorch_cifarnet/cm33_core0/pin_mux.c + ${SdkRootDirPath}/examples/_boards/mimxrt700evk/board.c + ${SdkRootDirPath}/examples/_boards/mimxrt700evk/pmic_support.c + ${SdkRootDirPath}/examples/_boards/mimxrt700evk/common/clock/cm33_core0/clock_config.c + ${SdkRootDirPath}/examples/eiq_examples/executorch_cifarnet/main.cpp + ${SdkRootDirPath}/examples/eiq_examples/executorch_cifarnet/RegisterKernels.cpp + ${SdkRootDirPath}/examples/eiq_examples/common/timer.c + ${SdkRootDirPath}/devices/RT/RT700/MIMXRT798S/startup_MIMXRT798S_cm33_core0.c + ${EXECUTORCH_ROOT_DIR}/backends/nxp/runtime/NeutronBackend.cpp + ${SdkRootDirPath}/middleware/tfm/tf-m/platform/ext/common/syscalls_stub.c + # Device-level drivers (clock, power, reset, system init). + ${SdkRootDirPath}/devices/RT/RT700/MIMXRT798S/drivers/fsl_clock.c + ${SdkRootDirPath}/devices/RT/RT700/MIMXRT798S/drivers/fsl_power.c + ${SdkRootDirPath}/devices/RT/RT700/MIMXRT798S/drivers/fsl_reset.c + ${SdkRootDirPath}/devices/RT/RT700/MIMXRT798S/system_MIMXRT798S_cm33_core0.c + # Common ARM driver (provides SDK_DelayAtLeastUs). + ${SdkRootDirPath}/drivers/common/fsl_common_arm.c + # Peripheral drivers. + ${SdkRootDirPath}/drivers/cache/xcache/fsl_cache.c + ${SdkRootDirPath}/drivers/lpflexcomm/fsl_lpflexcomm.c + ${SdkRootDirPath}/drivers/lpflexcomm/lpi2c/fsl_lpi2c.c + ${SdkRootDirPath}/drivers/lpflexcomm/lpuart/fsl_lpuart.c + ${SdkRootDirPath}/drivers/gpio/fsl_gpio.c + ${SdkRootDirPath}/drivers/glikey/fsl_glikey.c + # UART HAL adapter (provides HAL_UartInit etc.). + ${SdkRootDirPath}/components/uart/fsl_adapter_lpuart.c + # PMIC driver. + ${SdkRootDirPath}/components/pmic/pca9422/fsl_pca9422.c + # Debug console (provides DbgConsole_Init/Printf). + ${SdkRootDirPath}/components/debug_console_lite/fsl_debug_console.c +) + +target_include_directories( + ${MCUX_SDK_PROJECT_NAME} + PRIVATE + ${CMAKE_CURRENT_SOURCE_DIR} + ${SdkRootDirPath}/arch/arm/CMSIS/Core/Include + ${SdkRootDirPath}/devices/RT/RT700/MIMXRT798S + ${SdkRootDirPath}/devices/RT/RT700/MIMXRT798S/cm33_core0 + ${SdkRootDirPath}/devices/RT/RT700/MIMXRT798S/drivers + ${SdkRootDirPath}/devices/RT/RT700/periph + ${SdkRootDirPath}/drivers/common + ${SdkRootDirPath}/components/pmic/pca9422 + ${SdkRootDirPath}/components/uart + ${SdkRootDirPath}/components/debug_console_lite + ${SdkRootDirPath}/examples/_boards/mimxrt700evk + ${SdkRootDirPath}/examples/_boards/mimxrt700evk/flash_config + ${SdkRootDirPath}/examples/_boards/mimxrt700evk/eiq_examples/executorch_cifarnet/cm33_core0 + ${SdkRootDirPath}/examples/_boards/mimxrt700evk/common/clock/cm33_core0 + ${SdkRootDirPath}/examples/eiq_examples/executorch_cifarnet + ${SdkRootDirPath}/examples/eiq_examples/common + ${SdkRootDirPath}/boards/mimxrt700evk/eiq_examples/executorch_cifarnet/cm33_core0 + ${SdkRootDirPath}/examples/_boards/mimxrt700evk/eiq_examples/executorch_cifarnet/npu + ${SdkRootDirPath}/drivers/cache/xcache + ${SdkRootDirPath}/drivers/gpio + ${SdkRootDirPath}/drivers/lpflexcomm + ${SdkRootDirPath}/drivers/lpflexcomm/lpuart + ${SdkRootDirPath}/drivers/lpflexcomm/lpi2c + ${SdkRootDirPath}/drivers/xspi + ${SdkRootDirPath}/drivers/reset + ${SdkRootDirPath}/drivers/clock + ${SdkRootDirPath}/drivers/glikey + ${SdkRootDirPath}/drivers/mu1 + ${SdkRootDirPath}/drivers/power + ${SdkRootDirPath}/drivers/iopctl + ${SdkRootDirPath}/components/str +) + +set(EXECUTORCH_BUILD_PYBIND OFF) +set(EXECUTORCH_BUILD_TESTS OFF) +set(EXECUTORCH_BUILD_DEVTOOLS OFF) +set(EXECUTORCH_BUILD_EXECUTOR_RUNNER OFF) +set(EXECUTORCH_BUILD_CPUINFO OFF) +set(EXECUTORCH_BUILD_PTHREADPOOL OFF) +set(EXECUTORCH_BUILD_EXTENSION_RUNNER_UTIL ON) +set(EXECUTORCH_BUILD_PORTABLE_OPS ON) +set(EXECUTORCH_BUILD_KERNELS_QUANTIZED ON) +set(CMAKE_POSITION_INDEPENDENT_CODE OFF) +add_subdirectory(${EXECUTORCH_ROOT_DIR} EXCLUDE_FROM_ALL executorch) + +target_link_libraries( + ${MCUX_SDK_PROJECT_NAME} + PRIVATE -Wl,--start-group + executorch + executorch_core + extension_runner_util + quantized_kernels + portable_kernels + ${NEUTRON_LIB_DIR}/libNeutronDriver.a + ${NEUTRON_LIB_DIR}/libNeutronFirmware.a + -Wl,--end-group +) diff --git a/examples/nxp/mcuxpresso/imxrt700/executorch_cifarnet/build_example.sh b/examples/nxp/mcuxpresso/imxrt700/executorch_cifarnet/build_example.sh new file mode 100755 index 00000000000..6345361e17c --- /dev/null +++ b/examples/nxp/mcuxpresso/imxrt700/executorch_cifarnet/build_example.sh @@ -0,0 +1,45 @@ +#!/bin/bash +# Copyright 2026 NXP +# +# This source code is licensed under the BSD-style license found in the +# LICENSE file in the root directory of this source tree. + +cd "$(dirname "$0")" + +if [ -z ${ARMGCC_DIR+x} ]; then + echo "ARMGCC_DIR needs to be set in the environment!" + exit 1; +fi + +if [ -z ${SdkRootDirPath+x} ]; then + echo "SdkRootDirPath needs to be set in the environment!" + exit 1; +fi + +if [ ! -f model_pte.h ]; then + echo "Cannot find model_pte.h!" + exit 1; +fi + +if [ ! -f ${NEUTRON_LIB_DIR}/libNeutronDriver.a ]; then + echo "Neutron driver not found in ${NEUTRON_LIB_DIR}!" + exit 1; +fi + +if [ ! -f ${NEUTRON_LIB_DIR}/libNeutronFirmware.a ]; then + echo "Neutron firmware not found in ${NEUTRON_LIB_DIR}!" + exit 1; +fi + +mkdir -p cmake-out + +cd cmake-out + +cmake -DSdkRootDirPath=${SdkRootDirPath} \ + -DCMAKE_TOOLCHAIN_FILE=${SdkRootDirPath}/cmake/toolchain/armgcc.cmake \ + -DNEUTRON_LIB_DIR=${NEUTRON_LIB_DIR} \ + -DCMAKE_BUILD_TYPE=flash_release \ + -G "Unix Makefiles" \ + .. + +make -j 6 executorch_cifarnet.elf diff --git a/examples/nxp/mcuxpresso/imxrt700/executorch_cifarnet/prepare_model.sh b/examples/nxp/mcuxpresso/imxrt700/executorch_cifarnet/prepare_model.sh new file mode 100755 index 00000000000..0633bcf818e --- /dev/null +++ b/examples/nxp/mcuxpresso/imxrt700/executorch_cifarnet/prepare_model.sh @@ -0,0 +1,32 @@ +#!/bin/bash +# Copyright 2026 NXP +# +# This source code is licensed under the BSD-style license found in the +# LICENSE file in the root directory of this source tree. + +set -u +EIQ_PYPI_URL="${EIQ_PYPI_URL:-https://eiq.nxp.com/repository}" + +pushd "$(dirname "$0")/../../../../.." + +./install_executorch.sh +./devtools/install_requirements.sh + +pip install --index-url ${EIQ_PYPI_URL} eiq-neutron-sdk==3.2.0 + +python3 -m examples.nxp.aot_neutron_compile -m cifar10 -d -q --use_channels_last_dim_order --remove-quant-io-ops +mv cifar10_nxp_delegate.pte model.pte +xxd -i model.pte > model_pte.h + +popd +cd "$(dirname "$0")" + +echo '#ifdef __MCUXPRESSO' > model_pte.h +echo '#define __PLACEMENT __attribute__((section(".data.$modeldata")))' >> model_pte.h +echo '#else' >> model_pte.h +echo '#define __PLACEMENT __attribute__((section(".modeldata")))' >> model_pte.h +echo '#endif' >> model_pte.h +echo >> model_pte.h +echo 'static const uint8_t model_pte[] __ALIGNED(16) __PLACEMENT = {' >> model_pte.h + +cat ../../../../../model_pte.h | grep -v unsigned >> model_pte.h diff --git a/examples/nxp/mcuxpresso/imxrt700/executorch_cifarnet/test_build_from_scratch.sh b/examples/nxp/mcuxpresso/imxrt700/executorch_cifarnet/test_build_from_scratch.sh new file mode 100755 index 00000000000..87d7f6bad7b --- /dev/null +++ b/examples/nxp/mcuxpresso/imxrt700/executorch_cifarnet/test_build_from_scratch.sh @@ -0,0 +1,56 @@ +#!/bin/bash +# Copyright 2026 NXP +# +# This source code is licensed under the BSD-style license found in the +# LICENSE file in the root directory of this source tree. + +set -u +ARM_TOOLCHAIN_URL="${ARM_TOOLCHAIN_URL:-https://developer.arm.com/-/media/Files/downloads/gnu/15.2.rel1/binrel/arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi.tar.xz}" + +cd "$(dirname "$0")" + +# Get arm gcc +if [ ! -d arm-toolchain ]; then + mkdir -p arm-toolchain + pushd arm-toolchain + wget $ARM_TOOLCHAIN_URL + tar -xvf *.tar.xz + rm *.tar.xz + popd +fi +export ARMGCC_DIR=`pwd`/arm-toolchain/`ls arm-toolchain` + +# Prepare model +# Side effect: the neutron SDK is installed +./prepare_model.sh +# Check the model exists +if [ ! -f model_pte.h ]; then + echo "Cannot create the model_pte.h!" + exit 1; +fi + +# Locate Neutron SDK +NEUTRON_LIB_DIR=`python3 -c 'exec("try:\n import eiq_neutron_sdk\n print(eiq_neutron_sdk.__path__[0])\nexcept:\n print()")'` +export NEUTRON_LIB_DIR=${NEUTRON_LIB_DIR}/target/imxrt700/rt700/cm33 + +# Get MCUX SDK +if [ ! -d sdk-next ]; then + pip install west + west init -m https://github.com/nxp-mcuxpresso/mcuxsdk-manifests.git mcuxpresso-sdk + pushd mcuxpresso-sdk + west update_board --set board mimxrt700evk + popd +fi +export SdkRootDirPath=`pwd`/mcuxpresso-sdk/mcuxsdk + +# Build now +./build_example.sh + +# Test the result +if [ ! -f flash_release/executorch_cifarnet.elf ]; then + echo "Build not successful!" + exit 1; +else + echo "Build successful." + exit 0; +fi