tilelang.tools.lower_trace.core¶

IR lower trace — zero-intrusion debug tool for visualizing compilation passes.

Monkey-patches tvm.ir.transform.Pass.__call__ and PassPipeline.lower to automatically capture IR before/after every pass and generate diff reports.

This module reads its configuration (TL_LOWER_TRACE / TL_LOWER_TRACE_DIR) through the centralized tilelang.env environment, or via values passed programmatically to enable().

Supports two architectures: - New: PassPipeline.lower (each backend registers a pipeline object) - Old: phase-based functions called from tilelang.engine.lower

Usage:

TL_LOWER_TRACE=1 python my_kernel.py        # HTML report
TL_LOWER_TRACE=terminal python my_kernel.py  # terminal diff only
TL_LOWER_TRACE=both python my_kernel.py      # both terminal and HTML

Attributes¶

`STATUS_COMPLETED`
`STATUS_FAILED`
`STATUS_SKIPPED`
`STATUS_CODEGEN`

Classes¶

LowerRecord

Result of running a single pass.

Functions¶

`enable`(*[, mode, trace_dir, codegen_output])	Enable IR pass tracing via monkey-patching.
`disable`()	Remove the pass tracing hook and restore original behavior.
`reset`()	Clear collected records and section cache.

Module Contents¶

tilelang.tools.lower_trace.core.STATUS_COMPLETED = 'completed'¶

tilelang.tools.lower_trace.core.STATUS_FAILED = 'failed'¶

tilelang.tools.lower_trace.core.STATUS_SKIPPED = 'skipped'¶

tilelang.tools.lower_trace.core.STATUS_CODEGEN = 'codegen'¶

class tilelang.tools.lower_trace.core.LowerRecord¶

Result of running a single pass.

phase: str¶

name: str¶

index: int¶

before_text: str¶

after_text: str¶

changed: bool¶

add_lines: int = 0¶

del_lines: int = 0¶

status: str = 'completed'¶

error_msg: str = ''¶

tilelang.tools.lower_trace.core.enable(*, mode=_UNSET, trace_dir=_UNSET, codegen_output=_UNSET)¶

Enable IR pass tracing via monkey-patching.

Parameters:

mode (str | None, optional) – Force a trace mode ('terminal', 'html', 'both', or None to disable). When omitted, the mode is read from the TL_LOWER_TRACE env var (via tilelang.env) or a prior enable override.
trace_dir (str | None, optional) – Force the trace output base directory. When omitted, falls back to the TL_LOWER_TRACE_DIR env var, then ./tmp/lower_trace_dir.
codegen_output (str | None, optional) – Path to save the codegen-generated C++/CUDA/etc. source code. When omitted, defaults to <script_dir>/codegen.cpp (inside the per-script output directory, beside .run_records/). Pass None explicitly to suppress all extra saves. See _wrap_codegen_ffi for the three-file (<path> / <path>.original / <path>.latest) patch-and-recompile workflow.

tilelang.tools.lower_trace.core.disable()¶: Remove the pass tracing hook and restore original behavior.

tilelang.tools.lower_trace.core.reset()¶

Clear collected records and section cache.

_script_dir is preserved (stable across runs, holds codegen files + html symlink). _run_dir is also preserved: clearing it here would split a single run into two directories, because pre-pipeline passes (which lazily create it via _ensure_run_dir) run before PassPipeline.lower/_wrap_phase invokes reset on its first run. A fresh _run_dir for each subsequent run is instead established directly in _traced_pipeline_lower / _wrap_phase (when _run_counter > 1), without calling reset so that records keep accumulating across runs.