Creating Bug Repros for TTNN Using TT-MLIR Codegen

While developing in tt-mlir, it's not uncommon to encounter bugs originating in the TTNN library. To isolate and report such bugs, a practical approach is to use the C++ codegen feature (EmitC) to generate a minimal repro. This guide walks you through how to create such repros and integrate them into the tt-metal repository, where TTNN is developed.

Step-by-Step Guide

Note: If you run into issues while following these steps, check the Known Issues section at the end of this guide for common problems and solutions.

1. Generate C++ Code from TT-MLIR

Use the ttnn-standalone tool to run the compiler and emit C++ code.

📖 See ttnn-standalone.md for instructions on how to generate C++ code from your MLIR input using EmitC.

2. Scope Down the Repro

Once you've generated the C++ code:

Use the ttnn-standalone tool to run and debug it in isolation.
Reduce the repro to the minimal example that still triggers the bug.
Confirm the issue still reproduces reliably.

3. Clone the TT-Metal Repository

Clone the tt-metal repo:

git clone git@github.com:tenstorrent/tt-metal.git
cd tt-metal

4. Add the Repro to the GTest Infrastructure

Place your .cpp file in:

tests/ttnn/unit_tests/gtests/emitc/

and add it to the cmake file:

tests/ttnn/unit_tests/gtests/CMakeLists.txt

like so:

set(EMITC_UNIT_TESTS_SRC
    ${CMAKE_CURRENT_SOURCE_DIR}/emitc/test_sanity.cpp
    ${CMAKE_CURRENT_SOURCE_DIR}/emitc/your_test_name.cpp  # <<<===
)

Use the existing file test_sanity.cpp in that directory as a reference.

5. Modify the Repro for GTest

There are some modifications that need to be made in order to fit the GTest infra:

Convert the main() function to a TEST(...) macro:

TEST(EmitC, YourTestName) {
    // Your original main function body here
}

Remove any return statements from the TEST(...) function body.
Replace #include "ttnn-precompiled.hpp" with #include "emitc.hpp"

6. Build the TTNN EmitC Tests

First, activate the python virtual env, and set some env variables:

source python_env/bin/activate
export TT_METAL_HOME=$(pwd)
export PYTHONPATH=$(pwd)

Then, build the tests:

./build_metal.sh --build-ttnn-tests

Note: some unrelated gtests might fail here, we can ignore them.

7. Run the EmitC Unit Tests

To run all EmitC tests:

./build/test/ttnn/unit_tests_ttnn_emitc

To run a specific test:

./build/test/ttnn/unit_tests_ttnn_emitc --gtest_filter=EmitC.YourTestName

Create a branch with your changes.
Open a GitHub issue or comment on an existing one.
Link to your branch and include the instructions for running the repro

./build_metal.sh --build-ttnn-tests
./build/test/ttnn/unit_tests_ttnn_emitc
./build/test/ttnn/unit_tests_ttnn_emitc --gtest_filter=EmitC.YourTestName

Known Issues

Missing sfpi compiler or other dependencies If you encounter errors about a missing sfpi compiler or other system-level dependencies, refer to the tt-metal installation guide for instructions on installing the required packages.
TTNN test compilation failures If the build fails when compiling TTNN tests, inspect the specific tests that caused the failure. If the failures are unrelated to EmitC tests, they can typically be ignored — this is a known issue.

tt-mlir documentation