Programming Guide

This page covers compiler options, print debugging, performance tools, the simulator, and examples for TT-Lang operation development.

Compiler Options

Operations accept compiler options that control code generation (e.g., --no-ttl-maximize-dst, --no-ttl-fpu-binary-ops). These can be passed as command-line arguments, via the @ttl.operation decorator’s options= parameter, or the TTLANG_COMPILER_OPTIONS environment variable. Command-line arguments take highest priority.

# List available options
python examples/elementwise-tutorial/step_4_multinode_grid_full.py --ttl-help

# Run an operation with options
python examples/elementwise-tutorial/step_4_multinode_grid_full.py --no-ttl-maximize-dst

See the full compiler options reference for all decorator parameters, CompilerOptions flags with their MLIR pass mappings, environment variables, and ttlang-opt pass options.

External Functions

ttl.call_extern_func invokes custom C++ from a selected compute or data-movement kernel. The external functions reference documents template arguments, runtime arguments, DFB descriptors, tensor addresses, include directories, and logical kernel= selectors.

Operation Runtime Resources

runtime_resource_factory creates invocation-specific program semaphores, per-logical-kernel runtime arguments and definitions, and retained host owners. The operation runtime resources reference documents its typed records, validation, specialization, cache identity, and emitted-runner contract.

Print Debugging

Use print() inside kernel code to emit device debug prints. Enable at runtime with TT_METAL_DPRINT_CORES:

export TT_METAL_DPRINT_CORES=0,0   # core to capture
python my_kernel.py > output.txt 2>&1

@ttl.compute()
def compute():
    with inp_dfb.wait() as tile, out_dfb.reserve() as o:
        print("hello")                             # auto: math thread
        print(tile)                                # auto: pack thread
        result = ttl.exp(tile)
        print(_dump_dst_registers=True, label="after exp") # auto: math thread
        o.store(result)

@ttl.datamovement()
def dm_write():
    print(out_dfb)                               # CB metadata
    with out_dfb.wait() as blk:
        print(blk, num_pages=1)                  # raw tensor page
        tx = ttl.copy(blk, out[0, 0])
        tx.wait()

Prints can be extremely large and slow; redirect output to a file and use grep.
In compute kernels, guard prints with thread="math", thread="pack", or thread="unpack" to avoid overlapping output from the three TRISC threads.
When using multi-tile block sizes (DFB shape > 1x1), prints inside the generated loop will dump all tiles in the block.

See the full print debugging reference for all supported modes (scalars, tiles, tensor pages, DFB details, DST registers, thread conditioning).

Performance Tools

TT-Lang includes built-in performance analysis tools for profiling operations on hardware:

Perf Summary (TTLANG_PERF_DUMP=1) — NOC traffic and per-kernel wall time breakdown
Auto-Profiling (TTLANG_AUTO_PROFILE=1) — automatic per-line cycle count instrumentation
User-Defined Signposts (TTLANG_SIGNPOST_PROFILE=1) — targeted cycle counts for ttl.signpost() regions
Perfetto Trace Server (TTLANG_PERF_SERV=1) — visualize profiler data in the Perfetto UI

Performance tracing (Tracy) is enabled by default at build time. To disable it, configure with -DTTLANG_ENABLE_PERF_TRACE=OFF.

See the full performance tools reference for environment variable details, valid combinations, and sample output.

Simulator

See the Functional Simulator page for running kernels without hardware, debugging setup, and test commands.

Examples

See the examples/ and test/ directories for complete working examples, including:

test/python/simple_add.py
test/python/simple_fused.py

The tour provides an introduction to TT-Lang features.