onnx-mlir

onnx-mlir compiles ONNX models to native code using MLIR and LLVM. A model is imported into the ONNX dialect, transformed (shape inference, constant propagation, decompositions), and lowered. The main path goes through the Krnl dialect, then Affine/SCF/MemRef and LLVM. Other paths start from the same ONNX dialect:

• Linalg: --use-linalg-path replaces Krnl for selected ops (--linalg-ops).
• StableHLO and TOSA: conversion passes in src/Conversion/ONNXToStablehlo/ and ONNXToTOSA/, run through onnx-mlir-opt. StableHLO is built when ONNX_MLIR_ENABLE_STABLEHLO is on, which is the default.
• NNPA (IBM Z): the accelerator lowers supported ops through the ZHigh and ZLow dialects (src/Accelerators/NNPA/).

Where things are

• src/Builder/: ONNX model importer
• src/Dialect/ONNX/, src/Dialect/Krnl/: dialects, ops, shape inference
• src/Dialect/ONNX/Transforms/, src/Transform/: ONNX-level and Krnl-level passes
• src/Conversion/: lowerings (ONNXToKrnl/, KrnlToAffine/, KrnlToLLVM/, ...)
• src/Accelerators/NNPA/: NNPA accelerator
• src/Compiler/: driver and options (CompilerOptions.cpp)
• src/Runtime/: runtime library and Python/Java bindings
• src/Tools/: onnx-mlir-opt and other tools
• test/mlir/: lit tests; test/backend/: ONNX backend tests; test/numerical/: numerical tests
• utils/: scripts (gen_onnx_mlir.py, fixLitTest.py, GroundLitTest.py, ...)
• third_party/: vendored submodules, not modified here

Build and test

onnx-mlir builds against a specific LLVM commit, the one in utils/clone-mlir.sh. Full setup is in docs/BuildOnLinuxOSX.md; NNPA builds add -DONNX_MLIR_ACCELERATORS=NNPA. From an existing build/ directory:

cmake --build .                                  # build; binaries in <Config>/bin
cmake --build . --target check-onnx-lit          # lit tests, required for every change
llvm-lit -v test/mlir/onnx/<file>.mlir           # one lit test (path relative to build/)
cmake --build . --target check-onnx-backend      # ONNX backend tests
TEST_CASE_BY_USER=<test_name> cmake --build . --target check-onnx-backend
cmake --build . --target check-onnx-numerical    # numerical tests

llvm-lit is in the LLVM build's bin/ directory. Other targets and environment variables are in docs/Testing.md.

A lit test's CHECK lines only confirm that the output has a given shape, not that it is correct. When adding or changing a lowering or pass, ground each case by running it with utils/GroundLitTest.py before recording the CHECK lines; see docs/GroundedLitTests.md.

Style

• C++: LLVM coding standards, formatted with clang-format using the repository's .clang-format. CI checks src/.
• Python: formatted with black, which CI also checks.
• Project-specific rules are in CODING_PRACTICE.md and the coding-conventions skill.

Generated files: do not edit by hand

• src/Dialect/ONNX/ONNXOps.td.inc: edit utils/gen_onnx_mlir.py, then regenerate with make OMONNXOpsIncTranslation and commit the output (docs/ImportONNXDefs.md).
• docs/Dialects/*.md: regenerate with make onnx-mlir-docs.
• docs/SupportedONNXOps-*.md: generated by utils/documentOps.py.
• .agents/skills/: exported from a knowledge base; see its README.

Skills

Task guides live in .agents/skills/, one SKILL.md per task: adding ONNX ops (dialect, lowering, end to end), passes, op fusion, grounded lit tests, debugging compilation, NNPA performance, and LLVM upgrades. onnx-mlir-internals and nnpa-internals hold background reference pages. Load the skill that matches the task before starting.

Contribution rules

These come from CONTRIBUTING.md, which follows the LLVM AI Tool Use Policy:

• A human must approve every commit, PR, and comment. Never push, open a PR, or post on GitHub on your own.
• Commits need a DCO sign-off (git commit -s). Note substantial AI help with an Assisted-by: <tool> trailer or in the PR description.
• Keep changes focused on the task, and don't reformat or refactor unrelated code.