Using the Coral MLIR compiler

The Google compiler for Coral NPU is a plug-in for the open-source IREE compiler.

You must build the Coral NPU compiler from the GitHub repository. Follow the instructions in the README file to clone the project and build the compiler.

You can build a standalone version of the compiler, or take advantage of the Coral NPU MPACT simulator library (libcoralnpu_simulator_mpact.so or libcoralnpu_simulator.so) to also build the runtime HAL driver simulation backend (coralnpu_runtime::sim).

The compiler's GitHub repository is designed to use the Bazel build tool, or Cmake, as much as possible. The following are prerequisites that are not handled by Bazel or CMake:

Bazel
Cmake
git
Bash
clang
lld
Python
shfmt, for bash scripts formatting https://github.com/mvdan/sh

Run the standalone compiler

After you have successfully built the compiler, you can run it using this Bazel command:

bazel run --config={dev|release} //compiler/tools:coralnpu-compile -- [coralnpu-compile options]

Note that anything before the -- will be interpreted by bazel and not coralnpu-compile. A normal compilation, without errors or warnings, does not print anything to stdout or stderr, unless a command-line option that specifically prints information is used.

For example, to compile model.mlir:

# Compile for the host machine and Coral NPU, then run in MPACT simulator

bazel run --config=dev //compiler/tools:coralnpu-compile -- \
    --iree-hal-target-device=local \
    --iree-hal-local-target-device-backends=llvm-cpu \
    --iree-llvmcpu-target-cpu=host \
    --iree-hal-target-device=coralnpu \
    --iree-global-opt-experimental-disable-conv-generalization \
    model.mlir \
    -o model.vmfb

To see a complete list of the command-line options available, use the --help option:

bazel run --config=dev //compiler/tools:coralnpu-compile -- --help

The following options may be particularly useful:

Affinity execution profile report

--coralnpu-dump-affinity-profile-format={pretty|csv|json}

Dumps statistics about the compilation, such as the number of dispatches, estimated data size, and estimated work. The statistics are grouped by the device affinity (for example, host CPU versus Coral NPU).

Register allocation report

--coralnpu-dump-register-allocation-report-format={pretty|json} --coralnpu-dump-register-allocation-report-dir=directory --coralnpu-dump-register-allocation-report-filter=pattern

Dumps a report containing vector register utilization (unique registers used, vector configuration) and register allocator remarks (spills, reloads, copies) for each loop and at the function level. If the directory is -, the report is written to stdout; if empty or omitted, it is written to stderr. The filter option accepts a regular expression pattern to only report functions matching the name (default is .*dispatch.*|main).

Executable linking

--coralnpu-link-executables={true|false}

Controls whether all executable dispatches are linked into a single library or emitted as individual self-contained executables (default is false). Emitting separate executables per-dispatch avoids overflowing tightly constrained Coral ITCM memory (for example, 8 KB) on multi-dispatch models.

Shell scripts

When working with the Google Coral compiler tools and shell scripts, always use bash shell with this header:

#!/usr/bin/env bash
# Exit immediately on error (including in a pipeline), or when accessing an unset variable
set -euo pipefail

Examples

The compiler's GitHub repository includes several examples that you can experiment with.

MobileNet V2 (JAX) – ahead-of-time compilation

The compiler can be used to compile a JAX/StableHLO MLIR model to a VMFB binary that can be loaded by the IREE runtime Python bindings.

./examples/mobilenetv2-jax-aot/test_classify.sh

This script first exports the model to MLIR, using the StableHLO dialect. It then compiles the model to a .vmfb file, targeting the local host + CoralNPU. Finally, it runs an inference using the compiled model; the Coral NPU payload runs in simulation.

MobileNet V2 (TFLite / TOSA) – ahead-of-time compilation

The toolchain supports compiling LiteRT (TFLite) models via TOSA MLIR, targeting Coral NPU:

./examples/mobilenetv2-tflite-aot/test_classify.sh

This script does the following:

Downloads the official MobileNetV2 TFLite model.
Legalizes the TFLite FlatBuffer to TOSA MLIR via tosa-converter-for-tflite.
Compiles the TOSA model to a .vmfb module targeting Coral NPU.
Executes image classification inference in the Coral NPU MPACT simulator.

PJRT plugin

The PJRT plugin invokes the IREE HAL device APIs and builds the dynamic library used by JAX for Just-in-Time (JIT) compilation and execution. It is a unified multi-device PJRT plugin that supports both CPU (device 0) and Coral NPU (device 1) targets. This functionality is provided by the libiree_pjrt_coralnpu_dylib.so library file.

Running multi-device JAX tests (CPU + Coral NPU)

./examples/gemma3-jax-pjrt/test_basic.sh