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 a63362c4b [DOCS][IR] Operators, Calls, and Regions; Op.register; enum
display in format_tree (#136)
a63362c4b is described below
commit a63362c4b6cce8d6d923d59cf55d43996bc6ab0b
Author: Tianqi Chen <[email protected]>
AuthorDate: Fri Oct 30 21:49:28 2026 -0400
[DOCS][IR] Operators, Calls, and Regions; Op.register; enum display in
format_tree (#136)
This PR rewrites `docs/ir/operators_and_calls.rst` around operators as
the main extension point of TIRx, and adds `ir.Op.register` so Python
code can define an operator without the internal FFI function.
**API**
- `ir.Op.register(name, doc)` adds an operator to the global registry
and returns it. The operator starts with an empty signature and no
attributes. Registering a name twice raises `AttributeError`. A test is
added in `tests/python/ir/test_attrs.py`.
- `ir.format_tree` renders enums as `EnumType(NAME)`. FFI enums such as
`MemoryScope` used to print their private fields
(`MemoryScope(_int_index=1, _str_index='shared')`) and now print
`MemoryScope(shared)` on the parent's line. `For.kind` used to print as
an int (`kind=3`) and now prints `ForKind(UNROLLED)`. Unknown loop kinds
still print as ints. One test is added and two loop-kind assertions are
updated.
**Docs** (new title: Operators, Calls, and Regions)
- `ir.Op`: a named, shared operator, and how a call uses it.
- Operator Attributes: attributes are named maps from operators to
values, and they are extensible. Passes find operators through
attributes, so a new operator works with existing passes and a new pass
can add attributes to existing operators. Includes a table of common
keys.
- Defining an Operator: a brief `Op.register` example with a signature,
effect kind, and type rule, plus `expose()`. A note points to the Rust
extension guide for the full example.
- Regions: region operators via
`FRegionGetBodyParams`/`FRegionValidate`, using `tirx.device_entry` and
its launch configuration as the example.
- Call fields, `ty_args`, `attrs`, and function calls are now covered in
Types and Expressions (#135). The overview's description of this chapter
is updated.
All 6 snippets run against `apache-tvm-tirx` 0.1.0a6 with this `op.py`,
and the 5 printed outputs match the page. `tests/python/ir` passes (87
passed, 6 skipped).
---
docs/index.rst | 2 +-
docs/ir/operators_and_calls.rst | 483 --------------------------------
docs/ir/operators_calls_and_regions.rst | 293 +++++++++++++++++++
docs/ir/overview.rst | 4 +-
docs/ir/statements.rst | 2 +-
docs/ir/types_and_expressions.rst | 2 +-
python/tvm_tirx/ir/format_tree.py | 8 +-
python/tvm_tirx/ir/op.py | 30 ++
tests/python/ir/test_attrs.py | 15 +
tests/python/ir/test_ir_format_tree.py | 9 +-
10 files changed, 357 insertions(+), 491 deletions(-)
diff --git a/docs/index.rst b/docs/index.rst
index d72f2b01d..76d8901c6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -50,7 +50,7 @@ Table of Contents
ir/overview
ir/types_and_expressions
ir/statements
- ir/operators_and_calls
+ ir/operators_calls_and_regions
ir/functions_and_modules
ir/printing_and_parsing
diff --git a/docs/ir/operators_and_calls.rst b/docs/ir/operators_and_calls.rst
deleted file mode 100644
index 239e282a6..000000000
--- a/docs/ir/operators_and_calls.rst
+++ /dev/null
@@ -1,483 +0,0 @@
-.. 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.
-
-Operators and Calls
-===================
-
-In this chapter, we will introduce operators and calls. A registered
-operator provides the shared argument requirements, type rules, and effect
-information for a computation. A call refers to an operator or function
-and records the argument expressions for one use. We will examine how
-the IR records these definitions and calls, infers result types, and
-checks arguments.
-
-Operators
----------
-
-An operator identifies a computation, such as sigmoid or a CUDA
-thread-index lookup. :class:`ir.Op <tvm_tirx.ir.Op>` represents a
-registered operator and records its name, argument descriptions, and
-attributes. The operator's registration also provides rules for
-result-type inference and argument validation.
-
-A CUDA kernel can read a thread's x-axis coordinate with
-``T.cuda.thread_idx("x")``. The registered operator behind this helper is
-``tirx.cuda.thread_idx``. We can retrieve its ``ir.Op`` object and inspect
-the names of the parameters it accepts:
-
-.. code-block:: python
-
- from tvm_tirx import ir
- from tvm_tirx.script import tirx as T
-
- op = ir.Op.get("tirx.cuda.thread_idx")
- argument_names = [argument.name for argument in op.args_info]
- print(argument_names)
-
-The output is:
-
-.. code-block:: text
-
- ['axis']
-
-The list contains one parameter name, ``axis``.
-``T.cuda.thread_idx("x")`` passes the string ``"x"`` for this parameter.
-This selects the x axis, so the call reads the current thread's x-axis
-coordinate within its block.
-
-Calls
------
-
-:class:`ir.Call <tvm_tirx.ir.Call>` represents one use of an operator or
-function with specific argument expressions. Its ``op`` field references
-the expression being called, known as the callee, and ``args`` holds the
-arguments for this use. The main fields describe what is called, what
-is passed to it, and what type of value it produces:
-
-.. list-table::
- :header-rows: 1
- :widths: 25 75
-
- * - Field
- - Meaning
- * - ``op``
- - The callee: a registered operator or another function-valued expression.
- * - ``args``
- - Value arguments in calling order.
- * - ``ty_args``
- - Types passed as arguments to the callee, empty by default.
- * - ``attrs``
- - Operator-specific configuration or annotations for this call,
- stored as an ``Attrs`` object, or ``None``.
- * - ``ty``
- - The result type of this call, inferred or explicitly specified.
-
-The thread-index call refers to the registered ``tirx.cuda.thread_idx``
-operator. We can construct it directly through the IR API:
-
-.. code-block:: python
-
- op = ir.Op.get("tirx.cuda.thread_idx")
- x_call = ir.Call(op, [ir.StringImm("x")])
-
-``ir.Op.get`` retrieves the shared operator definition. ``ir.Call``
-creates an expression whose ``op`` refers to that definition and whose
-``args`` contains the axis argument. Its ``ty`` records the int32 result:
-
-.. code-block:: python
-
- print(ir.format_tree(
- x_call,
- expand=[(ir.Call, "ty")],
- hide=["attrs", "ty_args"],
- ))
-
-The output is:
-
-.. code-block:: text
-
- Call(op=tirx.cuda.thread_idx)
- ├── ty: PrimType(dtype=int32)
- └── args[0]: StringImm(value='x')
-
-``op.args_info[0].name`` is the parameter name ``"axis"``;
-``x_call.args[0]`` holds its argument value ``"x"``. The call describes
-reading the current thread's x-axis coordinate when the compiled GPU
-program runs.
-
-For this registered operator, ``ir.Call`` infers ``ty`` from the
-operator's type rule. If we pass ``ty`` to the constructor, it uses that
-result type and skips inference.
-
-The constructor also accepts the registered name directly:
-``ir.Call("tirx.cuda.thread_idx", [ir.StringImm("x")])``.
-
-The call above selects the x axis. We can construct a call for the
-y axis with the same operator:
-
-.. code-block:: python
-
- y_call = ir.Call(op, [ir.StringImm("y")])
-
-Both ``x_call.op`` and ``y_call.op`` reference the shared ``op``. Each
-call has its own ``args`` array, containing ``"x"`` or ``"y"``, and
-both calls produce an int32 coordinate. We can check that their operator
-references identify the same object:
-
-.. code-block:: python
-
- print(x_call.op.same_as(y_call.op))
-
-The output is:
-
-.. code-block:: text
-
- True
-
-A call's result can be an operand in a larger expression. A kernel with
-256 threads per block can combine the block and thread coordinates to
-find the tensor element assigned to a thread:
-
-.. code-block:: python
-
- n = T.dynamic("n")
-
- @T.function
- def gpu_add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
- T.device_entry(launch=T.cuda.LaunchConfig(grid=T.ceildiv(n, 256),
block=256))
- i = T.cuda.block_idx("x") * 256 + T.cuda.thread_idx("x")
- if i < n:
- B[i] = A[i] + 1
-
-The block-index call produces the block coordinate, and the thread-index
-call produces the coordinate within that block. Each helper constructs
-an ``ir.Call``. The multiplication and addition use the calls' results
-as operands:
-
-.. code-block:: python
-
- device_region = gpu_add_one.body.seq[0]
- index_binding = device_region.body.seq[0] # The definition of i.
- print(ir.format_tree(index_binding.value, hide=["attrs", "ty_args"]))
-
-The output is:
-
-.. code-block:: text
-
- Add
- ├── a: Mul
- │ ├── a: Call(op=tirx.cuda.block_idx)
- │ │ └── args[0]: StringImm(value='x')
- │ └── b: IntImm(value=256)
- └── b: Call(op=tirx.cuda.thread_idx)
- └── args[0]: StringImm(value='x')
-
-Expression Arguments
-~~~~~~~~~~~~~~~~~~~~
-
-A call can also receive a computation as an argument. We can add one to
-a float32 scalar and pass the result to sigmoid:
-
-.. code-block:: python
-
- scalar_value = ir.Var("scalar_value", "float32")
- scalar_plus_one = scalar_value + 1
- activated_plus_one = ir.prim.sigmoid(scalar_plus_one)
-
-``activated_plus_one`` is the ``ir.Call`` returned by the
-``ir.prim.sigmoid`` helper. Its result type is ``ir.PrimType("float32")``,
-so it is also a primitive expression. We can construct the same call
-explicitly:
-
-.. code-block:: python
-
- sigmoid_op = ir.Op.get("prim.sigmoid")
- activated_plus_one = ir.Call(sigmoid_op, [scalar_plus_one])
-
-In both forms, the call's ``op`` refers to the registered ``prim.sigmoid``
-operator, and ``args[0]`` refers to the addition expression
``scalar_plus_one``:
-
-.. code-block:: python
-
- print(ir.format_tree(
- activated_plus_one,
- expand=[(ir.Call, "ty")],
- hide=["attrs", "ty_args"],
- ))
-
-The output is:
-
-.. code-block:: text
-
- Call(op=prim.sigmoid)
- ├── ty: PrimType(dtype=float32)
- └── args[0]: Add
- ├── a: scalar_value
- └── b: FloatImm(value=1.0)
-
-When the compiled program runs, sigmoid receives the result of the
-addition. This expression therefore computes
-``1 / (1 + exp(-(scalar_value + 1)))`` and produces a float32 value.
-
-Function Calls
---------------
-
-The callee can also be a function defined in IR. An ``IRModule`` stores
-named function definitions, and an ``ir.GlobalVar`` identifies one of
-those definitions. For example, a small helper can put the scalar
-add-one computation in a function:
-
-.. code-block:: python
-
- from tvm_tirx.script import tirx as T
-
- @T.function(private=True)
- def add_one_scalar(value: T.float32) -> T.float32:
- return value + 1
-
-``private=True`` makes this an internal helper. We can place it in a
-module and construct a call that passes ``scalar_value`` as its argument:
-
-.. code-block:: python
-
- call_module = ir.IRModule({"add_one_scalar": add_one_scalar})
- callee = call_module.get_global_var("add_one_scalar")
- function_call = ir.Call(callee, [scalar_value], ty=add_one_scalar.ret_type)
-
-``callee`` is the module's global reference to ``add_one_scalar``.
-``function_call.op`` refers to this ``GlobalVar``, and
-``function_call.args[0]`` holds the value passed to the helper's parameter
-``value``. The call records this reference and argument; the module holds
-the function's definition.
-
-In this example, ``callee.ty`` is ``MissingType``, so the reference does
-not provide a signature for result-type inference. We pass the return
-type from the definition through ``ty`` instead. Other function-valued
-IR expressions can also serve as callees. When their ``ty`` is a
-``FuncType``, the constructor can infer the result from its return type.
-
-Calls in Function Bodies
-------------------------
-
-A call contributes to a function's computation through the expression or
-statement that uses it. This CPU function applies sigmoid to each
-input element after adding one:
-
-.. code-block:: python
-
- n = T.dynamic("n")
-
- @T.function
- def add_one_sigmoid(A: T.Tensor((n,), T.float32), B: T.Tensor((n,),
T.float32)):
- for i in range(n):
- B[i] = T.sigmoid(A[i] + 1)
-
-The TVMScript helper ``T.sigmoid`` builds a call to ``prim.sigmoid``.
-The tensor store uses that call as its ``value`` expression:
-
-.. code-block:: python
-
- activation_store = add_one_sigmoid.body.seq[0].body.seq[0]
- activation_call = activation_store.value
- print(ir.format_tree(activation_store, hide=["attrs", "ty_args"]))
-
-The output is:
-
-.. code-block:: text
-
- TensorStore(dest=B, indices=[i])
- └── value: Call(op=prim.sigmoid)
- └── args[0]: Add
- ├── a: TensorLoad(source=A, indices=[i])
- └── b: FloatImm(value=1.0)
-
-When the function runs, the addition produces the sigmoid input and the
-store writes its result to ``B[i]``.
-
-Calls for Their Effects
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Some registered operators perform a memory write themselves. A common
-example is a masked store, which writes only selected vector lanes. A
-vector version of add-one can use masked reads and writes to process
-four elements at a time, including a final group with fewer than four
-elements:
-
-.. code-block:: python
-
- @T.function
- def masked_add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,),
T.float32)):
- for base in range(0, n, 4):
- indices = T.Ramp(base, 1, 4)
- values = T.masked_load(A, indices, indices < n)
- T.masked_store(B, values + 1, indices, indices < n)
-
-``indices`` contains four consecutive positions starting at ``base``.
-The mask ``indices < n`` enables only positions within the tensor for
-both the read and the write. For example, if ``n = 10``, valid indices
-range from 0 to 9. The final group contains indices 8, 9, 10, and 11, so
-the mask enables only the first two lanes.
-
-``T.masked_store`` builds a call to ``tirx.masked_store``, which performs
-the write and returns ``void``. The TVMScript helper places this call in
-an ``ir.Evaluate`` statement inside the loop body:
-
-.. code-block:: python
-
- memory_loop = masked_add_one.body.seq[0]
- write_statement = memory_loop.body.seq[2]
- write_call = write_statement.value
- print(ir.format_tree(
- write_statement,
- hide=["args", "attrs", "ty_args"],
- ))
-
-The output is:
-
-.. code-block:: text
-
- Evaluate
- └── value: Call(op=tirx.masked_store)
-
-The loop body first binds ``indices`` and ``values``. Its third
-statement, ``write_statement``, evaluates the masked-store call.
-This view hides the call's arguments to focus on the ``Evaluate`` wrapper.
-Through the IR API, ``ir.Evaluate(write_call)`` constructs the
-corresponding statement. Even with a ``void`` result type, the call is
-an expression; ``Evaluate`` gives it a place in the statement sequence.
-
-The operators' effect attributes explain why these two calls need
-different treatment when their results are unused:
-
-.. code-block:: python
-
- activation_effect = activation_call.op.get_attr("TCallEffectKind")
- write_effect = write_call.op.get_attr("TCallEffectKind")
-
-``activation_effect`` is ``ir.CallEffectKind.Pure``: the sigmoid
-operation has no memory side effects. ``write_effect`` is
-``ir.CallEffectKind.UpdateState``. Compiler passes cannot discard this
-write merely because its result is unused; it updates the output tensor.
-
-Type Arguments and Attributes
------------------------------
-
-A call's value arguments do not always determine its result type.
-A tensor allocation, for example, has no input tensor from which to
-infer a shape or dtype. We pass the required tensor type through
-``ty_args``. This call describes four float32 elements in local storage:
-
-.. code-block:: python
-
- from tvm_tirx import tirx
-
- temporary_type = tirx.TensorType((4,), "float32", scope="local")
- allocation_call = ir.Call(
- "tirx.alloc_tensor", [], ty_args=[temporary_type],
- attrs={"tirx.volatile": True},
- )
-
-``ty_args[0]`` gives the tensor type to the allocation operator. Its
-type rule uses this argument as the result type, so ``allocation_call.ty``
-is ``temporary_type``. A call can therefore produce a tensor as well as a
-scalar or vector value.
-
-The ``attrs`` dictionary configures this allocation. It becomes an
-``ir.DictAttrs`` object, and ``"tirx.volatile": True`` requests volatile
-accesses: code generation must preserve the loads and stores to this
-storage. These attributes belong to this call; the attributes on ``ir.Op``
-describe the operation shared by all its calls.
-
-We can give the allocated tensor a name with a binding:
-
-.. code-block:: python
-
- temporary = ir.Var("temporary", temporary_type)
- allocation_binding = ir.Bind(temporary, allocation_call)
-
-The binding's ``value`` is the allocation call, and its ``var`` is
-``temporary``. A function body can place this binding before statements
-that read or write the temporary tensor.
-
-.. _types-and-validation:
-
-.. _type-inference-and-validation:
-
-Call Types and Validation
--------------------------
-
-A call needs a result type that matches its inputs. For sigmoid, a scalar
-float32 input produces float32, and a four-lane input produces float32x4.
-The constructor normally infers this type. An explicit ``ty`` skips
-inference, and ``ty=ir.Type.missing()`` leaves the result undetermined.
-With the scalar addition defined above, the three choices are:
-
-.. code-block:: python
-
- sigmoid_op = ir.Op.get("prim.sigmoid")
- inferred_call = ir.Call(sigmoid_op, [scalar_plus_one])
- typed_call = ir.Call(sigmoid_op, [scalar_plus_one], ty="float32")
- untyped_call = ir.Call(sigmoid_op, [scalar_plus_one], ty=ir.Type.missing())
-
-``inferred_call`` and ``typed_call`` both store a float32 result type.
-``untyped_call`` explicitly sets ``MissingType``, so its result type
-remains undetermined.
-
-Now suppose we are rebuilding the scalar call to work on four values at
-once. We can first set its vector argument and leave the result type
-undetermined until we run the operator's inference rule:
-
-.. code-block:: python
-
- vector_value = ir.Var("vector_value", "float32x4")
- untyped_sigmoid = ir.Call(sigmoid_op, [vector_value], ty=ir.Type.missing())
-
-With the vector argument in place,
-:func:`ir.reinfer_type <tvm_tirx.ir.reinfer_type>` applies the sigmoid
-operator's type rule and returns the result type. We can use it to
-construct a new call with that type:
-
-.. code-block:: python
-
- inferred = ir.reinfer_type(untyped_sigmoid)
- rebuilt_call = ir.Call(sigmoid_op, untyped_sigmoid.args, ty=inferred)
-
-``ir.reinfer_type`` returns ``ir.PrimType("float32x4")`` without changing
-``untyped_sigmoid.ty``, which remains ``MissingType``. ``rebuilt_call``
-stores the returned type.
-
-The sigmoid operator also requires one input argument. ``rebuilt_call``
-passes ``vector_value`` as that input. The following call leaves it out:
-
-.. code-block:: python
-
- invalid_sigmoid = ir.Call(sigmoid_op, [], ty="float32x4")
-
-``ty="float32x4"`` sets the result type directly, so the constructor
-skips inference. It still creates the incomplete ``ir.Call`` object
-because argument checks do not run automatically. We can use
-:meth:`Call.validate() <tvm_tirx.ir.Call.validate>` to check whether the
-arguments satisfy the operator's requirements:
-
-.. code-block:: python
-
- invalid_sigmoid.validate()
-
-``invalid_sigmoid.validate()`` raises ``TypeError`` for the missing input.
-``untyped_sigmoid.validate()`` succeeds because the call includes
-``vector_value``. Its ``ty`` remains ``MissingType`` because validation
-checks the arguments without inferring the result type.
diff --git a/docs/ir/operators_calls_and_regions.rst
b/docs/ir/operators_calls_and_regions.rst
new file mode 100644
index 000000000..f722b11f0
--- /dev/null
+++ b/docs/ir/operators_calls_and_regions.rst
@@ -0,0 +1,293 @@
+.. 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.
+
+
+Operators, Calls, and Regions
+=============================
+
+This guide introduces **operators**, the main extension point of TIRx.
+An operator, ``ir.Op``, names a computation such as sigmoid or a
+thread-index read, and carries attributes that tell the compiler how to
+treat it. A call applies an operator as an expression, and a region
+applies one as a statement. New computations and new kinds of
+statements are added by registering operators, without new IR node
+classes.
+
+This GPU add-one function uses both forms:
+
+.. code-block:: python
+
+ from tvm_tirx import ir
+ from tvm_tirx.script import tirx as T
+
+ n = T.dynamic("n")
+
+ @T.function
+ def gpu_add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+ T.device_entry(launch=T.cuda.LaunchConfig(grid=T.ceildiv(n, 256),
block=256))
+ i = T.cuda.block_idx("x") * 256 + T.cuda.thread_idx("x")
+ if i < n:
+ B[i] = A[i] + 1
+
+ print(ir.format_tree(
+ gpu_add_one.body[0],
+ hide=["attrs", "args", "ty_args", "body_params", "result_vars",
+ "var", "then_case"]))
+
+The output is:
+
+.. code-block:: text
+
+ RegionStmt(op=tirx.device_entry)
+ └── body: SeqStmt
+ ├── seq[0]: Bind
+ │ └── value: Add
+ │ ├── a: Mul
+ │ │ ├── a: Call(op=tirx.cuda.block_idx)
+ │ │ └── b: IntImm(value=256)
+ │ └── b: Call(op=tirx.cuda.thread_idx)
+ └── seq[1]: If(else_case=None)
+ └── condition: LT
+ ├── a: i
+ └── b: n
+
+The region applies the ``tirx.device_entry`` operator, which marks its
+body as GPU code. Inside it, two calls apply the ``tirx.cuda.block_idx``
+and ``tirx.cuda.thread_idx`` operators to read the current block and
+thread coordinates. The view hides operands and other fields to show
+only where operators appear.
+
+Operators
+---------
+
+``ir.Op`` is a registered operator, looked up by name with
+``ir.Op.get``. Its ``name`` identifies it, and its ``args_info``
+describes the arguments it accepts:
+
+.. code-block:: python
+
+ from tvm_tirx import ir
+
+ op = ir.Op.get("prim.sigmoid")
+ print(op.name)
+ for arg in op.args_info:
+ print(arg.name, "-", arg.doc)
+
+The output is:
+
+.. code-block:: text
+
+ prim.sigmoid
+ x - The input value.
+
+Each operator is a single shared object. A call stores the operator in
+its ``op`` field and its own operands in ``args``, so every call to
+sigmoid refers to this same ``op``. When a call is constructed, the
+operator's type rule computes the call's ``ty`` from its arguments.
+
+.. note::
+
+ :doc:`types_and_expressions` covers the fields of a call, including
+ ``ty_args``, ``attrs``, and calls to functions.
+
+Operator Attributes
+-------------------
+
+An operator's behavior comes from its **attributes**: named values
+attached to the operator, such as its type rule, its side effects, or
+how to lower it for a target. Attributes are stored by name. All values
+for one name form a map from operators to values, which
+``ir.Op.get_attr_map`` returns. ``op.get_attr(name)`` reads one
+operator's value. For example, ``TCallEffectKind`` records whether a
+call only computes a value or also changes state:
+
+.. code-block:: python
+
+ from tvm_tirx import ir
+
+ effect = ir.Op.get_attr_map("TCallEffectKind")
+ for name in ["prim.sigmoid", "tirx.masked_store"]:
+ kind = ir.CallEffectKind(effect[ir.Op.get(name)])
+ print(name, kind.name)
+
+The output is:
+
+.. code-block:: text
+
+ prim.sigmoid Pure
+ tirx.masked_store UpdateState
+
+Sigmoid is ``Pure``, so a pass may remove a call whose result is
+unused. A masked store is ``UpdateState``: it writes memory, so it must
+be kept.
+
+Attributes are extensible. Any library can introduce a new attribute
+name and set it on any operator, built-in or new, for example
+``ir.Op.get("prim.sigmoid").set_attr("my_pass.Cost", 4)``. Passes find
+operators through attributes, never through a list of operator names.
+To lower calls for a target, TIRx looks each operator up under keys
+built from the target name, such as ``cuda.FLowerIntrinsic``, and falls
+back to ``default`` keys such as ``default.FLegalize``. Extension therefore
works in both
+directions: a new operator works with existing passes once it sets the
+attributes those passes read, and a new pass can define its own
+attribute and set it on existing operators.
+
+The common attributes are:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 32 68
+
+ * - Attribute
+ - Meaning
+ * - ``FInferType``
+ - Computes a call's result type from its arguments.
+ * - ``TFixedReturnType``
+ - A result type that does not depend on the arguments.
+ * - ``TCallEffectKind``
+ - Whether a call is pure, reads state, or updates state.
+ * - ``<target>.FLowerIntrinsic``
+ - Lowers a call to code for one target, such as ``llvm`` or
+ ``cuda``.
+ * - ``<target>.FLegalize``
+ - Rewrites a call into simpler operations, for one target or with
+ ``default`` for all targets.
+ * - ``TVectorizable``
+ - Whether a call can be applied lane by lane to vectors.
+ * - ``TGlobalSymbol``
+ - The name of the external function the call maps to.
+ * - ``FRegionGetBodyParams``, ``FRegionValidate``
+ - Make the operator a region operator: define the body's
+ parameters and check the region's operands.
+
+Defining an Operator
+--------------------
+
+``ir.Op.register`` adds a new operator. The operator starts with no
+signature and no attributes, so the definition sets both. This operator
+squares a value:
+
+.. code-block:: python
+
+ from tvm_tirx import ir
+
+ op = ir.Op.register("my_ext.square", "Square a value.")
+ op.set_signature(args=[("x", "The value to square.")])
+ op.set_attr("TCallEffectKind", ir.CallEffectKind.Pure.value)
+ op.set_attr("FInferType", lambda call: call.args[0].ty)
+
+The signature declares one argument. ``TCallEffectKind`` marks the
+operator as pure, and ``FInferType`` gives a call the type of its
+argument. A call to the new operator now gets its type from that rule:
+
+.. code-block:: python
+
+ v = ir.Var("v", "float32x4")
+ squared = ir.Call(op, [v])
+ print(ir.format_tree(squared, expand=[(ir.Expr, "ty")],
+ hide=["attrs", "ty_args"]))
+
+The output is:
+
+.. code-block:: text
+
+ Call(op=my_ext.square)
+ ├── ty: PrimType(dtype=float32x4)
+ └── args[0]: v
+
+The signature also lets ``Call.validate()`` reject a call with the
+wrong number of arguments: ``ir.Call(op, [], ty="float32").validate()``
+raises ``TypeError``.
+
+Once its signature and attributes are set, ``op.expose()`` publishes
+the operator as Python helpers in the namespaces that serve its name
+prefix. For example, an operator named ``prim.<name>`` becomes available
+as ``ir.prim.<name>`` and, in TVMScript, as ``T.<name>``.
+
+.. note::
+
+ To compile calls to a new operator, it also needs lowering
+ attributes, such as ``default.FLegalize``, that rewrite it into
+ operations a backend supports.
+ :doc:`../advanced/defining_ir_extensions` walks through a complete
+ extension with its own type, operators, and lowering pass.
+
+Regions
+-------
+
+A region applies an operator to a nested body of statements. An
+operator becomes a region operator by setting two attributes:
+``FRegionGetBodyParams`` defines the variables its body receives, and
+``FRegionValidate`` checks its operands. ``ir.RegionStmt`` records one
+use of such an operator: ``op``, the operands ``args`` and ``attrs``,
+the ``body``, and any variables the region defines in ``body_params``
+and ``result_vars``.
+
+``tirx.device_entry`` is a region operator that enters a GPU kernel. Its
+operands carry the kernel's launch configuration:
+
+.. code-block:: python
+
+ from tvm_tirx import ir
+ from tvm_tirx.script import tirx as T
+
+ n = T.dynamic("n")
+
+ @T.function
+ def gpu_add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+ T.device_entry(launch=T.cuda.LaunchConfig(grid=T.ceildiv(n, 256),
block=256))
+ i = T.cuda.block_idx("x") * 256 + T.cuda.thread_idx("x")
+ if i < n:
+ B[i] = A[i] + 1
+
+ region = gpu_add_one.body[0]
+ print(ir.format_tree(region, hide=["body"]))
+
+The output is:
+
+.. code-block:: text
+
+ RegionStmt(op=tirx.device_entry)
+ ├── attrs: DictAttrs
+ │ └── dict: Map
+ │ ├── 'cuda.kernel_attrs': {}
+ │ ├── 'cuda.launch_fields'[0]: 'grid.x'
+ │ ├── 'cuda.launch_fields'[1]: 'grid.y'
+ │ ├── 'cuda.launch_fields'[2]: 'grid.z'
+ │ ├── 'cuda.launch_fields'[3]: 'block.x'
+ │ ├── 'cuda.launch_fields'[4]: 'block.y'
+ │ └── 'cuda.launch_fields'[5]: 'block.z'
+ ├── args[0]: FloorDiv
+ │ ├── a: Sub
+ │ │ ├── a: Add
+ │ │ │ ├── a: n
+ │ │ │ └── b: IntImm(value=256)
+ │ │ └── b: IntImm(value=1)
+ │ └── b: IntImm(value=256)
+ ├── args[1]: IntImm(value=1)
+ ├── args[2]: IntImm(value=1)
+ ├── args[3]: IntImm(value=256)
+ ├── args[4]: IntImm(value=1)
+ ├── args[5]: IntImm(value=1)
+ ├── body_params: []
+ └── result_vars: []
+
+The ``args`` are the six launch values, and ``cuda.launch_fields`` in
+``attrs`` names each one: the grid has ``ceildiv(n, 256)`` blocks along
+x, and each block has 256 threads. The region's body, hidden here, runs
+on the GPU with that configuration. ``device_entry`` defines no
+variables, so ``body_params`` and ``result_vars`` are empty.
diff --git a/docs/ir/overview.rst b/docs/ir/overview.rst
index ec6877cdc..4888433e9 100644
--- a/docs/ir/overview.rst
+++ b/docs/ir/overview.rst
@@ -248,8 +248,8 @@ What to Read Next
shapes are represented.
- :doc:`statements` covers how a body binds variables, writes tensors,
branches, and loops.
-- :doc:`operators_and_calls` introduces registered operators and function
- calls.
+- :doc:`operators_calls_and_regions` covers operators, the main extension
+ point, and how calls and regions apply them.
- :doc:`functions_and_modules` shows how functions are defined and organized
in modules.
- :doc:`printing_and_parsing` covers utilities for parsing and printing
diff --git a/docs/ir/statements.rst b/docs/ir/statements.rst
index 45d283867..9fb2aaab6 100644
--- a/docs/ir/statements.rst
+++ b/docs/ir/statements.rst
@@ -450,7 +450,7 @@ statements inside the region.
Regions and calls are the two ways operators extend TIRx: a call
applies an operator as an expression, and a region applies one as a
statement.
- :doc:`operators_and_calls` covers how operators are registered and
+ :doc:`operators_calls_and_regions` covers how operators are registered and
how calls and regions use them.
:ref:`Region Syntax <tvmscript-region-syntax>` explains how TVMScript
writes a region, and :doc:`../advanced/defining_ir_extensions` walks
diff --git a/docs/ir/types_and_expressions.rst
b/docs/ir/types_and_expressions.rst
index 230fa8b3b..0a6fbb559 100644
--- a/docs/ir/types_and_expressions.rst
+++ b/docs/ir/types_and_expressions.rst
@@ -569,7 +569,7 @@ result type from that signature.
.. note::
Operators are the main extension point of TIRx.
- :doc:`operators_and_calls` covers how operators are registered and
+ :doc:`operators_calls_and_regions` covers how operators are registered and
how their attributes define type rules, effects, and lowering.
.. _user-ir-dependent-type:
diff --git a/python/tvm_tirx/ir/format_tree.py
b/python/tvm_tirx/ir/format_tree.py
index 1b59a6990..d1230e1e9 100644
--- a/python/tvm_tirx/ir/format_tree.py
+++ b/python/tvm_tirx/ir/format_tree.py
@@ -16,15 +16,17 @@
# under the License.
"""Text trees for inspecting IR and extension objects."""
+import enum
from collections.abc import Callable, Iterable, Mapping
from typing import Any
import tvm_ffi
+from tvm_ffi.dataclasses import Enum as _FFIEnum
from .expr import Expr, Var
from .function import BaseFunc
from .op import Op
-from .stmt import For
+from .stmt import For, ForKind
from .type import PrimType
FieldSelector = str | tuple[type, str]
@@ -68,6 +70,8 @@ _FFI_VALUES = (tvm_ffi.Object, tvm_ffi.Array, tvm_ffi.List,
tvm_ffi.Map, tvm_ffi
def _scalar(value):
+ if isinstance(value, enum.Enum | _FFIEnum):
+ return f"{type(value).__name__}({value.name})"
if isinstance(value, tvm_ffi.dtype):
return str(value)
if isinstance(value, str):
@@ -209,6 +213,8 @@ class _TreeFormatter:
and role != "ignore"
else None
)
+ if isinstance(value, For) and field.name == "kind" and child
in ForKind:
+ child = ForKind(child) # Stored as an int; show the enum
name.
entries.append((field.name, child, role, action))
return name, "object", entries
return type(value).__name__, "opaque", []
diff --git a/python/tvm_tirx/ir/op.py b/python/tvm_tirx/ir/op.py
index 2f4de6090..21ad23e5b 100644
--- a/python/tvm_tirx/ir/op.py
+++ b/python/tvm_tirx/ir/op.py
@@ -54,6 +54,36 @@ class Op(Expr):
"""
return _ffi_api.GetOp(op_name)
+ @staticmethod
+ def register(op_name, doc=""):
+ """Register a new operator and return it.
+
+ The operator is added to the global registry for the rest of the
+ process, so ``Op.get(op_name)`` returns the same object afterwards. It
+ starts with an empty signature and no attributes: set them with
+ :py:meth:`set_signature` and :py:meth:`set_attr`, then call
+ :py:meth:`expose` to make it available to API destinations.
+
+ Parameters
+ ----------
+ op_name : str
+ The canonical operator name. It must not already be registered.
+ doc : str, optional
+ A short description of the operator.
+
+ Returns
+ -------
+ Op
+ The newly registered operator.
+
+ Raises
+ ------
+ AttributeError
+ If an operator with the same name is already registered.
+ """
+ _ffi_api.RegisterOp(op_name, doc)
+ return Op.get(op_name)
+
@staticmethod
def list_op_names():
"""List registered operator names in unspecified order.
diff --git a/tests/python/ir/test_attrs.py b/tests/python/ir/test_attrs.py
index b30d0acfa..dc0eade23 100644
--- a/tests/python/ir/test_attrs.py
+++ b/tests/python/ir/test_attrs.py
@@ -71,6 +71,21 @@ def test_assert_structural_equal_reports_mismatch():
assert "and rhs at" in message
+def test_op_register_returns_new_op():
+ name = "test.python_register"
+ op = tvm_tirx.ir.Op.register(name, "Python registration test")
+ assert isinstance(op, tvm_tirx.ir.Op)
+ assert op.same_as(tvm_tirx.ir.Op.get(name))
+ assert op.name == name
+ assert op.doc == "Python registration test"
+ assert name in tvm_tirx.ir.Op.list_op_names()
+ assert len(op.args_info) == 0 and len(op.ty_args_info) == 0
+ assert op.var_args_info is None and op.var_ty_args_info is None
+ assert all(op.get_attr(key) is None for key in
tvm_tirx.ir.Op.list_attr_names())
+ with pytest.raises(AttributeError, match=r"is registered before"):
+ tvm_tirx.ir.Op.register(name)
+
+
def test_op_set_signature_metadata_and_counts():
name = "test.python_set_signature"
tvm_tirx.ir._ffi_api.RegisterOp(name, "Python signature test")
diff --git a/tests/python/ir/test_ir_format_tree.py
b/tests/python/ir/test_ir_format_tree.py
index 36b6ee2d1..49516082e 100644
--- a/tests/python/ir/test_ir_format_tree.py
+++ b/tests/python/ir/test_ir_format_tree.py
@@ -226,12 +226,12 @@ def test_native_loop_defaults_and_structural_comparison():
assert "For(var=i," in ir.format_tree(loop, fold=[(ir.For, "var")])
assert "step=" not in text and "kind=" not in text and "annotations" not
in text
assert "step=IntImm(value=1)" in ir.format_tree(loop, show_defaults=True)
- assert "kind=0" in ir.format_tree(loop, show_defaults=True)
+ assert "kind=ForKind(DEFAULT)" in ir.format_tree(loop, show_defaults=True)
assert "annotations: {}" in ir.format_tree(loop, expand=[(ir.For,
"annotations")])
assert "step=IntImm(value=1)" in ir.format_tree(loop, fold=[(ir.For,
"step")])
assert "step=IntImm(value=2)" in ir.format_tree(make_loop(step=2))
assert "step=IntImm(value=1)" in ir.format_tree(make_loop(dtype="int64"))
- assert "kind=1" in ir.format_tree(make_loop(kind=ir.ForKind.PARALLEL))
+ assert "kind=ForKind(PARALLEL)" in
ir.format_tree(make_loop(kind=ir.ForKind.PARALLEL))
assert "'tag': 1" in ir.format_tree(make_loop(annotations={"tag": 1}))
# Metadata defaults also participate in generic reflected construction.
constructed = ir.make_node(
@@ -335,5 +335,10 @@ def test_invalid_callback_output(result):
ir.format_tree(ir.Var("i", "int32"), fold_formatters={ir.PrimType:
lambda obj: result})
+def test_ffi_enum_renders_as_type_and_name():
+ tensor_type = tirx.TensorType((4,), "float32", scope="shared")
+ assert
ir.format_tree(tensor_type).startswith("TensorType(scope=MemoryScope(shared))")
+
+
if __name__ == "__main__":
tvm_tirx.testing.main()