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 definingtransform_module. Callafter = pass_object(before)to execute the callback under the current PassContext. Its callback, rather than this wrapper class, defines how the IR changes; seemodule_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(), ortvm_tirx.tirx.transform.function_pass(), then callafter = pass_object(before): a pass takes an IRModule and returns the transformed IRModule. The call runs under the currentPassContext, whose instruments observe it. A direct call always runs the pass; the optimization level and therequired_pass/disabled_passoptions apply when aSequentialruns it. Theinfoproperty 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
PassContextas awithblock. Every pass that runs inside the block, called directly or by aSequential, sees this context asPassContext.current()and receives it as thectxargument of its callback. Outside anywithblock, a default context withopt_level=2and no other options is active.- Parameters:
opt_level (Optional[int]) – Maximum optimization level enabled in sequential pipelines (default 2). A
Sequentialskips a child pass whoseinfo.opt_levelis 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_ctxcallbacks are called. Then switching to new instruments and calling newenter_pass_ctxcallbacks.- instrumentsSequence[PassInstrument]
The list of pass instrument implementations.
- static current()#
Return the current pass context.
- class tvm_tirx.ir.transform.PassInfo(opt_level, name)#
Metadata of a pass: its name and optimization level.
Every pass carries a
PassInfo, available asPass.info.PassContextuses the name inrequired_passanddisabled_pass, andSequentialcompares the optimization level with the context’sopt_level. Pass instruments receive thePassInfoof each pass they observe.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 withPassContext(instruments=[...]); it then sees every pass that runs while the context is active, whether the pass is called directly or by aSequential.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:
mod (tvm_tirx.ir.module.IRModule) – The module on which an optimization pass is being run.
info (tvm_tirx.ir.transform.PassInfo) – The pass information.
- Returns:
should_run – True to run the pass, or False to skip the pass.
- Return type:
- 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:
mod (tvm_tirx.ir.module.IRModule) – The module on which an optimization pass is being run.
info (tvm_tirx.ir.transform.PassInfo) – The pass information.
- 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:
mod (tvm_tirx.ir.module.IRModule) – The module on which an optimization pass is being run.
info (tvm_tirx.ir.transform.PassInfo) – The pass information.
- 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:
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_levelis at most the context’sopt_levelor its name is inrequired_pass, and never when its name is indisabled_pass. ASequentialis itself a pass, so it can be nested in anotherSequential.- 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 ofenter_pass_ctx,exit_pass_ctx,should_run,run_before_pass, andrun_after_pass, with the signatures documented onPassInstrument; the decorator returns aPassInstrumentsubclass that calls them.- Parameters:
pi_cls (class) – Instrument class. See example below.
- Returns:
result – The instrument class, or a decorator when
pi_clsis omitted.- Return type:
type or Callable
Examples
Skip a pass by name.
should_runreturnsFalsefor 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