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()

Reply via email to