Files
Raptor/README.md
T
2026-11-06 11:33:33 +01:00

91 lines
3.4 KiB
Markdown

# Raptor
Raptor is an MLIR compiler for ONNX neural networks targeting processing-in-memory
(PIM) architectures. It extends ONNX-MLIR and emits per-core `.pim` binaries,
`memory.bin`, `config.json`, and weights for the simulators under
`backend-simulators/pim/`. Optional JSON instructions use `--pim-emit-json`.
The target has shared host memory, PIM cores with ReRAM crossbars, explicit
inter-core communication, and no hardware branches or loops. Lowering,
scheduling, and memory planning keep repeated work compact until codegen.
## Build
Initialize submodules:
```bash
git submodule update --init --recursive
```
Follow [ONNX-MLIR's LLVM/MLIR build instructions](onnx-mlir/docs/BuildOnLinuxOSX.md).
The [CI workflow](.github/workflows/validate_operations.yml) records dependency
versions and setup, including CMake and Protobuf. Rust stable is required for
the functional simulator. Python requirements include the Graph Explorer and
need Python 3.13+; create the repository environment if absent, then install:
```bash
python3.13 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
```
If compatible Protobuf libraries are unavailable locally:
```bash
git clone --depth 1 --branch v34.0 https://github.com/protocolbuffers/protobuf
cmake -S protobuf -B protobuf/build -G Ninja \
-DCMAKE_BUILD_TYPE=Release -Dprotobuf_BUILD_TESTS=OFF
cmake --build protobuf/build
sudo cmake --install protobuf/build
```
Configure and build Raptor, adjusting `MLIR_DIR` to your LLVM build:
```bash
cmake -S . -B build_release -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DONNX_MLIR_ACCELERATORS=PIM \
-DLLVM_ENABLE_ASSERTIONS=ON \
-DMLIR_DIR="$PWD/onnx-mlir/llvm-project/build_release/lib/cmake/mlir"
cmake --build ./build_release
```
Use release builds first. For debugging, configure `build_debug` with
`-DCMAKE_BUILD_TYPE=Debug` and the matching MLIR package, then run
`cmake --build ./build_debug`. Use debug only for small cases requiring symbols.
Optional `mold` linking uses `-fuse-ld=mold` in
`CMAKE_{EXE,SHARED,MODULE}_LINKER_FLAGS`.
Always build through `cmake --build`; invoking `ninja` directly bypasses CMake
configuration and generated shim updates.
## Compile a model
```bash
./build_release/Release/bin/onnx-mlir model.onnx -o /tmp/raptor/model \
--maccel=PIM --EmitPimCodegen \
--crossbar-count=64 --crossbar-size=128 --core-count=144
```
This writes artifacts under `/tmp/raptor/pim/`. All three hardware flags are
mandatory positive values. The example uses the development/YOLO profile;
[Pimcomp comparison profiles](validation/networks/pimcomp_models/README.md#hardware-profiles)
differ, and validation defaults to Arch-A.
## Documentation
Open the [dialect operation reference](docs/dialects/index.html) in a browser.
It describes each operation's printed syntax, inputs, outputs, semantics, and constraints.
The [paper artifact](artifact/README.md) builds the pinned compiler and simulators
in Docker, runs the comparison and ablation experiments, and generates plots.
Start with the [documentation index](docs/README.md). It links the
[compiler architecture](docs/compiler/architecture.md),
[compiler options](docs/compiler/options.md), and
[evaluation methodology](docs/evaluation/methodology.md).
[Validation commands](validation/README.md), the
[operation inventory](validation/operations/INVENTORY.md), and the
[Graph Explorer](tools/raptor_graph_explorer/README.md) remain beside their
components.