Progress Report & Reference: MLIR Dialect for Hardware-Level SPMW

[jifengwu2k]

This is intended as a living document to record my progress, lessons learned, and useful reference materials related to developing an MLIR dialect for hardware-level SPMW. By using the issue in this way, we can easily share updates, document our findings, and support collaboration within the team.

Update: 2026-02-09

I have looked through the implementation of circt-opt.cpp. It seems like circt-opt only supports a hardcoded list consisting of built-in dialects, and not arbitrary user-defined dialects. Furthermore, the Verilog emitter implemented in ExportVerilog.cpp only supports the Comb, Debug, Emit, HW, LTL, OM, SV dialects. This means that we would need to implement our own binaries that lower our dialect to these dialects to work with the rest of Circt.

Update: 2026-02-08

The Debug dialect is built following standard MLIR conventions. Its implementation uses TableGen for declarative specification, C++ for custom logic.

TableGen Files

These describe the declarative portions of the dialect:

• DebugDialect.td
  Defines the dialect's properties (name: "dbg", summary, namespace, etc.) and extra methods for ops/types registration.
• DebugOps.td
  Declares the key IR operations provided by the dialect:
  • dbg.scope - defines a debug scope
  • dbg.variable - marks a value to be tracked in debug info
  • dbg.struct - aggregates values into a struct
  • dbg.array - aggregates values into an array
    Specifies operands, results, custom assembly formats, and documentation.
• DebugTypes.td
  Declares the custom types the dialect introduces:
  • ScopeType
  • StructType
  • ArrayType
• Debug.td
  Includes all the above together, forming the dialect's full TableGen definition. Only this file is directly involved in file generation.

Generated Files (inc/cpp.inc) (not directly authored, but referenced)

• DebugDialect.h.inc, DebugDialect.cpp.inc, Debug.h.inc, Debug.cpp.inc, DebugTypes.h.inc, DebugTypes.cpp.inc
  • Generated by TableGen (when building) from the .td files.
  • Contain boilerplate code for dialect/ops/types registration, class bodies, etc.
  • They're included at the right place in the hand-written C++ code.

Dialect Header/Implementation Files

• DebugDialect.h
  • Declares C++ class for the Debug dialect.
  • Includes the generated operation class.
• DebugOps.h
  • Declares C++ classes for all dialect operations.
  • Includes the generated operation classes.
• DebugTypes.h
  • Declares C++ classes for the dialect's custom types.
  • Includes the generated type-defs.
• DebugDialect.cpp
  • Implements the main dialect class, especially initialize() (registering custom ops/types).
  • Includes the generated dialect implementation.
• DebugOps.cpp
  • Implements any custom parsing/printing for ops (notably, dbg.struct and dbg.array have custom assembly format logic).
  • Implements dialect operation registration (DebugDialect::registerOps()).
  • Includes the generated operation implementation.
• DebugTypes.cpp
  • Implements dialect type registration (DebugDialect::registerTypes()).
  • Includes the generated type implementation.

Suppose your dialect is called foo.

myproject/
  include/
    myproject/
      Dialect/
        Foo/
          Foo.h
          FooDialect.h
          FooOps.h
          FooTypes.h
          Foo.td
          FooDialect.td
          FooOps.td
          FooTypes.td
  lib/
    Dialect/
      Foo/
        FooDialect.cpp
        FooOps.cpp
        FooTypes.cpp

Write TableGen Descriptions

• FooDialect.td
• FooOps.td
• FooTypes.td
• Foo.td

Write C++ Headers

• FooDialect.h
• FooOps.h
• FooTypes.h

Write C++ Sources

• FooOps.cpp
• FooTypes.cpp

Use Your Dialect

1. Include and link your dialect library in your code.
2. Register your dialect with the MLIR context:

   #include "myproject/Dialect/Foo/FooDialect.h"
   // ...
   mlir::MLIRContext ctx;
   ctx.getOrLoadDialect<myproject::foo::FooDialect>();

3. Build operations via the builder or parsing:

   mlir::OpBuilder builder(&ctx);
   auto myType = myproject::foo::MyType::get(&ctx);
   auto myOp = builder.create<myproject::foo::MyOp>(loc, myType, inVal);

4. Parse/print MLIR with your dialect
   • When parsing or printing, MLIR will recognize your dialect's ops/types as long as it is registered in the MLIRContext.

Update: 2026-02-07

By analyzing the build graph, I have tracked all the dependencies of circt-opt:

- "build/bin/circt-opt":
  - "build/tools/circt/tools/circt-opt/CMakeFiles/circt-opt.dir/circt-opt.cpp.o":
    - "tools/circt-opt/circt-opt.cpp"
  - "build/lib/libLLVM<llvm-library-name>.a":
    - build/lib/<llvm-library-name>/CMakeFiles/LLVM<llvm-library-name>.dir/<llvm-source-file>.o:
      - "llvm/llvm/lib/<llvm-library-name>/<llvm-source-file>"
  - "build/lib/libMLIR<mlir-library-name>.a":
    - "build/tools/mlir/**/CMakeFiles/*<mlir-library-name>.dir/<mlir-source-file>.o":
      - "llvm/mlir/**/<mlir-source-file>"
  - "build/lib/libCIRCT<circt-library-name>.a":
    - "build/tools/circt/**/CMakeFiles/*<circt-library-name>.dir/<circt-source-file>.o":
        - "**/<circt-source-file>"

As for the headers used for compiling the object files:

LLVM Object Files

• llvm/llvm/include
• Containing Directory

MLIR Object Files

• llvm/llvm/include
• llvm/mlir/include
• Containing Directory

CIRCT Object Files

• llvm/llvm/include
• llvm/mlir/include
• include
• Containing Directory

From this point of view, LLVM is a subproject of MLIR, which itself is a subproject of CIRCT.

I have also analyzed the filesystem structure of a dialect:

- include:
  - circt-c:
    - Dialect:
      - Debug.h
  - circt:
    - Dialect:
      - Debug:
        - Debug.td
        - DebugDialect.h
        - DebugDialect.td
        - DebugOps.h
        - DebugOps.td
        - DebugTypes.h
        - DebugTypes.td
- lib:
  - CAPI:
    - Dialect:
      - Debug.cpp
  - Dialect:
    - Debug:
      - DebugDialect.cpp
      - DebugOps.cpp
      - DebugTypes.cpp
- tools:
  - circt-opt:
    - circt-opt.cpp

Progress Report: 2026-02-02

Summary

This week's focus was on infrastructure setup and understanding CIRCT build systems and workflows.

What I Did

1. Repository Creation

• Created a GitHub repository:
  Set up a central place for all artifacts related to the SPMW MLIR dialect development. Link: https://github.com/jw2858/MLIR-SPMW-Dialect

  Purpose: Facilitate sharing, version control, and collaboration as the project evolves.

2. Compiling and Analyzing CIRCT

• Compiled CIRCT from source
• Analyzed build dependencies:
  • Constructed a build graph from CIRCT's build process (tracked via Ninja logs).
  • Facilitates understanding of the build steps and dependencies, making it easier to modify and "hack" the build process when developing a new dialect.

Build Graph Construction and Analysis

Developed a Python-based tool, split into several scripts, for build graph construction and analysis:

Scripts and Their Functionality:

• 01_construct_build_graph.py

  • Parses Ninja build logs.
  • Extracts compiler (cc, c++) and archive (ar) commands.
  • Builds a networkx.DiGraph where nodes are files and edges are dependencies.
  • Outputs: build-graph.json

• 02_construct_file_path_trie.py

  • Builds a trie of unique file paths.
  • Outputs: file-path-trie.pkl

• 03_construct_paths_to_relpaths.py

  • Maps absolute paths to project-relative paths using the trie.
  • Outputs: paths-to-relpaths.json

• 04_construct_relpath_build_graph.py

  • Creates a build graph using only relative paths for easier navigation.
  • Outputs: relpath-build-graph.json

• 05_analyze_extensions.py

  • Groups files by extension (.o, .a, binaries, etc.)
  • Outputs cross-references: extensions → targets → source files (target-extensions-to-targets-to-sources.json)

3. CIRCT Documentation Review

• Scraped and reviewed CIRCT's documentation:
  • Noted that it is somewhat vague and limited.
  • Focused on understanding the typical developer workflow for hardware modules using MLIR-based dialects.

Typical CIRCT Workflow

1. Define Circuits in MLIR:

   • hw dialect (for modules, ports, wires)
   • comb dialect (for combinational logic)

   Example:

   hw.module @foo(in %a: i32, in %b: i32, out out: i32) {
     %wire_a = hw.wire %a : i32
     %wire_b = hw.wire %b : i32
     %c1 = hw.constant 1 : i32
     %wire_1 = hw.wire %c1 : i32
   
     %ap1 = comb.add bin %wire_a, %wire_1 : i32
     %wire_ap1 = hw.wire %ap1 : i32
   
     %ap1pb = comb.add bin %wire_ap1, %wire_b : i32
     %wire_ap1pb = hw.wire %ap1pb : i32
   
     hw.output %wire_ap1pb : i32
   }

2. Optimize:

   • Use passes in circt-opt:
     • --canonicalize
     • --cse (common subexpression elimination)
     • --inline
     • --comb-int-range-narrowing
     • --comb-balance-mux
     • --hw-flatten-modules
   • View available passes with:
     circt-opt --help

3. Convert & Simulate:

   • Transform MLIR to Verilog:
     circt-opt output.mlir --export-verilog -o /dev/null > output.v
   • Feed to simulators (e.g., Verilator) or synthesis tools.

• Key Insight:
  circt-opt serves as a central entrypoint both for working with dialects and as a focus for dependency analysis, since it links against all CIRCT dialects.

4. Work in Progress

• Further exploring CIRCT's optimization and lowering infrastructure, starting from circt-opt.
• Begin prototyping SPMW MLIR dialect based on knowledge gained.
  • Develop scripts or workflows to streamline dialect experimentation "out-of-tree" (separate from CIRCT/MLIR source).

Progress Report: 2026-01-27

Timeframe: Past week

What I did

Explored Relevant Codebases

• Reviewed MLIR, CIRCT, and Shardy as suggested by Hongzheng.
• Concluded Shardy's design (but not its implementation) is relevant to the SPMW MLIR dialect for hardware/
• Noted that Shardy and CIRCT adopt different build systems (Bazel vs. CMake), making integration challenging.
• Recognized that CIRCT and Shardy's monorepo approaches slow down builds, reduce IDE support, and hinder experimentation.

Gained Preliminary Understanding of MLIR Python Bindings

• Built the MLIR Python package.
• Found the binding system complex and under-documented.
• Determined the bindings wrap the MLIR C API and are mostly for interoperability with existing dialects, not for developing new ones.

Gained Preliminary Understanding of MLIR Dialect Implementation in C++

• Studied MLIR's examples/standalone template for dialect development.
• Learned standard MLIR dialect folder structure.
• Learned standard MLIR dialect development process.
  • Define dialects, operations, and types in TableGen files.
  • Use mlir-tblgen to generate C++ headers.
  • Write C++ implementations.
• Learned building out-of-tree MLIR dialects by setting CMAKE_PREFIX_PATH.

Takeaways

• MLIR provides solid infrastructure for new dialects but rapid prototyping is best done in C++, not Python.
• Integration between CIRCT (CMake) and Shardy (Bazel) is non-trivial and a major hurdle for unified development.

Plans & Next Steps

• Utilize a more powerful server to build CIRCT and Shardy in-tree with MLIR; capture build commands for reference.
• Deepen understanding of where features are implemented in each codebase.
• Investigate and prototype MLIR dialect development out-of-tree for easier, faster iterations.

Reference: MLIR Dialect Project Structure

A typical MLIR dialect project (following the examples/standalone template) is organized as follows:

- MyDialect:
  - include:
    - MyDialect:
      # Dialect definition
      - MyDialect.td
      # Operations definitions
      - MyOps.td
      # Types definitions
      - MyTypes.td
      # Generated: dialect class
      - MyDialect.h
      # Generated: operations classes
      - MyOps.h
      # Generated: types classes
      - MyTypes.h
      # Additional .td/.h as needed
  - lib:
    # Dialect C++ implementation
    - MyDialect.cpp
    # Operations C++ implementation
    - MyOps.cpp
    # Types C++ implementation
    - MyTypes.cpp
    # Additional .cpp as needed

[jw2858]

First you would have to set up a bunch of environment variables.

I was using a Conda environment, so I first installed the following in the Conda environment:

conda install -c conda-forge clang clangxx libcxx libcxxabi libcxx-devel lld llvm-tools
conda install -c conda-forge cmake libxml2 ninja python zlib 
pip install ml_dtypes nanobind numpy pyyaml typing_extensions

Then I set up the following environment variables:

export CPATH="$CONDA_PREFIX/include"
export LIBRARY_PATH="$CONDA_PREFIX/lib"
export CC="clang"
export CXX="clang++ -stdlib=libc++"
export LDFLAGS="-Wl,-rpath,$LIBRARY_PATH"
export AR="$CONDA_PREFIX/bin/llvm-ar"
export RANLIB="$CONDA_PREFIX/bin/llvm-ranlib"
export LD="$CONDA_PREFIX/bin/ld.lld"

Then I basically followed Circt's official compilation instructions. Note Circt is a monorepo, it has a full LLVM submodule in it.

# Clone the repository and its submodules
git clone --recursive https://github.com/llvm/circt.git

cd circt

# Configure the build
cmake -G Ninja llvm/llvm -B build \
    -DCMAKE_BUILD_TYPE=Debug \  # enables debug information, which makes the whole tree compile slower, but allows you to step through code into the LLVM and MLIR frameworks
    -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \  # generates a compile_commands.json file, which can be used by editors and language servers for autocomplete and other IDE-like features
    -DLLVM_ENABLE_ASSERTIONS=ON \
    -DLLVM_TARGETS_TO_BUILD=host \
    -DLLVM_ENABLE_PROJECTS=mlir \
    -DLLVM_EXTERNAL_PROJECTS=circt \
    -DLLVM_EXTERNAL_CIRCT_SOURCE_DIR=$PWD \
    -DLLVM_ENABLE_LLD=ON

# Build everything about the CIRCT tools and libraries
# Add `-v` to print build commands
ninja -C build check-circt