tvm_tirx.ir.transform#

IR passes, pass contexts, sequential pipelines, and pass instrumentation.

class tvm_tirx.ir.transform.ModulePass(pass_info)#

A pass whose callback receives and returns a complete IRModule.

Create instances with module_pass(), which accepts a function or a class defining transform_module. Call after = pass_object(before) to execute the callback under the current PassContext. Its callback, rather than this wrapper class, defines how the IR changes; see module_pass() for a TVMScript before/after example.

class tvm_tirx.ir.transform.Pass(*args: Any, **kwargs: Any)#

Base interface for callable IRModule transformations and analyses.

Obtain a concrete pass from a pass factory, module_pass(), or tvm_tirx.tirx.transform.function_pass(), then call after = pass_object(before): a pass takes an IRModule and returns the transformed IRModule. The call runs under the current PassContext, whose instruments observe it. A direct call always runs the pass; the optimization level and the required_pass/disabled_pass options apply when a Sequential runs it. The info property exposes its name and optimization level. The base class defines no transformation of its own.

Examples

from tvm_tirx import tirx

simplify = tirx.transform.StmtSimplify()
after = simplify(mod)
print(simplify.info.name)  # tirx.StmtSimplify
property info#

Get the pass meta.

class tvm_tirx.ir.transform.PassContext(opt_level=2, required_pass=None, disabled_pass=None, instruments=None, config=None)#

Scope optimization levels, pass selection, instruments, and pass options.

Use a PassContext as a with block. Every pass that runs inside the block, called directly or by a Sequential, sees this context as PassContext.current() and receives it as the ctx argument of its callback. Outside any with block, a default context with opt_level=2 and no other options is active.

Parameters:
  • opt_level (Optional[int]) – Maximum optimization level enabled in sequential pipelines (default 2). A Sequential skips a child pass whose info.opt_level is higher. Calling a pass directly ignores this level.

  • required_pass (Optional[Union[List[str], Set[str], Tuple[str]]]) – Pass names to enable regardless of their optimization level.

  • disabled_pass (Optional[Union[List[str], Set[str], Tuple[str]]]) – Pass names to skip in sequential pipelines, even if required.

  • instruments (Optional[Sequence[PassInstrument]]) – The list of pass instrument implementations. They observe every pass that runs inside the context.

  • config (Optional[Dict[str, Object]]) – Additional configurations for specific passes. Keys must be registered option names, which list_configs() lists; an unknown key raises an error.

Examples

from tvm_tirx import tirx
from tvm_tirx.ir.transform import PassContext, Sequential

pipeline = Sequential([tirx.transform.StmtSimplify(), my_pass])
with PassContext(opt_level=3, disabled_pass=["tirx.StmtSimplify"]):
    assert PassContext.current().opt_level == 3
    after = pipeline(mod)  # runs only my_pass
override_instruments(instruments)#

Override instruments within this PassContext.

If there are existing instruments, their exit_pass_ctx callbacks are called. Then switching to new instruments and calling new enter_pass_ctx callbacks.

instrumentsSequence[PassInstrument]

The list of pass instrument implementations.

static current()#

Return the current pass context.

static list_configs()#

List all registered PassContext configuration names and metadata.

Returns:

configs

Return type:

Dict[str, Dict[str, str]]

class tvm_tirx.ir.transform.PassInfo(opt_level, name)#

Metadata of a pass: its name and optimization level.

Every pass carries a PassInfo, available as Pass.info. PassContext uses the name in required_pass and disabled_pass, and Sequential compares the optimization level with the context’s opt_level. Pass instruments receive the PassInfo of each pass they observe.

Parameters:
  • opt_level (int) – The optimization level of this pass.

  • name (str) – The pass name.

Examples

from tvm_tirx import tirx

info = tirx.transform.StmtSimplify().info
print(info.name, info.opt_level)  # tirx.StmtSimplify 0
class tvm_tirx.ir.transform.PassInstrument#

A pass instrument implementation.

An instrument observes the passes that run inside a PassContext, for example to print, time, or skip them. Install it with PassContext(instruments=[...]); it then sees every pass that runs while the context is active, whether the pass is called directly or by a Sequential.

To use, a user class can either subclass from PassInstrument directly, or can apply the pass_instrument() wrapper. In either case, the enter_pass_ctx, exit_pass_ctx, should_run, run_before_pass, and run_after_pass methods can be defined to adjust the instrument’s behavior. See the no-op implementations in this class definition for more information on each.

Examples

Record the name of every pass that runs:

from tvm_tirx import tirx
from tvm_tirx.ir.transform import PassContext, pass_instrument

@pass_instrument
class RecordNames:
    def __init__(self):
        self.names = []

    def run_before_pass(self, mod, info):
        self.names.append(info.name)


recorder = RecordNames()
with PassContext(instruments=[recorder]):
    tirx.transform.StmtSimplify()(mod)
print(recorder.names)  # ['tirx.StmtSimplify']
enter_pass_ctx()#

Called when entering the instrumented context.

Return type:

None

exit_pass_ctx()#

Called when exiting the instrumented context.

Return type:

None

should_run(mod, info)#

Determine whether to run the pass or not.

Called once for each pass that is run while the instrumented context is active.

Parameters:
Returns:

should_run – True to run the pass, or False to skip the pass.

Return type:

bool

run_before_pass(mod, info)#

Instrument before the pass runs.

Called once for each pass that is run while the instrumented context is active.

Parameters:
Return type:

None

run_after_pass(mod, info)#

Instrument after the pass runs.

Called once for each pass that is run while the instrumented context is active.

Parameters:
Return type:

None

tvm_tirx.ir.transform.PrintIR(header='')#

Log the header and module IR, returning the module unchanged.

Parameters:

header (str) – The header to be displayed along with the dump.

Returns:

fpass – A module pass with optimization level zero.

Return type:

Pass

Examples

The observation pass returns the module unchanged.

import tvm_tirx as tvm
from tvm_tirx.script import ir as I, tirx as T

@I.ir_module
class Before:
    @T.function(private=True)
    def main():
        T.evaluate(0)

@I.ir_module
class Expected:
    @T.function(private=True)
    def main():
        T.evaluate(0)

def run_pass():
    return tvm.ir.transform.PrintIR("before lowering")(Before)

tvm.ir.assert_structural_equal(run_pass(), Expected)
class tvm_tirx.ir.transform.Sequential(passes=None, opt_level=0, name='sequential')#

A pass that works on a sequence of pass objects. Multiple passes can be executed sequentially using this class.

Passes run in the given order, subject to the optimization level and the required/disabled pass controls in PassContext. A child pass runs when its info.opt_level is at most the context’s opt_level or its name is in required_pass, and never when its name is in disabled_pass. A Sequential is itself a pass, so it can be nested in another Sequential.

Parameters:
  • passes (Optional[List[Pass]]) – A sequence of passes candidate for optimization.

  • opt_level (Optional[int]) – The optimization level of this sequential pass. The opt_level of a default sequential pass is set to 0. Child passes use the active PassContext’s optimization level.

  • name (Optional[str]) – The name of the sequential pass.

Examples

from tvm_tirx import tirx
from tvm_tirx.ir.transform import PassContext, Sequential

@tirx.transform.function_pass(opt_level=3)
def expensive(func, mod, ctx):
    return func


pipeline = Sequential([tirx.transform.StmtSimplify(), expensive])
with PassContext(opt_level=2):
    after = pipeline(mod)  # skips expensive, whose opt_level is 3
with PassContext(opt_level=2, required_pass=["expensive"]):
    after = pipeline(mod)  # runs both passes
tvm_tirx.ir.transform.module_pass(pass_func=None, opt_level=None, name=None)#

Decorate a module pass.

This function returns a callback when pass_func is provided. Otherwise, it serves a decorator function.

pass_func can also be a class type with a method transform_module. This function will create a decorated ModulePass using transform_module as the pass function.

Parameters:
  • pass_func (Optional[Callable[(Module, PassContext) ->Module]]) – The transformation function or class.

  • opt_level (int) – The optimization level of this module pass.

  • name (Optional[str]) – The name of the module pass. The name could be empty. In this case, the name of the optimization function will be used as the pass name.

Returns:

create_module_pass – A decorator will be returned if pass_func is not provided, otherwise return the decorated result. The returned decorator has two behaviors depending on the input: A new ModulePass will be returned when we decorate a pass function. A new ModulePass class will be returned when we decorate a class type.

Return type:

Union[Callable, ModulePass]

Examples

Decorate a class for a configurable pass, or a function for a fixed pass. Both forms below simplify a TIRx module.

import tvm_tirx as tvm
from tvm_tirx.script import ir as I, tirx as T

@I.ir_module
class Before:
    @T.function(private=True)
    def main(A: T.Tensor((4,), "int32")):
        for i in T.serial(4):
            A[i] = i // 4

@I.ir_module
class Expected:
    @T.function(private=True)
    def main(A: T.Tensor((4,), "int32")):
        for i in T.serial(4):
            A[i] = 0

@tvm.ir.transform.module_pass(opt_level=0)
class CustomPipeline:
    def __init__(self, enable_simplify=True):
        self.enable_simplify = enable_simplify

    def transform_module(self, mod, ctx):
        if self.enable_simplify:
            mod = tvm.tirx.transform.StmtSimplify()(mod)
        return mod

pipeline = CustomPipeline()
tvm.ir.assert_structural_equal(pipeline(Before), Expected)
tvm.ir.assert_structural_equal(CustomPipeline(False)(Before), Before)

@tvm.ir.transform.module_pass(opt_level=0)
def simplify(mod, ctx):
    return tvm.tirx.transform.StmtSimplify()(mod)

tvm.ir.assert_structural_equal(simplify(Before), Expected)
tvm_tirx.ir.transform.pass_instrument(pi_cls=None)#

Decorate a class as a pass instrument.

The class does not need to inherit from PassInstrument. It defines any of enter_pass_ctx, exit_pass_ctx, should_run, run_before_pass, and run_after_pass, with the signatures documented on PassInstrument; the decorator returns a PassInstrument subclass that calls them.

Parameters:

pi_cls (class) – Instrument class. See example below.

Returns:

result – The instrument class, or a decorator when pi_cls is omitted.

Return type:

type or Callable

Examples

Skip a pass by name. should_run returns False for the pass to skip:

from tvm_tirx import tirx
from tvm_tirx.ir.transform import PassContext, pass_instrument

@pass_instrument
class SkipPass:
    def __init__(self, skipped_name):
        self.skipped_name = skipped_name

    def should_run(self, mod, info):
        return info.name != self.skipped_name


with PassContext(instruments=[SkipPass("tirx.StmtSimplify")]):
    after = tirx.transform.StmtSimplify()(mod)  # returns mod unchanged