This is an automated email from the ASF dual-hosted git repository.
Seven-Streams 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 1470dd0b9 [DOCS] Clarify guide structure and core concepts (#175)
1470dd0b9 is described below
commit 1470dd0b9c99ad06b67d95ab29b2c25ef8973410
Author: Ruihang Lai <[email protected]>
AuthorDate: Tue Nov 3 12:52:59 2026 -0500
[DOCS] Clarify guide structure and core concepts (#175)
Introduce TIRx's compiler foundation and plugin model, and explain how
metaprogramming generates and specializes kernels before execution.
Consolidate region documentation and clarify variable scopes to reduce
duplication between the IR guides.
Rename Language Basics to CUDA Functions and Launches and update its
links. Prioritize loops in the control-flow guide, place CUDA
troubleshooting next to compilation, simplify tile guide headings, and
clarify CUDA interface and API reference titles.
---
docs/advanced/extending_ir_in_rust.rst | 8 ++-
docs/get_started/quick_start.rst | 21 +++----
docs/index.rst | 11 ++--
docs/ir_guides/operators_calls_and_regions.rst | 5 +-
docs/ir_guides/statements.rst | 66 ++--------------------
docs/programming_guides/control_flow.rst | 40 ++++++-------
..._basics.rst => cuda_functions_and_launches.rst} | 33 +++--------
docs/programming_guides/cuda_ptx_interfaces.rst | 4 +-
docs/programming_guides/index.rst | 2 +-
docs/programming_guides/metaprogramming.rst | 13 +++--
docs/programming_guides/tile/index.rst | 7 +--
11 files changed, 74 insertions(+), 136 deletions(-)
diff --git a/docs/advanced/extending_ir_in_rust.rst
b/docs/advanced/extending_ir_in_rust.rst
index ab19d4609..e5d286c48 100644
--- a/docs/advanced/extending_ir_in_rust.rst
+++ b/docs/advanced/extending_ir_in_rust.rst
@@ -23,11 +23,17 @@ Getting Started with Rust Extensions
All the code in this tutorial is in the repository, as the Python package
`examples/extension
<https://github.com/apache/tvm-tirx/tree/main/examples/extension>`_.
+TIRx is designed around the idea that "everything is a plugin": compiler
+features can be provided by separately built libraries, using the same IR and
+registration interfaces as built-in features. This chapter puts that idea into
practice
+with a complex-number extension that loads into TIRx without modifying its
+core library.
+
This tutorial shows how to extend TIRx from Rust: define new IR types and
operators, write a pass that lowers them, and use them from Python like
built-in features.
-In this chapter, we will first look at why extensions are written in Rust, then
+On this page, we will first look at why extensions are written in Rust, then
get ready for the rest of the tutorial: a Python package for the extension and
the example program it will compile.
diff --git a/docs/get_started/quick_start.rst b/docs/get_started/quick_start.rst
index 9a51a4011..ffb5cfb3e 100644
--- a/docs/get_started/quick_start.rst
+++ b/docs/get_started/quick_start.rst
@@ -118,6 +118,15 @@ shows ``device='cuda:0'``):
tensor([ 1., 2., 3., 4., 5., 6., 7., 8., 9., 10.])
+.. note::
+
+ If compiling for CUDA fails with ``ValueError: CUDA compilation requires an
+ explicit backend_config arch or Target arch when no CUDA device is
available``
+ even though the machine has a GPU, TIRx could not find the CUDA runtime
library
+ ``libcudart.so.13``. Install and import a CUDA 13 build of PyTorch, which
ships
+ this library, or install the CUDA 13 toolkit and add its ``lib64``
directory to
+ ``LD_LIBRARY_PATH``.
+
Inspect and Transform the Program
---------------------------------
@@ -288,18 +297,6 @@ The same program can also be built with CMake. The
``CMakeLists.txt`` in
cmake --build build --config RelWithDebInfo
build/load_cpp
-
-Troubleshooting
----------------
-
-If compiling for CUDA fails with ``ValueError: CUDA compilation requires an
-explicit backend_config arch or Target arch when no CUDA device is available``
-even though the machine has a GPU, TIRx could not find the CUDA runtime library
-``libcudart.so.13``. Install and import a CUDA 13 build of PyTorch, which ships
-this library, or install the CUDA 13 toolkit and add its ``lib64`` directory to
-``LD_LIBRARY_PATH``.
-
-
Further Reading
---------------
diff --git a/docs/index.rst b/docs/index.rst
index 26055fff0..a80c03482 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,8 +18,11 @@
Apache TVM TIRx Documentation
=============================
-Welcome to the documentation for TVM TIRx. You can get started by reading the
-Get Started section, then reading through the other sections.
+Welcome to the documentation for TVM TIRx. TIRx is a compiler foundation for
+building ML compilers and agentic compiler harnesses. It provides shared IR,
+symbolic analysis, transformations, code generation, and runtime support that
+you can inspect, customize, and compose. Start with the Get Started section,
+then explore the guides and API reference.
Installation
------------
@@ -64,7 +67,7 @@ Table of Contents
:titlesonly:
programming_guides/index
- programming_guides/language_basics
+ programming_guides/cuda_functions_and_launches
programming_guides/control_flow
programming_guides/types_tensors_memory
programming_guides/metaprogramming
@@ -85,7 +88,7 @@ Table of Contents
.. toctree::
:maxdepth: 1
- :caption: Reference
+ :caption: API Reference
Python API <reference/python/index>
C++ API <reference/cpp/index>
diff --git a/docs/ir_guides/operators_calls_and_regions.rst
b/docs/ir_guides/operators_calls_and_regions.rst
index 1a6a9078f..38c314caa 100644
--- a/docs/ir_guides/operators_calls_and_regions.rst
+++ b/docs/ir_guides/operators_calls_and_regions.rst
@@ -235,7 +235,10 @@ operator becomes a region operator by setting two
attributes:
``FRegionValidate`` checks its operands. ``ir.RegionStmt`` records one
use of such an operator: ``op``, the operands ``args`` and ``attrs``,
the ``body``, and any variables the region defines in ``body_params``
-and ``result_vars``.
+and ``result_vars``. Operands and attributes are evaluated in the enclosing
+scope. ``body_params`` are visible only inside the body, while
+``result_vars`` are defined after the region and are available to subsequent
+statements in the enclosing sequence.
``tirx.device_entry`` is a region operator that enters a GPU kernel. Its
operands carry the kernel's launch configuration:
diff --git a/docs/ir_guides/statements.rst b/docs/ir_guides/statements.rst
index a100e9941..2882f2870 100644
--- a/docs/ir_guides/statements.rst
+++ b/docs/ir_guides/statements.rst
@@ -387,64 +387,10 @@ 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:
+``ir.RegionStmt`` groups statements under an operator that defines their
+meaning. For example, ``tirx.device_entry`` marks a body as GPU code and
+carries its launch configuration. Regions let libraries introduce new kinds
+of statements without adding a dedicated IR node class.
-.. 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_calls_and_regions` explains region fields, variable scopes,
+and operator registration, with a device-region example.
diff --git a/docs/programming_guides/control_flow.rst
b/docs/programming_guides/control_flow.rst
index a23f66174..e963e8f4b 100644
--- a/docs/programming_guides/control_flow.rst
+++ b/docs/programming_guides/control_flow.rst
@@ -24,7 +24,7 @@ Control Flow
`examples/programming_guides/control_flow.py
<https://github.com/apache/tvm-tirx/blob/main/examples/programming_guides/control_flow.py>`_.
-This guide shows how to write conditions and loops in TIRx kernels. TIRx uses
+This guide shows how to write loops and conditions in TIRx kernels. TIRx uses
Python's own control flow syntax: ``if``, ``elif``, ``else``, ``for``,
``while``, ``break``, and ``continue`` all mean what they mean in Python, and
each thread executes them independently with its own values.
@@ -36,25 +36,6 @@ The examples use the following imports and a symbolic length
``n``:
:start-after: # [imports.begin]
:end-before: # [imports.end]
-``if`` Statements
------------------
-
-An ``if`` statement runs its body only on the threads whose condition holds.
-The following kernel implements ReLU, which keeps positive values and replaces
-the rest with zero:
-
-.. literalinclude:: ../../examples/programming_guides/control_flow.py
- :language: python
- :start-after: # [if.begin]
- :end-before: # [if.end]
-
-The outer ``if i < n`` is the usual bounds check: the last block may have more
-threads than elements left, and the check keeps those threads from reading or
-writing past the end of the tensors. Inside it, ``if`` and ``else`` choose
-between two stores for each element, and ``elif`` can add more branches, just
-as in Python. A branch-free ``T.max(A[i], 0.0)`` would also compute ReLU; the
-``if`` form shows how threads can take different paths.
-
``for`` Loops
-------------
@@ -112,6 +93,25 @@ local scalars, so they keep their updates from one
iteration to the next.
iteration, just as in Python. Both work in ``for`` and ``while`` loops, and
each thread decides on its own when to break or continue.
+``if`` Statements
+-----------------
+
+An ``if`` statement runs its body only on the threads whose condition holds.
+The following kernel implements ReLU, which keeps positive values and replaces
+the rest with zero:
+
+.. literalinclude:: ../../examples/programming_guides/control_flow.py
+ :language: python
+ :start-after: # [if.begin]
+ :end-before: # [if.end]
+
+The outer ``if i < n`` is the usual bounds check: the last block may have more
+threads than elements left, and the check keeps those threads from reading or
+writing past the end of the tensors. Inside it, ``if`` and ``else`` choose
+between two stores for each element, and ``elif`` can add more branches, just
+as in Python. A branch-free ``T.max(A[i], 0.0)`` would also compute ReLU; the
+``if`` form shows how threads can take different paths.
+
Early Thread Exit
-----------------
diff --git a/docs/programming_guides/language_basics.rst
b/docs/programming_guides/cuda_functions_and_launches.rst
similarity index 88%
rename from docs/programming_guides/language_basics.rst
rename to docs/programming_guides/cuda_functions_and_launches.rst
index 23ac987f5..22d50a6e8 100644
--- a/docs/programming_guides/language_basics.rst
+++ b/docs/programming_guides/cuda_functions_and_launches.rst
@@ -20,12 +20,15 @@
https://tvm.apache.org/docs/_sources/tirx/native_basics/cuda/control_flow.rst
https://tvm.apache.org/docs/_sources/tirx/native_basics/cuda/parser_utils.rst
-Language Basics
-===============
+CUDA Functions and Launches
+===========================
This guide shows how to define CUDA functions, configure their launches, and
-assign work to threads. We will use the GPU add-one program from :doc:`Quick
-Start </get_started/quick_start>`, then extend it with a runtime parameter.
+assign work to threads. The :doc:`IR guides </ir_guides/functions_and_modules>`
+explain how functions are represented; here we focus on writing and launching
+a kernel with tensor and scalar arguments. We will use the GPU add-one program
+from :doc:`Quick Start </get_started/quick_start>`, then extend it with a
runtime
+parameter.
A CUDA Function
---------------
@@ -54,28 +57,6 @@ the launch, the index assigned to each thread, and the
guarded tensor store.
Parameters
----------
-The parameter annotations specify the types of arguments a kernel accepts:
-
-.. list-table::
- :header-rows: 1
- :widths: 34 36 30
-
- * - Annotation
- - Meaning
- - Argument
- * - ``T.Tensor(shape, dtype)``
- - A tensor with the declared shape and dtype
- - A tensor on the expected device
- * - ``T.int32``, ``T.float32``, etc.
- - A runtime scalar
- - A Python ``int`` or ``float``
- * - ``T.handle``
- - An opaque handle
- - A handle value
- * - ``T.constexpr`` (``@T.jit``)
- - A compile-time parameter
- - Passed to ``.specialize(...)``
-
We can extend ``add_one`` so each call chooses the amount to add.
The ``increment: T.float32`` parameter controls that amount:
diff --git a/docs/programming_guides/cuda_ptx_interfaces.rst
b/docs/programming_guides/cuda_ptx_interfaces.rst
index cbbfbc93b..29f59cefb 100644
--- a/docs/programming_guides/cuda_ptx_interfaces.rst
+++ b/docs/programming_guides/cuda_ptx_interfaces.rst
@@ -17,8 +17,8 @@
.. Adapted from Apache TVM:
https://tvm.apache.org/docs/_sources/tirx/native_basics/cuda/threads_sync.rst
-Calling CUDA and PTX
-====================
+CUDA and PTX Interfaces
+=======================
This guide shows how to use three interfaces for CUDA programming in TVMScript.
Backend intrinsics under ``T.cuda`` provide common operations, such as
diff --git a/docs/programming_guides/index.rst
b/docs/programming_guides/index.rst
index 5ffa3a647..c2f050dd7 100644
--- a/docs/programming_guides/index.rst
+++ b/docs/programming_guides/index.rst
@@ -129,7 +129,7 @@ recurring hardware operations appear as tile operations.
Guides in This Section
----------------------
-- :doc:`language_basics` covers defining and launching kernels.
+- :doc:`cuda_functions_and_launches` covers defining and launching kernels.
- :doc:`control_flow` covers conditions, loops, and early thread exit.
- :doc:`types_tensors_memory` covers element types, tensors, and memory
spaces.
diff --git a/docs/programming_guides/metaprogramming.rst
b/docs/programming_guides/metaprogramming.rst
index 748a38fd9..086b0cc6a 100644
--- a/docs/programming_guides/metaprogramming.rst
+++ b/docs/programming_guides/metaprogramming.rst
@@ -24,10 +24,15 @@ Metaprogramming
`examples/programming_guides/metaprogramming.py
<https://github.com/apache/tvm-tirx/blob/main/examples/programming_guides/metaprogramming.py>`_.
-This guide shows how to use Python to generate, reuse, and specialize TIRx
-kernels. TIRx functions are written in Python, so ordinary Python code runs
-before compilation and decides what each kernel contains: which dtypes and
-sizes it uses, which helper code it includes, and which values are fixed.
+Metaprogramming means writing code that constructs or specializes other code.
+In TIRx, ordinary Python functions can generate kernel definitions, inline
+helpers can insert reusable statements, and compile-time parameters can
+produce specialized kernels. These choices determine the program before it
+runs on the GPU; runtime parameters supply data to the resulting program.
+
+This guide shows these three techniques: capturing Python values in kernel
+generators, reusing code with ``@T.inline``, and specializing ``@T.jit``
+functions.
The examples use the following imports:
diff --git a/docs/programming_guides/tile/index.rst
b/docs/programming_guides/tile/index.rst
index f70ea0ef0..43c7e32ec 100644
--- a/docs/programming_guides/tile/index.rst
+++ b/docs/programming_guides/tile/index.rst
@@ -31,9 +31,6 @@ an explanation of how operand axes divide the work across
threads. The
:doc:`instruction reference </reference/python/backend.cuda.tile.instructions>`
lists each family's parameters, operand layouts, and alignment requirements.
-CUDA Instruction Guides
------------------------
-
The guides below show how to use these interfaces for data movement,
arithmetic, asynchronous transfers, and matrix instructions. Asynchronous
examples include the completion protocol required by their instruction family.
@@ -46,7 +43,7 @@ examples include the completion protocol required by their
instruction family.
arithmetic
Asynchronous Transfers
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
.. toctree::
:maxdepth: 1
@@ -55,7 +52,7 @@ Asynchronous Transfers
tma
Matrix Instructions
-~~~~~~~~~~~~~~~~~~~
+-------------------
.. toctree::
:maxdepth: 1
