This is an automated email from the ASF dual-hosted git repository.
tlopex 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 273969879 [DOCS] Make the IR walkthrough self-contained and expand
examples (#123)
273969879 is described below
commit 27396987961331a98a24943136c977f1804042cc
Author: Shushi Hong <[email protected]>
AuthorDate: Thu Oct 29 10:22:56 2026 -0400
[DOCS] Make the IR walkthrough self-contained and expand examples (#123)
This PR makes each IR Walkthrough chapter readable independently by
including the program definitions it uses and explaining how source
constructs map to IR objects.
also adds examples for branches, loops, assertions, returns, pointer and
tuple types, boolean operations, and casts. Expand the printing
diagnostic example, improve transitions, and reduce repeated
explanations and prerequisite cross-references.
---
docs/ir/functions_and_modules.rst | 61 ++++++++--------
docs/ir/operators_and_calls.rst | 141 ++++++++++++++++++++-----------------
docs/ir/overview.rst | 24 +++----
docs/ir/printing_and_parsing.rst | 87 +++++++++++++----------
docs/ir/statements.rst | 143 +++++++++++++++++++++++++++++++++++---
docs/ir/types_and_expressions.rst | 130 ++++++++++++++++++++++++----------
6 files changed, 401 insertions(+), 185 deletions(-)
diff --git a/docs/ir/functions_and_modules.rst
b/docs/ir/functions_and_modules.rst
index 330897ece..af9811169 100644
--- a/docs/ir/functions_and_modules.rst
+++ b/docs/ir/functions_and_modules.rst
@@ -27,11 +27,25 @@ implementation and locate definitions through global
references.
Functions
---------
-:class:`ir.BaseFunc <tvm_tirx.ir.BaseFunc>` is the common base class for
-IR function definitions. It provides the ``attrs`` field for named
-function properties. :class:`tirx.Function <tvm_tirx.tirx.Function>` is
-its subclass for tensor programs, adding parameters, a return type, and
-a statement body:
+We can inspect a small CPU function to see how its parameters and body
+fit together. It accepts two tensors of length ``n`` and writes each
+input value plus one to the output:
+
+.. 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
+
+``@T.function`` parses the definition into a
+:class:`tirx.Function <tvm_tirx.tirx.Function>` object, which the name
+``add_one`` now refers to. Its ``params`` field holds ``A`` and ``B``,
+and its ``body`` holds the loop.
+
+``tirx.Function`` inherits from
+:class:`ir.BaseFunc <tvm_tirx.ir.BaseFunc>`, the common base class for
+IR function definitions. The base class provides ``attrs`` for named
+function properties. ``tirx.Function`` adds the tensor program's
+parameters, return type, and statement body:
.. code-block:: text
@@ -55,17 +69,8 @@ The main fields of ``tirx.Function`` are:
* - ``attrs``
- An ``ir.DictAttrs`` containing named function properties.
-In TVMScript, ``@T.function`` produces this IR object from a function
-definition. The CPU example is defined as:
-
-.. 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
-
-The name ``add_one`` refers to the resulting ``tirx.Function``. Its
-parameters are the variables ``A`` and ``B``, and its body contains the
-loop. The loop has its own body containing the tensor store:
+The loop has its own body containing the tensor store. These nested
+bodies give ``add_one`` the following structure:
.. code-block:: text
@@ -94,8 +99,8 @@ themselves. ``return_type`` is the same type stored in
``add_one.ret_type``: an empty tuple type, ``ir.TupleType([])``, indicating
no return value. This function writes its results into ``B``.
-A function can also return a value explicitly. The ``add_one_scalar``
-helper from :doc:`operators_and_calls` returns a single float32 value:
+A function can also return a value explicitly. This helper adds one
+to a scalar and returns the result:
.. code-block:: python
@@ -132,7 +137,7 @@ The new function takes ``A`` and ``B`` as parameters and
runs ``loop``
as its body. The constructor wraps this single statement in a ``SeqStmt``.
``ret_type=ir.TupleType([])`` specifies that the function returns no value;
its loop writes the result to ``B``. A function that returns a value needs
-its return type supplied through ``ret_type``; the constructor does not
+its return type set through ``ret_type``; the constructor does not
infer it from the body.
We will put ``ir_function`` in a module and compile it below. To make the
@@ -144,9 +149,8 @@ compiled function available under the name ``"add_one"``,
we set its
ir_function = ir_function.with_attr("global_symbol", "add_one")
``with_attr``, inherited from ``ir.BaseFunc``, returns a new function with
-this entry in ``attrs``. For public functions written in TVMScript,
-``@T.function`` sets
-``global_symbol`` to the Python function name automatically.
+this entry in ``attrs``. For public TVMScript functions, ``@T.function``
+sets ``global_symbol`` to the Python function name automatically.
Modules
-------
@@ -186,17 +190,18 @@ then use it to look up the definition:
The first line returns the ``GlobalVar`` key, and the second returns
the ``tirx.Function`` stored under it. ``module["add_one"]`` retrieves
the same definition directly by name. A call can use ``add_one_ref`` as
-its ``op`` to identify this function, as in the function-call example in
-:doc:`operators_and_calls`.
+its ``op`` to identify this function. The call records the reference and
+its arguments; the module stores the definition that the reference
+identifies.
The name ``"add_one"`` used in this lookup is the function's name within
the module. The function's ``attrs["global_symbol"]`` specifies its
exported name for code generation. Both names are ``"add_one"`` in this
example, but they serve these separate purposes.
-``tvm_tirx.compile`` accepts a module as well as a standalone function. We
-can compile ``module`` with the same LLVM target used in Quick Start,
-then create CPU tensors and call its exported ``add_one`` function:
+``tvm_tirx.compile`` accepts a module as well as a standalone function.
+We can compile ``module`` for the CPU with LLVM, then call its exported
+``add_one`` function with input and output tensors:
.. code-block:: python
@@ -210,4 +215,4 @@ then create CPU tensors and call its exported ``add_one``
function:
compiled["add_one"](a, b)
``compiled["add_one"]`` retrieves the exported function. The call reads
-``a`` and writes ``a + 1`` into ``b``, just as in Quick Start.
+``a`` and writes ``a + 1`` into ``b``.
diff --git a/docs/ir/operators_and_calls.rst b/docs/ir/operators_and_calls.rst
index 09208ffed..fd1a0f803 100644
--- a/docs/ir/operators_and_calls.rst
+++ b/docs/ir/operators_and_calls.rst
@@ -21,7 +21,7 @@ Operators and Calls
In this chapter, we will introduce operators and calls. A registered
operator provides the shared argument requirements, type rules, and effect
information for a computation. A call refers to an operator or function
-and supplies argument expressions for that use. We will examine how
+and records the argument expressions for one use. We will examine how
the IR records these definitions and calls, infers result types, and
checks arguments.
@@ -34,13 +34,16 @@ registered operator and records its name, argument
descriptions, and
attributes. The operator's registration also provides rules for
result-type inference and argument validation.
-The GPU example uses the registered operator ``tirx.cuda.thread_idx`` to
-obtain a thread coordinate. ``ir.Op.get`` retrieves its ``ir.Op`` object,
-and ``op.args_info`` describes its parameters. We can extract their names:
+A CUDA kernel can read a thread's x-axis coordinate with
+``T.cuda.thread_idx("x")``. The registered operator behind this helper is
+``tirx.cuda.thread_idx``. We can retrieve its ``ir.Op`` object and inspect
+the names of the parameters it accepts:
.. code-block:: python
from tvm_tirx import ir
+ from tvm_tirx.script import tirx as T
+
op = ir.Op.get("tirx.cuda.thread_idx")
argument_names = [argument.name for argument in op.args_info]
print(argument_names)
@@ -51,7 +54,7 @@ The output is:
['axis']
-The list contains one parameter name, ``axis``. In the GPU example,
+The list contains one parameter name, ``axis``.
``T.cuda.thread_idx("x")`` passes the string ``"x"`` for this parameter.
This selects the x axis, so the call reads the current thread's x-axis
coordinate within its block.
@@ -76,12 +79,12 @@ is passed to it, and what type of value it produces:
* - ``args``
- Value arguments in calling order.
* - ``ty_args``
- - Types supplied as arguments to the callee, empty by default.
+ - Types passed as arguments to the callee, empty by default.
* - ``attrs``
- Operator-specific configuration or annotations for this call,
stored as an ``Attrs`` object, or ``None``.
* - ``ty``
- - The result type of this call, inferred or explicitly supplied.
+ - The result type of this call, inferred or explicitly specified.
The thread-index call refers to the registered ``tirx.cuda.thread_idx``
operator. We can construct it directly through the IR API:
@@ -103,19 +106,19 @@ creates an expression whose ``op`` refers to that
definition and whose
└── ty: ir.PrimType int32
``op.args_info[0].name`` is the parameter name ``"axis"``;
-``x_call.args[0]`` supplies its argument value ``"x"``. The call describes
+``x_call.args[0]`` holds its argument value ``"x"``. The call describes
reading the current thread's x-axis coordinate when the compiled GPU
program runs.
For this registered operator, ``ir.Call`` infers ``ty`` from the
-operator's type rule. An explicit ``ty`` supplies the result type directly
-and skips inference.
+operator's type rule. If we pass ``ty`` to the constructor, it uses that
+result type and skips inference.
The constructor also accepts the registered name directly:
``ir.Call("tirx.cuda.thread_idx", [ir.StringImm("x")])``.
-The program uses the x axis. As an additional example, we can construct
-a call for the y axis with the same operator:
+The call above selects the x axis. We can construct a call for the
+y axis with the same operator:
.. code-block:: python
@@ -131,8 +134,9 @@ both calls produce an int32 coordinate:
├──> op: ir.Op tirx.cuda.thread_idx
y_call.op ──┘
-A call's result can be an operand in a larger expression. In the GPU
-example, two calls contribute to the element index ``i``:
+A call's result can be an operand in a larger expression. A kernel with
+256 threads per block can combine the block and thread coordinates to
+find the tensor element assigned to a thread:
.. literalinclude:: ../../examples/quick_start/add_one_cuda.py
:language: python
@@ -140,10 +144,10 @@ example, two calls contribute to the element index ``i``:
:end-at: i = T.cuda.block_idx
:dedent: 4
-``T.cuda.block_idx("x")`` supplies the block coordinate, and
-``T.cuda.thread_idx("x")`` supplies the thread's coordinate within that
-block. Each helper constructs an ``ir.Call``. The multiplication and
-addition use the calls' results as operands:
+The block-index call produces the block coordinate, and the thread-index
+call produces the coordinate within that block. Each helper constructs
+an ``ir.Call``. The multiplication and addition use the calls' results
+as operands:
.. code-block:: text
@@ -156,10 +160,8 @@ addition use the calls' results as operands:
Expression Arguments
~~~~~~~~~~~~~~~~~~~~
-A call can also receive a computation as an argument.
-As an extension of the scalar add-one expression, we can apply sigmoid to
-``scalar_value + 1``. The variable ``scalar_value`` has type
-``ir.PrimType("float32")``:
+A call can also receive a computation as an argument. We can add one to
+a float32 scalar and pass the result to sigmoid:
.. code-block:: python
@@ -167,10 +169,10 @@ As an extension of the scalar add-one expression, we can
apply sigmoid to
scalar_plus_one = scalar_value + 1
activated_plus_one = ir.prim.sigmoid(scalar_plus_one)
-``ir.prim.sigmoid(...)`` constructs and returns an ``ir.Call`` object.
-``activated_plus_one`` refers to this call, which is also a primitive
-expression because its result type is ``ir.PrimType("float32")``.
-We can construct the same call explicitly:
+``activated_plus_one`` is the ``ir.Call`` returned by the
+``ir.prim.sigmoid`` helper. Its result type is ``ir.PrimType("float32")``,
+so it is also a primitive expression. We can construct the same call
+explicitly:
.. code-block:: python
@@ -196,9 +198,10 @@ addition. This expression therefore computes
Function Calls
--------------
-The callee can also be a function defined in IR. A function stored in an
-``IRModule`` is referenced through an ``ir.GlobalVar``. For example, a
-small helper can put the scalar add-one computation in a function:
+The callee can also be a function defined in IR. An ``IRModule`` stores
+named function definitions, and an ``ir.GlobalVar`` identifies one of
+those definitions. For example, a small helper can put the scalar
+add-one computation in a function:
.. code-block:: python
@@ -219,20 +222,22 @@ module and construct a call that passes ``scalar_value``
as its argument:
``callee`` is the module's global reference to ``add_one_scalar``.
``function_call.op`` refers to this ``GlobalVar``, and
-``function_call.args[0]`` supplies the value for the helper's parameter
-``value``. A function-valued callee with a ``FuncType`` supplies a return
-type for inference. Here, ``callee.ty`` is ``MissingType``: the reference
-itself does not carry the function's signature. We therefore supply the
-return type from the definition through ``ty``. The call holds the
-reference and argument; the module holds the function's definition.
-Other function-valued IR expressions can also serve as callees.
+``function_call.args[0]`` holds the value passed to the helper's parameter
+``value``. The call records this reference and argument; the module holds
+the function's definition.
+
+In this example, ``callee.ty`` is ``MissingType``, so the reference does
+not provide a signature for result-type inference. We pass the return
+type from the definition through ``ty`` instead. Other function-valued
+IR expressions can also serve as callees. When their ``ty`` is a
+``FuncType``, the constructor can infer the result from its return type.
Calls in Function Bodies
------------------------
A call contributes to a function's computation through the expression or
-statement that uses it. We can extend the CPU example to apply sigmoid
-to each add-one result:
+statement that uses it. This CPU function applies sigmoid to each
+input element after adding one:
.. code-block:: python
@@ -258,7 +263,7 @@ The tensor store uses that call as its ``value`` expression:
└── value: ir.Call prim.sigmoid
└── args[0]: ir.prim.Add A[i] + 1
-When the function runs, the addition supplies the sigmoid input and the
+When the function runs, the addition produces the sigmoid input and the
store writes its result to ``B[i]``.
Calls for Their Effects
@@ -324,10 +329,10 @@ write merely because its result is unused; it updates the
output tensor.
Type Arguments and Attributes
-----------------------------
-Some operators need a type as an input to describe the value they
-produce. For example, a tensor allocation needs the shape and element
-type of the storage to create. This additional example describes a
-four-element float32 tensor in local storage:
+A call's value arguments do not always determine its result type.
+A tensor allocation, for example, has no input tensor from which to
+infer a shape or dtype. We pass the required tensor type through
+``ty_args``. This call describes four float32 elements in local storage:
.. code-block:: python
@@ -335,21 +340,31 @@ four-element float32 tensor in local storage:
temporary_type = tirx.TensorType((4,), "float32", scope="local")
allocation_call = ir.Call(
- "tirx.alloc_tensor", [], ty_args=[temporary_type], attrs={}
+ "tirx.alloc_tensor", [], ty_args=[temporary_type],
+ attrs={"tirx.volatile": True},
)
-``ty_args[0]`` supplies the tensor type to the allocation operator. Its
+``ty_args[0]`` gives the tensor type to the allocation operator. Its
type rule uses this argument as the result type, so ``allocation_call.ty``
is ``temporary_type``. A call can therefore produce a tensor as well as a
scalar or vector value.
-A surrounding ``ir.Bind`` can name the allocated tensor for subsequent
-reads and writes, as described in :doc:`statements`.
-The ``attrs`` argument supplies annotations for an individual call. A
-dictionary becomes an ``ir.DictAttrs`` object; the operator determines
-which annotations it supports and how they are used. These annotations
-belong to this call, while the attributes on ``ir.Op`` describe
-properties shared by every call to that operator.
+The ``attrs`` dictionary configures this allocation. It becomes an
+``ir.DictAttrs`` object, and ``"tirx.volatile": True`` requests volatile
+accesses: code generation must preserve the loads and stores to this
+storage. These attributes belong to this call; the attributes on ``ir.Op``
+describe the operation shared by all its calls.
+
+We can give the allocated tensor a name with a binding:
+
+.. code-block:: python
+
+ temporary = ir.Var("temporary", temporary_type)
+ allocation_binding = ir.Bind(temporary, allocation_call)
+
+The binding's ``value`` is the allocation call, and its ``var`` is
+``temporary``. A function body can place this binding before statements
+that read or write the temporary tensor.
.. _types-and-validation:
@@ -358,11 +373,11 @@ properties shared by every call to that operator.
Call Types and Validation
-------------------------
-The earlier examples inferred a call's result type or supplied it
-explicitly. During IR construction, we may also need a call whose result
-type is not known yet. ``ty=ir.Type.missing()`` records this state and
-defers inference. The same scalar sigmoid input, ``scalar_plus_one``,
-lets us compare all three choices:
+A call needs a result type that matches its inputs. For sigmoid, a scalar
+float32 input produces float32, and a four-lane input produces float32x4.
+The constructor normally infers this type. An explicit ``ty`` skips
+inference, and ``ty=ir.Type.missing()`` leaves the result undetermined.
+With the scalar addition defined above, the three choices are:
.. code-block:: python
@@ -372,12 +387,12 @@ lets us compare all three choices:
untyped_call = ir.Call(sigmoid_op, [scalar_plus_one], ty=ir.Type.missing())
``inferred_call`` and ``typed_call`` both store a float32 result type.
-``untyped_call`` explicitly supplies ``MissingType``, so its result type
+``untyped_call`` explicitly sets ``MissingType``, so its result type
remains undetermined.
-The same operator also accepts a four-lane float32 vector. We can leave
-this call's result type undetermined, then infer it from the vector
-argument:
+Now suppose we are rebuilding the scalar call to work on four values at
+once. We can first set its vector argument and leave the result type
+undetermined until we run the operator's inference rule:
.. code-block:: python
@@ -405,7 +420,7 @@ passes ``vector_value`` as that input. The following call
leaves it out:
invalid_sigmoid = ir.Call(sigmoid_op, [], ty="float32x4")
-``ty="float32x4"`` supplies the result type directly, so the constructor
+``ty="float32x4"`` sets the result type directly, so the constructor
skips inference. It still creates the incomplete ``ir.Call`` object
because argument checks do not run automatically. We can use
:meth:`Call.validate() <tvm_tirx.ir.Call.validate>` to check whether the
@@ -416,6 +431,6 @@ arguments satisfy the operator's requirements:
invalid_sigmoid.validate()
``invalid_sigmoid.validate()`` raises ``TypeError`` for the missing input.
-``untyped_sigmoid.validate()`` succeeds because the call supplies
+``untyped_sigmoid.validate()`` succeeds because the call includes
``vector_value``. Its ``ty`` remains ``MissingType`` because validation
checks the arguments without inferring the result type.
diff --git a/docs/ir/overview.rst b/docs/ir/overview.rst
index b8ace5c16..aa7724b13 100644
--- a/docs/ir/overview.rst
+++ b/docs/ir/overview.rst
@@ -18,18 +18,18 @@
IR Overview
===========
-One primary design goal of TIRx is to allow developers and agents to quickly
-access every stage of compilation, not only its input and output, and to
-work with every stage in the same way, so they can customize the compiler.
+TIRx gives developers and agents direct access to the programs and
+transformations at each stage of compilation. They can inspect the
+intermediate program, apply an existing pass, or add their own compiler
+components.
TIRx represents a program as a tree of intermediate representation (IR)
nodes, such as functions, statements, and values. The tree is similar to the
abstract syntax tree (AST) of Python code, but in a more structured, typed
-form. A compiler pipeline analyzes and transforms this tree step by step and
-maps it to the target program. At every stage, the tree can be printed as
-Python code, in a syntax we call TVMScript (provided by the
-``tvm_tirx.script`` module). For example, the following TVMScript program
-defines ``add_one`` for a GPU:
+form. A compiler pipeline analyzes and transforms this tree step by step
+to produce target code. The ``tvm_tirx.script`` interfaces print the IR as
+TVMScript, a Python-based notation for tensor programs. For example, this
+TVMScript definition describes an add-one computation on a GPU:
.. literalinclude:: ../../examples/quick_start/add_one_cuda.py
:language: python
@@ -159,10 +159,10 @@ same way, registering new operators, defining new types,
and adding their own
TVMScript namespaces from Python, C++, or Rust, while reusing TIRx as a
foundation.
-Every IR node can also carry a source location
-(:py:class:`ir.Location <tvm_tirx.ir.Location>`) in its ``loc`` field, which
-records where the node comes from in the source code and can be used for
-diagnostics.
+IR nodes can also carry source locations
+(:py:class:`ir.Location <tvm_tirx.ir.Location>`). For example, an expression's
+``loc`` field records where it came from in the source, so a diagnostic
+can point back to the original code.
.. _choose-a-chapter:
diff --git a/docs/ir/printing_and_parsing.rst b/docs/ir/printing_and_parsing.rst
index 0713f5ecd..408809c54 100644
--- a/docs/ir/printing_and_parsing.rst
+++ b/docs/ir/printing_and_parsing.rst
@@ -21,7 +21,7 @@ Printing and Parsing
====================
In this chapter, we will introduce printing and parsing with TVMScript,
-the Python-based syntax used to describe tensor programs in Quick Start.
+TIRx's Python-based syntax for tensor programs.
The printer turns IR objects into readable TVMScript code, and the parser
constructs IR objects from that code. We will use these interfaces to
inspect the add-one function, save and load programs, and examine a
@@ -30,8 +30,9 @@ compiler pass's changes.
Printing IR
-----------
-In the CPU example, the TVMScript decorator ``@T.function`` parses the
-function definition into a ``tirx.Function`` IR object:
+We will use a CPU function that adds one to each tensor element. The
+TVMScript decorator ``@T.function`` parses its definition into a
+``tirx.Function`` IR object:
.. literalinclude:: ../../examples/quick_start/add_one_cpu.py
:language: python
@@ -112,9 +113,9 @@ variables, loop, and tensor store. It can be inspected or
compiled
through the same interfaces as ``add_one``.
The import inside ``source_text`` tells the parser what ``T`` refers to.
-The earlier ``source`` returned by ``add_one.script()`` has this import
-commented out. In that case, ``extra_vars`` supplies the existing ``T``
-namespace:
+Our first call to ``add_one.script()`` returned ``source`` with that
+import commented out. To parse this string, we can bind the name ``T``
+to the existing namespace through ``extra_vars``:
.. code-block:: python
@@ -132,8 +133,8 @@ Saving and Loading a Module
An IR module can be saved as TVMScript for later inspection or reuse.
We can store the CPU function in a module and write its source to a file.
-To let that file supply its own namespaces when parsed, we include the
-imports with ``ir.comment_imports=False``:
+The file can include its own imports, so a parser can read it in another
+process. ``ir.comment_imports=False`` enables those imports:
.. code-block:: python
@@ -151,8 +152,8 @@ We can read the saved source and reconstruct the module:
restored_module = from_source(output_path.read_text())
ir.assert_structural_equal(module, restored_module)
-The imports in the file supply the namespaces needed by the parser, so
-this call needs no ``extra_vars``. ``restored_module`` is an ``ir.IRModule``
+The parser resolves the namespace names from the imports, so this call
+needs no ``extra_vars``. ``restored_module`` is an ``ir.IRModule``
with the same function definitions as ``module``.
Inspecting IR
@@ -166,29 +167,35 @@ or see how a compiler pass changes the program.
Highlighting IR Objects
~~~~~~~~~~~~~~~~~~~~~~~
-The function's body lets us reach the addition in ``B[i] = A[i] + 1``.
-To find this expression in the printed program, we can ask the printer to
-underline it:
+An analysis may need to identify an expression in a diagnostic. We can
+reach the addition in ``B[i] = A[i] + 1`` through the function's body,
+then ask the printer to underline it and attach a message about its type:
.. code-block:: python
loop = add_one.body[0]
store = loop.body[0]
addition = store.value
- marked_source = add_one.script(obj_to_underline=[addition])
+ marked_source = add_one.script(
+ obj_to_underline=[addition],
+ obj_to_annotate={addition: "result dtype: float32"},
+ print_line_numbers=True,
+ num_context_lines=1,
+ )
print(marked_source)
The marked lines include:
.. code-block:: text
- B[i] = A[i] + T.float32(1.0)
- ^^^^^^^^^^^^^^^^^^^^^
+ 7 for i in range(n):
+ 8 B[i] = A[i] + T.float32(1.0) # result dtype: float32
+ ^^^^^^^^^^^^^^^^^^^^^
-``obj_to_underline`` selects the IR objects to mark. For a diagnostic,
-``print_line_numbers=True`` adds line numbers, ``obj_to_annotate`` can
-attach messages to selected objects, and ``num_context_lines`` limits the
-surrounding source.
+``obj_to_underline`` selects the expression to mark, and ``obj_to_annotate``
+attaches the message. The line numbers refer to this printed source.
+``num_context_lines=1`` keeps one surrounding line, so the diagnostic
+shows the loop containing the addition.
For interactive inspection,
:meth:`add_one.show() <tvm_tirx.tirx.Function.show>` displays highlighted
@@ -197,8 +204,8 @@ source directly and accepts the same options.
Inspecting a Transformation
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The printer also helps us check what a compiler pass changes. We can
-extend the CPU example with a bounds check inside the loop:
+The printer also helps us check what a compiler pass changes. Consider
+this version of add-one with a bounds check inside the loop:
.. code-block:: python
@@ -231,8 +238,9 @@ The second output contains the simplified loop:
Building Program Variants
-------------------------
-For functions that differ only in a constant, ``from_source`` can parse
-the same template with different ``extra_vars``. This template replaces
+A source generator may produce functions with the same structure but
+different constants. ``from_source`` can parse the same template with
+different ``extra_vars`` to build these variants. This template replaces
the add-one constant with ``increment``:
.. code-block:: python
@@ -256,7 +264,7 @@ The same text can produce versions that add one or two:
)
print(add_two_variant.script())
-The parser turns the ``increment`` value supplied through ``extra_vars``
+The parser turns the ``increment`` value passed through ``extra_vars``
into a constant. The addition in ``add_two_variant`` is therefore
``A[i] + T.float32(2.0)``; both functions still take only ``A`` and ``B``
as parameters.
@@ -306,18 +314,21 @@ file:
│ └── name path to the source file
└── start_line line of A's declaration
-The ``filename`` argument labels generated source in parser diagnostics.
-The following example removes the required type annotation from ``A``
-in the template:
+Source locations are also useful when parsing fails. The following
+source is missing the type annotation for parameter ``A``. We give the
+text a filename so the diagnostic can identify it:
.. code-block:: python
- invalid_source = variant_source.replace("A: T.Tensor((n,), T.float32)", "A")
+ invalid_source = """@T.function
+ def invalid_add_one(A):
+ T.evaluate(0)
+ """
try:
from_source(
invalid_source,
- extra_vars={"T": T, "increment": 1.0},
- filename="generated_add_constant.py",
+ extra_vars={"T": T},
+ filename="generated_add_one.py",
)
except SyntaxError as error:
print(error)
@@ -326,20 +337,20 @@ The output is:
.. code-block:: text
- Parameter 'A' requires an annotation (generated_add_constant.py, line 3)
+ Parameter 'A' requires an annotation (generated_add_one.py, line 2)
-The program comes from ``invalid_source``; ``filename`` supplies the
-name shown in the message, and successfully parsed nodes record it in
-their ``loc`` fields.
+The message identifies the supplied source text and the line with the
+invalid parameter. Successfully parsed nodes record the filename and
+their positions in ``loc``.
.. _tvmscript-region-syntax:
Region Syntax
-------------
-The parser also determines which statements belong to a region. In the
-GPU example, TVMScript recognizes ``T.device_entry`` as a region
-construct. Its standalone form starts the device region:
+The parser also determines which statements belong to a region. A CUDA
+function uses ``T.device_entry`` to mark the statements that execute on
+the GPU. In the following function, the region starts at that line:
.. literalinclude:: ../../examples/quick_start/add_one_cuda.py
:language: python
diff --git a/docs/ir/statements.rst b/docs/ir/statements.rst
index bc37a3239..895645545 100644
--- a/docs/ir/statements.rst
+++ b/docs/ir/statements.rst
@@ -27,6 +27,14 @@ execution through a branch or loop. These statements form
the function's
body, which compiler passes can inspect and rewrite through the IR
interfaces.
+We will start with this CPU function, which adds one to every element
+of ``A`` and writes the results 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
+
.. _statements-and-sequences:
Statement Classes
@@ -87,7 +95,7 @@ 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``.
-The CPU example writes one output element in each loop iteration:
+The loop in ``add_one`` writes one output element in each iteration:
.. literalinclude:: ../../examples/quick_start/add_one_cpu.py
:language: python
@@ -106,6 +114,7 @@ from ``add_one``:
from tvm_tirx import ir
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])
@@ -172,7 +181,10 @@ 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.
-The CPU example visits every element with a loop:
+For loops
+~~~~~~~~~
+
+``add_one`` visits every element with a loop:
.. literalinclude:: ../../examples/quick_start/add_one_cpu.py
:language: python
@@ -212,9 +224,32 @@ the order of the statements within it. The
:class:`~tvm_tirx.ir.ForKind` API reference describes the other execution
kinds.
-The GPU example distributes this work across threads. ``T.device_entry``
-introduces the GPU computation. Each thread computes an index ``i`` and
-checks whether it has an element to process:
+Branches
+~~~~~~~~
+
+A branch can choose between two results. This CPU function applies
+ReLU: positive input values pass through, and all other values become
+zero:
+
+.. code-block:: python
+
+ @T.function
+ def relu(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+ for i in range(n):
+ if A[i] > 0:
+ B[i] = A[i]
+ 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.
+
+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. These statements belong inside its
+function body:
.. literalinclude:: ../../examples/quick_start/add_one_cuda.py
:language: python
@@ -241,8 +276,8 @@ the store in ``then_case``. An else branch has its own
``SeqStmt`` in
tensor access. These branch bodies can also contain further loops and
branches.
-The standalone ``T.device_entry(...)`` groups the remaining statements
-in this function into a device region. An
+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:
@@ -260,5 +295,95 @@ a ``SeqStmt`` containing the index definition followed by
the branch:
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 standalone syntax and the equivalent
-``with`` form.
+the grouping rule for this syntax and the equivalent ``with`` form.
+
+While loops
+~~~~~~~~~~~
+
+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:
+
+.. 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:
+
+.. code-block:: text
+
+ ir.While
+ ├── condition: ir.prim.LT i < n
+ └── body: ir.SeqStmt
+ ├── seq[0]: ir.TensorStore B[i] = A[i] + 1
+ └── seq[1]: ir.TensorStore i += 1
+
+The mutable scalar uses a one-element local tensor in IR. The second
+store writes its next value, which the condition reads 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:
+
+.. code-block:: python
+
+ @T.function
+ def first_positive(A: T.Tensor((n,), T.int32), B: T.Tensor((1,), T.int32)):
+ B[0] = -1
+ for i in range(n):
+ if A[i] <= 0:
+ continue
+ 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.
+
+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:
+
+.. code-block:: python
+
+ @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:: text
+
+ first_plus_one.body: ir.SeqStmt
+ ├── seq[0]: ir.AssertStmt assert n > 0, ...
+ └── seq[1]: ir.Return
+ └── value: ir.prim.Add A[0] + 1
+
+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.
diff --git a/docs/ir/types_and_expressions.rst
b/docs/ir/types_and_expressions.rst
index 687186457..73b2369d1 100644
--- a/docs/ir/types_and_expressions.rst
+++ b/docs/ir/types_and_expressions.rst
@@ -22,9 +22,17 @@ Types and Expressions
In this chapter, we will introduce types and expressions. Expressions
represent values and computations, and their types describe properties
-such as dtypes, tensor shapes, and function signatures. The add-one
-examples will show how to inspect these objects and construct expressions
-directly with the IR API.
+such as dtypes, tensor shapes, and function signatures. We will inspect
+the values in a small add-one function, then construct scalar and vector
+expressions through the IR API.
+
+This CPU function reads each element of ``A``, adds one, and writes the
+result to ``B``. Both tensors have the same symbolic length ``n``:
+
+.. 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
.. _user-ir-type:
@@ -57,8 +65,8 @@ for scalar and vector values, tensor types, and function
types:
- A tensor's shape, element type, and storage properties
- ``shape``, ``dtype``, ``scope``, ``data_alignment``, ``layout``
-Next, we will look at two common types in tensor programs in more detail:
-``ir.PrimType`` for scalar and vector values, and ``tirx.TensorType`` for
tensors.
+We will examine primitive and tensor types first, then look at the
+pointer type used for a tensor's data address.
.. _user-ir-prim-type:
@@ -72,14 +80,14 @@ floating-point, and boolean values, either as scalars or
vectors. Its
In the program's tensor annotations, ``T.float32`` is an
``ir.PrimType("float32")`` object.
-The program declares its dynamic length as:
+The tensor length ``n`` is an integer symbol:
.. literalinclude:: ../../examples/quick_start/add_one_cpu.py
:language: python
:start-at: from tvm_tirx.script import tirx as T
:end-at: n = T.dynamic
-where ``n`` is a 32-bit integer symbol with type ``ir.PrimType("int32")``.
+The default dtype is int32, so ``n`` has type ``ir.PrimType("int32")``.
The loop index ``i`` has the same primitive type.
We can express the addition ``A[i] + 1`` directly through the IR API,
@@ -141,6 +149,22 @@ when the function is compiled. Each call determines ``n``
from the length
of ``A``. Since ``B`` uses the same symbol in its type, its length must
match ``A``. The loop then uses ``n`` as its bound.
+PtrType
+~~~~~~~
+
+Some low-level operations take a memory address. The ``data`` property
+of a tensor parameter constructs an expression for its data pointer:
+
+.. code-block:: python
+
+ data_pointer = add_one.params[0].data
+ pointer_type = data_pointer.ty
+
+``pointer_type`` is an ``ir.PtrType``. Its ``element_type`` is
+``ir.PrimType("float32")``, and its ``scope`` is ``"global"``, matching
+the tensor's storage. This type describes the elements addressed by the
+pointer. The tensor's ``TensorType`` also records their shape.
+
Expressions
-----------
@@ -175,15 +199,13 @@ The output is:
float32
float32
-The variable's type was supplied by the ``"float32"`` argument in
-``ir.Var("scalar_value", "float32")``. The addition's constructor
-determines its result type from its operands; this process is called
-type inference.
+``ir.Var("scalar_value", "float32")`` sets the variable's type explicitly.
+The addition's constructor determines its result type from its operands;
+this process is called type inference.
An expression under construction can also have an ``ir.MissingType``
-in ``ty`` while its type is undetermined. The
-:ref:`Call Types and Validation <types-and-validation>` section shows
-how a missing result type can be inferred later.
+in ``ty`` while its type is undetermined. Once its inputs are ready,
+the appropriate type rule can determine a concrete result type.
Each expression class adds fields for its value or operands, alongside
the shared ``ty`` field:
@@ -229,10 +251,9 @@ they produce primitive scalar or vector values.
**Scalar expressions.** The CPU example uses the int32 expressions ``n``
and ``i`` for the loop bound and index. The tensor read ``A[i]`` and the
-addition ``A[i] + 1`` both produce a single float32 value. In the GPU
-example, ``i < n`` produces a boolean that decides whether a thread
-writes its result. These scalar result types are stored as ``PrimType``
-objects in ``ty``.
+addition ``A[i] + 1`` both produce a single float32 value. A comparison
+such as ``i < n`` produces a boolean. These scalar result types are
+stored as ``PrimType`` objects in ``ty``.
``A`` itself represents the whole tensor and has a ``TensorType``.
The expression ``A[i]`` reads element ``i`` of this tensor. TVMScript
@@ -262,11 +283,10 @@ For example, the GPU expression
``T.cuda.thread_idx("x")`` is an
Primitive Operations
~~~~~~~~~~~~~~~~~~~~
-The previous section grouped expressions by result type. The operations
-below describe the computations that produce those values. The
-``ir.prim`` namespace provides node classes and Python helpers for
-arithmetic, comparisons, boolean logic, casts, and other primitive
-computations:
+Arithmetic and comparisons combine variables, constants, and tensor
+reads into larger expressions. The ``ir.prim`` namespace provides node
+classes and Python helpers for these operations, as well as boolean
+logic, casts, and other primitive computations:
.. list-table::
:header-rows: 1
@@ -282,9 +302,6 @@ computations:
Python operators such as ``+``, ``*``, and ``<`` construct arithmetic
and comparison nodes. The Python helper ``ir.prim.sigmoid`` constructs
a call to a registered operator; the returned IR node is an ``ir.Call``.
-The :ref:`Call <user-ir-call>` section below examines its fields.
-The :doc:`ir.prim </reference/python/ir.prim>` API reference lists the
-available classes and construction helpers.
In the CPU example, ``A[i] + 1`` becomes an ``ir.prim.Add``. A binary node
stores its left operand in ``a`` and its right operand in ``b``:
@@ -303,8 +320,9 @@ These constructors also support vector operands. In
``vector_value + 1``,
the scalar constant is broadcast to all four lanes, producing the
four-lane expression ``vector_plus_one``.
-The GPU example combines multiplication, addition, and comparison to
-compute and check each thread's element index:
+A GPU version assigns one element to each thread. The following part of
+its body combines multiplication, addition, and comparison to compute
+and check that element's index:
.. literalinclude:: ../../examples/quick_start/add_one_cuda.py
:language: python
@@ -325,6 +343,31 @@ operands are the index and tensor length:
The comparison checks whether the thread has a valid element to process.
+Boolean operations combine comparisons into a single condition. For
+example, both checks must hold for a scalar to lie in the interval
+``[0, 1)``:
+
+.. code-block:: python
+
+ in_unit_interval = ir.prim.And(scalar_value >= 0, scalar_value < 1)
+
+The ``And`` node holds the two comparisons in ``a`` and ``b``. Its result
+type is ``ir.PrimType("bool")``.
+
+An operation can also change the dtype of a value. To produce a float16
+version of the add-one result, we can use a cast:
+
+.. code-block:: python
+
+ half_plus_one = ir.prim.Cast("float16", scalar_plus_one)
+
+The cast's ``value`` field refers to ``scalar_plus_one``. Its ``ty`` is
+``ir.PrimType("float16")``, which tells code generation to convert the
+float32 result to float16.
+
+The :doc:`ir.prim </reference/python/ir.prim>` API reference lists other
+operations and their construction helpers.
+
.. _user-ir-var:
Var
@@ -334,11 +377,9 @@ Var
function parameters, loop indices, or intermediate values defined by
bindings.
-The tensor parameters ``A`` and ``B`` in the program are represented by
-``ir.Var`` objects. The PyTorch tensors ``a`` and ``b`` are passed to these
-parameters when the compiled function is called. In the CPU example, we
-can retrieve the parameter variables from ``add_one.params`` and inspect
-their types through ``ty``:
+The tensor parameters ``A`` and ``B`` in our CPU function are represented
+by ``ir.Var`` objects. We can retrieve them from ``add_one.params`` and
+inspect their types through ``ty``:
.. code-block:: python
@@ -368,6 +409,25 @@ scalar add-one example in PrimType uses this constructor:
``ir.Var("scalar_value", "float32")`` creates a variable whose ``name``
is ``"scalar_value"`` and whose ``ty`` is ``ir.PrimType("float32")``.
+Tuples
+~~~~~~
+
+An expression can group several values into a tuple. For example, we can
+keep the original scalar and its add-one result together, then select
+the second value:
+
+.. code-block:: python
+
+ paired_values = ir.Tuple([scalar_value, scalar_plus_one])
+ second_value = ir.TupleGetItem(paired_values, 1)
+
+``paired_values.fields`` holds the two expressions. Its type is an
+``ir.TupleType`` whose ``fields`` holds their types: two
+``ir.PrimType("float32")`` objects. ``TupleGetItem`` records the tuple
+in ``tuple_value`` and the selected position in ``index``. Index 1
+selects ``scalar_plus_one``, so ``second_value`` has type
+``ir.PrimType("float32")``.
+
.. _user-ir-call:
Call
@@ -378,8 +438,8 @@ function. Its ``op`` field refers to the operator or
function expression
being called, and ``args`` holds the argument expressions. A registered
operator is represented by ``ir.Op``.
-In the GPU example, the index expression contains calls to
-``T.cuda.block_idx("x")`` and ``T.cuda.thread_idx("x")``.
+The GPU index calculation above uses ``T.cuda.block_idx("x")`` and
+``T.cuda.thread_idx("x")`` to read the block and thread coordinates.
These TVMScript helpers construct calls to registered CUDA operators.
We can construct the thread-index call directly through the IR API: