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 3c40ca478 [DOCS][IR] Restructure Functions and Modules around a
two-function module and GlobalVar (#144)
3c40ca478 is described below
commit 3c40ca478c700a01e9f60d4aa616eec442dfd436
Author: Tianqi Chen <[email protected]>
AuthorDate: Sat Oct 31 11:01:18 2026 -0400
[DOCS][IR] Restructure Functions and Modules around a two-function module
and GlobalVar (#144)
Restructure the IR Walkthrough's Functions and Modules chapter around a
two-function module and `GlobalVar`.
- Open with why programs need several functions, and show the module in
TVMScript (`@T.ir_module` with a public `add_one` that calls a private
`add_one_scalar`).
- Functions: what `params`, `ret_type`, and `body` hold; the shared
`attrs`, `ty`, and `loc`; attributes such as `global_symbol`, set with
`T.func_attr` or `with_attr`.
- Modules: what `functions`, `attrs`, and `global_infos` hold.
- Global Variables: how a call refers to another function through a
`GlobalVar`, reference versus definition, and module name versus
exported symbol.
- Code comes from the runnable `examples/ir_walkthrough`.
- Types and Expressions: add `ir.GlobalVar` to the expression table,
link its Call example to the new section, and write the module with
`@T.ir_module`.
---
docs/ir/functions_and_modules.rst | 281 ++++++++---------------
docs/ir/types_and_expressions.rst | 11 +-
examples/ir_walkthrough/functions_and_modules.py | 87 +++++++
examples/ir_walkthrough/run_all_cpu.sh | 3 +
4 files changed, 193 insertions(+), 189 deletions(-)
diff --git a/docs/ir/functions_and_modules.rst
b/docs/ir/functions_and_modules.rst
index b77faa82e..ba0300461 100644
--- a/docs/ir/functions_and_modules.rst
+++ b/docs/ir/functions_and_modules.rst
@@ -18,220 +18,131 @@
Functions and Modules
=====================
-In this chapter, we will introduce functions and modules as the structures
-that organize IR programs. A function combines parameters, a result type,
-and a statement body; a module collects named function definitions. Compiler
-passes use these structures to inspect a function's interface and
-implementation and locate definitions through global references.
+A function describes one piece of computation: its parameters and types
+say how it is called, and its body says what it does. In many cases, a
+program needs multiple functions that interact with each other, such as a
+host function that launches device kernels. A module collects these
+functions under their names, so calls can refer to one another and passes
+can transform the whole program.
-Functions
----------
-
-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:
+In TVMScript, a module is written as a class marked with ``@T.ir_module``,
+with one ``@T.function`` per member:
-.. literalinclude:: ../../examples/quick_start/add_one_cpu.py
+.. literalinclude:: ../../examples/ir_walkthrough/functions_and_modules.py
:language: python
- :start-at: from tvm_tirx.script import tirx as T
- :end-at: B[i] = A[i] + 1
+ :start-after: # [module.begin]
+ :end-before: # [module.end]
-``@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.
+``add_one`` and ``add_two`` add one and two to each element of ``A``.
+The rest of this chapter looks at the functions and then at how the
+module ties them together.
-``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.
+.. note::
+
+ The runnable code in this chapter is under
+ `examples/ir_walkthrough
<https://github.com/apache/tvm-tirx/tree/main/examples/ir_walkthrough>`_
+ in the repository.
+
+Functions
+---------
-The main fields of ``tirx.Function`` are:
+A ``tirx.Function`` has three fields of its own:
.. list-table::
:header-rows: 1
- :widths: 25 75
+ :widths: 20 80
* - Field
- - Meaning
+ - What it holds
* - ``params``
- - Parameter variables in calling order.
+ - The parameter variables, in calling order. ``add_one`` has ``A`` and
+ ``B``.
* - ``ret_type``
- - The declared return type.
+ - The type of the returned value. ``add_one`` returns nothing, an
+ empty tuple type, and writes its result into ``B`` instead. A
+ function that returns a value declares it with ``->``, as in
+ ``def f(x: T.float32) -> T.float32``.
* - ``body``
- - A ``SeqStmt``, or ``None`` for a declaration without an implementation.
- * - ``attrs``
- - An ``ir.DictAttrs`` containing named function properties.
-
-The loop has its own body containing the tensor store. We can print
-these nested bodies and expand the function's return type:
-
-.. code-block:: python
-
- from tvm_tirx import ir
-
- print(ir.format_tree(add_one, expand=[(ir.BaseFunc, "ret_type")]))
-
-The output is:
-
-.. code-block:: text
-
- Function
- ├── params[0]: A = Var(ty=TensorType(shape=[n], dtype=float32))
- ├── params[1]: B = Var(ty=TensorType(shape=[n], dtype=float32))
- ├── ret_type: TupleType
- │ └── fields: []
- └── body: 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)
-
-``add_one.ty`` stores an ``ir.FuncType`` describing the function's
-signature: its parameter types and return type. We can inspect these
-types directly:
-
-.. code-block:: python
-
- signature = add_one.ty
- parameter_types = signature.arg_types
- return_type = signature.ret_type
-
-``parameter_types`` contains the tensor types of ``A`` and ``B`` in
-calling order. The entries in ``add_one.params`` are the variables
-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. This helper adds one
-to a scalar and returns the result:
-
-.. code-block:: python
-
- @T.function(private=True)
- def add_one_scalar(value: T.float32) -> T.float32:
- return value + 1
-
-The return annotation ``-> T.float32`` sets its ``ret_type`` to
-``ir.PrimType("float32")``, and the ``return`` becomes an ``ir.Return``
-statement in its body. The result of ``add_one`` goes into an output
-parameter; the result of ``add_one_scalar`` is a return value.
-
-So far, ``@T.function`` has built a function object for us from source
-code. Compiler code can also build this kind of object directly with
-``tirx.Function``. To focus on the function constructor, we can reuse
-the parameters and loop already stored in ``add_one``:
+ - The statements that run when the function is called.
-.. code-block:: python
+It also has the fields every ``ir.BaseFunc`` shares: ``attrs``, described
+below; ``ty``, the function's signature, built from its parameter and
+return types; and ``loc``, its source location.
- from tvm_tirx import ir, tirx
+Attributes
+~~~~~~~~~~
- A, B = add_one.params
- loop = add_one.body[0]
+``attrs`` allows us to store additional attribute information about a
+function. For example, ``global_symbol`` locks in the symbol name of a
+public function: ``add_one`` is exported as ``"add_one"`` in the compiled
+library. ``@T.function`` sets it from the Python name. A function
+marked ``@T.function(private=True)`` has no ``global_symbol`` and stays
+internal to the module.
-``A`` and ``B`` are the IR parameter variables, and ``loop`` is the
-``ir.For`` shown in the tree above. We can pass these objects to the
-constructor to create another function with the same computation:
+In TVMScript, ``T.func_attr`` adds attributes in the function body, and
+the printer writes them back the same way:
-.. code-block:: python
-
- ir_function = tirx.Function([A, B], loop, ret_type=ir.TupleType([]))
-
-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 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
-compiled function available under the name ``"add_one"``, we set its
-``global_symbol`` attribute:
-
-.. code-block:: python
+.. literalinclude:: ../../examples/ir_walkthrough/functions_and_modules.py
+ :language: python
+ :start-after: # [func_attr.begin]
+ :end-before: # [func_attr.end]
+ :dedent: 4
- ir_function = ir_function.with_attr("global_symbol", "add_one")
+From Python, ``with_attr`` returns a new function with an attribute added
+and leaves the original unchanged:
-``with_attr``, inherited from ``ir.BaseFunc``, returns a new function with
-this entry in ``attrs``. For public TVMScript functions, ``@T.function``
-sets ``global_symbol`` to the Python function name automatically.
+.. literalinclude:: ../../examples/ir_walkthrough/functions_and_modules.py
+ :language: python
+ :start-after: # [with_attr.begin]
+ :end-before: # [with_attr.end]
Modules
-------
-A program can contain several functions that call one another.
-:class:`ir.IRModule <tvm_tirx.ir.IRModule>` collects their definitions so
-compiler passes can find the functions being called and transform the
-program as a whole. We can put the function we just constructed,
-``ir_function``, in a module under the name ``"add_one"``:
-
-.. code-block:: python
-
- module = ir.IRModule({"add_one": ir_function})
-
-The module's ``functions`` field maps global references to function
-definitions. Each key is an :class:`ir.GlobalVar <tvm_tirx.ir.GlobalVar>`,
-and each value is a function definition whose class inherits
-``ir.BaseFunc``. Here, that value is our ``tirx.Function`` object,
-``ir_function``. The constructor creates a ``GlobalVar`` named
-``"add_one"`` from the string key and associates it with this function:
-
-.. code-block:: python
-
- print(ir.format_tree(module.functions, max_depth=3))
-
-The output is:
+A module has three main fields:
-.. code-block:: text
-
- Map
- ├── [0][0]: GlobalVar(name_hint='add_one')
- └── [0][1]: Function
- ├── params: Array(...)
- └── body: SeqStmt(...)
-
-The map displays each entry as a key/value pair: ``[0][0]`` is the
-global reference and ``[0][1]`` is its function definition. ``max_depth``
-limits the display, so ``...`` marks fields left unexpanded. The
-``GlobalVar`` serves as a reference; the function body belongs to
-the associated ``tirx.Function``. We can retrieve the reference by name,
-then use it to look up the definition:
-
-.. code-block:: python
-
- add_one_ref = module.get_global_var("add_one")
- function = module[add_one_ref]
-
-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. 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.
+.. list-table::
+ :header-rows: 1
+ :widths: 20 80
-``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:
+ * - Field
+ - What it holds
+ * - ``functions``
+ - The module's functions, keyed by ``GlobalVar``.
+ * - ``attrs``
+ - Additional attribute information about the whole module, in the same
+ form as a function's ``attrs``.
+ * - ``global_infos``
+ - Reserved for special use cases that need named objects shared
+ across functions. Most modules leave it empty.
-.. code-block:: python
+``functions`` is keyed by ``GlobalVar``, which the next section explains.
+The module also keeps an index from names to ``GlobalVar`` keys, which
+``Module["add_one"]`` uses to look up a function by name.
- import torch
+.. _ir-global-var:
- import tvm_tirx
+Global Variables
+----------------
- compiled = tvm_tirx.compile(module, target="llvm")
- a = torch.arange(10, dtype=torch.float32)
- b = torch.empty(a.shape, dtype=a.dtype)
- compiled["add_one"](a, b)
+``ir.GlobalVar`` is an expression, listed in the
+:ref:`expression table <user-ir-expr>`, that refers to a function in a
+module. The module's ``functions`` map is keyed by ``GlobalVar``: we can
+get the reference by name and look up its definition:
-``compiled["add_one"]`` retrieves the exported function. The call reads
-``a`` and writes ``a + 1`` into ``b``.
+.. literalinclude:: ../../examples/ir_walkthrough/functions_and_modules.py
+ :language: python
+ :start-after: # [global_var.begin]
+ :end-before: # [global_var.end]
+
+Keeping the reference separate from the definition lets IR refer to a
+function without containing its body. For example, a ``Call`` whose
+``op`` is a ``GlobalVar`` calls that function, and a pass can rewrite or
+replace the definition without touching the places that refer to it.
+In practice, references between functions mostly connect host and device
+functions, such as a host function and the kernels it launches.
+
+The ``GlobalVar``'s name is the function's name within the module. It is
+separate from ``global_symbol``, the name a public function is exported
+under. For ``add_one``, both are ``"add_one"``; a private function has a
+module name but no exported symbol.
diff --git a/docs/ir/types_and_expressions.rst
b/docs/ir/types_and_expressions.rst
index 0a6fbb559..07d00a988 100644
--- a/docs/ir/types_and_expressions.rst
+++ b/docs/ir/types_and_expressions.rst
@@ -196,6 +196,9 @@ adds, and the subsections below introduce them in turn:
* - ``ir.Call``
- A call to an operator or function
- ``op``, ``args``, ``ty_args``, ``attrs``
+ * - ``ir.GlobalVar``
+ - A reference to a function in a module
+ - ``name_hint``
.. _user-ir-var:
@@ -535,10 +538,9 @@ 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
+ @T.ir_module
class Module:
@T.function(private=True)
def add_one_scalar(value: T.float32) -> T.float32:
@@ -563,8 +565,9 @@ The output is:
└── 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.
+helper, explained in :ref:`Global Variables <ir-global-var>`. Its type is
+the helper's ``FuncType``, and the call takes its result type from that
+signature.
.. note::
diff --git a/examples/ir_walkthrough/functions_and_modules.py
b/examples/ir_walkthrough/functions_and_modules.py
new file mode 100644
index 000000000..8064c26c7
--- /dev/null
+++ b/examples/ir_walkthrough/functions_and_modules.py
@@ -0,0 +1,87 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Functions, modules, and global variables in a two-function module."""
+
+# [module.begin]
+from tvm_tirx.script import tirx as T
+
+n = T.dynamic("n")
+
+
[email protected]_module
+class Module:
+ @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
+
+ @T.function
+ def add_two(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+ for i in range(n):
+ B[i] = A[i] + 2
+
+
+# [module.end]
+
+add_one = Module["add_one"]
+assert [p.name for p in add_one.params] == ["A", "B"]
+assert len(add_one.ret_type.fields) == 0
+print(add_one.ty)
+assert add_one.attrs["global_symbol"] == "add_one"
+
+
+def private_example():
+ @T.function(private=True)
+ def helper(A: T.Tensor((n,), T.float32)):
+ A[0] = T.float32(0)
+
+ return helper
+
+
+assert "global_symbol" not in private_example().attrs
+
+
+def attrs_example():
+ # [func_attr.begin]
+ @T.function
+ def add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+ T.func_attr({"note": "example"})
+ for i in range(n):
+ B[i] = A[i] + 1
+
+ # [func_attr.end]
+ return add_one
+
+
+noted = attrs_example()
+assert noted.attrs["note"] == "example"
+print(noted.script())
+
+# [with_attr.begin]
+add_one = Module["add_one"]
+marked = add_one.with_attr("note", "example")
+assert "note" not in add_one.attrs # the original is unchanged
+# [with_attr.end]
+assert marked.attrs["note"] == "example"
+
+# [global_var.begin]
+add_one_ref = Module.get_global_var("add_one")
+add_one = Module[add_one_ref]
+# [global_var.end]
+assert add_one_ref.name_hint == "add_one"
+assert add_one.same_as(Module["add_one"])
+print("functions and modules: OK")
diff --git a/examples/ir_walkthrough/run_all_cpu.sh
b/examples/ir_walkthrough/run_all_cpu.sh
index 03fa00cb2..1121cb72b 100755
--- a/examples/ir_walkthrough/run_all_cpu.sh
+++ b/examples/ir_walkthrough/run_all_cpu.sh
@@ -20,3 +20,6 @@ cd "$(dirname "$0")"
# Print, parse, and build add_one
python printing_and_parsing.py
+
+# Functions, modules, and global variables
+python functions_and_modules.py