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 436f2a720 [DOCS][RUST] Add a tvm-tirx extension tutorial (#122)
436f2a720 is described below
commit 436f2a720d8f19a66a92a47b111888416d70ef53
Author: Linzhang Li <[email protected]>
AuthorDate: Thu Oct 29 17:48:46 2026 -0400
[DOCS][RUST] Add a tvm-tirx extension tutorial (#122)
## Summary
This PR adds a tutorial on extending TIRx from Rust, in a new
documentation section, "Extending
TIRx: everything is a plugin". One running example, complex numbers,
covers the whole path:
- **Rust.** A Rust library defines a complex IR type, four operators,
and a pass that lowers them to
scalar arithmetic.
- **Python.** Python loads the library and writes a kernel with the new
type in TVMScript. It
compiles the kernel with LLVM through a pipeline that runs the pass, and
checks the result
against NumPy.
This PR is based on #121, which lets an `rs_class` type be constructed
without a `Placeholder`.
Until #121 merges, its commit also shows in this PR's diff.
### Chapters
- **Getting Started with Rust Extensions**
(`docs/advanced/extending_ir_in_rust.rst`)
- **Why Rust.** The C++ core stays stable, and an extension iterates on
its own. The extension
is a separate Rust library built on the `tvm-tirx` crate. It defines
types, operators and
passes on the same IR objects as C++ and Python, and loads without
rebuilding TIRx.
- **Setting up the project.** A `cdylib` crate that depends on
`tvm-tirx` by path, built with
`uv run --no-sync cargo build`.
- **The case study.** The kernel that multiplies two arrays of complex
numbers.
- **Defining Types, Operators, and Passes**
(`docs/advanced/defining_ir_extensions.rst`)
- **The type.** `ComplexType`, an `rs_class` type registered with
`register_type`.
- **The operators.** `complex`, `cmul`, `real` and `imag`, defined as
`OpDef` chains with Rust
type inference and validators.
- **The pass.** `LowerComplex`, built from three parts:
- a `#[dispatch(map)]` rewriter that `structural_map` runs over the
function;
- a second walk that rejects any complex value left over;
- `FunctionPass::new`, which wraps the function as a pass.
- **Using and Compiling the Extension**
(`docs/advanced/using_ir_extensions.rst`)
- **Loading.** The script loads the library and declares the `my_ext`
module for the builders.
- **Compiling.** The script registers a pipeline that runs the pass
before the default
lowering. Compiling with the default pipeline instead fails in LLVM code
generation.
- **Checking the result.** The script compares the outputs with NumPy.
---
docs/advanced/defining_ir_extensions.rst | 230 ++++++++++++++++++++
docs/advanced/extending_ir_in_rust.rst | 123 +++++++++++
docs/advanced/using_ir_extensions.rst | 112 ++++++++++
docs/index.rst | 9 +
docs/reference/rust/index.rst | 16 +-
examples/extension/.gitignore | 20 ++
examples/extension/CMakeLists.txt | 30 +++
examples/extension/Cargo.toml | 33 +++
examples/extension/README.md | 43 ++++
examples/extension/pyproject.toml | 33 +++
examples/extension/python/my_ext/__init__.py | 46 ++++
examples/extension/run_example.py | 65 ++++++
examples/extension/rustfmt.toml | 21 ++
examples/extension/src/lib.rs | 302 +++++++++++++++++++++++++++
tests/python/ir/test_op_rust.py | 186 +++++++++++++++--
15 files changed, 1250 insertions(+), 19 deletions(-)
diff --git a/docs/advanced/defining_ir_extensions.rst
b/docs/advanced/defining_ir_extensions.rst
new file mode 100644
index 000000000..1ba916634
--- /dev/null
+++ b/docs/advanced/defining_ir_extensions.rst
@@ -0,0 +1,230 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+.. http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Defining Types, Operators, and Passes
+=====================================
+
+In this chapter, we walk through the Rust library of the package set up in
+:doc:`extending_ir_in_rust`: a complex type, four operators, and a pass that
+lowers them to scalar arithmetic. The excerpts come from
+:download:`src/lib.rs <../../examples/extension/src/lib.rs>`, which also
contains
+the validation and traversal helpers they use.
+
+Defining a Type
+---------------
+
+``ComplexType`` has one field, ``elem``, the scalar type shared by the real and
+imaginary parts:
+
+.. literalinclude:: ../../examples/extension/src/lib.rs
+ :language: rust
+ :start-after: // begin type
+ :end-before: // end type
+
+As in C++, the type is defined in two parts: ``ComplexTypeObj`` is the object
+that holds the fields, and ``ComplexType`` is a reference-counted reference to
+it, which IR nodes store and functions pass around. ``base: TypeObj`` makes the
+object an IR type, and ``rs_class`` registers its fields for reflection,
through
+which Python and IR JSON loading construct the type as they construct a C++
one.
+
+``def_object_ref!(pub ComplexType, Type, ComplexTypeObj)`` defines the
+reference. Its arguments are:
+
+- ``pub ComplexType``: the name and visibility of the reference.
+- ``Type``: the reference to the parent object, ``TypeObj``. A ``ComplexType``
+ converts into a ``Type`` with ``into()`` wherever a ``Type`` is expected,
such
+ as the result of type inference.
+- ``ComplexTypeObj``: the object it refers to. A ``ComplexTypeObj`` converts
+ into a ``ComplexType`` with ``into()``, and a ``ComplexType`` dereferences to
+ it, so ``ty.elem`` reads the field.
+
+``infer_complex`` in the next section uses both conversions: it builds a
+``ComplexTypeObj``, turns it into a ``ComplexType``, and returns it as a
+``Type``.
+
+The ``static_init_block!`` runs ``register_type`` when the library loads, as a
+``TVM_FFI_STATIC_INIT_BLOCK`` does for C++, and Python then sees the type as
+``my_ext.Complex``.
+
+A ``ComplexType`` records the scalar type of the two parts, and a
+``complex(re, im)`` call supplies their values as its operands. ``elem`` can be
+any scalar float type, such as ``float32``, ``float64`` or ``bfloat16``; this
+tutorial uses ``float32``.
+
+Defining Operators
+------------------
+
+To support operations on the new type, we need to define new operators. In our
+case, complex arithmetic needs four: one builds a complex value from two
+scalars, one multiplies complex values, and two read the parts back as scalars
+so that results can be stored in ordinary ``float32`` buffers. Like the type,
+they are registered under the ``my_ext`` namespace:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 40 30
+
+ * - Operator
+ - Meaning
+ - Result type (``float32`` parts)
+ * - ``complex(re, im)``
+ - Construct a complex value
+ - ``my_ext.Complex(T.float32)``
+ * - ``cmul(z, w)``
+ - Multiply two complex values
+ - ``my_ext.Complex(T.float32)``
+ * - ``real(z)``
+ - Extract the real part
+ - ``T.float32``
+ * - ``imag(z)``
+ - Extract the imaginary part
+ - ``T.float32``
+
+The constructor is registered as an ``OpDef`` chain in a
+``static_init_block!``. Each step updates the operator registry, and the chain
+completes when its statement ends:
+
+.. literalinclude:: ../../examples/extension/src/lib.rs
+ :language: rust
+ :start-after: // begin constructor
+ :end-before: // end constructor
+
+``signature`` declares the arguments of the operator and of its Python and
+TVMScript builder. ``set_infer_type`` attaches a named Rust function that
+checks the arguments and computes the result type:
+
+.. literalinclude:: ../../examples/extension/src/lib.rs
+ :language: rust
+ :start-after: // begin inference
+ :end-before: // end inference
+
+``set_validator`` repeats these checks for a call whose result type is given
+explicitly rather than inferred. ``Pure`` marks the operator as computing a
+value without writing memory.
+
+``infer_complex`` requires both parts to be scalar floats of the same type, and
+converts neither. The other three operators follow the same pattern. ``cmul``
+requires two complex arguments of the same type and returns it; ``real`` and
+``imag`` require one and return its ``elem``. Passing an ordinary scalar to
``cmul`` therefore fails
+with ``TypeError: my_ext.cmul expects a complex value``.
+
+Writing a Pass
+--------------
+
+Although the new type and operators can be used like built-in ones when writing
+programs, the existing passes know nothing about them: they can neither
+optimize them further nor lower them to what the backend supports. We therefore
+add a pass of our own to handle them. In our case, ``LowerComplex`` applies
+three rewrite rules:
+
+.. code-block:: text
+
+ cmul(complex(a, b), complex(c, d)) -> complex(a*c - b*d, a*d + b*c)
+ real(complex(a, b)) -> a
+ imag(complex(a, b)) -> b
+
+A complex local variable ``z = complex(a, b)`` is split into two scalar
+variables, ``z_re = a`` and ``z_im = b``, and later uses of ``z`` resolve to
+that pair. This lets the rules apply to the step-by-step function from
+:doc:`extending_ir_in_rust`, whose loop body becomes:
+
+.. code-block:: python
+
+ z_re: T.let[T.float32] = A[i]
+ z_im: T.let[T.float32] = B[i]
+ w_re: T.let[T.float32] = C[i]
+ w_im: T.let[T.float32] = D[i]
+ product_re: T.let[T.float32] = z_re * w_re - z_im * w_im
+ product_im: T.let[T.float32] = z_re * w_im + z_im * w_re
+ R[i] = product_re
+ Im[i] = product_im
+
+Only scalar arithmetic remains. The pass refers to the four operators through
+handles:
+
+.. literalinclude:: ../../examples/extension/src/lib.rs
+ :language: rust
+ :start-after: // begin handles
+ :end-before: // end handles
+
+A handle names a registered operator and looks it up on first use.
+``CMUL.is(&call.op)`` tests whether a call's ``op`` is ``my_ext.cmul``, and
+``COMPLEX.get()?`` returns ``my_ext.complex`` to build a new call. ``Lowering``
+implements these rewrites with them:
+
+.. literalinclude:: ../../examples/extension/src/lib.rs
+ :language: rust
+ :start-after: // begin lowering
+ :end-before: // end lowering
+ :prepend: #[derive(Default)]
+ struct Lowering {
+ bindings: Vec<(Var, Var, Var)>,
+ }
+ impl Lowering {
+ fn parts(&self, expr: &Expr) -> Result<(Expr, Expr)> { ... }
+ }
+ #[dispatch(map)]
+ impl Lowering {
+ fn map_sequence(&mut self, seq: SeqStmt) -> SeqStmt { ... }
+ :append: }
+
+``bindings`` records each complex variable with its two scalar replacements,
+and ``parts`` reads the real and imaginary parts of an operand, either a
+``complex(re, im)`` call or a variable already split. ``#[dispatch(map)]``
+sends each node to the ``map_`` method of its type, and leaves other nodes
+unchanged: ``map_call`` applies the three rules, ``map_bind`` splits a complex
+binding, and ``map_sequence`` flattens the sequence that a split binding leaves
+inside another.
+
+The pass is built from an ordinary named function:
+
+.. literalinclude:: ../../examples/extension/src/lib.rs
+ :language: rust
+ :start-after: // begin function callback
+ :end-before: // end function callback
+
+It receives a function, its module, and the pass context, and returns the
+rewritten function; ``Some`` replaces the original. The first
``structural_map``
+walks the function with ``Lowering``. ``PostOrder`` visits children before
their
+parent, so the operands of ``cmul`` are lowered before ``cmul`` itself. The
+second ``structural_map`` only checks the result. It takes a tuple of three
+functions, and calls each on the nodes of its parameter type:
+
+.. code-block:: rust
+
+ /// Reject a complex type, wherever it appears: on a variable, a parameter
or an expression.
+ fn check_type(ty: Type) -> Result<Type> { ... }
+
+ /// Reject an expression whose type is complex.
+ fn check_expr(expr: Expr) -> Result<Expr> { ... }
+
+ /// Reject a call to one of the four complex operators that the rewrite did
not consume.
+ fn check_call_lowered(call: Call) -> Result<Call> { ... }
+
+Each returns its node unchanged and raises a ``ValueError`` on an unsupported
+use, such as a complex function parameter, so the pass reports such a use
+before code generation.
+
+Finally, ``FunctionPass::new`` wraps the function as a pass, and the factory is
+exported so that Python can call it as ``lib.lower_complex()``:
+
+.. literalinclude:: ../../examples/extension/src/lib.rs
+ :language: rust
+ :start-after: // begin pass
+ :end-before: // end pass
+
+Next, :doc:`using_ir_extensions` loads the library and compiles the function.
diff --git a/docs/advanced/extending_ir_in_rust.rst
b/docs/advanced/extending_ir_in_rust.rst
new file mode 100644
index 000000000..b637140e3
--- /dev/null
+++ b/docs/advanced/extending_ir_in_rust.rst
@@ -0,0 +1,123 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+.. http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Getting Started with Rust Extensions
+====================================
+
+.. note::
+
+ 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>`_.
+
+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
+get ready for the rest of the tutorial: a Python package for the extension and
+the example program it will compile.
+
+Why Rust
+--------
+
+TIRx is built on a stable C++ library for its IR, analysis, transformations,
+and code generation. In most cases, you work with it from Python: tensor
+programs are written as Python functions in TVMScript, then compiled and run
+directly.
+
+With agents, compiler development iterates quickly. Along the way, a project
may
+need new types and operators to describe its own concepts, such as a new number
+format or a hardware feature, and passes that lower them to what the backend
+supports. To support this, TIRx provides Rust bindings, the ``tvm-tirx`` crate,
+which let you define new types, operators, and passes on the same IR objects as
+C++ and Python. An extension is a separate Rust library that builds and loads
on
+its own, without changing the C++ library, so the C++ core stays stable while
+the extension iterates quickly. Once loaded, its types and operators can be
+written in TVMScript and its passes can run in Python compilation pipelines,
+just like built-in ones.
+
+Setting Up the Project
+----------------------
+
+An extension is shipped as a Python package that contains its Rust library, so
+it is installed and imported like any other package. The example package,
+``my-ext``, has this layout:
+
+.. code-block:: text
+
+ examples/extension/
+ ├── Cargo.toml # the Rust library, which depends on tvm-tirx
+ ├── src/lib.rs # the type, operators, and pass
+ ├── CMakeLists.txt # builds the library with cargo and installs it into
my_ext
+ ├── pyproject.toml # the Python package, built with scikit-build-core
+ ├── python/my_ext/ # loads the library and registers a compilation
pipeline
+ └── run_example.py # compiles and runs a function that uses the extension
+
+The Rust library is an ordinary crate that builds a shared library:
+
+.. literalinclude:: ../../examples/extension/Cargo.toml
+ :language: toml
+ :start-at: [lib]
+ :end-before: # Standalone crate
+
+``tvm-tirx`` re-exports TVM FFI as ``tvm_tirx::tvm_ffi``, so it is the only
+dependency.
+
+To build and install the package, follow :doc:`../dev/source_build` to install
+TIRx with LLVM enabled, and use Rust 1.84 or newer; the build looks for cargo
+in ``~/.cargo/bin``, where rustup installs it, and then on ``PATH``. Then, from
+the TIRx repository root:
+
+.. code-block:: bash
+
+ uv pip install scikit-build-core
+ uv pip install --no-build-isolation examples/extension
+
+``--no-build-isolation`` builds the package against the TIRx in the project
+environment: the cargo build runs its ``tvm-tirx-config`` and
+``tvm-ffi-config`` tools to find the native libraries, so the extension links
+the TIRx it runs with.
+
+Case Study: Complex Numbers
+---------------------------
+
+To show how to define new types, operators, and passes, we will use complex
+numbers as a running example throughout this tutorial: a complex type,
operators
+that build and multiply complex values, and a pass that expands complex
+multiplication into real arithmetic:
+
+.. math::
+
+ (a + bi)(c + di) = (ac - bd) + (ad + bc)i.
+
+The following function multiplies two arrays of complex numbers element by
+element. ``A`` and ``B`` hold the real and imaginary parts of the first
operand,
+``C`` and ``D`` those of the second:
+
+.. literalinclude:: ../../examples/extension/run_example.py
+ :language: python
+ :start-after: # begin kernel
+ :end-before: # end kernel
+
+``my_ext`` is the extension's Python package, which holds the builders of its
+type and operators; :doc:`using_ir_extensions` shows how it provides them.
``z``, ``w``, and ``product`` are complex
+values that exist only in the IR.
+The function's inputs and outputs are ordinary ``float32`` arrays, so no
+runtime storage format for complex numbers is needed.
+
+Next, :doc:`defining_ir_extensions` defines the type, operators, and pass this
+function uses, and :doc:`using_ir_extensions` compiles and runs it.
diff --git a/docs/advanced/using_ir_extensions.rst
b/docs/advanced/using_ir_extensions.rst
new file mode 100644
index 000000000..95b0454c3
--- /dev/null
+++ b/docs/advanced/using_ir_extensions.rst
@@ -0,0 +1,112 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+.. http://www.apache.org/licenses/LICENSE-2.0
+
+.. Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Using and Compiling the Extension
+=================================
+
+In this chapter, we look at the Python package that loads the library defined
+in :doc:`defining_ir_extensions`, then use it to compile the complex
+multiplication function and check the result against NumPy.
+
+The Python Package
+------------------
+
+In :doc:`defining_ir_extensions`, the type and operators were registered in
+static init blocks, which run as soon as the library loads. To write them in
+TVMScript, Python also needs a module that holds their builders. Definitions
+under ``tirx.`` go to ``T``, but an extension namespace such as ``my_ext`` is
+published only into a module that the extension declares. The package's
+:download:`__init__.py <../../examples/extension/python/my_ext/__init__.py>`
+therefore declares itself as that module before it loads the library:
+
+.. literalinclude:: ../../examples/extension/python/my_ext/__init__.py
+ :language: python
+ :start-after: # begin load
+ :end-before: # end load
+
+The two ``_init_exposed_*_api`` calls, internal to ``tvm_tirx.ir`` for now,
+publish the operators and the type into ``my_ext``; ``auto_emit_void_call``
+gives its builders the TVMScript behavior of the ``T`` builders.
+``load_lib_module`` finds the library that the package installs next to
+``__init__.py``. To parse printed IR that uses the extension, pass the package
+as well, as in ``extra_vars={"T": T, "my_ext": my_ext}``.
+
+The registered type and operators let the IR express complex values;
+``LowerComplex`` turns them into a form the backend can compile. The default
+pipeline does not know about the pass, so the package registers a pipeline,
+also named ``my_ext``, that runs it first:
+
+.. literalinclude:: ../../examples/extension/python/my_ext/__init__.py
+ :language: python
+ :start-after: # begin pipeline
+ :end-before: # end pipeline
+
+``lower_complex`` returns the pass that the library exports.
+
+Compile the Function
+--------------------
+
+:download:`run_example.py <../../examples/extension/run_example.py>` imports
+``my_ext``, which loads the library and registers the pipeline, and compiles
+the function from :doc:`extending_ir_in_rust` with it:
+
+.. literalinclude:: ../../examples/extension/run_example.py
+ :language: python
+ :start-after: # begin compile
+ :end-before: # end compile
+
+Compiling with the default pipeline instead fails in LLVM code generation,
+which has no complex type.
+
+Check the Result
+----------------
+
+A successful compilation shows that ``LowerComplex`` left no complex values for
+the backend. To check that its rewrite also computes the right numbers, the
+script runs the compiled function on random ``float32`` inputs and compares
+both outputs with NumPy's complex multiplication:
+
+.. literalinclude:: ../../examples/extension/run_example.py
+ :language: python
+ :start-after: # begin comparison
+ :end-before: # end comparison
+
+With the package installed as in :doc:`extending_ir_in_rust`, run the script:
+
+.. code-block:: bash
+
+ uv run --no-sync python examples/extension/run_example.py
+
+A successful run prints:
+
+.. code-block:: text
+
+ Complex multiplication matches NumPy.
+
+``tests/python/ir/test_op_rust.py`` runs the script too, and also checks
+printing and parsing, invalid calls, chained products, and that lowering leaves
+no complex types or operators.
+
+Next Steps
+----------
+
+Complex addition or conjugation needs one more operator and one more rewrite
+rule in ``LowerComplex``, registered and written the same way. The example
+keeps complex values inside a function: parameters and outputs are ordinary
+arrays, and complex numbers have no runtime storage format or calling
+convention. See the :doc:`Rust API reference <../reference/rust/index>` for
+the full Rust API.
diff --git a/docs/index.rst b/docs/index.rst
index 9a018804e..51071bd6d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -77,6 +77,15 @@ Table of Contents
compiler/symbolic_integer_analysis
+.. toctree::
+ :maxdepth: 1
+ :caption: Extending TIRx: everything is a plugin
+ :titlesonly:
+
+ advanced/extending_ir_in_rust
+ advanced/defining_ir_extensions
+ advanced/using_ir_extensions
+
.. toctree::
:maxdepth: 1
:caption: Reference
diff --git a/docs/reference/rust/index.rst b/docs/reference/rust/index.rst
index bd88642ad..1ca675b7a 100644
--- a/docs/reference/rust/index.rst
+++ b/docs/reference/rust/index.rst
@@ -21,8 +21,14 @@ Rust API
The ``tvm-tirx`` crate in ``rust/`` binds the TIRx compiler objects over TVM
FFI.
Its modules follow the Python package: ``tvm_tirx::ir`` is :doc:`tvm_tirx.ir
<../python/ir>`, ``tvm_tirx::tirx`` is :doc:`tvm_tirx.tirx <../python/tirx>`,
and so
-on. Operators can also be defined from Rust with its ``register_ops!`` macro,
as
-:doc:`tvm_tirx.backend.rust <../python/backend.rust>` loads them.
+on. Operators and types can also be defined from Rust in
``tvm_ffi::static_init_block!``
+blocks, which run when :doc:`tvm_tirx.backend.rust <../python/backend.rust>`
loads the
+library.
+
+The crate is built on the ``tvm-ffi`` crate, which provides the objects,
functions,
+containers and macros its API is written in. This site therefore also hosts the
+``tvm-ffi`` reference, so links between the two crates resolve here, against
the version
+TIRx is built with.
The reference is generated by ``cargo doc`` when the documentation is built
with
``BUILD_RUST_DOCS=1`` (see :doc:`../../dev/doc_build`).
@@ -38,7 +44,7 @@ Crates
- Description
* - 📦 `tvm-tirx <generated/tvm_tirx/index.html>`_
- The IR, TIRx, symbolic analysis, target, backend, runtime, codegen and
script
- bindings, the Rust IR constructors and operators, and ``register_ops!``.
+ bindings, and the Rust IR constructors and operators.
* - 📦 `tvm-ffi <generated/tvm_ffi/index.html>`_
- - The TVM FFI objects, functions and containers the bindings are built on,
- re-exported as ``tvm_tirx::tvm_ffi``.
+ - The TVM FFI objects, functions, containers and ``static_init_block!``
the
+ bindings are built on, re-exported as ``tvm_tirx::tvm_ffi``.
diff --git a/examples/extension/.gitignore b/examples/extension/.gitignore
new file mode 100644
index 000000000..7137982ad
--- /dev/null
+++ b/examples/extension/.gitignore
@@ -0,0 +1,20 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Cargo build output
+/target/
+/Cargo.lock
diff --git a/examples/extension/CMakeLists.txt
b/examples/extension/CMakeLists.txt
new file mode 100644
index 000000000..0be8356fe
--- /dev/null
+++ b/examples/extension/CMakeLists.txt
@@ -0,0 +1,30 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# scikit-build-core runs this to build the Rust library with cargo and install
it into my_ext.
+cmake_minimum_required(VERSION 3.18)
+project(my_ext LANGUAGES NONE)
+
+# rustup's cargo is preferred over an older one on PATH.
+find_program(CARGO cargo HINTS "$ENV{HOME}/.cargo/bin" REQUIRED)
+set(cargo_target_dir "${CMAKE_BINARY_DIR}/cargo")
+set(lib_name
"${CMAKE_SHARED_LIBRARY_PREFIX}my_ext${CMAKE_SHARED_LIBRARY_SUFFIX}")
+add_custom_target(my_ext ALL
+ COMMAND "${CMAKE_COMMAND}" -E env "CARGO_TARGET_DIR=${cargo_target_dir}"
+ "${CARGO}" build --release --manifest-path
"${CMAKE_CURRENT_SOURCE_DIR}/Cargo.toml"
+ USES_TERMINAL VERBATIM)
+install(FILES "${cargo_target_dir}/release/${lib_name}" DESTINATION my_ext)
diff --git a/examples/extension/Cargo.toml b/examples/extension/Cargo.toml
new file mode 100644
index 000000000..aa004ed92
--- /dev/null
+++ b/examples/extension/Cargo.toml
@@ -0,0 +1,33 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+[package]
+name = "my-ext"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+# The shared library that the Python package loads.
+crate-type = ["cdylib"]
+
+[dependencies]
+# The tvm-tirx crate is not published yet, so the extension depends on it by
path.
+tvm-tirx = { path = "../../rust" }
+
+# Standalone crate: not a member of any enclosing workspace.
+[workspace]
diff --git a/examples/extension/README.md b/examples/extension/README.md
new file mode 100644
index 000000000..df9a945d6
--- /dev/null
+++ b/examples/extension/README.md
@@ -0,0 +1,43 @@
+<!--- Licensed to the Apache Software Foundation (ASF) under one -->
+<!--- or more contributor license agreements. See the NOTICE file -->
+<!--- distributed with this work for additional information -->
+<!--- regarding copyright ownership. The ASF licenses this file -->
+<!--- to you under the Apache License, Version 2.0 (the -->
+<!--- "License"); you may not use this file except in compliance -->
+<!--- with the License. You may obtain a copy of the License at -->
+
+<!--- http://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!--- Unless required by applicable law or agreed to in writing, -->
+<!--- software distributed under the License is distributed on an -->
+<!--- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -->
+<!--- KIND, either express or implied. See the License for the -->
+<!--- specific language governing permissions and limitations -->
+<!--- under the License. -->
+
+# TIRx Extension Example
+
+A Python package, `my-ext`, that extends TIRx from Rust: a complex-number type,
+operators that build and multiply complex values, and a pass that lowers them
to
+scalar arithmetic. Importing `my_ext` loads the Rust library, provides the
+`my_ext.*` builders for TVMScript, and registers the `my_ext` compilation
+pipeline. The tutorial in `docs/advanced/` walks through the code.
+
+- `src/lib.rs`: the type, operators, and pass, built by cargo as a shared
library
+- `CMakeLists.txt`, `pyproject.toml`: build the library and install it into
the package
+- `python/my_ext/`: loads the library and registers the pipeline
+- `run_example.py`: compiles a function that uses the extension and checks it
against NumPy
+
+## Install and Run
+
+Install TIRx from source with LLVM enabled, and Rust 1.84 or newer. From the
+repository root:
+
+```bash
+uv pip install scikit-build-core
+uv pip install --no-build-isolation examples/extension
+uv run --no-sync python examples/extension/run_example.py
+```
+
+`--no-build-isolation` builds against the TIRx in the project environment,
+whose `tvm-tirx-config` and `tvm-ffi-config` the cargo build runs.
diff --git a/examples/extension/pyproject.toml
b/examples/extension/pyproject.toml
new file mode 100644
index 000000000..36a9f3e26
--- /dev/null
+++ b/examples/extension/pyproject.toml
@@ -0,0 +1,33 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+[project]
+name = "my-ext"
+version = "0.1.0"
+description = "A TIRx extension written in Rust: a complex type, its
operators, and a lowering pass"
+requires-python = ">=3.10"
+dependencies = ["apache-tvm-tirx"]
+
+[build-system]
+# apache-tvm-tirx provides tvm-tirx-config and tvm-ffi-config, which the cargo
build runs.
+requires = ["scikit-build-core>=0.11", "apache-tvm-tirx"]
+build-backend = "scikit_build_core.build"
+
+[tool.scikit-build]
+wheel.py-api = "py3"
+wheel.packages = ["python/my_ext"]
+cmake.build-type = "Release"
diff --git a/examples/extension/python/my_ext/__init__.py
b/examples/extension/python/my_ext/__init__.py
new file mode 100644
index 000000000..07ce41bb0
--- /dev/null
+++ b/examples/extension/python/my_ext/__init__.py
@@ -0,0 +1,46 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""The complex type and operators of the Rust library, and a pipeline that
lowers them."""
+
+from pathlib import Path
+
+from tvm_ffi.libinfo import load_lib_module
+
+from tvm_tirx import ir, tirx
+from tvm_tirx.ir._expose_api import _init_exposed_op_api,
_init_exposed_type_api
+from tvm_tirx.script.ir_builder.base import auto_emit_void_call
+
+# begin load
+_init_exposed_op_api("my_ext", __name__, wrapper=auto_emit_void_call)
+_init_exposed_type_api("my_ext", __name__)
+_LIB = load_lib_module("my-ext", "my_ext",
extra_lib_paths=[Path(__file__).parent])
+# end load
+
+
+def lower_complex() -> ir.transform.Pass:
+ """The pass that lowers complex values to scalar arithmetic."""
+ return _LIB.lower_complex()
+
+
+# begin pipeline
+def _pipeline(*, target=None):
+ lower, finalize_host, finalize_device = tirx.get_tir_pipeline("default",
target=target)
+ return ir.transform.Sequential([lower_complex(), lower]), finalize_host,
finalize_device
+
+
+tirx.register_tir_pipeline("my_ext", _pipeline)
+# end pipeline
diff --git a/examples/extension/run_example.py
b/examples/extension/run_example.py
new file mode 100644
index 000000000..4aa4a4648
--- /dev/null
+++ b/examples/extension/run_example.py
@@ -0,0 +1,65 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Compile a function that multiplies complex numbers with my_ext, and check
it against NumPy."""
+
+import my_ext
+import numpy as np
+
+import tvm_tirx
+from tvm_tirx import runtime
+from tvm_tirx.script import tirx as T
+
+# begin kernel
+N = 16
+
+
[email protected]
+def complex_product(
+ A: T.Tensor((N,), "float32"),
+ B: T.Tensor((N,), "float32"),
+ C: T.Tensor((N,), "float32"),
+ D: T.Tensor((N,), "float32"),
+ R: T.Tensor((N,), "float32"),
+ Im: T.Tensor((N,), "float32"),
+):
+ for i in range(N):
+ z = my_ext.complex(A[i], B[i])
+ w = my_ext.complex(C[i], D[i])
+ product = my_ext.cmul(z, w)
+ R[i] = my_ext.real(product)
+ Im[i] = my_ext.imag(product)
+
+
+# end kernel
+
+# begin compile
+compiled = tvm_tirx.compile(complex_product, target="llvm", pipeline="my_ext")
+# end compile
+
+# begin comparison
+rng = np.random.default_rng(0)
+a, b, c, d = rng.standard_normal((4, N)).astype("float32")
+inputs = [runtime.tensor(x) for x in (a, b, c, d)]
+real_out = runtime.empty((N,), "float32")
+imag_out = runtime.empty((N,), "float32")
+compiled(*inputs, real_out, imag_out)
+
+expected = (a + 1j * b) * (c + 1j * d)
+np.testing.assert_allclose(real_out.numpy(), expected.real, rtol=1e-5,
atol=1e-6)
+np.testing.assert_allclose(imag_out.numpy(), expected.imag, rtol=1e-5,
atol=1e-6)
+# end comparison
+print("Complex multiplication matches NumPy.")
diff --git a/examples/extension/rustfmt.toml b/examples/extension/rustfmt.toml
new file mode 100644
index 000000000..59604833f
--- /dev/null
+++ b/examples/extension/rustfmt.toml
@@ -0,0 +1,21 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Match the layout `tvm-ffi-stubgen --target rust` emits, so `cargo fmt` leaves
+# the generated blocks byte-identical and `tvm-ffi-stubgen --check` stays
clean.
+use_small_heuristics = "Max"
+reorder_imports = false
diff --git a/examples/extension/src/lib.rs b/examples/extension/src/lib.rs
new file mode 100644
index 000000000..e50168731
--- /dev/null
+++ b/examples/extension/src/lib.rs
@@ -0,0 +1,302 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+//! Complex values in the IR, lowered to ordinary scalar arithmetic.
+//! See docs/advanced/extending_ir_in_rust.rst; the my_ext Python package
loads this library.
+
+use tvm_tirx::ir::op_attr::CALL_EFFECT_KIND;
+use tvm_tirx::ir::prim::ex;
+use tvm_tirx::ir::sig::{self, PrimExpr};
+use tvm_tirx::ir::transform::{Pass, PassContext, PassInfo};
+use tvm_tirx::ir::{
+ dtype, register_type, Bind, Call, CallEffectKind, CallObj, Expr, IRModule,
Op, OpDef, OpHandle,
+ PrimType, SeqStmt, Stmt, Type, TypeObj, Var,
+};
+use tvm_tirx::tirx::transform::FunctionPass;
+use tvm_tirx::tirx::Function;
+use tvm_tirx::tvm_ffi::{
+ self, def_object_ref, dispatch, rs_class, Error, ObjectRefCast,
ObjectRefCore, Result,
+ WalkOrder,
+};
+
+// begin type
+/// A complex number whose real and imaginary parts share a scalar type.
+#[rs_class("my_ext.ComplexType", final)]
+pub struct ComplexTypeObj {
+ base: TypeObj,
+ pub elem: PrimType,
+}
+def_object_ref!(pub ComplexType, Type, ComplexTypeObj);
+
+tvm_ffi::static_init_block! {
+ register_type::<ComplexType>()?;
+}
+// end type
+
+fn type_error(message: &str) -> Error {
+ Error::new(tvm_ffi::TYPE_ERROR, message, "")
+}
+
+fn require(condition: bool, message: &str) -> Result<()> {
+ if condition {
+ Ok(())
+ } else {
+ Err(type_error(message))
+ }
+}
+
+fn check_call(call: &CallObj, count: usize) -> Result<()> {
+ require(call.args.len() == count, &format!("expected {count} value
arguments"))?;
+ require(call.ty_args.is_empty(), "type arguments are not supported")?;
+ require(call.attrs.is_none(), "call attributes are not supported")
+}
+
+/// The type of a part of a complex number: a scalar float, such as `float32`,
`float64` or
+/// `bfloat16`.
+fn float_part(ty: &Type) -> Result<PrimType> {
+ let elem: PrimType =
+ ty.clone().try_cast().map_err(|_| type_error("expected a scalar
float"))?;
+ let bits = elem.dtype.bits;
+ let float = elem.dtype == dtype::float(bits) || elem.dtype ==
dtype::bfloat(bits);
+ require(float, "expected a scalar float")?;
+ Ok(elem)
+}
+
+// begin inference
+fn infer_complex(call: &CallObj) -> Result<Type> {
+ check_call(call, 2)?;
+ let elem = float_part(&call.args.get(0)?.ty)?;
+ let im = float_part(&call.args.get(1)?.ty)?;
+ require(elem.dtype == im.dtype, "my_ext.complex expects parts of the same
type")?;
+ let ty: ComplexType = ComplexTypeObj::new(TypeObj::new(call.loc.clone()),
elem).into();
+ Ok(ty.into())
+}
+// end inference
+
+fn complex_arg(call: &CallObj, index: usize) -> Result<ComplexType> {
+ let op: Op = call.op.clone().try_cast()?;
+ let ty: ComplexType = call
+ .args
+ .get(index)?
+ .ty
+ .clone()
+ .try_cast()
+ .map_err(|_| type_error(&format!("{} expects a complex value",
op.name.as_str())))?;
+ float_part(&ty.elem.clone().into())?;
+ Ok(ty)
+}
+
+fn infer_cmul(call: &CallObj) -> Result<Type> {
+ check_call(call, 2)?;
+ let (a, b) = (complex_arg(call, 0)?, complex_arg(call, 1)?);
+ require(a.elem.dtype == b.elem.dtype, "my_ext.cmul expects complex values
of the same type")?;
+ Ok(a.into())
+}
+
+fn infer_part(call: &CallObj) -> Result<Type> {
+ check_call(call, 1)?;
+ Ok(complex_arg(call, 0)?.elem.clone().into())
+}
+
+// Explicit result types bypass inference, so validation checks the inputs and
result again.
+fn validate_call(call: &CallObj) -> Result<()> {
+ let expected = if COMPLEX.is(&call.op) {
+ infer_complex(call)?
+ } else if CMUL.is(&call.op) {
+ infer_cmul(call)?
+ } else {
+ infer_part(call)?
+ };
+ let matches: bool = tvm_ffi::cached_global_func!("ffi.StructuralEqual")
+ .call_tuple((&expected, &call.ty, false, false))?
+ .try_into()?;
+ require(matches, "incorrect result type for complex operator")
+}
+
+// begin constructor
+tvm_ffi::static_init_block! {
+ OpDef::new("my_ext.complex", "Construct the complex number re + im * i.")
+ .signature((
+ sig::arg::<PrimExpr>("re", "The real part."),
+ sig::arg::<PrimExpr>("im", "The imaginary part."),
+ ))
+ .set_infer_type(infer_complex)
+ .set_validator(validate_call)
+ .set_attr(CALL_EFFECT_KIND, CallEffectKind::Pure);
+}
+// end constructor
+
+tvm_ffi::static_init_block! {
+ OpDef::new("my_ext.cmul", "Multiply two complex numbers.")
+ .signature((
+ sig::arg::<Expr>("a", "The first complex value."),
+ sig::arg::<Expr>("b", "The second complex value."),
+ ))
+ .set_infer_type(infer_cmul)
+ .set_validator(validate_call)
+ .set_attr(CALL_EFFECT_KIND, CallEffectKind::Pure);
+ OpDef::new("my_ext.real", "Extract the real part of a complex number.")
+ .signature(sig::arg::<Expr>("z", "The complex value."))
+ .set_infer_type(infer_part)
+ .set_validator(validate_call)
+ .set_attr(CALL_EFFECT_KIND, CallEffectKind::Pure);
+ OpDef::new("my_ext.imag", "Extract the imaginary part of a complex
number.")
+ .signature(sig::arg::<Expr>("z", "The complex value."))
+ .set_infer_type(infer_part)
+ .set_validator(validate_call)
+ .set_attr(CALL_EFFECT_KIND, CallEffectKind::Pure);
+}
+
+// begin handles
+static COMPLEX: OpHandle = OpHandle::new("my_ext.complex");
+static CMUL: OpHandle = OpHandle::new("my_ext.cmul");
+static REAL: OpHandle = OpHandle::new("my_ext.real");
+static IMAG: OpHandle = OpHandle::new("my_ext.imag");
+// end handles
+
+#[derive(Default)]
+struct Lowering {
+ // Each complex local variable is replaced by two scalar local variables.
+ bindings: Vec<(Var, Var, Var)>,
+}
+
+impl Lowering {
+ fn parts(&self, expr: &Expr) -> Result<(Expr, Expr)> {
+ if let Some(call) = expr.as_node::<CallObj>() {
+ if COMPLEX.is(&call.op) {
+ return Ok((call.args.get(0)?, call.args.get(1)?));
+ }
+ }
+ for (var, re, im) in &self.bindings {
+ if var.same_as(expr) {
+ return Ok((re.clone().into(), im.clone().into()));
+ }
+ }
+ Err(Error::new(tvm_ffi::VALUE_ERROR, "LowerComplex cannot resolve
complex operand", ""))
+ }
+}
+
+#[dispatch(map)]
+impl Lowering {
+ fn map_sequence(&mut self, seq: SeqStmt) -> SeqStmt {
+ SeqStmt::new(seq.seq.iter(), seq.loc.clone())
+ }
+
+ // begin lowering
+ fn map_call(&mut self, call: Call) -> Result<Expr> {
+ if COMPLEX.is(&call.op) || CMUL.is(&call.op) || REAL.is(&call.op) ||
IMAG.is(&call.op) {
+ validate_call(&call)?;
+ }
+ if CMUL.is(&call.op) {
+ let (a, b) = self.parts(&call.args.get(0)?)?;
+ let (c, d) = self.parts(&call.args.get(1)?)?;
+ // (a + bi)(c + di) = (ac - bd) + (ad + bc)i
+ let re = ex(&a) * ex(&c) - ex(&b) * ex(&d);
+ let im = ex(&a) * ex(&d) + ex(&b) * ex(&c);
+ return Ok(Call::new(
+ None,
+ COMPLEX.get()?,
+ [re, im],
+ None,
+ Vec::<Type>::new(),
+ call.loc.clone(),
+ )?
+ .into());
+ }
+ if REAL.is(&call.op) || IMAG.is(&call.op) {
+ let (re, im) = self.parts(&call.args.get(0)?)?;
+ return Ok(if REAL.is(&call.op) { re } else { im });
+ }
+ Ok(call.into())
+ }
+
+ fn map_bind(&mut self, bind: Bind) -> Result<Stmt> {
+ if let Some(ty) = bind.var.ty.as_node::<ComplexTypeObj>() {
+ let (re, im) = self.parts(&bind.value)?;
+ let name = bind.var.name.as_str();
+ let re_var = Var::new(&format!("{name}_re"), ty.elem.clone(),
bind.var.loc.clone());
+ let im_var = Var::new(&format!("{name}_im"), ty.elem.clone(),
bind.var.loc.clone());
+ self.bindings.push((bind.var.clone(), re_var.clone(),
im_var.clone()));
+ let binds = [
+ Bind::new(re_var, re, bind.loc.clone())?,
+ Bind::new(im_var, im, bind.loc.clone())?,
+ ];
+ return Ok(SeqStmt::new(binds, bind.loc.clone()).into());
+ }
+ Ok(bind.into())
+ }
+ // end lowering
+}
+
+/// Reject a complex type, wherever it appears: on a variable, a parameter or
an expression.
+fn check_type(ty: Type) -> Result<Type> {
+ if ty.as_node::<ComplexTypeObj>().is_some() {
+ return Err(Error::new(
+ tvm_ffi::VALUE_ERROR,
+ "LowerComplex left an unsupported complex type",
+ "",
+ ));
+ }
+ Ok(ty)
+}
+
+/// Reject an expression whose type is complex.
+fn check_expr(expr: Expr) -> Result<Expr> {
+ check_type(expr.ty.clone())?;
+ Ok(expr)
+}
+
+/// Reject a call to one of the four complex operators that the rewrite did
not consume.
+fn check_call_lowered(call: Call) -> Result<Call> {
+ if COMPLEX.is(&call.op) || CMUL.is(&call.op) || REAL.is(&call.op) ||
IMAG.is(&call.op) {
+ return Err(Error::new(
+ tvm_ffi::VALUE_ERROR,
+ "LowerComplex left an unsupported complex call",
+ "",
+ ));
+ }
+ Ok(call)
+}
+
+// begin function callback
+fn lower_function(
+ func: Function,
+ _module: IRModule,
+ _ctx: PassContext,
+) -> Result<Option<Function>> {
+ let mut lowering = Lowering::default();
+ let rewritten = tvm_ffi::structural_map(func, &mut lowering,
WalkOrder::PostOrder)?;
+ let checked = tvm_ffi::structural_map(
+ rewritten,
+ (check_type, check_call_lowered, check_expr),
+ WalkOrder::PostOrder,
+ )?;
+ let function: Function = checked.try_into()?;
+ Ok(Some(function))
+}
+// end function callback
+
+// begin pass
+fn lower_complex() -> Result<Pass> {
+ let pass = FunctionPass::new(lower_function, PassInfo::new(0,
"my_ext.LowerComplex"));
+ Ok(Pass::from(&pass))
+}
+
+tvm_ffi::tvm_ffi_dll_export_typed_func!(lower_complex, lower_complex);
+// end pass
diff --git a/tests/python/ir/test_op_rust.py b/tests/python/ir/test_op_rust.py
index a72dd18b1..a3e5a1725 100644
--- a/tests/python/ir/test_op_rust.py
+++ b/tests/python/ir/test_op_rust.py
@@ -34,7 +34,10 @@ from pathlib import Path
import pytest
+import tvm_tirx
+
RUST_DIR = Path(__file__).resolve().parents[3] / "rust"
+EXTENSION_DIR = RUST_DIR.parent / "examples" / "extension"
def find_cargo():
@@ -54,29 +57,51 @@ def find_cargo():
return None
[email protected](scope="module")
-def define_ir_library():
- """The example library of Rust operators and types, built by cargo."""
+def cargo_build(manifest, *args):
+ """Build with cargo in rust/'s target directory, shared with the crate,
and return the
+ directory of the debug build."""
cargo = find_cargo()
if cargo is None or not shutil.which("tvm-ffi-config") or not
shutil.which("tvm-tirx-config"):
pytest.skip(
"building rust/ needs a cargo as new as its rust-version, and
tvm-ffi-config and "
"tvm-tirx-config on PATH"
)
- manifest = RUST_DIR / "Cargo.toml"
- subprocess.run(
- [cargo, "build", "--manifest-path", str(manifest), "--example",
"define_ir"], check=True
- )
target_dir = Path(os.environ.get("CARGO_TARGET_DIR", RUST_DIR / "target"))
- name = {"darwin": "libdefine_ir.dylib", "win32": "define_ir.dll"}.get(
- sys.platform, "libdefine_ir.so"
- )
- return target_dir / "debug" / "examples" / name
+ env = {**os.environ, "CARGO_TARGET_DIR": str(target_dir)}
+ subprocess.run([cargo, "build", "--manifest-path", str(manifest), *args],
check=True, env=env)
+ return target_dir / "debug"
+
+
+def library_name(name):
+ """The file name of the shared library that cargo builds for `name`."""
+ return {"darwin": f"lib{name}.dylib", "win32":
f"{name}.dll"}.get(sys.platform, f"lib{name}.so")
+
+
+def build_rust_example(example):
+ """Build an example library of Rust operators and types with cargo."""
+ debug_dir = cargo_build(RUST_DIR / "Cargo.toml", "--example", example)
+ return debug_dir / "examples" / library_name(example)
+
+
[email protected](scope="module")
+def define_ir_library():
+ """The example library of Rust operators and types, built by cargo."""
+ return build_rust_example("define_ir")
+
+
[email protected](scope="module")
+def extension_package(tmp_path_factory):
+ """The my_ext package of examples/extension, laid out as its wheel
installs it."""
+ debug_dir = cargo_build(EXTENSION_DIR / "Cargo.toml")
+ root = tmp_path_factory.mktemp("extension")
+ package = shutil.copytree(EXTENSION_DIR / "python" / "my_ext", root /
"my_ext")
+ shutil.copy(debug_dir / library_name("my_ext"), package)
+ return root
-def run_python(*code, libraries):
- """Run `code` in a fresh interpreter, with the paths of `libraries` as its
arguments, and
- return its standard error.
+def run_python(*code, libraries=(), python_path=()):
+ """Run `code` in a fresh interpreter, with the paths of `libraries` as its
arguments and
+ `python_path` before PYTHONPATH, and return its standard error.
The code runs from a file: TVMScript reads the source of the functions it
parses, which Python
keeps for code passed with `-c` only from 3.13 on.
@@ -84,11 +109,13 @@ def run_python(*code, libraries):
with tempfile.TemporaryDirectory() as tmp:
script = Path(tmp) / "script.py"
script.write_text("\n".join(textwrap.dedent(part) for part in code))
+ paths = [*map(str, python_path), *filter(None,
[os.environ.get("PYTHONPATH")])]
result = subprocess.run(
[sys.executable, str(script), *map(str, libraries)],
capture_output=True,
text=True,
check=False,
+ env={**os.environ, "PYTHONPATH": os.pathsep.join(paths)},
)
assert result.returncode == 0, result.stderr
return result.stderr
@@ -138,6 +165,131 @@ ROUND_TRIP = """
"""
+# Checks of the extension beyond those of its example script: the type,
printing and parsing,
+# invalid calls, chained products, float64 parts, and what the lowering
rejects.
+EXTENSION_CHECKS = """
+ # Run after examples/extension/run_example.py, whose names it uses.
+ import tvm_ffi
+ from tvm_tirx import ir, tirx
+
+ # Inspect the registered type and round-trip the IR through text and JSON.
+ a_var, b_var = ir.Var("a", "float32"), ir.Var("b", "float32")
+ z = my_ext.complex(a_var, b_var)
+ assert isinstance(z.ty, my_ext.Complex)
+ assert tvm_ffi.structural_equal(z.ty.elem, ir.PrimType("float32"))
+ assert tvm_ffi.structural_equal(ir.load_json(ir.save_json(z.ty)), z.ty)
+ text = complex_product.script()
+ parsed = tvm_tirx.script.parse(text, extra_vars={"T": T, "my_ext": my_ext})
+ assert tvm_ffi.structural_equal(parsed, complex_product)
+ assert
tvm_ffi.structural_equal(ir.load_json(ir.save_json(complex_product)),
complex_product)
+ for name in ("complex", "cmul", "real", "imag"):
+ op = ir.Op.get(f"my_ext.{name}")
+ assert op.get_attr("TCallEffectKind") == ir.CallEffectKind.Pure
+ assert getattr(my_ext, name).__doc__ == op.doc
+
+ lower = my_ext.lower_complex()
+ lowered = lower(ir.IRModule({"main": complex_product}))
+ assert "my_ext." not in lowered["main"].script()
+
+
+ for original, tensor in zip((a, b, c, d), inputs):
+ np.testing.assert_array_equal(tensor.numpy(), original)
+
+
+ # Further checks stay out of the tutorial's code slices.
+ def expect_error(error_type, message, function, *args):
+ try:
+ function(*args)
+ except error_type as error:
+ assert message in str(error), str(error)
+ else:
+ raise AssertionError(f"expected {error_type.__name__}: {message}")
+
+
+ # The parts are scalar floats of one type; nothing is converted or
promoted.
+ for dtype in ("int32", "float32x4"):
+ wrong = ir.Var("wrong", dtype)
+ expect_error(TypeError, "expected a scalar float", my_ext.complex,
wrong, b_var)
+ expect_error(TypeError, "expected a scalar float", my_ext.complex,
a_var, wrong)
+ wide = ir.Var("wide", "float64")
+ expect_error(TypeError, "parts of the same type", my_ext.complex, a_var,
wide)
+ z64 = my_ext.complex(wide, wide)
+ assert tvm_ffi.structural_equal(z64.ty, my_ext.Complex(T.float64))
+ assert tvm_ffi.structural_equal(my_ext.real(z64).ty, T.float64)
+ expect_error(TypeError, "complex values of the same type", my_ext.cmul, z,
z64)
+ brain = ir.Var("brain", "bfloat16")
+ assert tvm_ffi.structural_equal(my_ext.complex(brain, brain).ty,
my_ext.Complex(T.bfloat16))
+ expect_error(TypeError, "cmul expects a complex value", my_ext.cmul,
a_var, z)
+ expect_error(TypeError, "cmul expects a complex value", my_ext.cmul, z,
a_var)
+ expect_error(TypeError, "real expects a complex value", my_ext.real, a_var)
+ expect_error(TypeError, "imag expects a complex value", my_ext.imag, a_var)
+
+ # Explicit result types must not let invalid calls escape validation.
+ for name, args in (("complex", [a_var, b_var]), ("cmul", [z, z]), ("real",
[z]), ("imag", [z])):
+ invalid = ir.Call(f"my_ext.{name}", args, ty="int32")
+ expect_error(TypeError, "incorrect result type", invalid.validate)
+ invalid = ir.Call("my_ext.cmul", [a_var, z], ty=z.ty)
+ expect_error(TypeError, "expects a complex value", invalid.validate)
+ bad_type = my_ext.Complex(T.int32)
+ expect_error(TypeError, "expected a scalar float", my_ext.real,
ir.Var("bad", bad_type))
+
+ # Complex function parameters and unconsumed complex values are outside
this lowering.
+ unsupported = tirx.Function([ir.Var("z", z.ty)],
ir.SeqStmt([ir.Evaluate(0)]))
+ expect_error(ValueError, "unsupported complex type", lower,
ir.IRModule({"main": unsupported}))
+ unsupported = tirx.Function([a_var, b_var], ir.SeqStmt([ir.Evaluate(z)]))
+ expect_error(ValueError, "unsupported complex", lower,
ir.IRModule({"main": unsupported}))
+
+
+ # Aliases, chained products and inline constructors take the same lowering
path.
+ @T.function
+ def cube(
+ A: T.Tensor((N,), "float32"),
+ B: T.Tensor((N,), "float32"),
+ R: T.Tensor((N,), "float32"),
+ Im: T.Tensor((N,), "float32"),
+ ):
+ for i in range(N):
+ z = my_ext.complex(A[i], B[i])
+ alias = z
+ square = my_ext.cmul(alias, z)
+ R[i] = my_ext.real(my_ext.cmul(square, my_ext.complex(A[i], B[i])))
+ Im[i] = my_ext.imag(my_ext.cmul(square, z))
+
+
+ cube_lowered = lower(ir.IRModule({"main": cube}))
+ assert "my_ext." not in cube_lowered["main"].script()
+ cube_compiled = tvm_tirx.compile(cube, target="llvm", pipeline="my_ext")
+ cube_compiled(*inputs[:2], real_out, imag_out)
+ expected_cube = (a + 1j * b) ** 3
+ np.testing.assert_allclose(real_out.numpy(), expected_cube.real,
rtol=1e-5, atol=1e-6)
+ np.testing.assert_allclose(imag_out.numpy(), expected_cube.imag,
rtol=1e-5, atol=1e-6)
+
+
+ # The same lowering handles float64 parts.
+ @T.function
+ def product64(
+ A: T.Tensor((N,), "float64"),
+ B: T.Tensor((N,), "float64"),
+ R: T.Tensor((N,), "float64"),
+ Im: T.Tensor((N,), "float64"),
+ ):
+ for i in range(N):
+ z = my_ext.complex(A[i], B[i])
+ product = my_ext.cmul(z, z)
+ R[i] = my_ext.real(product)
+ Im[i] = my_ext.imag(product)
+
+
+ a64, b64 = rng.standard_normal((2, N))
+ real64, imag64 = runtime.empty((N,), "float64"), runtime.empty((N,),
"float64")
+ product64_compiled = tvm_tirx.compile(product64, target="llvm",
pipeline="my_ext")
+ product64_compiled(runtime.tensor(a64), runtime.tensor(b64), real64,
imag64)
+ expected64 = (a64 + 1j * b64) ** 2
+ np.testing.assert_allclose(real64.numpy(), expected64.real, rtol=1e-12)
+ np.testing.assert_allclose(imag64.numpy(), expected64.imag, rtol=1e-12)
+"""
+
+
def test_library_is_loaded_on_import():
"""``import tvm_tirx`` loads libtvm_tirx_rust, when the build has it, as a
backend."""
from tvm_ffi.libinfo import _find_library_by_basename # pylint:
disable=import-outside-toplevel
@@ -152,6 +304,12 @@ def test_library_is_loaded_on_import():
assert "tvm_tirx_rust" in _LOADED_LIBS
[email protected](not tvm_tirx.runtime.enabled("llvm"), reason="LLVM is not
enabled")
+def test_extension_example(extension_package):
+ script = EXTENSION_DIR / "run_example.py"
+ run_python(script.read_text(), EXTENSION_CHECKS,
python_path=[extension_package])
+
+
def test_rust_operators_are_registered_by_their_library(define_ir_library):
run_python(
"""