add-onnx-transform-pass
Skill1.1k starsChanged 12 days agoApache-2.0View on GitHub
Use when creating a new onnx-mlir compiler pass (ONNX-level transform or other): declaring it in the right Passes.td with TableGen, implementing it, wiring CMake, registering it in onnx-mlir-opt, and adding it to the compiler pipeline.
Trending
Quiet since December.about the whole repository
Who's talking about onnx/onnx-mlir
- elixir-nx/nx“Import of MLIR modules”GitHub · Mar 5, 2024 · 4 reactions
- PyTorchKR/pytorchcore-kr“더 나은 질의 응답 구조를 위한 Discussion 활용 방안”GitHub · Jan 20, 2025 · 2 reactions
- llvm/torch-mlir“[RFC] Support for an embedded build of Torch-MLIR”GitHub · Sep 23, 2022 · 2 reactions
- Samsung/ONE“[circle-mlir] Update onnx-mlir to official release”GitHub · Jun 8, 2025 · 1 reactions
- Xilinx/onnx-mlir“ONNX to TOSA Legalization Upstream tracker”GitHub · Apr 20, 2023 · 1 reactions
The biggest 5 of 22 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 22
Talked about on GitHub (22 times).
On GitHub · 22
- Mar 5, 2024Import of MLIR modules — elixir-nx/nx4 reactions · 2 comments
- Jan 20, 2025더 나은 질의 응답 구조를 위한 Discussion 활용 방안 — PyTorchKR/pytorchcore-kr2 reactions
- Sep 23, 2022[RFC] Support for an embedded build of Torch-MLIR — llvm/torch-mlir2 reactions · 4 comments
- Jun 8, 2025[circle-mlir] Update onnx-mlir to official release — Samsung/ONE1 reaction · 4 comments
- Apr 20, 2023ONNX to TOSA Legalization Upstream tracker — Xilinx/onnx-mlir1 reaction
17 more on GitHub
- Dec 16, 2025[ttl] Automate elementwise op generation from specifications — tenstorrent/tt-lang0 reactions · 1 comment
- Jul 29, 2025Missing Symbols due to visibility setting change — onnx/onnx0 reactions · 2 comments
- Nov 19, 2024Add fancier CI badges showing number of tests and/or test coverage — iree-org/iree-test-suites0 reactions · 2 comments
- Aug 6, 2024Standardize rewriter tests; testing facilities — microsoft/onnxscriptsays it tested it0 reactions · 1 comment
- May 8, 2024Fix macos build by pinning version — Xilinx/onnx-mlir0 reactions
- Mar 30, 2024Include the ".onnxtext" extension in supported serialization format — onnx/onnx0 reactions · 1 comment
- Dec 20, 2023add filecheck test for add.onnx — xdslproject/xdsl0 reactions · 7 comments
- Dec 1, 2023Failed to build with the use of --cpp-implementation — protocolbuffers/protobuf0 reactions
- Oct 27, 2023Bring in the fix for empty slice in canonicalization — Xilinx/onnx-mlir0 reactions
- Oct 25, 2023Cherry-picked upstream PR: Add conversion for DivOp ONNX to TOSA (#2207) — Xilinx/onnx-mlir0 reactions
- Aug 26, 2023Build error on M1 MacOS machine — onnx/onnx0 reactions · 3 comments
- Oct 18, 2022ONNX MLIR exporter — nod-ai/onnx-mlir-exporter0 reactions · 1 comment
- Oct 9, 2022[Feature request] Machine Readable definition of Operations (Schema file instead of Markdown or cc file) — onnx/onnx0 reactions · 14 comments
- Jun 28, 2022Can we have newer opset of bidaf-9 model (including opset 9 or newer onnx.Scan op)? — onnx/models0 reactions · 1 comment
- Jun 5, 2022Broken Links — onnx/onnx.github.io0 reactions · 3 comments
- May 12, 2022Update the onnx-mlir version — DependableSystemsLab/LLTFI0 reactions · 2 comments
- Jun 30, 2020Error when trying to lower alex net onnx model to MLIR — onnx/models0 reactions · 1 comment
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- add-fusion-patternSkill
- add-new-onnx-operationSkill
- add-onnx-op-loweringSkill
- add-onnx-op-to-dialectSkill
- coding-conventionsSkill
- debug-compilationSkill
- debug-type-catalogueSkill
- ground-lit-testsSkill
- nnpa-internalsSkill
- nnpa-performanceSkill
- onnx-mlir-internalsSkill
- upgrade-llvm-mlirSkill
- using-torch-onnxmlir-with-huggingfaceSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 0 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 35
If your new pass belongs to one of these areas, add a def there.
- Very specific: line 118
Add the .cpp to (or add a new) add_onnx_mlir_library(...) target in that directory's CMakeLists.txt, and make sure it depends on the …
- Very specific: line 140
Compiler driver: call pm.addPass(onnx_mlir::create{{PASS_NAME}}(...)) at the right pipeline stage in src/Compiler/CompilerPasses.cpp — …
- Very specific: line 151
Run it on a small .mlir input to confirm it's reachable and does what's expected:
- Very specific: line 171
Files read: all of the above, plus a PassWrapper-based cross-check on Decompose.cpp, ConvOpt.cpp, ShapeInferencePass.cpp, …
- Very specific: line 172
How to test: after adding a pass per Steps 1–6, onnx-mlir-opt --help should list --{{CLI_NAME}}.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- Generated from the onnx-mlir knowledge base (skills/add-onnx-transform-pass.md), verified against onnx-mlir@b505d64b. Do not edit here: see .agents/skills/README.md. -->Add a New Pass Using TableGen
Recipe for declaring a new onnx-mlir compiler pass's class via TableGen (Passes.td + PassBase.td) instead of hand-rolling a PassWrapper subclass. This is the pattern to follow for any new pass; most existing passes in this area predate the convention and hand-roll their class directly — see "Legacy pattern" below before copying one of those as a template.
Parameters
| Parameter | Description | Example |
{{PASS_NAME}} | Pass class name (CamelCase, ends in Pass) | AppendDecodingStrategyPass |
{{CLI_NAME}} | Command-line pass name (kebab-case) | append-decoding-strategy |
{{ROOT_OP}} | MLIR op type the pass runs on | ModuleOp |
{{OWNER_DIR}} | Directory owning the Passes.td for this area | src/Dialect/ONNX/Transforms |
Step 1: Pick the owning Passes.td
Four pass-declaration .td files exist repo-wide today. Three are wired into the build by the add_onnx_mlir_pass(NAME TD_FILE PREFIX) CMake helper in MLIR.cmake (mlir_tablegen(...-gen-pass-decls -name ${NAME}) + add_public_tablegen_target(OM${NAME}PassIncGen)):
src/Dialect/ONNX/Transforms/Passes.td— ONNX-dialect graph-level passes (add_onnx_mlir_pass(ONNXTransforms Passes ONNXTransforms)in that directory'sCMakeLists.txt)src/Transform/Passes.td— cross-dialect/general transforms (OpenMP/parallel plumbing, instrumentation, CSE) (add_onnx_mlir_pass(Transforms Passes Transforms))src/Transform/PassesKrnl.td— Krnl-specific transforms, split into its own file so Krnl-dialect code can depend on it separately; today onlyLowerKrnlRegionPass(add_onnx_mlir_pass(TransformsKrnl PassesKrnl TransformsKrnl), targetOMTransformsKrnlPassIncGen)
The fourth, src/Conversion/ONNXToLinalg/Passes.td (the ONNX→Linalg conversion pass), calls mlir_tablegen(Passes.h.inc -gen-pass-decls -name ONNXToLinalg) and add_public_tablegen_target(OMONNXToLinalgPassIncGen) directly instead of using the helper.
If your new pass belongs to one of these areas, add a def there. Otherwise, create a new Passes.td and add a matching add_onnx_mlir_pass(...) call to that directory's CMakeLists.txt, mirroring the first three above.
Step 2: Write the def
def {{PASS_NAME}} : Pass<"{{CLI_NAME}}", "{{ROOT_OP}}"> {
let summary = "One-line summary.";
let description = [{
Longer description of what the pass does and why.
}];
}This is exactly the shape of the passes already following this convention in src/Dialect/ONNX/Transforms/Passes.td: AppendDecodingStrategyPass, AppendInstrumentedOutputsPass, FusionOpTransformPass (all ModuleOp), and ExpandAttentionMaskPass (func::FuncOp). ExpandAttentionMaskPass additionally sets let constructor = "onnx_mlir::createExpandAttentionMaskPass()"; and let dependentDialects = [...], declares the factory by hand in src/Pass/Passes.hpp, and defines it at the bottom of its .cpp — a default-constructible pass does not need that, but it is a working variant.
Step 2a: Prefer a TableGen Option over a hand-written constructor
If the pass needs a simple per-invocation setting (a string/bool/int), give it a TableGen Option rather than a custom C++ constructor — it becomes a real field on the generated base class and a CLI flag settable through both onnx-mlir-opt and pass-pipeline strings, at no extra registration cost. ConvertONNXToLinalg (src/Conversion/ONNXToLinalg/Passes.td) is the grounded example:
let options = [
Option<"linalgOps", "linalg-ops", "std::string", /*default=*/"",
"...">,
Option<"useLinalgPath", "use-linalg-path", "bool", /*default=*/"false",
"...">
];Step 2b: Fall back to a custom constructor only when the value can't be an Option
Use this only when the value must be threaded in programmatically by the driver rather than exposed as a standalone --{{CLI_NAME}}=opt flag (e.g. it's derived from another already-parsed compiler option). AppendInstrumentedOutputsPass and InstrumentPass follow this fallback: the def in Passes.td stays option-less, and in src/Pass/Passes.hpp:
#define GEN_PASS_DECL_{{PASS_NAME_UPPERCASE}}
#include "{{OWNER_DIR}}/Passes.h.inc"
// GEN_PASS_DEF method only adds default constructor only,
// we add custom constructor with an explicit ... argument.
std::unique_ptr<mlir::Pass> create{{PASS_NAME}}(/* real args */);Reuse that exact comment (or a close variant) — it's the established way this codebase flags "yes, we deliberately bypassed the generated default constructor here."
Step 3: Implement the class
In the pass's .cpp:
namespace onnx_mlir {
#define GEN_PASS_DEF_{{PASS_NAME_UPPERCASE}}
#include "{{OWNER_DIR}}/Passes.h.inc"
} // namespace onnx_mlir
namespace {
class {{PASS_NAME}}
: public onnx_mlir::impl::{{PASS_NAME}}Base<{{PASS_NAME}}> {
public:
MLIR_DEFINE_EXPLICIT_INTERNAL_INLINE_TYPE_ID({{PASS_NAME}})
void runOnOperation() override {
// ...
}
};
} // namespaceAny Options from Step 2a show up as plain member fields on the base class (e.g. linalgOps, useLinalgPath) — don't redeclare them. If you took the Step 2b fallback, add the constructors you declared in Passes.hpp and store the extra state as an ordinary private member, the way AppendInstrumentedOutputsPass stores nodeNamePattern.
For a no-option, default-constructible pass, no hand-written factory is needed — the generated header already provides create{{PASS_NAME}}(), matching createAppendDecodingStrategyPass(). For the Step 2b fallback, define the factory yourself at the bottom of the .cpp, e.g.:
std::unique_ptr<mlir::Pass> onnx_mlir::create{{PASS_NAME}}(/* args */) {
return std::make_unique<{{PASS_NAME}}>(/* args */);
}Step 4: Wire up the build
Add the .cpp to (or add a new) add_onnx_mlir_library(...) target in that directory's CMakeLists.txt, and make sure it depends on the tablegen target from Step 1 so the generated header exists before the pass compiles:
add_onnx_mlir_library(OM{{LibraryName}}
{{PassName}}.cpp
DEPENDS
OM{{PREFIX}}PassIncGen
LINK_LIBS PUBLIC
OMONNXOps
MLIRPass
)(DEPENDS OMONNXTransformsPassIncGen is what OMAppendDecodingStrategy, OMInstrumentONNX, OMFusionOpTransform and OMExpandAttentionMask use for the ONNXTransforms area.) OMFusionOpHelper (FusionOpHelper.cpp) also declares it although it defines no pass, which orders it after the pass-declaration TableGen step.
Step 5: Register and wire into pipelines
onnx-mlir-opt: add amlir::registerPass([]() -> std::unique_ptr<mlir::Pass> { return create{{PASS_NAME}}(...); });lambda insideregisterOMPasses()insrc/Tools/onnx-mlir-opt/RegisterPasses.cpp. Note that even TableGen-declared passes inDialect/ONNX/Transforms/Passes.tdare registered this way, one lambda per pass — onnx-mlir does not rely on the TableGen-generated bulkregisterXXXPasses()entry point for that file (it does use it forsrc/Transform/Passes.tdandsrc/Conversion/ONNXToLinalg/Passes.td, via::registerTransformsPasses()/::registerONNXToLinalgPasses()).- Compiler driver: call
pm.addPass(onnx_mlir::create{{PASS_NAME}}(...))at the right pipeline stage insrc/Compiler/CompilerPasses.cpp—pm.addNestedPass<func::FuncOp>(...)for afunc::FuncOp-rooted pass. A pass only an accelerator wants is scheduled from that accelerator's driver instead, e.g.ExpandAttentionMaskPassinaddONNXToZHighPasses()(src/Accelerators/NNPA/Compiler/NNPACompilerUtils.cpp), gated by--nnpa-disable-expand-attention-mask.
Step 6: Build and verify
cd build && make -j$(nproc) onnx-mlir-opt onnx-mlir
onnx-mlir-opt --help | grep {{CLI_NAME}}Run it on a small .mlir input to confirm it's reachable and does what's expected:
onnx-mlir-opt --{{CLI_NAME}} /tmp/test.mlirThis confirms the pass is wired up, not that its output is correct. Before freezing that output into a FileCheck test, ground it numerically — ground-lit-tests.md is the workflow, and it also covers the two cases that matter most for a pass with a CLI option like this one: a case grounded with the option off over the same code, and a negative test for every restriction the pass documents (otherwise the restriction is only a comment). Its Step 1b also covers the RUN line itself: pass --{{CLI_NAME}} and as few other optimization passes as practical, so a failure is attributable to this pass rather than to something upstream of it.
Legacy pattern — do not copy for new passes
Most passes in src/Dialect/ONNX/Transforms/ predate this convention and hand-roll a PassWrapper<{{PassName}}, OperationPass<...>> subclass directly, with no corresponding Passes.td entry: DecomposeONNXToONNXPass, ConvOptONNXToONNXPass, ShapeInferencePass, ONNXHybridTransformPass, and ReplaceOpWithItsOperandPass all do this. They are not being retrofitted as part of this recipe — but a new pass should follow Steps 1–6 above, not imitate one of these.
Verification
- Re-checked at:
repo:onnx-mlir@b505d64:src/Dialect/ONNX/Transforms/Passes.td(fourdefs;ExpandAttentionMaskPassconstructor/dependentDialects),repo:onnx-mlir@b505d64:src/Dialect/ONNX/Transforms/CMakeLists.txt(DEPENDS OMONNXTransformsPassIncGenonOMFusionOpHelper,OMFusionOpTransform,OMInstrumentONNX,OMExpandAttentionMask,OMAppendDecodingStrategy),repo:onnx-mlir@b505d64:src/Pass/Passes.hpp("GEN_PASS_DEF method only adds default constructor only" comments),repo:onnx-mlir@b505d64:src/Accelerators/NNPA/Compiler/NNPACompilerUtils.cpp,repo:onnx-mlir@b505d64:src/Tools/onnx-mlir-opt/RegisterPasses.cpp(per-pass lambdas;::registerTransformsPasses(),::registerONNXToLinalgPasses()),repo:onnx-mlir@b505d64:MLIR.cmake(add_onnx_mlir_pass),repo:onnx-mlir@b505d64:src/Transform/CMakeLists.txtandsrc/Transform/PassesKrnl.td(the fourth.td, missing from the original grounding),repo:onnx-mlir@b505d64:src/Conversion/ONNXToLinalg/CMakeLists.txtandPasses.td(linalgOps/useLinalgPathoptions), and the five legacyPassWrapperfiles listed below - Originally grounded against (at
aeb55f8f):src/Dialect/ONNX/Transforms/Passes.td,src/Dialect/ONNX/Transforms/AppendDecodingStrategy.cpp,src/Dialect/ONNX/Transforms/AppendInstrumentedOutputsPass.cpp,src/Conversion/ONNXToLinalg/Passes.td,src/Transform/Passes.td,src/Pass/Passes.hpp,src/Tools/onnx-mlir-opt/RegisterPasses.cpp,src/Compiler/CompilerPasses.cpp,MLIR.cmake(add_onnx_mlir_pass),src/Dialect/ONNX/Transforms/CMakeLists.txt - Files read: all of the above, plus a
PassWrapper-based cross-check onDecompose.cpp,ConvOpt.cpp,ShapeInferencePass.cpp,ONNXHybridTransformPass.cpp,ReplaceOpWithItsOperand.cpp(confirming which existing passes are the legacy pattern, not the template) - How to test: after adding a pass per Steps 1–6,
onnx-mlir-opt --helpshould list--{{CLI_NAME}}; running it on a minimal.mlirfile exercising the pass'srunOnOperation()should produce the expected rewrite with no build errors from a missingDEPENDSon the...PassIncGentarget
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

