Small, runnable examples of every MLIR and LLVM construct a Gazprea compiler needs. Each topic builds the same short program several ways (its variants), and every variant prints the same output, so the IR of each can be compared side by side.
The code follows the layout of the Gazprea starter code: a BackEnd class with emitModule, lowerDialects, and dumpLLVM (include/BackEnd.h, src/BackEnd.cpp), a C runtime library in runtime/, and dragon-runner tests in tests/.
Each topic is one file, topics/<topic>/<Name>.cpp. The comment at the top gives the Gazprea program it compiles, and what each variant does and when to choose it.
| Topic | Variants |
|---|---|
00-setup |
llvm, func-arith |
01-arith |
arith, llvm |
02-casts |
arith, llvm |
03-pow |
math, loop-intrinsic, runtime-libm, float-wrong |
04-functions |
func, llvm, llvm-sret |
05-locals |
alloca-inplace, alloca-entry, memref, mem2reg, ssa |
06-if |
scf, select, cf, llvm |
07-loops |
scf, cf |
08-returns |
dead-block, check-terminator, erase-unreachable, scf-flag |
09-arrays |
llvm-struct, memref, tensor (advanced) |
10-matrices |
flat, rows, memref2d |
11-tuples |
struct-value, struct-alloca, split |
12-io |
printf-scanf, runtime |
13-globals |
initializer-region, attribute, init-function |
14-errors |
runtime-call, unreachable, runtime-op, assert |
15-pipelines |
staged, convert-to-llvm, llvm-only, bad-order |
16-dialect (advanced) |
conversion, greedy |
17-debugging |
debug-info, and an error gallery: err-dominance, err-no-terminator, err-after-terminator, err-type-mismatch, err-call-signature, err-unconverted |
18-crashes |
assert-cast, null-value, no-result, unloaded-dialect, erase-with-uses, no-insertion-point, out-of-bounds, stack-overflow |
The tensor variant of 09-arrays and all of 16-dialect are advanced techniques. Consult a TA before building a project on either.
bin/mlirex --list prints the same table.
Set up the course toolchain as for the Gazprea project, so that MLIR_DIR points at its MLIR installation, then:
mkdir build && cd build
cmake ..
make
bin/mlirex and bin/libgazrt.so are symlinked into bin/. The build defaults to Debug, so the examples can be stepped through in a debugger.
bin/mlirex <topic>/<variant> out.ll [--emit-mlir] [--print-ir-after-all]
--emit-mlirprints the module to stderr before and after lowering.--print-ir-after-allprints the module after every pass of the lowering pipeline.
To run the result:
llc -filetype=obj -relocation-model=pic out.ll -o out.o
clang out.o -o prog -Lbin -lgazrt
LD_LIBRARY_PATH=bin ./prog
or lli --load=bin/libgazrt.so out.ll.
tests/testfiles/<topic>/<variant>.test holds the Gazprea program and the expected output for each variant. Run them with:
cd tests
dragon-runner ExamplesConfig.json
ExamplesConfig.json names the llc and clang of the course installation on the lab machines (/cshome/cmput415/415-resources/llvm/23.1.1). On another machine, change both paths to the installation the examples are built against.
Every op of every standard dialect is declared in a TableGen file under the MLIR installation, for example:
| Dialect | File |
|---|---|
arith |
include/mlir/Dialect/Arith/IR/ArithOps.td |
llvm |
include/mlir/Dialect/LLVMIR/LLVMOps.td, LLVMIntrinsicOps.td |
scf |
include/mlir/Dialect/SCF/IR/SCFOps.td |
cf |
include/mlir/Dialect/ControlFlow/IR/ControlFlowOps.td |
func |
include/mlir/Dialect/Func/IR/FuncOps.td |
memref |
include/mlir/Dialect/MemRef/IR/MemRefOps.td |
math |
include/mlir/Dialect/Math/IR/MathOps.td |
Each op's entry lists its operands, attributes, and results by name. The generated C++ accessors are those names in camel case with get in front ($lhs becomes getLhs()). The generated create methods take the builder, a location, the result types (unless the op infers them), then the operands and attributes in the order declared; an op's builders section adds further create overloads. topics/16-dialect/include/DemoOps.td is a small, commented example of the format.