A builder to build Relax binding blocks. More...

#include <block_builder.h>

Inheritance diagram for tvm::relax::BlockBuilderNode:

Collaboration diagram for tvm::relax::BlockBuilderNode:

Public Member Functions
virtual NameSupply	name_supply ()=0
	Get the name supply for generating unique names. More...

virtual IRModule	GetContextIRModule () const =0
	Get the context IRModule in this builder. More...

virtual IRModule	Finalize ()=0
	Finalize the building process and return the result IRModule. Possibly rename GlobalVars in the IRModule to ensure name uniqueness and the invariant: every public function has the same name as its "global_symbol" attribute. More...

virtual GlobalVar	AddFunction (const BaseFunc &func, ffi::String func_name_hint)=0
	Add a Relax function or a TIR PrimFunc to internal context module. More...

virtual void	UpdateFunction (const GlobalVar &gv, BaseFunc function)=0
	Update a Relax function or a TIR PrimFunc in the internal context module. More...

virtual void	ReportFatal (const Diagnostic &diagnostic)=0
	Report an error during transformation construction. More...

virtual ffi::Optional< Expr >	LookupBinding (const Var &var)=0
	Lookup the binding value that var binds to in the current emitted sequences. More...

virtual void	BeginScope (ffi::Optional< ffi::Array< Var >> params)=0
	Begin a new scope, with optional parameters that are visible within the scope. More...

virtual void	BeginInnerScope ()=0
	Begin a new scope, which inherits visible parameters from its parent scope. More...

virtual void	AddDefinitionToScope (Var var)=0
	Append a definition to the current scope. More...

virtual void	EndScope ()=0
	End the previously defined scope. More...

virtual void	BeginDataflowBlock ()=0
	Begin to build a DataflowBlock. More...

virtual void	BeginBindingBlock ()=0
	Begin to build a BindingBlock. More...

virtual BindingBlock	EndBlock ()=0
	End building a BindingBlock. More...

virtual bool	CurrentBlockIsDataFlow ()=0
	Check if the block being built is DataflowBlock or not. More...

virtual Var	Emit (Expr expr, ffi::String name_hint="")=0
	Emits an Expr, and returns the variable it is bound to. More...

virtual Var	EmitMatchCast (Expr value, StructInfo struct_info, ffi::String name_hint="")=0
	Emit a MatchCast. More...

virtual Var	EmitOutput (Expr output, ffi::String name_hint="")=0
	Generate an output for the current dataflow block. More...

virtual void	EmitNormalized (Binding normalized_binding)=0
	Emit a binding that is already normalized. More...

virtual Expr	Normalize (const Expr &expr)=0
	Convert an expression to normal form, and try to eagerly infer types and shapes. More...

virtual Expr	NormalizeArgument (const Expr &expr)=0
	Normalize argument to a call or another IRNode. More...

virtual arith::Analyzer *	GetAnalyzer ()=0
	Get the analyzer of the BlockBuilder. More...

	TVM_FFI_DECLARE_OBJECT_INFO ("relax.BlockBuilder", BlockBuilderNode, Object)

Static Public Attributes
static constexpr const bool	_type_mutable = true

Detailed Description

A builder to build Relax binding blocks.

BlockBuilder provides the following three categories of main functionalities for IR building and transformations:

Global context management: manages the IRModule, allowing query, update the surrounding global context. Provide context tools for analysis.
Scope management:
- Manages block scopes for bulding nested blocks.
- Emit bindings to the current scope.
- Construct blocks by calling EndScope.
Normalization: Take an Expr, normalize it to deduce shape/type, turn things into normal forms.

Importantly, these three categories of features can be dependent on each other. For example, when we emit into scope we will call normalize to ensure the code is in normal form. Similarly, when we normalize we could choose to emit into the current context.

We would encourage the developers to keep these three category in mind when using and developing BlockBuilder, we can group the code in a logically clean way.

BlockBuilderNode is implemented as a virtual interface to allow logically grouped implementation and internal data structures that are hidden from the users.

Member Function Documentation

◆ AddDefinitionToScope()

virtual void tvm::relax::BlockBuilderNode::AddDefinitionToScope ( Var var )

pure virtual

Append a definition to the current scope.

Parameters

var	A variable within the current scope.

Note: This function should be called when a new variable is defined that may impact struct inference (e.g. MatchCast) to properly track the variable availability and help the best effort deduction.

See also: EndScope

◆ AddFunction()

virtual GlobalVar tvm::relax::BlockBuilderNode::AddFunction	(	const BaseFunc &	func,
		ffi::String	func_name_hint
	)

pure virtual

Add a Relax function or a TIR PrimFunc to internal context module.

Parameters

func	The function to be added.
func_name_hint	The name hint of the function to be added.

Note: If the function to be added already exists, return its GlobalVar directly.

Returns: The global var bound to the added function.

◆ BeginBindingBlock()

virtual void tvm::relax::BlockBuilderNode::BeginBindingBlock ( )

pure virtual

Begin to build a BindingBlock.

◆ BeginDataflowBlock()

virtual void tvm::relax::BlockBuilderNode::BeginDataflowBlock ( )

pure virtual

Begin to build a DataflowBlock.

◆ BeginInnerScope()

virtual void tvm::relax::BlockBuilderNode::BeginInnerScope ( )

pure virtual

Begin a new scope, which inherits visible parameters from its parent scope.

Symbolic variables from the parent scope are available.

Note: This function should be called when an inner scope is introduced (e.g. conditional branches) to properly track the variable availability and help the best effort deduction.

See also: EndScope

◆ BeginScope()

virtual void tvm::relax::BlockBuilderNode::BeginScope ( ffi::Optional< ffi::Array< Var >> params )

pure virtual

Begin a new scope, with optional parameters that are visible within the scope.

Symbolic variables from the parent scope are not available.

Parameters

params Parameters that are visible within the scope.

Note: This function should be called when new scope is introduced (e.g. function bodies) to properly track the variable availability and help the best effort deduction.

See also: EndScope

◆ CurrentBlockIsDataFlow()

virtual bool tvm::relax::BlockBuilderNode::CurrentBlockIsDataFlow ( )

pure virtual

Check if the block being built is DataflowBlock or not.

Returns: A boolean that indicates if the block being built is DataflowBlock or not.

◆ Emit()

virtual Var tvm::relax::BlockBuilderNode::Emit	(	Expr	expr,
		ffi::String	name_hint = `""`
	)

pure virtual

Emits an Expr, and returns the variable it is bound to.

Parameters

expr	The Expr to be emitted.
name_hint	Name hint for the bound variable.

Returns: The new variable that expr is bound to.

Note: This Emit function normalizes the expr, and performs shape and type deductions by calling Normalize.

◆ EmitMatchCast()

virtual Var tvm::relax::BlockBuilderNode::EmitMatchCast	(	Expr	value,
		StructInfo	struct_info,
		ffi::String	name_hint = `""`
	)

pure virtual

Emit a MatchCast.

Parameters

value	The input value.
struct_info	The struct info to be matched.
name_hint	Name hint for the bound variable.

Returns: The variable bound to the MatchCast.

◆ EmitNormalized()

virtual void tvm::relax::BlockBuilderNode::EmitNormalized ( Binding normalized_binding )

pure virtual

Emit a binding that is already normalized.

Parameters

normalized_binding A binding whose value is already normalized.

Note: This function requires binding to be pre-normalized.

◆ EmitOutput()

virtual Var tvm::relax::BlockBuilderNode::EmitOutput	(	Expr	output,
		ffi::String	name_hint = `""`
	)

pure virtual

Generate an output for the current dataflow block.

Parameters

output	The output variable of the block.
name_hint	Name hint for the bound variable.

Returns: The variable bound to output.

◆ EndBlock()

virtual BindingBlock tvm::relax::BlockBuilderNode::EndBlock ( )

pure virtual

End building a BindingBlock.

Returns: The BindingBlock being built.

◆ EndScope()

virtual void tvm::relax::BlockBuilderNode::EndScope ( )

pure virtual

End the previously defined scope.

◆ Finalize()

virtual IRModule tvm::relax::BlockBuilderNode::Finalize ( )

pure virtual

Finalize the building process and return the result IRModule. Possibly rename GlobalVars in the IRModule to ensure name uniqueness and the invariant: every public function has the same name as its "global_symbol" attribute.

Note: this method should be called only once at the end of the building process, since it may invalidate global vars previously returned by this builder. See also transform::NormalizeGlobalVar.

Returns: The result IRModule.

◆ GetAnalyzer()

virtual arith::Analyzer* tvm::relax::BlockBuilderNode::GetAnalyzer ( )

pure virtual

Get the analyzer of the BlockBuilder.

Returns: The BlockBuilder's arithmetic analyzer.

◆ GetContextIRModule()

virtual IRModule tvm::relax::BlockBuilderNode::GetContextIRModule ( ) const

pure virtual

Get the context IRModule in this builder.

Note: The context

Returns: The IRModule in this BlockBuilder.

◆ LookupBinding()

virtual ffi::Optional<Expr> tvm::relax::BlockBuilderNode::LookupBinding ( const Var & var )

pure virtual

Lookup the binding value that var binds to in the current emitted sequences.

Parameters

var	The input var.

Returns: The Expr bound to the input var.

Note: For function parameters, this function returns std::nullopt.

◆ name_supply()

virtual NameSupply tvm::relax::BlockBuilderNode::name_supply ( )

pure virtual

Get the name supply for generating unique names.

Returns: The name supply.

◆ Normalize()

virtual Expr tvm::relax::BlockBuilderNode::Normalize ( const Expr & expr )

pure virtual

Convert an expression to normal form, and try to eagerly infer types and shapes.

Parameters

expr	The input expression.

Returns: The normalized expression.

Note: Invariant: If any of the sub expr have struct_info field. they must have already been normalized.

◆ NormalizeArgument()

virtual Expr tvm::relax::BlockBuilderNode::NormalizeArgument ( const Expr & expr )

pure virtual

Normalize argument to a call or another IRNode.

Parameters

expr	The input expression.

Returns: The normalized expression.

Note: This function will create a binding var for non-leaf expressions such as Call.

◆ ReportFatal()

virtual void tvm::relax::BlockBuilderNode::ReportFatal ( const Diagnostic & diagnostic )

pure virtual

Report an error during transformation construction.

Parameters

diagnostic The diagnostic information.

◆ TVM_FFI_DECLARE_OBJECT_INFO()

tvm::relax::BlockBuilderNode::TVM_FFI_DECLARE_OBJECT_INFO	(	"relax.BlockBuilder"	,
		BlockBuilderNode	,
		Object
	)

◆ UpdateFunction()

virtual void tvm::relax::BlockBuilderNode::UpdateFunction	(	const GlobalVar &	gv,
		BaseFunc	function
	)

pure virtual

Update a Relax function or a TIR PrimFunc in the internal context module.

Parameters

gv	The global var referring the function to be updated.
function	The updated function.

Member Data Documentation

◆ _type_mutable

constexpr const bool tvm::relax::BlockBuilderNode::_type_mutable = true

staticconstexpr

The documentation for this class was generated from the following file:

include/tvm/relax/block_builder.h

Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ AddDefinitionToScope()

◆ AddFunction()

◆ BeginBindingBlock()

◆ BeginDataflowBlock()

◆ BeginInnerScope()

◆ BeginScope()

◆ CurrentBlockIsDataFlow()

◆ Emit()

◆ EmitMatchCast()

◆ EmitNormalized()

◆ EmitOutput()

◆ EndBlock()

◆ EndScope()

◆ Finalize()

◆ GetAnalyzer()

◆ GetContextIRModule()

◆ LookupBinding()

◆ name_supply()

◆ Normalize()

◆ NormalizeArgument()

◆ ReportFatal()

◆ TVM_FFI_DECLARE_OBJECT_INFO()

◆ UpdateFunction()

Member Data Documentation

◆ _type_mutable