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.

Reply via email to