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](https://github.com/google-coral/coralnpu-compiler). Follow the
instructions in the [README
file](https://github.com/google-coral/coralnpu-compiler/blob/main/README.md)
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`:

```c
# 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
```

> [!NOTE]
> **Note:** A `.vmfb` binary file is a Virtual Machine FlatBuffer, which is a compact serialized artifact produced by the IREE compiler.

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:

```c
#!/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](https://github.com/google-coral/coralnpu-compiler) 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:

1. Downloads the official MobileNetV2 TFLite model.
2. Legalizes the TFLite FlatBuffer to TOSA MLIR via `tosa-converter-for-tflite`.
3. Compiles the TOSA model to a `.vmfb` module targeting Coral NPU.
4. 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`

This script does the following:

1. Builds `libIREECompiler.so`, `libiree_pjrt_coralnpu_dylib.so`, and `coralnpu-compile` using Bazel.
2. Runs [`examples/gemma3-jax-pjrt/basic.py`](https://github.com/google-coral/coralnpu-compiler/blob/main/examples/gemma3-jax-pjrt/basic.py) to test single-device CPU execution, single-device Coral NPU execution, and concurrent multi-device execution (CPU + Coral NPU) in JAX.

#### Running Gemma3-270M JAX chat (CPU)

`./examples/gemma3-jax-pjrt/test_chat.sh`

This script builds `libiree_pjrt_coralnpu_dylib.so` and runs end-to-end,
interactive multi-turn chat with Gemma3-270M on the CPU via JAX JIT compilation.

<br />


*** ** * ** ***

<br />