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 558c3b933 [DOCS] Add the TVM-FFI Object System sections to the Rust
and C++ guides (#156)
558c3b933 is described below
commit 558c3b9335d7695469e3a8b4ee41024a9fb57d92
Author: Tianqi Chen <[email protected]>
AuthorDate: Sun Nov 1 20:13:00 2026 -0500
[DOCS] Add the TVM-FFI Object System sections to the Rust and C++ guides
(#156)
This PR adds a TVM-FFI Object System section to the Working with IR in
Rust and Working with IR in C++ guides. Each section explains why TIRx
IR nodes are TVM-FFI objects (dynamic extension first, cross-language
use second) and introduces the constructs for working with them in that
language, one concept at a time on an `x * 2 + 1` expression that the
examples build themselves.
Rust guide:
- New section after Setting Up, replacing Accessing and Creating IR
Nodes, with a key-constructs table and five subsections:
- Constructing Objects: `Var::new` and `ex()`.
- Objects and Managed References: the underlying object and its named
managed reference (`AddObj` / `Add`), why the reference is a named type,
identity, and immutability.
- Casts: `.into()` and `.try_cast()`, including a failed cast.
- Matching Node Types: `match_any!`, with the `_` arm as what keeps
existing code working when node types are added.
- Dispatching on Node Types: a `#[dispatch(walk)]` struct; unhandled
types fall back to the default traversal.
- The intro, Structural Utilities, Visitors and Mutators, and Quick
Reference describe the Rust forms on their own terms; API links point at
the site's Rust reference.
C++ guide:
- New section after Setting Up, replacing Accessing and Creating IR
Nodes, with a key-constructs table and five subsections:
- Constructing Objects: `PrimVar` and `PrimExpr` operators.
- Objects and Managed References: `AddObj` / `Add`, why the reference is
a named class, identity, and `CopyOnWrite()`.
- Casts: implicit upcasts and `as<T>()` / `as_or_throw<T>()`, including
a failed cast.
- Typed Views: `PrimExpr`, `IntExpr`, and `PrimVar`, which constrain an
expression by its type rather than its object class.
- Dispatching on Node Types: an `ExprFunctor` with one `Dispatch_`
overload per node class and `DispatchDefault_` for the rest.
- The intro, Structural Utilities, Visitor and Mutator Classes, and
Quick Reference describe the C++ forms on their own terms; Quick
Reference gains rows for typed views, `CopyOnWrite()`, and the functors.
The example crate and C++ source replace the `add_one`-based object
examples with argument-free functions that build their own IR, and the
drivers call them first.
---
docs/ir_guides/working_with_ir_in_cpp.rst | 490 +++++++++++++++++--------
docs/ir_guides/working_with_ir_in_rust.rst | 504 ++++++++++++++++----------
examples/ir_guides/cpp/working_with_ir.cc | 125 +++++--
examples/ir_guides/rust/src/lib.rs | 170 +++++----
examples/ir_guides/working_with_ir_in_cpp.py | 40 +-
examples/ir_guides/working_with_ir_in_rust.py | 31 +-
6 files changed, 909 insertions(+), 451 deletions(-)
diff --git a/docs/ir_guides/working_with_ir_in_cpp.rst
b/docs/ir_guides/working_with_ir_in_cpp.rst
index f001bb42c..1150c1a0e 100644
--- a/docs/ir_guides/working_with_ir_in_cpp.rst
+++ b/docs/ir_guides/working_with_ir_in_cpp.rst
@@ -18,38 +18,25 @@
Working with IR in C++
======================
-The IR objects we have used from Python are TVM-FFI objects implemented in
-C++. A C++ function can receive ``add_one`` from Python, inspect or rewrite
-it, and hand the result back, with no conversion in between. This lets us
-move a hot analysis or a large transformation to C++ while keeping the rest
-of the workflow in Python.
-
-This chapter assumes the concepts of the earlier chapters and shows their
-C++ form:
-
-- **Accessing and creating IR nodes**: read fields, check node types, and
- build new nodes.
-- **Structural utilities**: walk, map, and compare programs, with callbacks
- selected by their parameter types.
-- **Visitor and mutator classes**: C++ classes with one hook per node kind,
- for passes that customize many kinds of node.
+TIRx is implemented in C++, and a C++ function can read, build, and
+rewrite its IR directly. The function can receive a program written in
+TVMScript, inspect or rewrite it, and return the result, with no
+conversion in between, which lets us move a hot analysis or a large
+transformation to C++. This guide covers:
+
+- **TVM-FFI object system**: how IR nodes are represented and used in C++.
+- **Structural utilities**: walk, map, and compare programs.
+- **Visitor and mutator classes**: one hook per node type, for larger passes.
.. note::
- The runnable code in this chapter is under
+ The runnable code in this guide is under
`examples/ir_guides
<https://github.com/apache/tvm-tirx/tree/main/examples/ir_guides>`_
in the repository.
Setting Up
----------
-Throughout this chapter, we use the ``add_one`` function from Quick Start:
-
-.. 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 examples are packaged as ``tirx_ir_guide_examples`` under
`examples/ir_guides
<https://github.com/apache/tvm-tirx/tree/main/examples/ir_guides>`__.
Installing the package builds the C++ source, ``cpp/working_with_ir.cc``,
@@ -63,34 +50,38 @@ installation instead of fetching one from PyPI:
pip install scikit-build-core
pip install --no-build-isolation -e examples/ir_guides
-Each example is a C++ function that takes ``add_one`` as its argument. A
-``TVM_FFI_STATIC_INIT_BLOCK`` at the end of the source registers each one as
-a global function under ``tirx_ir_guide_examples.cpp``:
+A ``TVM_FFI_STATIC_INIT_BLOCK`` at the end of the source registers each
+example as a global function under ``tirx_ir_guide_examples.cpp``:
.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
:language: cpp
:start-at: refl::GlobalDef()
- :end-at: .def("tirx_ir_guide_examples.cpp.inspect", Inspect)
+ :end-at: .def("tirx_ir_guide_examples.cpp.construct", Construct)
:dedent: 2
The package's ``tirx_ir_guide_examples.cpp`` module loads the library and
-exposes these functions, so Python calls them by name:
+exposes these functions, so Python calls them by name. The driver
+``working_with_ir_in_cpp.py`` calls each example this way and prints the
+result.
-.. code-block:: python
+The object system examples take no arguments: each builds its own IR in
+C++. The later sections receive the ``add_one`` function from Quick Start,
+written in TVMScript:
- import tirx_ir_guide_examples.cpp
+.. 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
- tirx_ir_guide_examples.cpp.inspect(add_one)
+.. code-block:: python
-The driver ``working_with_ir_in_cpp.py`` calls each example this way and
-prints the result.
+ import tirx_ir_guide_examples.cpp
-Accessing and Creating IR Nodes
--------------------------------
+ tirx_ir_guide_examples.cpp.construct()
+ tirx_ir_guide_examples.cpp.tensors_written(add_one)
-Before reading any IR, it helps to know where the classes live. The
-headers relevant to this chapter sit in five folders under ``tvm/``; see
-:ref:`cpp-header-organization` for the full list:
+The headers relevant to this guide sit in five folders under ``tvm/``;
+see :ref:`cpp-header-organization` for the full list:
.. list-table::
:header-rows: 1
@@ -107,8 +98,8 @@ headers relevant to this chapter sit in five folders under
``tvm/``; see
``reflection/registry.h``
* - ``tvm/ir/``
- Core IR nodes, such as ``Expr``, ``Var``, ``Stmt``, ``For``, and
- ``TensorStore``, and the expression visitors in ``expr_functor.h``.
- - (through ``tvm/tirx/function.h``)
+ ``TensorStore``, and the expression functors in ``expr_functor.h``.
+ - ``expr_functor.h``
* - ``tvm/sym/``
- Symbolic analysis, such as ``sym::Analyzer`` and
``sym::ConstraintContext``.
@@ -121,38 +112,149 @@ headers relevant to this chapter sit in five folders
under ``tvm/``; see
- The IR builder and the TVMScript printer.
- None
-IR classes live in the ``tvm`` namespace, TIRx-specific ones such as
+IR classes live in the ``tvm`` namespace, primitive expressions such as
+:cpp:class:`tvm::prim::Add` in ``tvm::prim``, TIRx-specific ones such as
:cpp:class:`tvm::tirx::Function` in ``tvm::tirx``, and the TVM-FFI classes
in ``tvm::ffi``. The examples start with ``using namespace tvm;``, so these
-appear as ``Var``, ``tirx::Function``, and
+appear as ``Var``, ``prim::Add``, ``tirx::Function``, and
:cpp:func:`ffi::StructuralWalk <tvm::ffi::StructuralWalk>`.
-**Each IR node has two C++ classes.** The node class, named with an
-``Obj`` suffix such as :cpp:class:`tvm::ForObj`, holds the fields. The
-reference class without the suffix, such as :cpp:class:`tvm::For`, is a
-reference-counted handle to a node, and is what functions take and return.
-The ``->`` operator on a reference reaches the node's fields.
+TVM-FFI Object System
+---------------------
+
+Every TIRx IR node is a TVM-FFI object. TIRx is designed for **dynamic
+extension**: a library can add a new node type, for example a new
+statement for a hardware feature, and existing code keeps working on
+programs that contain it, which a fixed class hierarchy compiled into one
+library cannot offer. Generic utilities such as walking, rewriting, comparing,
and
+printing work on every node through its registered fields.
+
+TVM-FFI objects also work across languages. Python, C++, and Rust share
+the same native, immutable, reference-counted objects, so a program moves
+between them without conversion.
+
+**In C++, TVM-FFI objects are ordinary C++ classes, used through a few
+key constructs:**
+
+.. list-table::
+ :header-rows: 1
+ :widths: 35 65
+
+ * - Construct
+ - Purpose
+ * - Constructors, ``PrimExpr`` operators
+ - Build expressions with ordinary C++ operators
+ * - ``FooObj`` / ``Foo``
+ - Underlying object and its named managed reference: read fields with
+ ``->``, copy cheaply
+ * - ``CopyOnWrite()``
+ - Change a field, copying the object only if it is shared
+ * - Implicit upcast
+ - Pass a node wherever a parent type is expected
+ * - ``as<T>()`` / ``as_or_throw<T>()``
+ - Convert to a child type, with a checked result
+ * - Typed views (``PrimExpr``, ``IntExpr``, ``PrimVar``)
+ - Require an expression of a given type, checked on conversion
+ * - ``ExprFunctor`` / ``StmtFunctor``
+ - Process each node type in its own method
+
+The subsections below introduce each construct.
+
+Constructing Objects
+~~~~~~~~~~~~~~~~~~~~
+
+**We build IR with constructors and ordinary C++ operators.** Writing
+``x * 2 + 1`` as nested constructor calls would bury the expression, so
+arithmetic operators on :cpp:class:`PrimExpr <tvm::PrimExpr>` build the
+nodes for us. Let's build it:
+
+.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
+ :language: cpp
+ :start-after: // [construct.begin]
+ :end-before: // [construct.end]
+
+The output is:
+
+.. code-block:: text
+
+ x * 2 + 1
+
+:cpp:class:`PrimVar <tvm::PrimVar>` creates an integer variable ``x``, a
+variable known to have a primitive type.
+``*`` and ``+`` turn the literals ``2`` and ``1`` into constants of the
+type of ``x``, fold constants, and otherwise call the node constructors,
+such as ``prim::Add(a, b)``. Writing a node to a stream prints it as
+TVMScript; ``Print`` is our small helper that does so.
+
+We now have an expression; next, let's see what kind of C++ value it is.
+
+Objects and Managed References
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Every node type comes as a pair: an underlying object and a named
+managed reference.** The top of
+``x * 2 + 1`` is an addition, so let's view the expression as an addition,
+with a cast the next subsection explains, and read its two operands:
+
+.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
+ :language: cpp
+ :start-after: // [objects.begin]
+ :end-before: // [objects.end]
+
+The output is:
+
+.. code-block:: text
+
+ a = x * 2
+ b = 1
+ same object: true
+
+``alias`` is the same object as ``add``: copying a managed reference copies
+only the pointer, and ``same_as`` compares identity.
+
+:cpp:class:`AddObj <tvm::prim::AddObj>` is the **underlying object**: the
+class that holds the fields. :cpp:class:`Add <tvm::prim::Add>` is a
+**named managed reference** to it: an owning, reference-counted pointer,
+like ``std::shared_ptr<AddObj>`` except that it is never null, so copying
+it is cheap and ``->`` is always safe. Functions take and return managed
+references, and ``->`` on a managed reference reaches the object's fields:
+``add->a``.
+
+We define a separate named class ``Add`` instead of using a plain pointer
+to ``AddObj`` because the named class carries the interface: constructors,
+methods, and the type information that lets it pass through TVM-FFI
+functions. It can also impose additional constraints on the underlying
+object that the object alone does not express.
-Let's read ``add_one`` from its parameters down to the store in its loop:
+**Nodes are immutable once shared.** To change a field, ``CopyOnWrite()``
+returns a mutable pointer to the object, copying the object first if
+anyone else holds it:
.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
:language: cpp
- :start-after: // [inspect.begin]
- :end-before: // [inspect.end]
+ :start-after: // [cow.begin]
+ :end-before: // [cow.end]
The output is:
.. code-block:: text
- param A
- param B
- loop over i up to n
- store to B: A[i] + T.float32(1.0)
+ add = x * 2 + 1
+ changed = x * 2 + 3
-Fields have the types we know from Python, and writing an expression to a
-stream prints it in TVMScript. The elements of a ``SeqStmt`` are general
-``Stmt`` references, so we check the actual node type before reading a
-loop or a store. |ObjectRef::as|_ and its relatives offer three forms:
+``changed`` shared its object with ``add``, so ``CopyOnWrite()`` copied it
+before the write, and ``add`` is untouched.
+
+We reached ``Add`` with a cast; next, let's look at casts on their own.
+
+Casts
+~~~~~
+
+**Casts move a managed reference up and down the class hierarchy.** A
+function that takes any expression wants an ``Expr``, while reading the
+operands needs an ``Add``. Converting up is implicit, through C++
+inheritance. Converting down checks the node's actual type, with
+|ObjectRef::as|_ and its relatives in one of three forms:
.. list-table::
:header-rows: 1
@@ -160,85 +262,179 @@ loop or a store. |ObjectRef::as|_ and its relatives
offer three forms:
* - Call
- Returns
- * - ``stmt.as<ForObj>()``
- - A pointer to the node, or ``nullptr`` if it is not a loop.
- * - ``stmt.as<For>()``
- - A ``std::optional<For>`` reference.
- * - ``stmt.as_or_throw<For>()``
- - The ``For`` reference, or raises an error.
+ * - ``value.as<AddObj>()``
+ - A non-owning ``const AddObj*``, valid while a reference keeps the
+ object alive, or ``nullptr`` if it is not an addition.
+ * - ``value.as<Add>()``
+ - A ``std::optional<Add>``.
+ * - ``value.as_or_throw<Add>()``
+ - The ``Add``, or raises an error.
+
+.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
+ :language: cpp
+ :start-after: // [casts.begin]
+ :end-before: // [casts.end]
+
+The output is:
+
+.. code-block:: text
+
+ as<AddObj>: pointer
+ as<Add>: Add
+ as<Mul>: nullopt
+ as_or_throw<Mul>: Cannot treat type `prim.Add` as type `prim.Mul`
+
+``value`` is an ``Expr``, but the node behind it is still an addition, so
+the casts to ``AddObj`` and ``Add`` succeed and the cast to ``Mul`` finds
+nothing. ``as<AddObj>()`` works like ``dynamic_cast<const AddObj*>``, and
+``as<Add>()`` and ``as_or_throw<Add>()`` do the same check but return a
+managed reference. ``as_or_throw`` turns the same mismatch into an error
+that names both type keys: the actual ``prim.Add`` and the requested
+``prim.Mul``.
+
+Casts check the class of the object; next, let's look at references that
+also check the type of the expression.
+
+Typed Views
+~~~~~~~~~~~
+
+**A typed view constrains an expression by its type, not by its object
+class.** Arithmetic needs expressions whose result is a primitive value,
+but an addition, a variable, and a call can all produce one, so no single
+object class captures "primitive". :cpp:class:`PrimExpr <tvm::PrimExpr>`
+is a named managed reference that accepts any ``Expr`` whose ``ty`` is a
+``PrimType``, and has no object class of its own.
+
+.. list-table::
+ :header-rows: 1
+ :widths: 25 75
+
+ * - View
+ - Accepts
+ * - :cpp:class:`PrimExpr <tvm::PrimExpr>`
+ - Any expression whose ``ty`` is a ``PrimType``
+ * - :cpp:class:`IntExpr <tvm::IntExpr>`
+ - A scalar integer expression, signed or unsigned
+ * - :cpp:class:`PrimVar <tvm::PrimVar>`
+ - A ``Var`` whose ``ty`` is a ``PrimType``
+
+The same casts check the view. Let's try two variables, an integer and a
+float:
+
+.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
+ :language: cpp
+ :start-after: // [views.begin]
+ :end-before: // [views.end]
+
+The output is:
+
+.. code-block:: text
+
+ i as PrimExpr: yes
+ i as IntExpr: yes
+ f as IntExpr: no
+ as_or_throw<IntExpr>: Cannot treat type `ir.Var[ty=float32]` as type
`ir.IntExpr`
+
+Both variables are ``VarObj`` objects; only their ``ty`` differs, and the
+views check it. The error shows the type in brackets, ``ir.Var[ty=float32]``.
+This is why ``x`` is a ``PrimVar``: the operators take ``PrimExpr``, and a
+plain ``Var`` would first need a checked cast.
.. note::
- A function's ``body`` is always a ``SeqStmt``. The loop variable is stored
- as a ``PrimVar``, which views a ``Var`` as a ``PrimExpr``, so we read its
- name through ``as<VarObj>()``.
+ A view is not a subclass of the node's own reference class:
+ ``PrimVar`` derives from ``PrimExpr`` and converts to ``Var`` through a
+ conversion operator.
+
+A cast or a view looks at one node at a time; to process every node type
+in its own method, we dispatch.
-To create a node, we call the constructor of its reference class, and
-arithmetic operators on ``PrimExpr`` build new expressions. Let's build a
-store that writes twice the value of the store in ``add_one``:
+Dispatching on Node Types
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**A functor picks one of its own methods by the node's runtime type, as
+in the visitor pattern.** :cpp:class:`ExprFunctor <tvm::ExprFunctor>`
+declares a virtual ``Dispatch_`` overload for each expression class, and a
+subclass overrides the ones it cares about. ``Dispatch`` looks up the
+node's type in a table and calls the matching overload, so the nodes need
+no ``accept()`` method. Let's print an expression with
+explicit parentheses:
+
+.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
+ :language: cpp
+ :start-after: // [describe.begin]
+ :end-before: // [describe.end]
+
+We call it on ``x * 2 + 1`` and on ``x - 1``:
.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
:language: cpp
- :start-after: // [create.begin]
- :end-before: // [create.end]
+ :start-after: // [dispatch_use.begin]
+ :end-before: // [dispatch_use.end]
The output is:
-.. code-block:: python
+.. code-block:: text
+
+ ((x * 2) + 1)
+ <other>
+
+The template argument chooses the signature, here ``std::string`` from an
+``Expr``. A functor does not visit children on its own: the ``Add`` and
+``Mul`` overloads recurse by calling ``Dispatch`` on the operands, and the
+``Var`` and ``IntImm`` overloads end the recursion.
+
+**Unhandled node types fall back to a default method.** They go to
+``DispatchDefault_``, which raises an error unless we override it. Our
+override returns ``<other>``, so ``x - 1`` passes through instead of
+failing.
+:cpp:class:`tirx::StmtFunctor <tvm::tirx::StmtFunctor>` does the same for
+statements.
+
+.. note::
- n = T.dynamic("n", dtype="int32")
- B = T.Var("B", T.Tensor((n,), T.float32))
- i = T.dynamic("i", dtype="int32")
- A = T.Var("A", T.Tensor((n,), T.float32))
- B[i] = (A[i] + T.float32(1.0)) * T.float32(2.0)
+ The ``using ExprFunctor::Dispatch_;`` line keeps the overloads we did
+ not override visible, as usual for overloaded virtual functions in C++.
-The new store reuses the destination and indices of the old one, so the
-printer declares them as free variables first. ``store->value * 2`` turns
-the literal into a constant of the value's type, ``T.float32(2.0)``.
-Constructing nodes creates new objects; ``add_one`` itself is not modified.
+Dispatch looks at one node and recurses by hand; the structural utilities
+below walk whole programs for us.
Structural Utilities in C++
---------------------------
-The structural utilities from Python are available in C++ with the same
-behavior: :cpp:func:`ffi::StructuralWalk <tvm::ffi::StructuralWalk>`,
+The structural utilities are part of TVM-FFI and work on every node
+through its registered fields:
+:cpp:func:`ffi::StructuralWalk <tvm::ffi::StructuralWalk>`,
:cpp:func:`ffi::StructuralMap <tvm::ffi::StructuralMap>`,
:cpp:class:`ffi::StructuralEqual <tvm::ffi::StructuralEqual>`, and
-:cpp:class:`ffi::StructuralHash <tvm::ffi::StructuralHash>`. **What changes
-is how callbacks are written**:
+:cpp:class:`ffi::StructuralHash <tvm::ffi::StructuralHash>`. **Each piece
+takes a C++ form**:
.. list-table::
:header-rows: 1
- :widths: 25 35 40
+ :widths: 35 65
- * - Aspect
- - Python
- - C++
+ * - Piece
+ - C++ form
* - Nodes a callback receives
- - The type paired with it, such as ``(ir.TensorStore, f)``
- - The type of the callback's first parameter
+ - Selected by the type of the callback's first parameter
* - Walk callback result
- - ``None``, ``WalkResult.SKIP``, or a ``VisitInterrupt``
- ``ffi::Expected<WalkResult>``
* - Traversal order
- - ``order="pre"`` or the default post-order
- A required template argument, ``WalkOrder::kPreOrder`` or
``kPostOrder``
* - Keep a node in a map
- - Return the input node
- Return ``ffi::Unchanged()`` or the node
* - Result of a map
- - The new value
- An ``ffi::Any``, cast back with ``cast<T>()``
* - Definition region kind
- - Pass the callback through ``with_def_region_kind``
- A trailing ``TVMFFIDefRegionKind`` parameter
Structural Walk
~~~~~~~~~~~~~~~
-As in Python, a walk calls our callback on each node of the type it asks
-for. To find the tensors that ``add_one`` writes, the callback takes a
+A walk calls our callback on each node of the type it asks for. To find
+the tensors that ``add_one`` writes, the callback takes a
``const TensorStore&``:
.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
@@ -261,11 +457,11 @@ A walk callback returns an
the node's children in pre-order, and ``WalkResult::Interrupt(...)`` stops
the walk.
-To handle several node kinds in one walk, we pass one callback per kind as
-extra arguments. They are tried in
-declaration order, and only the first one whose parameter type matches a
-node runs; a node that matches none is still traversed but not reported.
-This walk records the loops and stores in pre-order:
+To handle several node types in one walk, we pass one callback per type as
+extra arguments. They are tried in declaration order, and only the first
+one whose parameter type matches a node runs; a node that matches none is
+still traversed but not reported. This walk records the loops and stores
+in pre-order:
.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
:language: cpp
@@ -307,10 +503,10 @@ Definitions and Uses
~~~~~~~~~~~~~~~~~~~~
A callback receives the definition region kind of each site when it takes
-a ``TVMFFIDefRegionKind`` as its last parameter. The kinds match Python's:
-``kTVMFFIDefRegionKindNone`` for a use, ``kTVMFFIDefRegionKindSimple`` for
-``DEF_SIMPLE``, and ``kTVMFFIDefRegionKindPattern`` for ``DEF_PATTERN``. Let's
list the definition sites in
-``add_one``:
+a ``TVMFFIDefRegionKind`` as its last parameter:
+``kTVMFFIDefRegionKindNone`` for a use, and ``kTVMFFIDefRegionKindSimple``
+and ``kTVMFFIDefRegionKindPattern`` for the two kinds of definition site.
+Let's list the definition sites in ``add_one``:
.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
:language: cpp
@@ -327,8 +523,8 @@ The output is:
n pattern
i simple
-These are the same sites as in Python: the parameters define ``A``, ``B``,
-and ``n`` by pattern, and the loop defines ``i``.
+The parameters define ``A``, ``B``, and ``n`` by pattern, and the loop
+defines ``i``.
Structural Map
~~~~~~~~~~~~~~
@@ -358,7 +554,7 @@ The output is:
For every other variable, the callback returns
:cpp:struct:`ffi::Unchanged <tvm::ffi::Unchanged>`\ ``()``, which keeps the
node as it is. The constant takes its type from the variable, ``var->ty``.
-As in Python, the mapper keeps definitions and uses consistent, so the new
+The mapper keeps definitions and uses consistent, so the new
``A`` and ``B`` and every use of them carry the specialized shape.
Equality and Hashing
@@ -367,7 +563,7 @@ Equality and Hashing
``ffi::StructuralEqual::Equal`` and ``ffi::StructuralHash::Hash`` compare
and hash by structure. Let's compare two ``add_one`` functions built
separately in Python by ``make_add(1)``, the helper from the structural
-utilities chapter:
+utilities guide:
.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
:language: cpp
@@ -382,15 +578,15 @@ The output is:
The functions are different objects, yet structurally equal with equal
hashes. ``Equal`` and ``Hash`` also take an optional ``map_free_vars``
-argument, which defaults to ``false`` as in Python.
+argument, which defaults to ``false``.
Visit and Mutate
~~~~~~~~~~~~~~~~
When a callback must decide which children to visit, we use
:cpp:func:`ffi::StructuralVisit <tvm::ffi::StructuralVisit>` and
-:cpp:func:`ffi::StructuralMutate <tvm::ffi::StructuralMutate>`, as in
-Python. Their callbacks also receive
+:cpp:func:`ffi::StructuralMutate <tvm::ffi::StructuralMutate>`. Their
+callbacks also receive
the visitor or mutator, such as
:cpp:class:`ffi::StructuralVisitorObj* <tvm::ffi::StructuralVisitorObj>`,
and descend into a node's children with ``DefaultVisitExpected`` or
@@ -399,8 +595,8 @@ and descend into a node's children with
``DefaultVisitExpected`` or
Visitor and Mutator Classes
---------------------------
-Walk and map cover most tasks. A pass that handles many kinds of node,
-however, reads better as a class with one method per kind:
+Walk and map cover most tasks. A pass that handles many node types,
+however, reads better as a class with one method per type:
.. list-table::
:header-rows: 1
@@ -411,26 +607,27 @@ however, reads better as a class with one method per kind:
- Use it for
* - Structural utilities
- Any TVM-FFI object
- - A few node kinds, written as callbacks
+ - A few node types, written as callbacks
* - :cpp:class:`tirx::StmtExprVisitor <tvm::tirx::StmtExprVisitor>`,
:cpp:class:`tirx::StmtExprMutator <tvm::tirx::StmtExprMutator>`
- TIRx statements and expressions (``tvm/tirx/stmt_functor.h``)
- - Passes that customize many node kinds
+ - Passes that customize many node types
* - :cpp:class:`ExprVisitor <tvm::ExprVisitor>`,
:cpp:class:`ExprMutator <tvm::ExprMutator>`
- Expressions alone (``tvm/ir/expr_functor.h``)
- Expression analyses and rewrites
* - :cpp:class:`ExprFunctor <tvm::ExprFunctor>`,
:cpp:class:`tirx::StmtFunctor <tvm::tirx::StmtFunctor>`
- - Dispatch on the node kind with a signature we choose, such as
+ - Dispatch on the node type with a signature we choose, such as
``int(const Expr&)``, without traversing children
- Computations where each hook decides which children to recurse into
-Each class declares a virtual hook for every node kind, named ``Visit_``
+Each class declares a virtual hook for every node type, named ``Visit_``
for a visitor and ``Mutate_`` for a mutator, and a subclass overrides only
-the kinds it cares about.
+the types it cares about. Unlike the functors, these classes traverse
+children for us.
-**These classes are built on the structural utilities.** A node kind
+**These classes are built on the structural utilities.** A node type
without a hook, such as a function, falls back to its structural traversal,
which hands each child back to our hooks.
@@ -441,8 +638,7 @@ which hands each child back to our hooks.
and ``ExprMutator`` from the mutator base behind ``StructuralMap``. Any
hook can read the definition region kind with ``def_region_kind()``.
-Let's record the loops around each write, as the structural visit example
-in Python did:
+Let's record the loops around each write:
.. literalinclude:: ../../examples/ir_guides/cpp/working_with_ir.cc
:language: cpp
@@ -457,7 +653,7 @@ The output is:
Our ``For`` hook pushes the loop variable, calls the base class hook to
visit the loop's bounds and body, then pops the variable. Calling the base
-hook plays the role of ``default_visit`` in Python, and returning its
+hook visits the children with their usual traversal, and returning its
result passes an interrupt from a child up to the caller. Visitors are
objects, so we allocate them with ``ffi::make_object``.
@@ -538,55 +734,53 @@ The functions are in
``tvm/tirx/structural_visit_with_constraint_context.h``
and ``tvm/tirx/structural_mutate_with_constraint_context.h``, and the classes
in ``tvm/tirx/stmt_functor_with_constraint_context.h``.
-These tools follow the same rules as in Python: IR is immutable, rewrites
-return new programs that share unchanged parts, and every utility respects
-definitions and uses. Because C++ and Python share the same objects, we can
-prototype a pass in Python and move parts of it to C++ as needed.
+Across these tools, IR is immutable, rewrites return new programs that
+share unchanged parts, and every utility respects definitions and uses.
+Because C++ and Python share the same objects, a pass can move between the
+two languages one function at a time.
Quick Reference
---------------
.. list-table::
:header-rows: 1
- :widths: 40 30 30
+ :widths: 45 55
- * - C++
+ * - Construct
- What it does
- - Python equivalent
- * - ``loop->var``, ``func->params``
+ * - ``PrimVar x("x", PrimType::Int(32))``, ``x * 2 + 1``
+ - Creates a node; builds an expression with operators
+ * - ``add->a``, ``loop->var``
- Reads a node's fields
- - ``loop.var``, ``func.params``
- * - ``stmt.as<ForObj>()``, ``stmt.as<For>()``,
- ``stmt.as_or_throw<For>()``
+ * - ``value.as<AddObj>()``, ``value.as<Add>()``,
+ ``value.as_or_throw<Add>()``
- Checks the node type and downcasts
- - ``isinstance(stmt, ir.For)``
- * - ``TensorStore(dest, indices, value)``, ``store->value * 2``
- - Creates a node; builds an expression with operators
- - ``ir.TensorStore(dest, indices, value)``, ``store.value * 2``
+ * - :cpp:class:`PrimExpr <tvm::PrimExpr>`, :cpp:class:`IntExpr
<tvm::IntExpr>`,
+ :cpp:class:`PrimVar <tvm::PrimVar>`
+ - Typed views that check an expression's ``ty``
+ * - ``ref.CopyOnWrite()->field = value``
+ - Changes a field, copying the object first if it is shared
+ * - :cpp:class:`ExprFunctor <tvm::ExprFunctor>`,
+ :cpp:class:`tirx::StmtFunctor <tvm::tirx::StmtFunctor>`
+ - One ``Dispatch_`` overload per node type, with explicit recursion
* - :cpp:func:`ffi::StructuralWalk <tvm::ffi::StructuralWalk>`\
``<ffi::WalkOrder::kPreOrder>(func, ...)``
- Walks with typed callbacks that return
``ffi::Expected<ffi::WalkResult>``
- - ``tvm_ffi.structural_walk(func, callbacks, order="pre")``
* - :cpp:func:`ffi::StructuralMap <tvm::ffi::StructuralMap>`\
``<order>(func, ...)``,
``ffi::Unchanged()``
- Rebuilds with replacements and returns an ``ffi::Any``
- - ``tvm_ffi.structural_map(func, callbacks)``
* - A trailing ``TVMFFIDefRegionKind`` parameter
- Receives the definition region kind
- - ``with_def_region_kind=``
* - :cpp:func:`ffi::StructuralEqual::Equal
<tvm::ffi::StructuralEqual::Equal>`,
:cpp:func:`ffi::StructuralHash::Hash <tvm::ffi::StructuralHash::Hash>`
- Compares and hashes by structure
- - ``tvm_ffi.structural_equal``, ``tvm_ffi.structural_hash``
* - :cpp:class:`tirx::StmtExprVisitor <tvm::tirx::StmtExprVisitor>`,
:cpp:class:`tirx::StmtExprMutator <tvm::tirx::StmtExprMutator>`,
:cpp:class:`ExprVisitor <tvm::ExprVisitor>`,
:cpp:class:`ExprMutator <tvm::ExprMutator>`
- - One ``Visit_`` or ``Mutate_`` hook per node kind
- - ``tvm_ffi.structural_visit``, ``tvm_ffi.structural_mutate``
+ - One ``Visit_`` or ``Mutate_`` hook per node type
* - ``TVM_FFI_STATIC_INIT_BLOCK``, ``refl::GlobalDef().def(...)``
- Registers C++ functions as global functions
- - ``tvm_ffi.register_global_func``
.. TVM-FFI C++ API page for ObjectRef, which the C++ reference does not
include.
diff --git a/docs/ir_guides/working_with_ir_in_rust.rst
b/docs/ir_guides/working_with_ir_in_rust.rst
index 6f86a0cd5..cb0e658e5 100644
--- a/docs/ir_guides/working_with_ir_in_rust.rst
+++ b/docs/ir_guides/working_with_ir_in_rust.rst
@@ -18,39 +18,24 @@
Working with IR in Rust
=======================
-The IR objects we have used so far in Python are TVM-FFI objects, and the
-same objects are available in Rust through the
-`tvm-tirx <https://crates.io/crates/tvm-tirx>`_ crate. A Rust function can
-receive a function written in TVMScript, read and rewrite it, and return
-the result to Python. Nothing is converted or copied along the way: Python
-and Rust hold references to the same native objects.
-
-This chapter assumes the concepts of the earlier chapters and shows their
-Rust form:
-
-- **Accessing and creating IR nodes**: read fields, branch on node types,
- and build new nodes.
-- **Structural utilities**: walk, map, and compare programs, with
- callbacks selected by their Rust parameter types.
-- **Visitors and mutators**: keep state across callbacks and control the
- traversal, with ``#[dispatch]`` structs and ``VisitCallbacks``.
+The `tvm-tirx <https://crates.io/crates/tvm-tirx>`_ crate lets a Rust
+function read, build, and rewrite TIRx IR. The function can receive a
+program written in TVMScript and return the result, and nothing is
+converted or copied along the way. This guide covers:
+
+- **TVM-FFI object system**: how IR nodes are represented and used in Rust.
+- **Structural utilities**: walk, map, and compare programs.
+- **Visitors and mutators**: keep state and control the traversal.
.. note::
- The runnable code in this chapter is under
+ The runnable code in this guide is under
`examples/ir_guides
<https://github.com/apache/tvm-tirx/tree/main/examples/ir_guides>`_
in the repository.
Setting Up
----------
-Throughout this chapter, we use the ``add_one`` function from Quick Start:
-
-.. 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 examples are packaged as ``tirx_ir_guide_examples`` under
`examples/ir_guides
<https://github.com/apache/tvm-tirx/tree/main/examples/ir_guides>`__.
When cargo is available, installing the package builds the Rust crate in
@@ -64,9 +49,8 @@ to build against that installation instead of fetching one
from PyPI:
pip install scikit-build-core
pip install --no-build-isolation -e examples/ir_guides
-Each example is a Rust function that takes ``add_one`` as its argument. A
-|static_init_block!|_ at the end of the crate registers each one as a
-global function under ``tirx_ir_guide_examples.rust``:
+A |static_init_block!|_ at the end of the crate registers each example as
+a global function under ``tirx_ir_guide_examples.rust``:
.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
:language: rust
@@ -75,78 +59,284 @@ global function under ``tirx_ir_guide_examples.rust``:
:dedent: 4
The package's ``tirx_ir_guide_examples.rust`` module loads the library and
-exposes these functions, so Python calls them by name:
+exposes these functions, so Python calls them by name. The driver
+``working_with_ir_in_rust.py`` calls each example this way and prints the
+result.
+
+The object system examples take no arguments: each builds its own IR in
+Rust. The later sections receive the ``add_one`` function from Quick
+Start, written in TVMScript:
+
+.. 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
import tirx_ir_guide_examples.rust
- tirx_ir_guide_examples.rust.inspect(add_one)
+ tirx_ir_guide_examples.rust.construct()
+ tirx_ir_guide_examples.rust.written_tensors(add_one)
+
+TVM-FFI Object System
+---------------------
+
+Every TIRx IR node is a TVM-FFI object. Rust IRs are typically built as
+enums and matched with ``match``, which works well when every node type is
+known in advance. TIRx is designed for **dynamic extension** instead: a
+library can add a new node type, for example a new statement for a
+hardware feature, and existing code keeps working on programs that contain
+it. Generic utilities such as walking, rewriting, comparing, and printing
+work on every node through its registered fields.
+
+TVM-FFI objects also work across languages. Python, C++, and Rust share
+the same native, immutable, reference-counted objects, so a program moves
+between them without conversion.
+
+**We designed the TVM-FFI object system to be ergonomic in Rust.** The
+key constructs are:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 70
+
+ * - Construct
+ - Purpose
+ * - Constructors, ``ex()``
+ - Build expressions with ordinary Rust operators
+ * - ``FooObj`` / ``Foo``
+ - Underlying object and its named managed reference: read fields
+ directly, clone cheaply
+ * - ``.into()``
+ - Convert to a parent type
+ * - |try_cast|_
+ - Convert to a child type, with a checked ``Result``
+ * - |match_any!|_
+ - Branch on the node type
+ * - |dispatch|_
+ - Process each node type in its own method, with shared state
+
+The subsections below introduce each construct.
+
+Constructing Objects
+~~~~~~~~~~~~~~~~~~~~
+
+**We build IR with constructors and ordinary Rust operators.** Writing
+``x * 2 + 1`` as nested constructor calls would bury the expression, so
+the crate lets us write it as we would in Rust. Let's build it:
+
+.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
+ :language: rust
+ :start-after: // [construct.begin]
+ :end-before: // [construct.end]
+
+The output is:
+
+.. code-block:: text
+
+ x * 2 + 1
+
+|Var::new|_ takes a name, a type, and a source location; ``UNKNOWN_LOC``
+means there is none. |ex|_ wraps ``x`` so that ``*`` and ``+`` build IR,
+and the literals ``2`` and ``1`` become constants of the type of ``x``.
+
+An operator can fail, for example on mismatched types, so ``ex`` carries
+the first error along, much like a chain of ``Result``\ s. ``.expr()``
+takes the result out and ``?`` passes an error on. |script|_ prints the
+node as TVMScript.
+
+We now have an expression; next, let's see what kind of Rust value it is.
+
+Objects and Managed References
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Every node type comes as a pair: an underlying object and a named
+managed reference.** The top of
+``x * 2 + 1`` is an addition, so let's convert the expression to ``Add``
+with ``try_cast``, which the next subsection explains, and read its two
+operands:
+
+.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
+ :language: rust
+ :start-after: // [objects.begin]
+ :end-before: // [objects.end]
+
+The output is:
+
+.. code-block:: text
+
+ a = x * 2
+ b = 1
+ same object: true
+
+``alias`` is the same object as ``add``: ``clone`` copies only the managed
+reference, and ``same_as`` compares identity, like ``Arc::ptr_eq``.
+
+|AddObj|_ is the **underlying object**: the struct that holds the fields.
|Add|_ is a **named managed reference**
+to it: an owning, reference-counted smart pointer, like ``Arc<AddObj>``,
+so cloning it is cheap. Functions take and return managed references, and
+a managed reference dereferences to its object, so fields read as ordinary
+struct fields: ``add.a``.
-The driver ``working_with_ir_in_rust.py`` calls each example this way and
-prints the result.
+We define a separate named type ``Add`` instead of using a plain pointer
+to ``AddObj`` because the named type carries the interface: constructors,
+methods, conversions to parent types, and the traits that let it pass
+through TVM-FFI functions. It can also impose additional constraints on
+the underlying object that the object alone does not express.
-Accessing and Creating IR Nodes
--------------------------------
+This is the newtype pattern. Simplified from the crate, the pair is:
-**Every IR node has two Rust types**: a handle such as |For|_, a
-reference-counted pointer that is cheap to clone, and the object it points
-to, such as |ForObj|_, which holds the fields. A handle dereferences to its
-object, so we read fields as ordinary struct fields.
+.. code-block:: rust
-Let's read ``add_one`` from its parameters down to the store in its loop.
-The statements of a body are general ``Stmt`` handles, and |match_any!|_
-branches on their actual node type, as ``match`` does on an enum:
+ #[repr(C)]
+ #[derive(Object)]
+ #[type_key = "prim.Add"]
+ pub struct AddObj {
+ base: ExprObj,
+ pub a: Expr,
+ pub b: Expr,
+ }
+
+ #[repr(C)]
+ #[derive(ObjectRef, Clone)]
+ pub struct Add {
+ base: ObjectArc<AddObj>,
+ }
+
+Rust has no inheritance; instead, ``#[repr(C)]`` puts the parent's object,
+``ExprObj``, first in ``AddObj``, so every addition is also an expression.
+``Add`` implements ``Deref`` to ``AddObj``, which is why ``add.a`` works.
+
+**Nodes are immutable.** As with data behind an ``Arc``, a managed
+reference gives read access only; to change a node, we build a new one.
+
+We reached ``Add`` with a cast; next, let's look at casts on their own.
+
+Casts
+~~~~~
+
+**Casts move a managed reference up and down the type hierarchy.** A
+function that takes any expression wants an ``Expr``, while reading the
+operands needs an ``Add``. ``.into()`` converts to a parent type through
+``From``/``Into`` and cannot fail. ``.try_cast()`` converts to a child
+type: like ``TryFrom``, it checks the node's actual type and returns a
+``Result``.
.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
:language: rust
- :start-after: // [inspect.begin]
- :end-before: // [inspect.end]
+ :start-after: // [casts.begin]
+ :end-before: // [casts.end]
The output is:
.. code-block:: text
- param A
- param B
- loop over i up to n
- store to B: A[i] + T.float32(1.0)
+ back to Add: x * 2 + 1
+ as Mul: Cannot convert from type `prim.Add` to `prim.Mul`
-Each arm names a handle type and binds the matching node to it; the arms
-are tried in order, and ``_`` takes everything else. Fields have the types
-we know from Python: ``params`` is an ``Array<Var>``, and the body of a
-loop is a ``SeqStmt`` whose ``seq`` holds its statements. |script|_ prints
-any node as TVMScript.
+``value`` is an ``Expr`` again, but the node behind it is still an
+addition, so the cast back to ``Add`` succeeds.
+
+What if we guess wrong? The cast to ``Mul`` returns an ``Err``, and its
+message names both type keys: the actual type ``prim.Add`` and the
+requested ``prim.Mul``.
.. note::
- A function's ``body`` is always a ``SeqStmt``. ``get`` on an array returns
- an error for an index out of range, and ``?`` passes it on.
+ ``try_cast`` consumes the managed reference it converts, so we clone
+ ``value`` before the first cast; the clone costs one reference-count
+ increment.
+
+Casting to one type at a time gets tedious when a node can be one of
+many; that is what matching is for.
+
+Matching Node Types
+~~~~~~~~~~~~~~~~~~~
+
+|match_any!|_ **branches on the actual type of a node**, as ``match`` does
+on an enum. Let's print an expression with explicit parentheses by
+matching each node and recursing into its operands:
+
+.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
+ :language: rust
+ :start-after: // [describe.begin]
+ :end-before: // [describe.end]
-To create a node, we call the constructor of its handle type, such as
-|TensorStore::new|_. |ex|_ wraps an expression so that the usual Rust
-operators build IR; constructors accept the result directly. Let's build a
store
-that writes twice the value of the store in ``add_one``:
+We call it on ``x * 2 + 1`` and on ``x - 1``:
.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
:language: rust
- :start-after: // [create.begin]
- :end-before: // [create.end]
+ :start-after: // [matching.begin]
+ :end-before: // [matching.end]
The output is:
-.. code-block:: python
+.. code-block:: text
+
+ ((x * 2) + 1)
+ <other>
+
+Each arm names a managed reference type and binds the matching node to it,
+and the first matching arm runs. The ``Add`` and ``Mul`` arms recurse into
+the operands, the ``Var`` and ``IntImm`` arms end the recursion, and
+``x - 1`` falls to the ``_`` arm because ``describe`` has no arm for
+subtraction.
+
+**The catch-all arm keeps existing code working as node types are added.**
+The set of node types is open, like a ``#[non_exhaustive]`` enum from
+another crate, so the match needs a ``_`` arm. A function handles the
+types it knows, and ``_`` lets programs with new types pass through.
+
+.. note::
+
+ Like ``try_cast``, ``match_any!`` consumes what it matches, so
+ ``describe`` passes it ``expr.clone()``. ``match_any!`` works on any
+ TVM-FFI object, such as tensors, shapes, and typed arrays, and on
+ ``Any`` values. Plain values such as integers take the ``_`` arm.
+
+A match looks at one node at a time; to process every node in a program
+while keeping state, we dispatch.
+
+Dispatching on Node Types
+~~~~~~~~~~~~~~~~~~~~~~~~~
- n = T.dynamic("n", dtype="int32")
- B = T.Var("B", T.Tensor((n,), T.float32))
- i = T.dynamic("i", dtype="int32")
- A = T.Var("A", T.Tensor((n,), T.float32))
- B[i] = (A[i] + T.float32(1.0)) * T.float32(2.0)
+|dispatch|_ **lets one struct process each node type in its own method,
+with shared state.** A compiler pass often needs one piece of logic per
+node type and state shared across them; ``#[dispatch]`` puts both on one
+struct. It works like a trait whose methods all have default bodies: we
+write methods for the node types we care about, and every other type gets
+the default behavior.
-The new store reuses the destination and indices of the old one, so the
-printer declares them as free variables first. Constructing nodes creates
-new objects; ``add_one`` itself is not modified. Here |try_cast|_ downcasts
-to a single known type instead of branching.
+``#[dispatch(walk)]`` on an ``impl`` block turns its ``walk_*`` methods
+into callbacks for |structural_walk|_, which visits every node. Each
+method borrows the nodes of its parameter type, and the methods are tried
+in source order. Let's count the variables and additions:
+
+.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
+ :language: rust
+ :start-after: // [counter.begin]
+ :end-before: // [counter.end]
+
+We walk ``x * 2 + 1`` with it. ``WalkResult::Advance`` continues into
+the node's children, and ``WalkOrder::PreOrder`` visits a node before its
+children:
+
+.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
+ :language: rust
+ :start-after: // [count.begin]
+ :end-before: // [count.end]
+
+The output is:
+
+.. code-block:: text
+
+ variables: 1, additions: 1
+
+**Node types without a method fall back to the default traversal**: the
+walk continues into their children, so new types pass through. Here the
+multiplication and the constants have no method, and the walk still
+reaches ``x`` inside the multiplication.
Structural Utilities
--------------------
@@ -154,44 +344,36 @@ Structural Utilities
The structural utilities are part of TVM-FFI, and the ``tvm_ffi`` crate,
re-exported as ``tvm_tirx::tvm_ffi``, provides them in Rust:
|structural_walk|_, |structural_map|_, |structural_visit|_, and
-|structural_mutate|_. They run on the same structural hooks as in Python,
-so they reach the same nodes and keep definitions and uses consistent in
-the same way. **What changes is the Rust form of each piece**:
+|structural_mutate|_. They work on every node through its registered
+fields and keep definitions and uses consistent. **Each piece takes a Rust
+form**:
.. list-table::
:header-rows: 1
- :widths: 25 35 40
+ :widths: 35 65
- * - Aspect
- - Python
- - Rust
+ * - Piece
+ - Rust form
* - Nodes a callback receives
- - The type paired with it, such as ``(ir.TensorStore, f)``
- - The type of the callback's parameter
+ - Selected by the type of the callback's parameter
* - Walk callback result
- - ``None``, ``WalkResult.SKIP``, or a ``VisitInterrupt``
- ``WalkResult``, or ``Result<WalkResult>`` to use ``?``
* - Traversal order
- - ``order="pre"`` or the default post-order
- A required argument, ``WalkOrder::PreOrder`` or ``PostOrder``
* - Result of a map
- - The new value
- An ``Any``, converted back with ``try_into``
* - Definition region kind
- - Pass the callback through ``with_def_region_kind``
- A trailing ``DefRegionKind`` parameter
* - Errors
- - Exceptions
- ``Result`` values
* - Structural equality
- - ``structural_equal``
- The global function ``ffi.StructuralEqual``
Structural Walk
~~~~~~~~~~~~~~~
-As in Python, a walk calls our callback on each node of the type it asks
-for. Let's find the tensors that ``add_one`` writes:
+A walk calls our callback on each node of the type it asks for. Let's find
+the tensors that ``add_one`` writes:
.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
:language: rust
@@ -220,7 +402,7 @@ The parameter list of a callback decides what it receives:
* - Callback
- Receives
* - ``|store: TensorStore|``
- - Each write, as a handle.
+ - Each write, as a managed reference.
* - ``|store: &TensorStoreObj|``
- Each write, as a borrowed object, without changing its reference
count.
@@ -272,9 +454,8 @@ The output is:
n Pattern
i Simple
-The kinds are the ones we saw in Python, under Rust names:
-``DefRegionKind::None`` for a use site, ``Pattern`` for ``DEF_PATTERN``,
-and ``Simple`` for ``DEF_SIMPLE``. ``structural_map`` callbacks take the
+``DefRegionKind::None`` marks a use site; ``Pattern`` and ``Simple`` are
+the two kinds of definition site. ``structural_map`` callbacks take the
same trailing parameter.
Structural Map
@@ -301,18 +482,16 @@ The output is:
for i in range(128):
B[i] = A[i] + T.float32(1.0)
-This is the same result as in Python. |make_const|_ builds the constant
-``128`` with the type of ``n``, and every other variable is returned as it
-is. ``structural_map`` takes ownership of the handle we pass and returns
-the new root as an ``Any``; Python still holds ``add_one``, which is
-unchanged.
+|make_const|_ builds the constant ``128`` with the type of ``n``, and
+every other variable is returned as it is. ``structural_map`` takes
+ownership of the managed reference we pass and returns the new root as an
+``Any``; Python still holds ``add_one``, which is unchanged.
Structural Equality
~~~~~~~~~~~~~~~~~~~
The crate has no Rust function for structural equality yet, so we call the
-global function that Python's ``structural_equal`` uses,
-``ffi.StructuralEqual``, with its four arguments: the two values,
+global function ``ffi.StructuralEqual`` with its four arguments: the two
values,
``map_free_vars``, and ``skip_tensor_content``. Let's specialize
``add_one`` twice and compare the results:
@@ -333,48 +512,17 @@ are structurally equal.
Visitors and Mutators in Rust
-----------------------------
-Rust has no separate layer of visitor and mutator classes. Stateful and
-typed traversals use the same four structural utilities, and the crate
-provides two conveniences to build them: |dispatch|_ turns the methods
-of a struct into typed callbacks, and |VisitCallbacks|_ and
-|MutateCallbacks|_ attach state to a tuple of callbacks.
-
-Typed Dispatch on a Struct
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The closures in a callback tuple cannot borrow the same state mutably at
-the same time, so callbacks that share state are written as methods
-instead. ``#[dispatch(walk)]`` on an ``impl`` block turns its ``walk_*``
-methods into callbacks: each method receives the nodes of its parameter
-type, and the methods are tried in source order. The struct holds the
-state. Let's record the loops and writes of ``add_one`` in the order the
-walk reaches them:
-
-.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
- :language: rust
- :start-after: // [dispatch_walk.begin]
- :end-before: // [dispatch_walk.end]
-
-Called with ``pre_order`` true and then false, the output is:
-
-.. code-block:: text
-
- ['loop i', 'write B']
- ['write B', 'loop i']
-
-Pre-order reports the loop before the write inside it, and post-order the
-reverse. A method may also take a trailing ``DefRegionKind``, as a closure
-can. ``#[dispatch(map)]``, ``#[dispatch(visit)]``, and
-``#[dispatch(mutate)]`` work the same way for ``map_*``, ``visit_*``, and
-``mutate_*`` methods.
-
-Visit and Mutate
-~~~~~~~~~~~~~~~~
+Stateful traversals use the same four structural utilities. The state
+lives either on a |dispatch|_ struct, as in Dispatching on Node Types, or
+in |VisitCallbacks|_ and |MutateCallbacks|_, which attach it to a tuple of
+callbacks. ``#[dispatch(map)]``, ``#[dispatch(visit)]``, and
+``#[dispatch(mutate)]`` work like ``#[dispatch(walk)]`` for ``map_*``,
+``visit_*``, and ``mutate_*`` methods.
-A visit or mutate callback takes control of its node's children, as in
-Python. Let's record the loops around each write. With ``VisitCallbacks``,
-each callback receives the node and a ``VisitContext``, which holds the
-shared state:
+**A visit or mutate callback takes control of its node's children.**
+Let's record the loops around each write. With ``VisitCallbacks``, each
+callback receives the node and a ``VisitContext``, which holds the shared
+state:
.. literalinclude:: ../../examples/ir_guides/rust/src/lib.rs
:language: rust
@@ -427,8 +575,7 @@ replacement before any use of ``i``.
``mutate_var`` replaces ``i`` only where ``def_region_kind()`` is
``None``, so the loop's own ``i`` stays a variable. |ObjectIdentity|_
- keys the map by object identity, as the Python version keys its
- dictionary by variable.
+ keys the map by object identity, so only this loop's ``i`` matches.
.. note::
@@ -447,88 +594,79 @@ Quick Reference
.. list-table::
:header-rows: 1
- :widths: 40 30 30
+ :widths: 45 55
- * - Rust
+ * - Construct
- What it does
- - Python equivalent
* - |match_any!|_
- Branches on the node type; the first matching arm runs
- - ``isinstance`` checks
* - |try_cast|_, |as_node|_
- - Downcasts to one type, as a ``Result`` handle or a borrowed
- ``Option``
- - ``isinstance(stmt, ir.For)``
- * - |TensorStore::new|_, |ex|_\ ``(...)``, ``.expr()``
+ - Downcasts to one type, as a managed reference in a ``Result`` or a
+ borrowed object in an ``Option``
+ * - ``.into()``
+ - Upcasts a managed reference to a parent type
+ * - |Var::new|_, |ex|_\ ``(...)``, ``.expr()``
- Creates a node; builds an expression with operators
- - ``ir.TensorStore(dest, indices, value)``, ``store.value * 2``
* - |structural_walk|_\ ``(&func, callbacks, WalkOrder::PreOrder)``
- Walks with typed callbacks that return ``WalkResult``
- - ``tvm_ffi.structural_walk(func, callbacks, order="pre")``
* - |structural_map|_\ ``(func, callbacks, order)``
- Rebuilds with replacements and returns an ``Any``
- - ``tvm_ffi.structural_map(func, callbacks)``
* - A trailing |DefRegionKind|_ parameter
- Receives the definition region kind
- - ``with_def_region_kind=``
* - ``Function::get_global("ffi.StructuralEqual")``
- Compares by structure
- - ``tvm_ffi.structural_equal``
* - |dispatch|_\ ``(walk)``, ``(map)``, ``(visit)``, ``(mutate)``
- Turns the methods of a struct into typed callbacks
- - A list of ``(type, callback)`` pairs
* - |VisitCallbacks|_, |MutateCallbacks|_
- Attach state to a tuple of visit or mutate callbacks
- - ``tvm_ffi.structural_visit``, ``tvm_ffi.structural_mutate``
* - |static_init_block!|_, |register_global_typed|_
- Registers Rust functions as global functions
- - ``tvm_ffi.register_global_func``
.. API pages of the tvm-tirx and tvm-ffi crates for the names above.
.. |static_init_block!| replace:: ``static_init_block!``
-.. _static_init_block!:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/macro.static_init_block.html
-.. |For| replace:: ``For``
-.. _For:
https://docs.rs/tvm-tirx/0.1.0-alpha.5/tvm_tirx/ir/stmt/struct.For.html
-.. |ForObj| replace:: ``ForObj``
-.. _ForObj:
https://docs.rs/tvm-tirx/0.1.0-alpha.5/tvm_tirx/ir/stmt/struct.ForObj.html
+.. _static_init_block!:
../reference/rust/generated/tvm_ffi/macro.static_init_block.html
+.. |AddObj| replace:: ``AddObj``
+.. _AddObj:
../reference/rust/generated/tvm_tirx/ir/prim/expr/struct.AddObj.html
+.. |Add| replace:: ``Add``
+.. _Add: ../reference/rust/generated/tvm_tirx/ir/prim/expr/struct.Add.html
.. |script| replace:: ``script``
-.. _script:
https://docs.rs/tvm-tirx/0.1.0-alpha.5/tvm_tirx/script/fn.script.html
-.. |try_cast| replace:: ``try_cast``
-.. _try_cast:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/object/trait.ObjectRefCast.html
+.. _script: ../reference/rust/generated/tvm_tirx/script/fn.script.html
+.. |try_cast| replace:: ``.try_cast()``
+.. _try_cast:
../reference/rust/generated/tvm_ffi/object/trait.ObjectRefCast.html
.. |structural_walk| replace:: ``structural_walk``
-.. _structural_walk:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/extra/structural_visit/fn.structural_walk.html
+.. _structural_walk:
../reference/rust/generated/tvm_ffi/extra/structural_visit/fn.structural_walk.html
.. |structural_map| replace:: ``structural_map``
-.. _structural_map:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/extra/structural_mutate/fn.structural_map.html
+.. _structural_map:
../reference/rust/generated/tvm_ffi/extra/structural_mutate/fn.structural_map.html
.. |structural_visit| replace:: ``structural_visit``
-.. _structural_visit:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/extra/structural_visit/fn.structural_visit.html
+.. _structural_visit:
../reference/rust/generated/tvm_ffi/extra/structural_visit/fn.structural_visit.html
.. |structural_mutate| replace:: ``structural_mutate``
-.. _structural_mutate:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/extra/structural_mutate/fn.structural_mutate.html
+.. _structural_mutate:
../reference/rust/generated/tvm_ffi/extra/structural_mutate/fn.structural_mutate.html
.. |WalkResult| replace:: ``WalkResult``
-.. _WalkResult:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/extra/structural_visit/enum.WalkResult.html
+.. _WalkResult:
../reference/rust/generated/tvm_ffi/extra/structural_visit/enum.WalkResult.html
.. |DefRegionKind| replace:: ``DefRegionKind``
-.. _DefRegionKind:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/extra/structural_visit/enum.DefRegionKind.html
+.. _DefRegionKind:
../reference/rust/generated/tvm_ffi/extra/structural_visit/enum.DefRegionKind.html
.. |make_const| replace:: ``make_const``
-.. _make_const:
https://docs.rs/tvm-tirx/0.1.0-alpha.5/tvm_tirx/ir/prim/op/fn.make_const.html
+.. _make_const:
../reference/rust/generated/tvm_tirx/ir/prim/op/fn.make_const.html
.. |dispatch| replace:: ``#[dispatch]``
-.. _dispatch: https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/attr.dispatch.html
+.. _dispatch: ../reference/rust/generated/tvm_ffi/attr.dispatch.html
.. |VisitCallbacks| replace:: ``VisitCallbacks``
-.. _VisitCallbacks:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/extra/structural_visit/struct.VisitCallbacks.html
+.. _VisitCallbacks:
../reference/rust/generated/tvm_ffi/extra/structural_visit/struct.VisitCallbacks.html
.. |MutateCallbacks| replace:: ``MutateCallbacks``
-.. _MutateCallbacks:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/extra/structural_mutate/struct.MutateCallbacks.html
+.. _MutateCallbacks:
../reference/rust/generated/tvm_ffi/extra/structural_mutate/struct.MutateCallbacks.html
.. |ex| replace:: ``ex``
-.. _ex: https://docs.rs/tvm-tirx/0.1.0-alpha.5/tvm_tirx/ir/prim/op/fn.ex.html
+.. _ex: ../reference/rust/generated/tvm_tirx/ir/prim/op/fn.ex.html
.. |ObjectIdentity| replace:: ``ObjectIdentity``
-.. _ObjectIdentity:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/object/struct.ObjectIdentity.html
+.. _ObjectIdentity:
../reference/rust/generated/tvm_ffi/object/struct.ObjectIdentity.html
.. |StructuralVisitorWithConstraintContext| replace::
``StructuralVisitorWithConstraintContext``
-.. _StructuralVisitorWithConstraintContext:
https://docs.rs/tvm-tirx/0.1.0-alpha.5/tvm_tirx/tirx/struct.StructuralVisitorWithConstraintContext.html
+.. _StructuralVisitorWithConstraintContext:
../reference/rust/generated/tvm_tirx/tirx/struct.StructuralVisitorWithConstraintContext.html
.. |StructuralMutatorWithConstraintContext| replace::
``StructuralMutatorWithConstraintContext``
-.. _StructuralMutatorWithConstraintContext:
https://docs.rs/tvm-tirx/0.1.0-alpha.5/tvm_tirx/tirx/struct.StructuralMutatorWithConstraintContext.html
+.. _StructuralMutatorWithConstraintContext:
../reference/rust/generated/tvm_tirx/tirx/struct.StructuralMutatorWithConstraintContext.html
.. |match_any!| replace:: ``match_any!``
-.. _match_any!:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/macro.match_any.html
-.. |TensorStore::new| replace:: ``TensorStore::new``
-.. _TensorStore::new:
https://docs.rs/tvm-tirx/0.1.0-alpha.5/tvm_tirx/ir/stmt/struct.TensorStore.html#method.new
+.. _match_any!: ../reference/rust/generated/tvm_ffi/macro.match_any.html
+.. |Var::new| replace:: ``Var::new``
+.. _Var::new:
../reference/rust/generated/tvm_tirx/ir/expr/struct.Var.html#method.new
.. |as_node| replace:: ``as_node``
-.. _as_node:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/object/trait.ObjectRefCore.html#method.as_node
+.. _as_node:
../reference/rust/generated/tvm_ffi/object/trait.ObjectRefCore.html#method.as_node
.. |register_global_typed| replace:: ``Function::register_global_typed``
-.. _register_global_typed:
https://docs.rs/tvm-ffi/0.1.15-post2/tvm_ffi/function/struct.Function.html#method.register_global_typed
+.. _register_global_typed:
../reference/rust/generated/tvm_ffi/function/struct.Function.html#method.register_global_typed
diff --git a/examples/ir_guides/cpp/working_with_ir.cc
b/examples/ir_guides/cpp/working_with_ir.cc
index 2cd25810c..e1b8d0479 100644
--- a/examples/ir_guides/cpp/working_with_ir.cc
+++ b/examples/ir_guides/cpp/working_with_ir.cc
@@ -18,11 +18,11 @@
*/
/*!
* \file working_with_ir.cc
- * \brief C++ fragments that inspect, traverse, and rewrite add_one.
+ * \brief C++ fragments that build IR, and that traverse and rewrite add_one.
*
- * Each function receives IR objects from Python and is registered as the
- * global function tirx_ir_guide_examples.cpp.<name>; working_with_ir_in_cpp.py
- * calls each function on add_one.
+ * Each function is registered as the global function
+ * tirx_ir_guide_examples.cpp.<name>; working_with_ir_in_cpp.py calls the
object
+ * system functions without arguments and the others on add_one.
*/
// [includes.begin]
#include <tvm/ffi/extra/structural_equal.h>
@@ -30,10 +30,12 @@
#include <tvm/ffi/extra/structural_mutate.h>
#include <tvm/ffi/extra/structural_visit.h>
#include <tvm/ffi/reflection/registry.h>
+#include <tvm/ir/expr_functor.h>
#include <tvm/tirx/function.h>
#include <tvm/tirx/stmt_functor.h>
// [includes.end]
+#include <optional>
#include <sstream>
#include <string>
#include <unordered_map>
@@ -43,31 +45,100 @@ namespace {
using namespace tvm;
-// [inspect.begin]
-ffi::String Inspect(const tirx::Function& func) {
+/*! \brief Print an object the way TVMScript writes it. */
+std::string Print(const ffi::ObjectRef& node) {
std::ostringstream os;
- for (const Var& param : func->params) {
- os << "param " << param->name << "\n";
+ os << node;
+ return os.str();
+}
+
+// [construct.begin]
+PrimExpr XTimes2Plus1() {
+ PrimVar x("x", PrimType::Int(32));
+ return x * 2 + 1;
+}
+
+ffi::String Construct() { return Print(XTimes2Plus1()); }
+// [construct.end]
+
+// [objects.begin]
+ffi::Array<ffi::String> Objects() {
+ prim::Add add = XTimes2Plus1().as_or_throw<prim::Add>();
+ prim::Add alias = add;
+ return {"a = " + Print(add->a), "b = " + Print(add->b),
+ std::string("same object: ") + (alias.same_as(add) ? "true" :
"false")};
+}
+// [objects.end]
+
+// [cow.begin]
+ffi::Array<ffi::String> CopyOnWrite() {
+ prim::Add add = XTimes2Plus1().as_or_throw<prim::Add>();
+ prim::Add changed = add;
+ changed.CopyOnWrite()->b = 3;
+ return {"add = " + Print(add), "changed = " + Print(changed)};
+}
+// [cow.end]
+
+// [casts.begin]
+ffi::Array<ffi::String> Casts() {
+ Expr value = XTimes2Plus1();
+ const prim::AddObj* node = value.as<prim::AddObj>();
+ std::optional<prim::Add> add = value.as<prim::Add>();
+ std::optional<prim::Mul> mul = value.as<prim::Mul>();
+ ffi::Array<ffi::String> lines = {
+ std::string("as<AddObj>: ") + (node != nullptr ? "pointer" : "nullptr"),
+ std::string("as<Add>: ") + (add.has_value() ? "Add" : "nullopt"),
+ std::string("as<Mul>: ") + (mul.has_value() ? "Mul" : "nullopt")};
+ try {
+ value.as_or_throw<prim::Mul>();
+ } catch (const ffi::Error& err) {
+ lines.push_back("as_or_throw<Mul>: " + std::string(err.message()));
}
- SeqStmt body = func->body;
- if (const ForObj* loop = body[0].as<ForObj>()) {
- os << "loop over " << loop->var.as<VarObj>()->name << " up to " <<
loop->end << "\n";
- if (const TensorStoreObj* store = loop->body[0].as<TensorStoreObj>()) {
- os << " store to " << store->dest.as<VarObj>()->name << ": " <<
store->value;
- }
+ return lines;
+}
+// [casts.end]
+
+// [views.begin]
+ffi::Array<ffi::String> TypedViews() {
+ Var i("i", PrimType::Int(32));
+ Var f("f", PrimType::Float(32));
+ ffi::Array<ffi::String> lines = {
+ std::string("i as PrimExpr: ") + (i.as<PrimExpr>().has_value() ? "yes" :
"no"),
+ std::string("i as IntExpr: ") + (i.as<IntExpr>().has_value() ? "yes" :
"no"),
+ std::string("f as IntExpr: ") + (f.as<IntExpr>().has_value() ? "yes" :
"no")};
+ try {
+ f.as_or_throw<IntExpr>();
+ } catch (const ffi::Error& err) {
+ lines.push_back("as_or_throw<IntExpr>: " + std::string(err.message()));
}
- return os.str();
+ return lines;
}
-// [inspect.end]
+// [views.end]
+
+// [describe.begin]
+class Describe : public ExprFunctor<std::string(const Expr&)> {
+ public:
+ using ExprFunctor::Dispatch_;
+
+ std::string Dispatch_(const prim::AddObj* add) override {
+ return "(" + Dispatch(add->a) + " + " + Dispatch(add->b) + ")";
+ }
+ std::string Dispatch_(const prim::MulObj* mul) override {
+ return "(" + Dispatch(mul->a) + " * " + Dispatch(mul->b) + ")";
+ }
+ std::string Dispatch_(const VarObj* var) override { return var->name; }
+ std::string Dispatch_(const IntImmObj* imm) override { return
Print(ffi::GetRef<IntImm>(imm)); }
+ std::string DispatchDefault_(const ffi::Object*) override { return
"<other>"; }
+};
+// [describe.end]
-// [create.begin]
-TensorStore DoubleStore(const tirx::Function& func) {
- For loop = func->body[0].as_or_throw<For>();
- TensorStore store = loop->body[0].as_or_throw<TensorStore>();
- PrimExpr doubled = store->value * 2;
- return TensorStore(store->dest, store->indices, doubled);
+// [dispatch_use.begin]
+ffi::Array<ffi::String> Dispatching() {
+ PrimVar x("x", PrimType::Int(32));
+ Describe describe;
+ return {describe(XTimes2Plus1()), describe(x - 1)};
}
-// [create.end]
+// [dispatch_use.end]
// [walk.begin]
ffi::Array<ffi::String> TensorsWritten(const tirx::Function& func) {
@@ -209,8 +280,12 @@ tirx::Function ReverseLoop(const tirx::Function& func) {
TVM_FFI_STATIC_INIT_BLOCK() {
namespace refl = tvm::ffi::reflection;
refl::GlobalDef()
- .def("tirx_ir_guide_examples.cpp.inspect", Inspect)
- .def("tirx_ir_guide_examples.cpp.double_store", DoubleStore)
+ .def("tirx_ir_guide_examples.cpp.construct", Construct)
+ .def("tirx_ir_guide_examples.cpp.objects", Objects)
+ .def("tirx_ir_guide_examples.cpp.copy_on_write", CopyOnWrite)
+ .def("tirx_ir_guide_examples.cpp.casts", Casts)
+ .def("tirx_ir_guide_examples.cpp.typed_views", TypedViews)
+ .def("tirx_ir_guide_examples.cpp.dispatching", Dispatching)
.def("tirx_ir_guide_examples.cpp.tensors_written", TensorsWritten)
.def("tirx_ir_guide_examples.cpp.trace_statements", TraceStatements)
.def("tirx_ir_guide_examples.cpp.find_write", FindWrite)
diff --git a/examples/ir_guides/rust/src/lib.rs
b/examples/ir_guides/rust/src/lib.rs
index 29fd682ab..1f100d28b 100644
--- a/examples/ir_guides/rust/src/lib.rs
+++ b/examples/ir_guides/rust/src/lib.rs
@@ -17,15 +17,16 @@
* under the License.
*/
-//! Functions that read, traverse, and rewrite `add_one` from Rust.
+//! Functions that build IR, and that read, traverse, and rewrite `add_one`,
from Rust.
//! See docs/ir_guides/working_with_ir_in_rust.rst. Each function is
registered as the global
-//! function `tirx_ir_guide_examples.rust.<name>`; working_with_ir_in_rust.py
calls each on `add_one`.
+//! function `tirx_ir_guide_examples.rust.<name>`; working_with_ir_in_rust.py
calls the object
+//! system functions without arguments and the others on `add_one`.
use std::collections::HashMap;
-use tvm_tirx::ir::prim::{ex, make_const};
+use tvm_tirx::ir::prim::{ex, make_const, Add, AddObj, Mul};
use tvm_tirx::ir::{
- Expr, For, ForObj, PrimType, Stmt, TensorStore, TensorStoreObj, Var,
UNKNOWN_LOC,
+ Expr, For, ForObj, IntImm, PrimType, TensorStore, TensorStoreObj, Var,
VarObj, UNKNOWN_LOC,
};
use tvm_tirx::script::script;
use tvm_tirx::tirx::Function;
@@ -37,49 +38,73 @@ use tvm_tirx::tvm_ffi::{
/// A Python list of strings.
type Strings = Array<tvm_ffi::String>;
-// [inspect.begin]
-fn inspect(func: Function) -> Result<tvm_ffi::String> {
- let mut lines = Vec::new();
- for param in func.params.iter() {
- lines.push(format!("param {}", param.name.as_str()));
- }
- let body = &func.body;
- for stmt in body.seq.iter() {
- describe(stmt, "", &mut lines)?;
+/// The lines of a printout, for Python.
+fn lines(items: impl IntoIterator<Item = String>) -> Strings {
+ items.into_iter().map(tvm_ffi::String::from).collect()
+}
+
+// [construct.begin]
+fn x_times_2_plus_1() -> Result<(Var, Expr)> {
+ let x = Var::new("x", PrimType::int(32), UNKNOWN_LOC);
+ let expr = (ex(&x) * 2 + 1).expr()?;
+ Ok((x, expr))
+}
+
+fn construct() -> Result<tvm_ffi::String> {
+ let (_, expr) = x_times_2_plus_1()?;
+ script(&expr)
+}
+// [construct.end]
+
+// [objects.begin]
+fn objects() -> Result<Strings> {
+ let (_, expr) = x_times_2_plus_1()?;
+ let add: Add = expr.try_cast()?;
+ let alias = add.clone();
+ Ok(lines([
+ format!("a = {}", script(&add.a)?.as_str()),
+ format!("b = {}", script(&add.b)?.as_str()),
+ format!("same object: {}", alias.same_as(&add)),
+ ]))
+}
+// [objects.end]
+
+// [casts.begin]
+fn casts() -> Result<Strings> {
+ let (_, expr) = x_times_2_plus_1()?;
+ let add: Add = expr.try_cast()?;
+ let value: Expr = add.into();
+ let again: Add = value.clone().try_cast()?;
+ let mut out = vec![format!("back to Add: {}", script(&again)?.as_str())];
+ if let Err(err) = value.try_cast::<Mul>() {
+ out.push(format!("as Mul: {}", err.message()));
}
- Ok(lines.join("\n").into())
+ Ok(lines(out))
}
+// [casts.end]
-fn describe(stmt: Stmt, indent: &str, lines: &mut Vec<String>) -> Result<()> {
- match_any! {
- stmt {
- For(loop_) => {
- let (var, end) = (loop_.var.name.as_str(),
script(&loop_.end)?);
- lines.push(format!("{indent}loop over {var} up to {}",
end.as_str()));
- for child in loop_.body.seq.iter() {
- describe(child, &format!("{indent} "), lines)?;
- }
- },
- TensorStore(store) => {
- let (dest, value) = (script(&store.dest)?,
script(&store.value)?);
- lines.push(format!("{indent}store to {}: {}", dest.as_str(),
value.as_str()));
- },
- _ => lines.push(format!("{indent}other statement")),
+// [describe.begin]
+fn describe(expr: &Expr) -> Result<String> {
+ let text = match_any! {
+ expr.clone() {
+ Add(add) => format!("({} + {})", describe(&add.a)?,
describe(&add.b)?),
+ Mul(mul) => format!("({} * {})", describe(&mul.a)?,
describe(&mul.b)?),
+ Var(var) => var.name.as_str().to_owned(),
+ IntImm(imm) => imm.value.to_string(),
+ _ => "<other>".to_owned(),
}
- }
- Ok(())
+ };
+ Ok(text)
}
-// [inspect.end]
+// [describe.end]
-// [create.begin]
-fn double_store(func: Function) -> Result<TensorStore> {
- let body = &func.body;
- let loop_: For = body.seq.get(0)?.try_cast()?;
- let store: TensorStore = loop_.body.seq.get(0)?.try_cast()?;
- let doubled = ex(&store.value) * 2;
- TensorStore::new(&store.dest, store.indices.iter(), doubled, UNKNOWN_LOC)
+// [matching.begin]
+fn matching() -> Result<Strings> {
+ let (x, expr) = x_times_2_plus_1()?;
+ let difference = (ex(&x) - 1).expr()?;
+ Ok(lines([describe(&expr)?, describe(&difference)?]))
}
-// [create.end]
+// [matching.end]
// [walk.begin]
fn written_tensors(func: Function) -> Result<Strings> {
@@ -144,32 +169,35 @@ fn compare_specialized(func: Function, n: Var) ->
Result<Array<bool>> {
}
// [equal.end]
-// [dispatch_walk.begin]
+// [counter.begin]
#[derive(Default)]
-struct StatementTrace {
- events: Vec<String>,
+struct Counter {
+ vars: usize,
+ adds: usize,
}
#[dispatch(walk)]
-impl StatementTrace {
- fn walk_for(&mut self, loop_: &ForObj) -> WalkResult {
- self.events.push(format!("loop {}", loop_.var.name.as_str()));
+impl Counter {
+ fn walk_var(&mut self, _var: &VarObj) -> WalkResult {
+ self.vars += 1;
WalkResult::Advance
}
- fn walk_store(&mut self, store: &TensorStoreObj) -> Result<WalkResult> {
- self.events.push(format!("write {}", script(&store.dest)?.as_str()));
- Ok(WalkResult::Advance)
+ fn walk_add(&mut self, _add: &AddObj) -> WalkResult {
+ self.adds += 1;
+ WalkResult::Advance
}
}
+// [counter.end]
-fn trace_statements(func: Function, pre_order: bool) -> Result<Strings> {
- let order = if pre_order { WalkOrder::PreOrder } else {
WalkOrder::PostOrder };
- let mut trace = StatementTrace::default();
- tvm_ffi::structural_walk(&func, &mut trace, order)?;
- Ok(trace.events.iter().map(tvm_ffi::String::from).collect())
+// [count.begin]
+fn count() -> Result<tvm_ffi::String> {
+ let (_, expr) = x_times_2_plus_1()?;
+ let mut counter = Counter::default();
+ tvm_ffi::structural_walk(&expr, &mut counter, WalkOrder::PreOrder)?;
+ Ok(format!("variables: {}, additions: {}", counter.vars,
counter.adds).into())
}
-// [dispatch_walk.end]
+// [count.end]
// [visit.begin]
#[derive(Default)]
@@ -234,14 +262,29 @@ fn reverse_loops(func: Function) -> Result<Function> {
tvm_ffi::static_init_block! {
tvm_ffi::Function::register_global_typed(
- "tirx_ir_guide_examples.rust.inspect",
- inspect,
- "Read the fields of a function.",
+ "tirx_ir_guide_examples.rust.construct",
+ construct,
+ "Build x * 2 + 1.",
)?;
tvm_ffi::Function::register_global_typed(
- "tirx_ir_guide_examples.rust.double_store",
- double_store,
- "Build a store that writes twice the value.",
+ "tirx_ir_guide_examples.rust.objects",
+ objects,
+ "Read the fields of an addition.",
+ )?;
+ tvm_ffi::Function::register_global_typed(
+ "tirx_ir_guide_examples.rust.casts",
+ casts,
+ "Cast an expression up and down.",
+ )?;
+ tvm_ffi::Function::register_global_typed(
+ "tirx_ir_guide_examples.rust.matching",
+ matching,
+ "Describe expressions by matching their nodes.",
+ )?;
+ tvm_ffi::Function::register_global_typed(
+ "tirx_ir_guide_examples.rust.count",
+ count,
+ "Count variables and additions with a dispatch struct.",
)?;
tvm_ffi::Function::register_global_typed(
"tirx_ir_guide_examples.rust.written_tensors",
@@ -268,11 +311,6 @@ tvm_ffi::static_init_block! {
compare_specialized,
"Compare two specializations.",
)?;
- tvm_ffi::Function::register_global_typed(
- "tirx_ir_guide_examples.rust.trace_statements",
- trace_statements,
- "Trace loops and writes.",
- )?;
tvm_ffi::Function::register_global_typed(
"tirx_ir_guide_examples.rust.loops_around_writes",
loops_around_writes,
diff --git a/examples/ir_guides/working_with_ir_in_cpp.py
b/examples/ir_guides/working_with_ir_in_cpp.py
index 9673f51fc..5dd8764d3 100644
--- a/examples/ir_guides/working_with_ir_in_cpp.py
+++ b/examples/ir_guides/working_with_ir_in_cpp.py
@@ -14,7 +14,7 @@
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.
-"""Call the C++ functions of tirx_ir_guide_examples on add_one.
+"""Call the C++ functions of tirx_ir_guide_examples.
Install the package first, building against the installed TIRx:
@@ -36,20 +36,34 @@ def add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,),
T.float32)):
B[i] = A[i] + 1
-summary = tirx_ir_guide_examples.cpp.inspect(add_one)
-print(summary)
-assert summary.splitlines() == [
- "param A",
- "param B",
- "loop over i up to n",
- " store to B: A[i] + T.float32(1.0)",
+# The object system examples build their own IR and take no arguments.
+print(tirx_ir_guide_examples.cpp.construct())
+print("\n".join(tirx_ir_guide_examples.cpp.objects()))
+print("\n".join(tirx_ir_guide_examples.cpp.copy_on_write()))
+print("\n".join(tirx_ir_guide_examples.cpp.casts()))
+print("\n".join(tirx_ir_guide_examples.cpp.typed_views()))
+print("\n".join(tirx_ir_guide_examples.cpp.dispatching()))
+assert tirx_ir_guide_examples.cpp.construct() == "x * 2 + 1"
+assert list(tirx_ir_guide_examples.cpp.objects()) == ["a = x * 2", "b = 1",
"same object: true"]
+assert list(tirx_ir_guide_examples.cpp.copy_on_write()) == [
+ "add = x * 2 + 1",
+ "changed = x * 2 + 3",
]
+assert list(tirx_ir_guide_examples.cpp.casts()) == [
+ "as<AddObj>: pointer",
+ "as<Add>: Add",
+ "as<Mul>: nullopt",
+ "as_or_throw<Mul>: Cannot treat type `prim.Add` as type `prim.Mul`",
+]
+assert list(tirx_ir_guide_examples.cpp.typed_views()) == [
+ "i as PrimExpr: yes",
+ "i as IntExpr: yes",
+ "f as IntExpr: no",
+ "as_or_throw<IntExpr>: Cannot treat type `ir.Var[ty=float32]` as type
`ir.IntExpr`",
+]
+assert list(tirx_ir_guide_examples.cpp.dispatching()) == ["((x * 2) + 1)",
"<other>"]
-doubled = tirx_ir_guide_examples.cpp.double_store(add_one)
-print(doubled.script())
-assert isinstance(doubled, ir.TensorStore)
-assert not doubled.same_as(add_one.body.seq[0].body.seq[0]) # add_one is
unchanged
-
+# The remaining examples take add_one.
writes = tirx_ir_guide_examples.cpp.tensors_written(add_one)
print(list(writes))
assert list(writes) == ["B"]
diff --git a/examples/ir_guides/working_with_ir_in_rust.py
b/examples/ir_guides/working_with_ir_in_rust.py
index 8c4d32982..f034249b1 100644
--- a/examples/ir_guides/working_with_ir_in_rust.py
+++ b/examples/ir_guides/working_with_ir_in_rust.py
@@ -36,20 +36,24 @@ def add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,),
T.float32)):
B[i] = A[i] + 1
-summary = tirx_ir_guide_examples.rust.inspect(add_one)
-print(summary)
-assert summary.splitlines() == [
- "param A",
- "param B",
- "loop over i up to n",
- " store to B: A[i] + T.float32(1.0)",
+# The object system examples build their own IR and take no arguments.
+print(tirx_ir_guide_examples.rust.construct())
+assert tirx_ir_guide_examples.rust.construct() == "x * 2 + 1"
+
+print("\n".join(tirx_ir_guide_examples.rust.objects()))
+print("\n".join(tirx_ir_guide_examples.rust.casts()))
+print("\n".join(tirx_ir_guide_examples.rust.matching()))
+assert list(tirx_ir_guide_examples.rust.objects()) == ["a = x * 2", "b = 1",
"same object: true"]
+assert list(tirx_ir_guide_examples.rust.casts()) == [
+ "back to Add: x * 2 + 1",
+ "as Mul: Cannot convert from type `prim.Add` to `prim.Mul`",
]
+assert list(tirx_ir_guide_examples.rust.matching()) == ["((x * 2) + 1)",
"<other>"]
-doubled = tirx_ir_guide_examples.rust.double_store(add_one)
-print(doubled.script())
-assert isinstance(doubled, ir.TensorStore)
-assert not doubled.same_as(add_one.body.seq[0].body.seq[0]) # add_one is
unchanged
+print(tirx_ir_guide_examples.rust.count())
+assert tirx_ir_guide_examples.rust.count() == "variables: 1, additions: 1"
+# The remaining examples take add_one.
print(list(tirx_ir_guide_examples.rust.written_tensors(add_one)))
assert list(tirx_ir_guide_examples.rust.written_tensors(add_one)) == ["B"]
@@ -80,11 +84,6 @@ assert
list(tirx_ir_guide_examples.rust.definitions(add_one)) == [
print(list(tirx_ir_guide_examples.rust.compare_specialized(add_one, n)))
assert list(tirx_ir_guide_examples.rust.compare_specialized(add_one, n)) ==
[False, True]
-print(list(tirx_ir_guide_examples.rust.trace_statements(add_one, True)))
-print(list(tirx_ir_guide_examples.rust.trace_statements(add_one, False)))
-assert list(tirx_ir_guide_examples.rust.trace_statements(add_one, True)) ==
["loop i", "write B"]
-assert list(tirx_ir_guide_examples.rust.trace_statements(add_one, False)) ==
["write B", "loop i"]
-
print(list(tirx_ir_guide_examples.rust.loops_around_writes(add_one)))
assert list(tirx_ir_guide_examples.rust.loops_around_writes(add_one)) == ["B
inside [i]"]