Understanding Kirin IR Declarations

In this section, we will learn about the terminology used in Kirin IR. This will help you understand the structure of the IR and how to write your own compiler using Kirin.

Dialect

The Dialect object is the main registry of all the statements and attributes that are available in the IR. You can create a dialect by just following:

from kirin import ir
dialect = ir.Dialect("my_dialect") # (1)!

1. The Dialect object is created with the name my_dialect.

Dialect Groups

A dialect group is a collection of dialects that can be used as a decorator for Python frontend. It is used to group multiple dialects together and define the passes, compiler options, and other configurations for the dialects.

from kirin.ir import Method, dialect_group

@dialect_group(
    [
        base,
        binop,
        cmp,
        unary,
        assign,
        attr,
        boolop,
        constant,
        indexing,
        func,
    ]
) # (1)!
def python_basic(self): # (2)!
    def run_pass(mt: Method) -> None: # (3)!
        pass # (4)!
    return run_pass

1. The dialect_group decorator is used to create a dialect group with the specified dialects. In this case, we construct a basic Python dialect that allows some basic operations.
2. The python_basic function is the entry point of the dialect group. It takes a self argument, which is the DialectGroup object. This argument is used to access the definition of the dialect group and optionally update the dialect group.
3. The run_pass function is the function that will be called when the dialect group is applied to a given Python function. This is where you can define the passes that will be applied to the method. See the next example.

The above dialect group python_basic allows you to use it as following:

@python_basic
def my_function():
    pass

However, if we want to run some compilation passes on the function, we need to define some passes in the run_pass function.

from kirin.passes.fold import Fold

@dialect_group(python_basic) # (1)!
def python(self):
    fold_pass = Fold(self) # (2)!

    def run_pass(mt: Method, *, verify: bool = True, fold: bool = True) -> None: # (3)!
        if verify: # (4)!
            mt.verify()

        if fold: # (5)!
            fold_pass(mt)
    return run_pass

1. The dialect_group decorator can also take a dialect group as an argument. This will use the dialects defined in the given dialect group with different passes.
2. The Fold pass is created when initializing the dialect group. This pass is used later when running the run_pass function.
3. The run_pass function is the function that will be called when the dialect group is applied to a given Python function. This function takes a mt argument, which is the ir.Method object, and optional arguments verify, fold, and aggressive.
4. If the verify argument is True, the method will be verified.
5. If the fold argument is True, the Fold pass will be applied to the method.

The above dialect group python allows you to use it as following:

@python(fold=True) # (1)!
def my_function():
    pass

1. The fold argument here is passed to the run_pass function defined in the dialect group. Looks complicated? Don't worry, the @dialect_group decorator will handle everything including the type hints!

Statement

In Kirin IR, a statement describes an operation that can be executed. Statements are the building blocks that contain the semantics of the program.

Defining a Statement

While a statement can be hand-written by inheriting ir.Statement, we provide a python-dataclass-like decorator statement and in combine with the info.argument,info.result,info.region, info.block field specifier to make it easier to define a statement.

from kirin import ir
from kirin.decl import statement, info

@statement # (1)!
class MyStatement(ir.Statement): # (2)!
    name = "awesome" # (3)!
    traits = frozenset({ir.Pure()}) # (4)!
    # blabla, we will talk about this later

Like a function, a statement can have multiple inputs and outputs.

@statement # (1)!
class Add(ir.Statement):
    traits = frozenset({ir.Pure()}) # (2)!
    lhs: ir.SSAValue = info.argument(ir.types.Int) # (3)!
    rhs: ir.SSAValue = info.argument(ir.types.Int) # (4)!
    output: ir.ResultValue = info.result(ir.types.Int) # (5)!

A statement can have blocks as successors, which describe the control flow of the program.

@statement
class Branch(Statement):
   name = "br"
   traits = frozenset({IsTerminator()}) # (1)!

   arguments: tuple[SSAValue, ...] # (2)!
   successor: Block = info.block() # (3)!

It can also have a region that contains other statements, for example, a function statement

@statement
class Function(ir.Statement):
   name = "func"
   traits = frozenset({SSACFGRegion()}) # (1)!
   sym_name: str = info.attribute(property=True) # (2)!
   body: Region = info.region(multi=True) # (3)!

Constructing a Statement

Statements can be constructed in similar ways to constructing a normal Python dataclass. Taking the previous definitions as an example:

from kirin.dialects.py.constant import Constant

lhs, rhs = Constant(1), Constant(2) # (1)!
add = Add(lhs.result, rhs=rhs.result) # (2)!

1. Two [Constant][kirin.dialect.py.constant.Constant] statements are created with the value 1 and 2.
2. An Add statement is created with the lhs and rhs fields set to the results of the lhs and rhs statements. Like @dataclass unless specified by kw_only=True, the fields are positional.

Block

A block is a sequence of statements that are executed in order. Optionally, a block can have arguments that are passed from the predecessor block and terminates with a terminator statement. Unlike ir.Statement, the ir.Block class is final and cannot be extended.

Constructing a Block

Block takes a Sequence of statements as an argument, e.g a list of statements.

from kirin import ir
ir.Block() # Block(_args=())
ir.Block([stmt_a, stmt_b])

continue the example from Constructing a Statement, we can construct a block like following:

block = ir.Block()
arg_x = block.args.append_from(ir.types.Any)
arg_y = block.args.append_from(ir.types.Any)
block.stmts.append(Add(arg_x, arg_y))

^0(%0, %1):
    %2 = add(lhs=%0, rhs=%1) : !py.int

Region

A region is a sequence of blocks that are connected by control flow. A region can contain multiple blocks and can be nested within another region via statements that contain a region field. Unlike ir.Statement, the ir.Region class is final and cannot be extended.

Constructing a Region

Continuing the example from Constructing a Block, we can construct a region like following:

region = ir.Region([block])

pretty printing the region will give you

{
  ^0(%1, %2):
  │ %0 = add(lhs=%1, rhs=%2) : !py.int
}

SSA Value

An SSA value is a value that is assigned only once in the program. In Kirin IR, an SSA value is represented by the ir.SSAValue class. Most of the time, one does not need to construct the SSA value directly, as it is automatically created when constructing a statement.

There are 3 types of SSA values:

• ir.SSAValue: the base class of SSA values.
• ir.ResultValue: SSA values that are the result of a statement, this object allows you to access the parent statement via result.owner property.
• ir.BlockArgument: SSA values that are the arguments of a block.