This is an automated email from the ASF dual-hosted git repository.
tqchen pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tvm-tirx.git
The following commit(s) were added to refs/heads/main by this push:
new ace4cc05c [DOCS] Restructure Statements and complete Types and
Expressions (#135)
ace4cc05c is described below
commit ace4cc05ce3860ea7291ab56f27242e91719d7ff
Author: Tianqi Chen <[email protected]>
AuthorDate: Fri Oct 30 21:02:03 2026 -0400
[DOCS] Restructure Statements and complete Types and Expressions (#135)
This PR restructures `docs/ir/statements.rst` in the same style as #134,
and completes `docs/ir/types_and_expressions.rst`.
**Statements**
- Opens with what the guide introduces and the add-one statement tree,
followed by a table of all statement classes.
- Sections: Sequences, Bindings, and Stores (including `Evaluate`);
Loops; Branches; Loop Exits; Assertions and Returns (how `message_parts`
keep error messages compact); Regions, the main place for extensions,
with a note linking Operators and Calls, Region Syntax, and the
extension tutorial.
**Types and Expressions**
- Expressions now starts with a table of expression classes, and
Primitive Expressions starts with its node table. The table now has a
TVMScript syntax column that includes `==`, `!=`, `and`, `or`, and
`not`.
- The Call section covers `ty_args`, `attrs`, and function calls through
a `GlobalVar`.
- What to Read Next is replaced by notes linking Operators and Calls and
the extension tutorial.
Examples are TVMScript functions inspected with `format_tree`. All
snippets run on `apache-tvm-tirx` 0.1.0a6, and every printed output
matches the page: 9 in Statements and 14 in Types and Expressions.
---
docs/ir/statements.rst | 594 +++++++++++++++++---------------------
docs/ir/types_and_expressions.rst | 195 ++++++++++---
2 files changed, 411 insertions(+), 378 deletions(-)
diff --git a/docs/ir/statements.rst b/docs/ir/statements.rst
index 79138421f..45d283867 100644
--- a/docs/ir/statements.rst
+++ b/docs/ir/statements.rst
@@ -20,154 +20,128 @@
Statements
==========
-In this chapter, we will introduce statements, which describe the actions
-a function performs and their execution order. A statement can bind an
-intermediate value to a variable, write a result to a tensor, or control
-execution through a branch or loop. These statements form the function's
-body, which compiler passes can inspect and rewrite through the IR
-interfaces.
+This guide introduces **statements**, the IR nodes that describe
+actions: binding a value to a variable, writing to a tensor, repeating
+work in a loop, or choosing between branches. TIRx provides a generic
+set of statements that appear in most high-level kernel programs.
+Statements run in order, and they contain expressions: a loop holds
+its bounds, and a store holds the value it writes.
-We will start with this CPU function, which adds one to every element
-of ``A`` and writes the results to ``B``:
+A function's ``body`` is a tree of statements. This add-one function
+loops over its input and writes each result to ``B``:
-.. literalinclude:: ../../examples/quick_start/add_one_cpu.py
- :language: python
- :start-at: from tvm_tirx.script import tirx as T
- :end-at: B[i] = A[i] + 1
+.. code-block:: python
+
+ from tvm_tirx import ir
+ from tvm_tirx.script import tirx as T
+
+ n = T.dynamic("n")
+
+ @T.function
+ def add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+ for i in range(n):
+ B[i] = A[i] + 1
+
+ print(ir.format_tree(add_one.body))
-.. _statements-and-sequences:
+The output is:
-Statement Classes
------------------
+.. code-block:: text
-``ir.Stmt`` is the base class for all statements, from bindings and tensor
-writes to sequences, branches, and loops:
+ SeqStmt
+ └── seq[0]: For(begin=IntImm(value=0), end=n)
+ ├── var: i = Var(ty=int32)
+ └── body: SeqStmt
+ └── seq[0]: TensorStore(dest=B, indices=[i])
+ └── value: Add
+ ├── a: TensorLoad(source=A, indices=[i])
+ └── b: FloatImm(value=1.0)
+
+The body is a sequence holding one ``For`` loop. The loop's body is
+another sequence holding one ``TensorStore``, which writes the
+expression ``A[i] + 1`` to ``B[i]``.
+
+``ir.Stmt`` is the base class of all statements. The following table
+lists the statement classes, and the sections below introduce them in
+turn, ending with regions, the main place for extensions:
.. list-table::
:header-rows: 1
- :widths: 25 35 40
+ :widths: 22 38 40
* - Class
- Represents
- Fields
+ * - ``ir.SeqStmt``
+ - Statements that run in order
+ - ``seq``
* - ``ir.Bind``
- A variable definition
- ``var``, ``value``
* - ``ir.TensorStore``
- - A tensor element write; the destination type must support stores
+ - A write to a tensor element
- ``dest``, ``indices``, ``value``
* - ``ir.Evaluate``
- - Expression evaluation with its result discarded
+ - An expression run for its effect
- ``value``
+ * - ``ir.For``
+ - A loop over an integer range
+ - ``var``, ``begin``, ``end``, ``step``, ``kind``, ``body``,
+ ``annotations``
+ * - ``ir.While``
+ - A loop that runs while a condition holds
+ - ``condition``, ``body``
+ * - ``ir.If``
+ - A choice between two sequences
+ - ``condition``, ``then_case``, ``else_case``
+ * - ``ir.Continue``
+ - Skip to the next iteration of the innermost loop
+ - None
+ * - ``ir.Break``
+ - Leave the innermost loop
+ - None
* - ``ir.AssertStmt``
- - A program assertion
+ - A run-time check that raises an error
- ``condition``, ``error_kind``, ``message_parts``
* - ``ir.Return``
- A function return
- ``value``
- * - ``ir.Break``
- - Exit the current loop
- - None
- * - ``ir.Continue``
- - Start the next loop iteration
- - None
- * - ``ir.SeqStmt``
- - A sequence of statements in execution order
- - ``seq``
- * - ``ir.If``
- - Select a branch
- - ``condition``, ``then_case``, ``else_case``
- * - ``ir.For``
- - Repeat a body over an integer range
- - ``var``, ``begin``, ``end``, ``step``, ``kind``, ``body``,
``annotations``
- * - ``ir.While``
- - Repeat while a condition is true
- - ``condition``, ``body``
* - ``ir.RegionStmt``
- An operator-defined statement with a nested body
- - ``op``, ``args``, ``attrs``, ``body_params``, ``body``, ``result_vars``
-
-Statement Sequences
--------------------
-
-A function body often contains several statements that run one after
-another. ``ir.SeqStmt`` stores these statements in execution order in
-its ``seq`` field. The statements inside a loop or branch are also
-stored in a ``SeqStmt``.
+ - ``op``, ``args``, ``attrs``, ``body_params``, ``body``,
+ ``result_vars``
-The loop in ``add_one`` writes one output element in each iteration:
+Sequences, Bindings, and Stores
+-------------------------------
-.. literalinclude:: ../../examples/quick_start/add_one_cpu.py
- :language: python
- :start-at: for i in range(n):
- :end-at: B[i] = A[i] + 1
- :dedent: 4
+``ir.SeqStmt`` holds statements that run one after another, in its
+``seq`` field. A function body, a loop body, and each branch of an
+``if`` are all sequences.
-The indented assignment ``B[i] = A[i] + 1`` becomes an
-``ir.TensorStore`` statement describing a write to a tensor element.
-The loop body is a ``SeqStmt`` containing this statement. We can retrieve
-it from the parsed function and print its structure:
+``ir.Bind`` defines a variable: its ``var`` field holds the new
+variable, and its ``value`` field holds the expression that computes
+it. ``ir.TensorStore`` writes ``value`` to the element of ``dest``
+selected by ``indices``. In this add-one loop, the sum is bound to a
+name before it is written:
.. code-block:: python
from tvm_tirx import ir
+ from tvm_tirx.script import tirx as T
- parsed_loop = add_one.body.seq[0] # The for statement.
- body = parsed_loop.body
- print(ir.format_tree(body))
-
-The output is:
-
-.. code-block:: text
-
- SeqStmt
- └── seq[0]: TensorStore(dest=B, indices=[i])
- └── value: Add
- ├── a: TensorLoad(source=A, indices=[i])
- └── b: FloatImm(value=1.0)
-
-When the compiled function runs, the store computes ``A[i] + 1`` and
-writes the result to element ``i`` of ``B``. We can retrieve this
-statement with ``body[0]``, which is shorthand for ``body.seq[0]``.
-
-We can also construct this body directly through the IR API:
-
-.. code-block:: python
-
- A, B = add_one.params
- n = A.ty.shape[0]
- i = ir.Var("i", "int32")
- store = ir.TensorStore(B, [i], A[i] + 1)
- body = ir.SeqStmt([store])
-
-``ir.TensorStore`` takes the destination tensor ``B``, the index list
-``[i]``, and the value expression ``A[i] + 1``. These arguments populate
-its ``dest``, ``indices``, and ``value`` fields. ``ir.SeqStmt([store])``
-puts the store in a sequence with the structure shown above.
-
-A small extension of the CPU loop names the addition's result before
-writing it to the output:
-
-.. code-block:: python
+ n = T.dynamic("n")
@T.function
- def add_one_bound(A: T.Tensor((n,), T.float32), B: T.Tensor((n,),
T.float32)):
+ def add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
for i in range(n):
value = A[i] + 1
B[i] = value
-The assignment to ``value`` becomes an ``ir.Bind`` statement: its
-``var`` field holds the variable, and its ``value`` field holds the
-addition expression. The following ``TensorStore`` uses that variable
-as the value to write. We can inspect the sequence in the loop body:
-
-.. code-block:: python
-
- bound_loop = add_one_bound.body.seq[0]
- bound_body = bound_loop.body
- print(ir.format_tree(bound_body))
+ loop = add_one.body[0]
+ print(ir.format_tree(loop.body))
-The output is:
+``add_one.body[0]`` is shorthand for ``add_one.body.seq[0]``, the first
+statement in the sequence. The output is:
.. code-block:: text
@@ -180,61 +154,59 @@ The output is:
└── seq[1]: TensorStore(dest=B, indices=[i])
└── value: value
-This prints the body parsed from ``add_one_bound``. The first statement
-binds the addition to ``value``, and the second uses that same variable
-as the value to store. When the function runs, the binding computes the
-addition before the store writes it to ``B[i]``.
+The ``Bind`` defines ``value``, and the ``TensorStore`` that follows it
+uses it. A variable defined by a statement in a sequence is visible to
+the statements after it in the same sequence, including any nested
+inside them, but not outside that sequence. Each variable is defined
+only once in a function.
-The IR API can also construct a sequence with a binding followed by a
-store:
+``ir.Evaluate`` runs an expression and discards its result. Its most
+common use is to hold a ``Call`` made only for its effect.
+``T.cuda.cta_sync()`` is such a call: it makes each thread in a GPU
+block wait until all threads in the block reach it:
.. code-block:: python
- value = ir.Var("value", "float32")
- binding = ir.Bind(value, A[i] + 1)
- store_from_value = ir.TensorStore(B, [i], value)
- sequence = ir.SeqStmt([binding, store_from_value])
-
-The next section places the original single-store ``body`` inside the
-CPU loop.
+ @T.function
+ def sync_block(A: T.Tensor((128,), T.float32)):
+ T.device_entry(launch=T.cuda.LaunchConfig(grid=1, block=128))
+ T.cuda.cta_sync()
-.. _control-flow-and-scope:
+ region = sync_block.body[0]
+ print(ir.format_tree(region.body[0], hide=["attrs", "ty_args"]))
-Control Flow
-------------
+The output is:
-Control-flow statements determine which parts of a program execute and
-how often. A loop repeats a body of statements, while a branch selects
-which body runs.
+.. code-block:: text
-For loops
-~~~~~~~~~
+ Evaluate
+ └── value: Call(op=tirx.cuda.cta_sync)
+ └── args: []
-``add_one`` visits every element with a loop:
+The barrier produces no value; ``Evaluate`` turns the call into a
+statement.
-.. literalinclude:: ../../examples/quick_start/add_one_cpu.py
- :language: python
- :start-at: for i in range(n):
- :end-at: B[i] = A[i] + 1
- :dedent: 4
+Loops
+-----
-The loop becomes an ``ir.For``. Its ``var`` field identifies the loop
-variable ``i``, and its ``body`` field holds the ``SeqStmt`` containing
-the tensor store. We can construct this loop using ``i`` and ``body``
-from the previous section:
+``ir.For`` repeats its ``body`` once for each value of its loop
+variable ``var``, from ``begin`` up to but not including ``end``, in
+steps of ``step``. The loop defines ``var``, which is visible only
+inside ``body``:
.. code-block:: python
- loop = ir.For(i, 0, n, 1, ir.ForKind.DEFAULT, body)
+ from tvm_tirx import ir
+ from tvm_tirx.script import tirx as T
-The arguments ``0``, ``n``, and ``1`` set the ``begin``, ``end``, and
-``step`` fields. ``ForKind.DEFAULT`` selects execution in iteration
-order. On each iteration, the loop executes the statements in ``body``:
+ n = T.dynamic("n")
-.. code-block:: python
+ @T.function
+ def add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+ for i in range(n):
+ B[i] = A[i] + 1
- parsed_loop = add_one.body.seq[0] # The for statement in the CPU
function.
- print(ir.format_tree(parsed_loop))
+ print(ir.format_tree(add_one.body[0]))
The output is:
@@ -248,25 +220,53 @@ The output is:
├── a: TensorLoad(source=A, indices=[i])
└── b: FloatImm(value=1.0)
-The default view puts ``begin`` and ``end`` on the loop's first line;
-its unit step and sequential kind are omitted because they match the
-defaults. The end bound is exclusive, so ``i`` runs from 0 through ``n - 1``.
-Each iteration executes the store in ``body`` with that value of ``i``.
-The loop defines ``i`` for use inside ``For.body``, which is its scope.
-The ``For`` establishes this scope, and its ``SeqStmt`` body records
-the order of the statements within it. The
-:class:`~tvm_tirx.ir.ForKind` API reference describes the other execution
-kinds.
+The tree omits ``step`` and ``kind`` because they have their default
+values: a step of one, and iterations that run in order. Other values
+of ``kind`` (``ir.ForKind``) ask for the iterations to be run in
+parallel, vectorized, or unrolled.
+
+``ir.While`` repeats its ``body`` as long as its ``condition`` is
+true. The condition is checked before each iteration. This loop halves
+a value until it is at most one:
+
+.. code-block:: python
+
+ @T.function
+ def halve_until_small(X: T.Tensor((1,), T.float32)):
+ while X[0] > 1.0:
+ X[0] = X[0] * 0.5
+
+ print(ir.format_tree(halve_until_small.body[0]))
+
+The output is:
+
+.. code-block:: text
+
+ While
+ ├── condition: GT
+ │ ├── a: TensorLoad(source=X, indices=[IntImm(value=0)])
+ │ └── b: FloatImm(value=1.0)
+ └── body: SeqStmt
+ └── seq[0]: TensorStore(dest=X, indices=[IntImm(value=0)])
+ └── value: Mul
+ ├── a: TensorLoad(source=X, indices=[IntImm(value=0)])
+ └── b: FloatImm(value=0.5)
Branches
-~~~~~~~~
+--------
-A branch can choose between two results. This CPU function applies
-ReLU: positive input values pass through, and all other values become
-zero:
+``ir.If`` runs ``then_case`` when its ``condition`` is true, and
+``else_case`` otherwise. Both cases are sequences, and ``else_case``
+is ``None`` when the branch has no ``else``. This loop applies ReLU,
+keeping positive values and replacing the rest with zero:
.. code-block:: python
+ from tvm_tirx import ir
+ from tvm_tirx.script import tirx as T
+
+ n = T.dynamic("n")
+
@T.function
def relu(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
for i in range(n):
@@ -275,17 +275,8 @@ zero:
else:
B[i] = 0.0
-TVMScript represents the branch as an ``ir.If``. Its ``condition`` is
-the boolean comparison ``A[i] > 0``. Its ``then_case`` and ``else_case``
-each hold a ``SeqStmt`` containing one store. Only the sequence selected
-by the condition runs for each element. We can retrieve the branch
-from the loop body:
-
-.. code-block:: python
-
- relu_loop = relu.body.seq[0]
- relu_branch = relu_loop.body.seq[0] # The if/else statement.
- print(ir.format_tree(relu_branch))
+ loop = relu.body[0]
+ print(ir.format_tree(loop.body[0]))
The output is:
@@ -302,146 +293,22 @@ The output is:
└── seq[0]: TensorStore(dest=B, indices=[i])
└── value: FloatImm(value=0.0)
-A bounds check uses the same kind of statement. A GPU version of add-one
-distributes the elements across threads, and each thread checks whether
-it has a valid element to process:
-
-.. code-block:: python
-
- @T.function
- def gpu_add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
- T.device_entry(launch=T.cuda.LaunchConfig(grid=T.ceildiv(n, 256),
block=256))
- i = T.cuda.block_idx("x") * 256 + T.cuda.thread_idx("x")
- if i < n:
- B[i] = A[i] + 1
-
-The ``if i < n`` becomes an ``ir.If``. Its ``condition`` field holds
-the comparison, an ``ir.prim.LT`` expression. Its ``then_case`` field
-holds a ``SeqStmt`` containing the tensor store:
-
-.. code-block:: python
-
- device_region = gpu_add_one.body.seq[0]
- branch = device_region.body.seq[1] # The if after the index definition.
- print(ir.format_tree(branch))
-
-The output is:
-
-.. code-block:: text
-
- If(else_case=None)
- ├── condition: LT
- │ ├── a: i
- │ └── b: n
- └── then_case: SeqStmt
- └── seq[0]: TensorStore(dest=B, indices=[i])
- └── value: Add
- ├── a: TensorLoad(source=A, indices=[i])
- └── b: FloatImm(value=1.0)
-
-The condition produces a boolean. When it is true, the thread executes
-the store in ``then_case``. An else branch has its own ``SeqStmt`` in
-``else_case``. This example has no else branch, so ``else_case`` is
-``None`` and threads whose indices are outside the tensor perform no
-tensor access. These branch bodies can also contain further loops and
-branches.
-
-The ``T.device_entry(...)`` line groups the statements that follow it in
-the same function body into a device region. An
-:class:`ir.RegionStmt <tvm_tirx.ir.RegionStmt>` represents this region in
-the IR. Its ``op`` identifies ``tirx.device_entry``, and its ``body`` is
-a ``SeqStmt`` containing the index definition followed by the branch:
-
-.. code-block:: python
-
- print(ir.format_tree(
- device_region,
- hide=["attrs", "args", "body_params", "result_vars", "value"],
- ))
-
-The output is:
-
-.. code-block:: text
-
- RegionStmt(op=tirx.device_entry)
- └── body: SeqStmt
- ├── seq[0]: Bind
- │ └── var: i = Var(ty=int32)
- └── seq[1]: If(else_case=None)
- ├── condition: LT
- │ ├── a: i
- │ └── b: n
- └── then_case: SeqStmt
- └── seq[0]: TensorStore(dest=B, indices=[i])
-
-This view hides launch settings and value expressions to focus on the
-statements inside ``body``. The ``Bind`` defines ``i`` before the ``If``
-uses it. The variable is available to the condition and tensor store
-within the region. The :ref:`Printing and Parsing <tvmscript-region-syntax>`
-chapter explains
-the grouping rule for this syntax and the equivalent ``with`` form.
-
-While loops
-~~~~~~~~~~~
+The condition is a boolean expression, here the comparison
+``A[i] > 0``. For each element, only one of the two stores runs.
-A ``while`` loop tests a condition before each iteration. We can express
-the same add-one computation with an index that advances until it reaches
-the tensor length:
+Loop Exits
+----------
-.. code-block:: python
-
- @T.function
- def add_one_while(A: T.Tensor((n,), T.float32), B: T.Tensor((n,),
T.float32)):
- i: T.int32 = 0
- while i < n:
- B[i] = A[i] + 1
- i += 1
-
-``i: T.int32 = 0`` creates a mutable scalar, so ``i += 1`` updates the
-index for the next test. The loop stops when ``i < n`` becomes false.
-Without that update, the loop would keep processing the same element.
-
-TVMScript represents the loop as an ``ir.While``. Its ``condition``
-holds the comparison, and its ``body`` contains both the output store
-and the index update:
+``ir.Continue`` skips to the next iteration of the innermost enclosing
+loop, and ``ir.Break`` leaves that loop. This loop records the index of
+the first positive element of ``A``:
.. code-block:: python
- while_loop = add_one_while.body.seq[2] # After i's allocation and
initialization.
- print(ir.format_tree(while_loop, hide=["indices"]))
-
-The output is:
-
-.. code-block:: text
-
- While
- ├── condition: LT
- │ ├── a: TensorLoad(source=i)
- │ └── b: n
- └── body: SeqStmt
- ├── seq[0]: TensorStore(dest=B)
- │ └── value: Add
- │ ├── a: TensorLoad(source=A)
- │ └── b: FloatImm(value=1.0)
- └── seq[1]: TensorStore(dest=i)
- └── value: Add
- ├── a: TensorLoad(source=i)
- └── b: IntImm(value=1)
-
-This view hides index lists to focus on the condition and the two stores.
-The mutable scalar uses a one-element local tensor in IR, so reads of
-``i`` appear as ``TensorLoad(source=i)``.
-The first store in the loop writes to ``B``; the second writes the new
-index to ``i``. The condition reads that index before the next iteration.
-
-Loop exits
-~~~~~~~~~~
-
-Some loops can finish before reaching their bound. This function finds
-the index of the first positive integer. It leaves ``B[0]`` at ``-1``
-if no such element exists:
+ from tvm_tirx import ir
+ from tvm_tirx.script import tirx as T
-.. code-block:: python
+ n = T.dynamic("n")
@T.function
def first_positive(A: T.Tensor((n,), T.int32), B: T.Tensor((1,), T.int32)):
@@ -452,17 +319,8 @@ if no such element exists:
B[0] = i
break
-``continue`` starts the next iteration when ``A[i]`` is nonpositive. If
-the element is positive, the store records its index and ``break`` ends
-the loop. These statements become
-``ir.Continue`` and ``ir.Break`` inside their enclosing loop; neither
-has operands or a nested body. We can inspect the loop after the initial
-store to ``B[0]``:
-
-.. code-block:: python
-
- search_loop = first_positive.body.seq[1] # The for loop after B[0] = -1.
- print(ir.format_tree(search_loop.body))
+ loop = first_positive.body[1]
+ print(ir.format_tree(loop.body))
The output is:
@@ -479,28 +337,28 @@ The output is:
│ └── value: i
└── seq[2]: Break()
-Assertions and returns
-~~~~~~~~~~~~~~~~~~~~~~
+``Continue`` and ``Break`` have no fields.
+
+Assertions and Returns
+----------------------
-A function can check a precondition before computing its result. This
-function adds one to the first input element and returns the value.
-The assertion ensures that the tensor has an element to read:
+``ir.AssertStmt`` checks a ``condition`` at run time and raises an
+error when it is false. ``ir.Return`` ends the function and gives its
+``value`` to the caller. This function checks that its input is not
+empty, then returns the first element plus one:
.. code-block:: python
+ from tvm_tirx import ir
+ from tvm_tirx.script import tirx as T
+
+ n = T.dynamic("n")
+
@T.function
def first_plus_one(A: T.Tensor((n,), T.float32)) -> T.float32:
assert n > 0, "the input must contain at least one element"
return A[0] + 1
-The ``assert`` becomes an ``ir.AssertStmt``. Its ``condition`` holds
-``n > 0``, its ``error_kind`` names ``RuntimeError``, and its
-``message_parts`` contains the error message. An empty input raises that
-error before the tensor read. Otherwise, execution reaches the
-``ir.Return``, whose ``value`` is the addition expression:
-
-.. code-block:: python
-
print(ir.format_tree(first_plus_one.body))
The output is:
@@ -519,6 +377,82 @@ The output is:
├── a: TensorLoad(source=A, indices=[IntImm(value=0)])
└── b: FloatImm(value=1.0)
-The return annotation ``-> T.float32`` declares the result type. For an
-input starting with ``3.5``, the function returns ``4.5`` directly to its
-caller. It needs no output tensor parameter.
+The assertion's ``error_kind`` names the error it raises, and its
+``message_parts`` hold the message as a list of string fragments. The
+fragments are joined only when the assertion fails, through the TVM FFI
+C API. Many assertions can therefore share common fragments, such as
+an argument name or a shared phrase, which keeps error messages
+compact in the compiled code. Calling the function with an empty
+tensor fails with this message before the tensor read. Otherwise, the
+function returns ``A[0] + 1``.
+
+Regions
+-------
+
+Regions are the main place for extensions. ``ir.RegionStmt`` is a
+statement whose meaning is defined by an operator rather than by a
+dedicated node class. A library registers a region operator to add a
+new kind of statement, and the IR represents every such statement in
+the same form:
+
+- ``op`` is the operator that defines the region's meaning.
+- ``args`` and ``attrs`` are the operator's operands and attributes,
+ evaluated in the enclosing scope.
+- ``body`` is the sequence of statements inside the region.
+- ``body_params`` are variables the region defines on entry, visible
+ only inside ``body``.
+- ``result_vars`` are variables the region defines for the statements
+ that follow it.
+
+This GPU version of add-one places its computation in a device region,
+where each thread handles one element:
+
+.. code-block:: python
+
+ from tvm_tirx import ir
+ from tvm_tirx.script import tirx as T
+
+ n = T.dynamic("n")
+
+ @T.function
+ def gpu_add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+ T.device_entry(launch=T.cuda.LaunchConfig(grid=T.ceildiv(n, 256),
block=256))
+ i = T.cuda.block_idx("x") * 256 + T.cuda.thread_idx("x")
+ if i < n:
+ B[i] = A[i] + 1
+
+ region = gpu_add_one.body[0]
+ print(ir.format_tree(
+ region, hide=["attrs", "args", "body_params", "result_vars", "value"]))
+
+The output is:
+
+.. code-block:: text
+
+ RegionStmt(op=tirx.device_entry)
+ └── body: SeqStmt
+ ├── seq[0]: Bind
+ │ └── var: i = Var(ty=int32)
+ └── seq[1]: If(else_case=None)
+ ├── condition: LT
+ │ ├── a: i
+ │ └── b: n
+ └── then_case: SeqStmt
+ └── seq[0]: TensorStore(dest=B, indices=[i])
+
+The ``tirx.device_entry`` operator marks its body as code that runs on
+the GPU, and its operands carry the launch configuration. The view
+hides those operands and the value expressions to focus on the
+statements inside the region.
+
+.. note::
+
+ Regions and calls are the two ways operators extend TIRx: a call
+ applies an operator as an expression, and a region applies one as a
+ statement.
+ :doc:`operators_and_calls` covers how operators are registered and
+ how calls and regions use them.
+ :ref:`Region Syntax <tvmscript-region-syntax>` explains how TVMScript
+ writes a region, and :doc:`../advanced/defining_ir_extensions` walks
+ through a complete extension with its own type, operators, and
+ lowering pass.
diff --git a/docs/ir/types_and_expressions.rst
b/docs/ir/types_and_expressions.rst
index c03af3e1a..230fa8b3b 100644
--- a/docs/ir/types_and_expressions.rst
+++ b/docs/ir/types_and_expressions.rst
@@ -165,6 +165,38 @@ finished expression always carries a concrete type. While
an expression
is still being built and its type is not yet known, ``ty`` holds the
placeholder ``ir.MissingType``.
+The following table lists the expression classes and the fields each
+adds, and the subsections below introduce them in turn:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 35 35
+
+ * - Class
+ - Represents
+ - Fields
+ * - ``ir.Var``
+ - A named value
+ - ``name``
+ * - ``ir.IntImm``, ``ir.FloatImm``, ``ir.StringImm``
+ - Literal constants
+ - ``value``
+ * - ``ir.prim`` nodes, such as ``ir.prim.Add``
+ - Primitive computations, listed in Primitive Expressions
+ - Operands, such as ``a`` and ``b``
+ * - ``ir.TensorLoad``
+ - A tensor element read
+ - ``source``, ``indices``
+ * - ``ir.Tuple``
+ - A group of values
+ - ``fields``
+ * - ``ir.TupleGetItem``
+ - One field of a tuple
+ - ``tuple_value``, ``index``
+ * - ``ir.Call``
+ - A call to an operator or function
+ - ``op``, ``args``, ``ty_args``, ``attrs``
+
.. _user-ir-var:
Var
@@ -252,6 +284,43 @@ analyses and transformations can recognize, reason about,
and simplify
them by their structure. Python operators on expressions construct
these nodes.
+The following table lists the primitive expression node classes in
+``ir.prim``:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 20 45 35
+
+ * - Category
+ - Node classes
+ - TVMScript syntax
+ * - Arithmetic
+ - ``Add``, ``Sub``, ``Mul``, ``Div``, ``Mod``, ``FloorDiv``,
+ ``FloorMod``, ``Min``, ``Max``
+ - ``+``, ``-``, ``*``, ``/`` (float), ``//``, ``%`` (int)
+ * - Comparison
+ - ``EQ``, ``NE``, ``LT``, ``LE``, ``GT``, ``GE``
+ - ``==``, ``!=``, ``<``, ``<=``, ``>``, ``>=``
+ * - Logical
+ - ``And``, ``Or``, ``Not``
+ - ``and``, ``or``, ``not``
+ * - Bitwise
+ - ``BitwiseAnd``, ``BitwiseOr``, ``BitwiseXor``, ``BitwiseNot``,
+ ``LShift``, ``RShift``
+ - ``&``, ``|``, ``^``, ``~``, ``<<``, ``>>``
+ * - Conversion
+ - ``Cast``
+ - —
+ * - Selection
+ - ``Select``
+ - —
+ * - Vector
+ - ``Broadcast``, ``Ramp``, ``Shuffle``
+ - —
+ * - Binding
+ - ``Let``
+ - —
+
**Index expressions.** Index calculations combine integer variables and
constants, such as a block offset plus a thread index. A binary node
stores its operands in ``a`` and ``b``, and nodes nest to form larger
@@ -321,43 +390,6 @@ The output is:
└── lanes: IntImm(value=4)
└── ty: PrimType(dtype=int32)
-The following table lists the primitive expression node classes in
-``ir.prim``:
-
-.. list-table::
- :header-rows: 1
- :widths: 20 45 35
-
- * - Category
- - Node classes
- - Python syntax
- * - Arithmetic
- - ``Add``, ``Sub``, ``Mul``, ``Div``, ``Mod``, ``FloorDiv``,
- ``FloorMod``, ``Min``, ``Max``
- - ``+``, ``-``, ``*``, ``/`` (float), ``//``, ``%`` (int)
- * - Comparison
- - ``EQ``, ``NE``, ``LT``, ``LE``, ``GT``, ``GE``
- - ``<``, ``<=``, ``>``, ``>=``
- * - Logical
- - ``And``, ``Or``, ``Not``
- - —
- * - Bitwise
- - ``BitwiseAnd``, ``BitwiseOr``, ``BitwiseXor``, ``BitwiseNot``,
- ``LShift``, ``RShift``
- - ``&``, ``|``, ``^``, ``~``, ``<<``, ``>>``
- * - Conversion
- - ``Cast``
- - —
- * - Selection
- - ``Select``
- - —
- * - Vector
- - ``Broadcast``, ``Ramp``, ``Shuffle``
- - —
- * - Binding
- - ``Let``
- - —
-
Operations without dedicated node classes, such as ``ir.prim.exp`` and
``ir.prim.sigmoid``, construct an ``ir.Call`` to a registered operator.
Their results are still primitive expressions.
@@ -465,9 +497,80 @@ The output is:
└── b: FloatImm(value=1.0)
└── ty: PrimType(dtype=float32)
-The example hides two other fields of ``ir.Call``: ``attrs``, which
-holds operator-specific attributes, and ``ty_args``, which holds
-explicit type arguments.
+**Type arguments and attributes.** Some calls need inputs that are not
+value expressions. ``ty_args`` passes types to the callee, and ``attrs``
+holds configuration specific to this call. A tensor allocation has no
+input from which to infer its shape, so it receives its tensor type in
+``ty_args``:
+
+.. code-block:: python
+
+ from tvm_tirx.script import tirx as T
+
+ @T.function
+ def scratch(A: T.Tensor((4,), T.float32)):
+ tmp = T.alloc_local((4,), T.float32)
+ for i in range(4):
+ tmp[i] = A[i] + 1
+
+ alloc = scratch.body[0].value
+ print(alloc.op.name)
+ print(alloc.ty_args[0])
+
+The output is:
+
+.. code-block:: text
+
+ tirx.alloc_tensor
+ T.Tensor((4,), T.float32, scope="local")
+
+The allocation's type rule uses this type argument as the call's result
+type, so the call produces a tensor. This allocation needs no extra
+configuration, so its ``attrs`` is empty.
+
+**Function calls.** The callee can also be another function in the
+same module. Here ``main`` calls the helper ``add_one_scalar`` on each
+element:
+
+.. code-block:: python
+
+ from tvm_tirx import ir
+ from tvm_tirx.script import ir as I
+ from tvm_tirx.script import tirx as T
+
+ @I.ir_module
+ class Module:
+ @T.function(private=True)
+ def add_one_scalar(value: T.float32) -> T.float32:
+ return value + 1
+
+ @T.function
+ def main(A: T.Tensor((4,), T.float32), B: T.Tensor((4,), T.float32)):
+ for i in range(4):
+ B[i] = Module.add_one_scalar(A[i])
+
+ store = Module["main"].body[0].body[0]
+ print(ir.format_tree(store.value, expand=[(ir.Expr, "ty")],
+ hide=["attrs", "ty_args"]))
+
+The output is:
+
+.. code-block:: text
+
+ Call(op=GlobalVar(ty=FuncType(arg_types=[float32], ret_type=float32),
name_hint='add_one_scalar'))
+ ├── ty: PrimType(dtype=float32)
+ └── args[0]: TensorLoad(source=A, indices=[i])
+ └── ty: PrimType(dtype=float32)
+
+The call's ``op`` is an ``ir.GlobalVar``, the module's name for the
+helper. Its type is the helper's ``FuncType``, and the call takes its
+result type from that signature.
+
+.. note::
+
+ Operators are the main extension point of TIRx.
+ :doc:`operators_and_calls` covers how operators are registered and
+ how their attributes define type rules, effects, and lowering.
.. _user-ir-dependent-type:
@@ -545,12 +648,8 @@ equivalence checking, printing, and parsing out of the
box. A library
adds only what is specific to its extension, such as passes that lower
the new operations to what the backend supports.
-What to Read Next
------------------
+.. note::
-- :doc:`statements` shows how expressions are used in loops, stores,
- and other statements.
-- :doc:`operators_and_calls` covers calls to functions, operator
- registration, and how operators define their result types.
-- :doc:`../advanced/defining_ir_extensions` walks through an extension
- that defines a complex type, its operators, and a lowering pass.
+ :doc:`../advanced/defining_ir_extensions` walks through a complete
+ extension that defines a complex type, its operators, and a lowering
+ pass.