You are viewing a plain text version of this content. The canonical link for it is here.
Posted to discuss-archive@tvm.apache.org by "junrushao (via GitHub)" <gi...@apache.org> on 2026/01/12 04:04:46 UTC
[PR] doc: abi overview [tvm-ffi]
junrushao opened a new pull request, #402:
URL: https://github.com/apache/tvm-ffi/pull/402
(no comment)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2683782294
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
Review Comment:
What is the C API for constructing a tensor?
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
Review Comment:
What is the C API for constructing a tensor (w/o DLPack)?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "gemini-code-assist[bot] (via GitHub)" <gi...@apache.org>.
gemini-code-assist[bot] commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2681241812
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
+The following C code constructs a :cpp:class:`~tvm::ffi::TensorObj` from a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_FromDLPack.begin]
+ :end-before: [Tensor_FromDLPack.end]
+
+.. hint::
+ TVM-FFI's Python API automatically wraps framework tensors (e.g., :py:class:`torch.Tensor`) as :cpp:class:`~tvm::ffi::TensorObj`,
+ so manual conversion is typically unnecessary.
+
+Destruct Tensor
+~~~~~~~~~~~~~~~
+
+As a standard TVM-FFI object, :cpp:class:`~tvm::ffi::TensorObj` follows the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+When the reference count reaches zero, the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes.
+
+Export Tensor to DLPack
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To share a :cpp:class:`~tvm::ffi::TensorObj` with other frameworks, export it as a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_ToDLPackVersioned.begin]
+ :end-before: [Tensor_ToDLPackVersioned.end]
+
+.. _abi-function:
+
+Function
+--------
+
+.. seealso::
+
+ :ref:`sec:function` for a detailed description of TVM-FFI functions.
+
+All functions in TVM-FFI follow a unified C calling convention that enables ABI-stable,
+type-erased, and cross-language function calls, defined by :cpp:type:`TVMFFISafeCallType`.
+
+**Calling convention.** The signature includes:
+
+- ``handle`` (``void*``): Optional resource handle passed to the callee; typically ``NULL`` for exported symbols
+- ``args`` (``TVMFFIAny*``) and ``num_args`` (``int``): Array of non-owning :cpp:class:`~tvm::ffi::AnyView` input arguments
+- ``result`` (``TVMFFIAny*``): Owning :cpp:class:`~tvm::ffi::Any` output value
+- Return value: ``0`` for success; ``-1`` or ``-2`` for errors (see :ref:`sec:exception`)
+
+**Object layout.** The :cpp:class:`~tvm::ffi::FunctionObj` stores call pointers after the object header.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIFunctionCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIFunctionCell.begin]
+ :end-before: [TVMFFIFunctionCell.end]
+ :caption: tvm/ffi/c_api.h
+
+Construct and Destroy
+~~~~~~~~~~~~~~~~~~~~~
+
+.. important::
+ Dynamic function creation is useful for passing lambdas or closures across language boundaries.
+
+The following C code constructs a :cpp:class:`~tvm::ffi::FunctionObj` from a :cpp:type:`TVMFFISafeCallType` and a ``deleter`` callback.
+The ``deleter`` cleans up resources owned by the function; for global symbols, it is typically ``NULL``.
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.Construct.begin]
+ :end-before: [Function.Construct.end]
+
+Release a :cpp:class:`~tvm::ffi::FunctionObj` using the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+
+Global Registry
+~~~~~~~~~~~~~~~
+
+**Retrieve a global function.** The following C code retrieves a function by name from the global registry:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.GetGlobal.begin]
+ :end-before: [Function.GetGlobal.end]
+
+**Register a global function.** The following C code registers a function by name in the global registry:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.SetGlobal.begin]
+ :end-before: [Function.SetGlobal.end]
+
+Call Function
+~~~~~~~~~~~~~
+
+The following C code invokes a :cpp:class:`~tvm::ffi::FunctionObj` with arguments:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.Call.begin]
+ :end-before: [Function.Call.end]
+
+
+.. _abi-exception:
+
+Exception
+---------
+
+.. seealso::
+
+ :ref:`sec:exception` for detailed exception handling patterns.
+
+Exceptions are a central part of TVM-FFI's ABI and calling convention.
+When errors occur, they are stored as objects with a :cpp:class:`TVMFFIErrorCell` payload.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIErrorCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIErrorCell.begin]
+ :end-before: [TVMFFIErrorCell.end]
+ :caption: tvm/ffi/c_api.h
+
+Retrieve Error Object
+~~~~~~~~~~~~~~~~~~~~~
+
+When a function returns ``-1``, an error object is stored in thread-local storage (TLS).
+Retrieve it with :cpp:func:`TVMFFIErrorMoveFromRaised`, which returns a :cpp:class:`tvm::ffi::ErrorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Error.HandleReturnCode.begin]
+ :end-before: [Error.HandleReturnCode.end]
+
+This function transfers ownership to the caller and clears the TLS slot.
+Call :cpp:func:`TVMFFIObjectDecRef` when done to avoid memory leaks.
+
+**Frontend errors (-2).** Error code ``-2`` is reserved for frontend errors.
+It is returned when :cpp:func:`TVMFFIEnvCheckSignals` detects a pending Python signal.
+In this case, do not retrieve the error from TLS; instead, consult the frontend's error mechanism.
+
+Print Error Message
+~~~~~~~~~~~~~~~~~~~
+
+The error payload is a :cpp:type:`TVMFFIErrorCell` structure containing the error kind, message, and backtrace.
+Access it by skipping the :cpp:type:`TVMFFIObject` header via pointer arithmetic:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Error.Print.begin]
+ :end-before: [Error.Print.end]
+
+This prints the error message along with its backtrace.
+
+Raise Exception
+~~~~~~~~~~~~~~~
+
+The following C code sets the TLS error and returns ``-1`` via :cpp:func:`TVMFFIErrorSetRaisedFromCStr`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Error.RaiseException.begin]
+ :end-before: [Error.RaiseException.end]
+
+For non-null-terminated strings, use :cpp:func:`TVMFFIErrorSetRaisedFromCStrParts`, which accepts explicit string lengths.
+
+.. note::
+ You rarely need to create a :cpp:class:`~tvm::ffi::ErrorObj` directly.
+ The C APIs :cpp:func:`TVMFFIErrorSetRaisedFromCStr` and :cpp:func:`TVMFFIErrorSetRaisedFromCStrParts` handle this internally.
+
+
+🚧 String and Byte
+------------------
+
+.. warning::
+ This section is under construction.
+
+The ABI supports strings and bytes as first-class citizens. A string can take multiple forms that are identified by
+its ``type_index``.
+
+- ``kTVMFFIRawStr``: raw C string terminated by ``\0``.
+- ``kTVMFFISmallStr``: small string, the length is stored in ``small_str_len`` and data is stored in ``v_bytes``.
+- ``kTVMFFIStr``: on-heap string object for strings that are longer than 7 characters.
+
+The following code shows the layout of the on-heap string object.
+
+.. code-block:: cpp
+
+ // span-like data structure to store header and length
+ typedef struct {
+ const char* data;
+ size_t size;
+ } TVMFFIByteArray;
+
+ // showcase the layout of the on-heap string.
+ class StringObj : public ffi::Object, public TVMFFIByteArray {
+ };
+
+
+The following code shows how to read a string from :cpp:class:`TVMFFIAny`
+
+.. code-block:: cpp
+
+ TVMFFIByteArray ReadString(const TVMFFIAny *value) {
+ TVMFFIByteArray ret;
+ if (value->type_index == kTVMFFIRawStr) {
+ ret.data = value->v_c_str;
+ ret.size = strlen(ret.data);
+ } else if (value->type_index == kTVMFFISmallStr) {
+ ret.data = value->v_bytes;
+ ret.size = value->small_str_len;
+ } else {
+ assert(value->type_index == kTVMFFIStr);
+ ret = *reinterpret_cast<TVMFFIByteArray*>(
+ reinterpret_cast<char*>(value->v_obj) + sizeof(TVMFFIObject));
+ }
+ return ret;
+ }
+
+
+Similarly, we have type indices to represent bytes. The C++ API provides classes
+:cpp:class:`~tvm::ffi::String` and :cpp:class:`~tvm::ffi::Bytes` to enable the automatic conversion of these values with Any storage format.
+
+**Rationales**. Separate string and bytes enable clear mappings from the Python side. Small string allows us to
+store short names on-stack. To favor 8-byte alignment (v_bytes) and keep things simple, we did not further
+pack characters into the ``small_len`` field.
Review Comment:

This paragraph explaining the rationales is a bit dense. Formatting it as a bulleted list would improve readability.
```suggestion
**Rationales**.
- Separate string and bytes types enable clear mappings from the Python side.
- Small string optimization allows us to store short names on-stack, avoiding heap allocation.
- To favor 8-byte alignment of ``v_bytes`` and maintain simplicity, we did not further pack characters into the ``small_len`` field.
```
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
Review Comment:

The current phrasing is slightly confusing as it states that `TVMFFIAny` (a C struct) has variants, but then lists the C++ wrapper classes `tvm::ffi::Any` and `tvm::ffi::AnyView`. To improve clarity, I suggest rephrasing to explain that `TVMFFIAny` can be used in two ways (owning vs. borrowing) and that these patterns are formalized by the C++ wrapper classes.
```suggestion
**Ownership.** The :cpp:class:`TVMFFIAny` struct can represent either an owning or a borrowing reference. These two ownership patterns are formalized by the C++ wrapper classes :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView`, which have identical memory layouts but different :ref:`ownership semantics <any-ownership>`:
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2683890581
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
+The following C code constructs a :cpp:class:`~tvm::ffi::TensorObj` from a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_FromDLPack.begin]
+ :end-before: [Tensor_FromDLPack.end]
+
+.. hint::
+ TVM-FFI's Python API automatically wraps framework tensors (e.g., :py:class:`torch.Tensor`) as :cpp:class:`~tvm::ffi::TensorObj`,
+ so manual conversion is typically unnecessary.
+
+Destruct Tensor
+~~~~~~~~~~~~~~~
+
+As a standard TVM-FFI object, :cpp:class:`~tvm::ffi::TensorObj` follows the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+When the reference count reaches zero, the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes.
+
+Export Tensor to DLPack
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To share a :cpp:class:`~tvm::ffi::TensorObj` with other frameworks, export it as a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_ToDLPackVersioned.begin]
+ :end-before: [Tensor_ToDLPackVersioned.end]
+
+.. _abi-function:
+
+Function
+--------
+
+.. seealso::
+
+ :ref:`sec:function` for a detailed description of TVM-FFI functions.
+
+All functions in TVM-FFI follow a unified C calling convention that enables ABI-stable,
+type-erased, and cross-language function calls, defined by :cpp:type:`TVMFFISafeCallType`.
+
+**Calling convention.** The signature includes:
+
+- ``handle`` (``void*``): Optional resource handle passed to the callee; typically ``NULL`` for exported symbols
+- ``args`` (``TVMFFIAny*``) and ``num_args`` (``int``): Array of non-owning :cpp:class:`~tvm::ffi::AnyView` input arguments
+- ``result`` (``TVMFFIAny*``): Owning :cpp:class:`~tvm::ffi::Any` output value
+- Return value: ``0`` for success; ``-1`` or ``-2`` for errors (see :ref:`sec:exception`)
Review Comment:
This large chunk of text is not very informative...Let me paraphrase it a little bit...
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2683837623
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
+The following C code constructs a :cpp:class:`~tvm::ffi::TensorObj` from a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_FromDLPack.begin]
+ :end-before: [Tensor_FromDLPack.end]
+
+.. hint::
+ TVM-FFI's Python API automatically wraps framework tensors (e.g., :py:class:`torch.Tensor`) as :cpp:class:`~tvm::ffi::TensorObj`,
+ so manual conversion is typically unnecessary.
+
+Destruct Tensor
+~~~~~~~~~~~~~~~
+
+As a standard TVM-FFI object, :cpp:class:`~tvm::ffi::TensorObj` follows the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+When the reference count reaches zero, the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes.
+
+Export Tensor to DLPack
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To share a :cpp:class:`~tvm::ffi::TensorObj` with other frameworks, export it as a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_ToDLPackVersioned.begin]
+ :end-before: [Tensor_ToDLPackVersioned.end]
+
+.. _abi-function:
+
+Function
+--------
+
+.. seealso::
+
+ :ref:`sec:function` for a detailed description of TVM-FFI functions.
+
+All functions in TVM-FFI follow a unified C calling convention that enables ABI-stable,
+type-erased, and cross-language function calls, defined by :cpp:type:`TVMFFISafeCallType`.
+
+**Calling convention.** The signature includes:
+
+- ``handle`` (``void*``): Optional resource handle passed to the callee; typically ``NULL`` for exported symbols
+- ``args`` (``TVMFFIAny*``) and ``num_args`` (``int``): Array of non-owning :cpp:class:`~tvm::ffi::AnyView` input arguments
+- ``result`` (``TVMFFIAny*``): Owning :cpp:class:`~tvm::ffi::Any` output value
+- Return value: ``0`` for success; ``-1`` or ``-2`` for errors (see :ref:`sec:exception`)
+
+**Object layout.** The :cpp:class:`~tvm::ffi::FunctionObj` stores call pointers after the object header.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIFunctionCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIFunctionCell.begin]
+ :end-before: [TVMFFIFunctionCell.end]
+ :caption: tvm/ffi/c_api.h
+
+Construct and Destroy
+~~~~~~~~~~~~~~~~~~~~~
+
+.. important::
+ Dynamic function creation is useful for passing lambdas or closures across language boundaries.
+
+The following C code constructs a :cpp:class:`~tvm::ffi::FunctionObj` from a :cpp:type:`TVMFFISafeCallType` and a ``deleter`` callback.
+The ``deleter`` cleans up resources owned by the function; for global symbols, it is typically ``NULL``.
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.Construct.begin]
+ :end-before: [Function.Construct.end]
+
+Release a :cpp:class:`~tvm::ffi::FunctionObj` using the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+
+Global Registry
+~~~~~~~~~~~~~~~
+
+**Retrieve a global function.** The following C code retrieves a function by name from the global registry:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.GetGlobal.begin]
+ :end-before: [Function.GetGlobal.end]
+
+**Register a global function.** The following C code registers a function by name in the global registry:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.SetGlobal.begin]
+ :end-before: [Function.SetGlobal.end]
+
+Call Function
+~~~~~~~~~~~~~
+
+The following C code invokes a :cpp:class:`~tvm::ffi::FunctionObj` with arguments:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.Call.begin]
+ :end-before: [Function.Call.end]
+
+
+.. _abi-exception:
+
+Exception
+---------
+
+.. seealso::
+
+ :ref:`sec:exception` for detailed exception handling patterns.
+
+Exceptions are a central part of TVM-FFI's ABI and calling convention.
+When errors occur, they are stored as objects with a :cpp:class:`TVMFFIErrorCell` payload.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIErrorCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIErrorCell.begin]
+ :end-before: [TVMFFIErrorCell.end]
+ :caption: tvm/ffi/c_api.h
+
+Retrieve Error Object
+~~~~~~~~~~~~~~~~~~~~~
+
+When a function returns ``-1``, an error object is stored in thread-local storage (TLS).
+Retrieve it with :cpp:func:`TVMFFIErrorMoveFromRaised`, which returns a :cpp:class:`tvm::ffi::ErrorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Error.HandleReturnCode.begin]
+ :end-before: [Error.HandleReturnCode.end]
+
+This function transfers ownership to the caller and clears the TLS slot.
+Call :cpp:func:`TVMFFIObjectDecRef` when done to avoid memory leaks.
+
+**Frontend errors (-2).** Error code ``-2`` is reserved for frontend errors.
+It is returned when :cpp:func:`TVMFFIEnvCheckSignals` detects a pending Python signal.
+In this case, do not retrieve the error from TLS; instead, consult the frontend's error mechanism.
+
+Print Error Message
+~~~~~~~~~~~~~~~~~~~
Review Comment:
How about that: making it an admonition instead of a section
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "gemini-code-assist[bot] (via GitHub)" <gi...@apache.org>.
gemini-code-assist[bot] commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2684156244
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,518 @@
+.. 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.
+
+ABI Overview
+============
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+.. important::
+ C code is used for clarity, precision and friendliness to compiler builders.
+ And C code can be readily translated into code generators such as LLVM IR builder.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+A small **static section** between :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+and :cpp:enumerator:`kTVMFFIDynObjectBegin <TVMFFITypeIndex::kTVMFFIDynObjectBegin>`
+is reserved for static object types, for example,
+
+- Strings (:cpp:enumerator:`kTVMFFIStr <TVMFFITypeIndex::kTVMFFIStr>`) and Bytes (:cpp:enumerator:`kTVMFFIBytes <TVMFFITypeIndex::kTVMFFIBytes>`): Section :ref:`abi-string-and-byte`
+- Errors (:cpp:enumerator:`kTVMFFIError <TVMFFITypeIndex::kTVMFFIError>`): Section :ref:`abi-exception`.
+- Functions (:cpp:enumerator:`kTVMFFIFunction <TVMFFITypeIndex::kTVMFFIFunction>`): Section :ref:`abi-function`.
+- Tensors (:cpp:enumerator:`kTVMFFITensor <TVMFFITypeIndex::kTVMFFITensor>`): Section :ref:`abi-tensor`.
+- Miscellaneous:
+ Modules (:cpp:enumerator:`kTVMFFIModule <TVMFFITypeIndex::kTVMFFIModule>`),
+ Arrays (:cpp:enumerator:`kTVMFFIArray <TVMFFITypeIndex::kTVMFFIArray>`),
+ Maps (:cpp:enumerator:`kTVMFFIMap <TVMFFITypeIndex::kTVMFFIMap>`),
+ Shapes (:cpp:enumerator:`kTVMFFIShape <TVMFFITypeIndex::kTVMFFIShape>`),
+ Opaque Python objects (:cpp:enumerator:`kTVMFFIOpaquePyObject <TVMFFITypeIndex::kTVMFFIOpaquePyObject>`).
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting, which includes both strong and weak references.
+Two C APIs manage strong reference counting:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire strong ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release strong ownership by decrementing the reference count
+
+The ``deleter`` callback (:cpp:member:`TVMFFIObject::deleter`) executes when the strong or weak count reaches zero with different flags.
+See :ref:`object-reference-counting` for details.
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor from DLPack
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code constructs a :cpp:class:`~tvm::ffi::TensorObj` from a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_FromDLPack.begin]
+ :end-before: [Tensor_FromDLPack.end]
+
+.. hint::
+ TVM-FFI's Python API automatically wraps framework tensors (e.g., :py:class:`torch.Tensor`) as :cpp:class:`~tvm::ffi::TensorObj`,
+ so manual conversion is typically unnecessary.
+
+Destruct Tensor
+~~~~~~~~~~~~~~~
+
+As a standard TVM-FFI object, :cpp:class:`~tvm::ffi::TensorObj` follows the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+When the reference count reaches zero, the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes.
+
+Export Tensor to DLPack
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To share a :cpp:class:`~tvm::ffi::TensorObj` with other frameworks, export it as a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_ToDLPackVersioned.begin]
+ :end-before: [Tensor_ToDLPackVersioned.end]
Review Comment:

The `Tensor_ToDLPackVersioned` example is helpful for showing how to export a tensor. However, it's missing a crucial detail about lifetime management. The returned `DLManagedTensorVersioned*` is owned by the caller, who is responsible for calling its `deleter` function once the tensor is no longer needed. This is a key part of the DLPack contract. Please add a note to clarify this and prevent potential resource leaks for users. For example:
```rst
.. note::
The caller takes ownership of the returned ``DLManagedTensorVersioned*`` and must call its ``deleter`` to release the tensor.
```
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,518 @@
+.. 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.
+
+ABI Overview
+============
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+.. important::
+ C code is used for clarity, precision and friendliness to compiler builders.
+ And C code can be readily translated into code generators such as LLVM IR builder.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+A small **static section** between :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+and :cpp:enumerator:`kTVMFFIDynObjectBegin <TVMFFITypeIndex::kTVMFFIDynObjectBegin>`
+is reserved for static object types, for example,
+
+- Strings (:cpp:enumerator:`kTVMFFIStr <TVMFFITypeIndex::kTVMFFIStr>`) and Bytes (:cpp:enumerator:`kTVMFFIBytes <TVMFFITypeIndex::kTVMFFIBytes>`): Section :ref:`abi-string-and-byte`
+- Errors (:cpp:enumerator:`kTVMFFIError <TVMFFITypeIndex::kTVMFFIError>`): Section :ref:`abi-exception`.
+- Functions (:cpp:enumerator:`kTVMFFIFunction <TVMFFITypeIndex::kTVMFFIFunction>`): Section :ref:`abi-function`.
+- Tensors (:cpp:enumerator:`kTVMFFITensor <TVMFFITypeIndex::kTVMFFITensor>`): Section :ref:`abi-tensor`.
+- Miscellaneous:
+ Modules (:cpp:enumerator:`kTVMFFIModule <TVMFFITypeIndex::kTVMFFIModule>`),
+ Arrays (:cpp:enumerator:`kTVMFFIArray <TVMFFITypeIndex::kTVMFFIArray>`),
+ Maps (:cpp:enumerator:`kTVMFFIMap <TVMFFITypeIndex::kTVMFFIMap>`),
+ Shapes (:cpp:enumerator:`kTVMFFIShape <TVMFFITypeIndex::kTVMFFIShape>`),
+ Opaque Python objects (:cpp:enumerator:`kTVMFFIOpaquePyObject <TVMFFITypeIndex::kTVMFFIOpaquePyObject>`).
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting, which includes both strong and weak references.
+Two C APIs manage strong reference counting:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire strong ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release strong ownership by decrementing the reference count
+
+The ``deleter`` callback (:cpp:member:`TVMFFIObject::deleter`) executes when the strong or weak count reaches zero with different flags.
+See :ref:`object-reference-counting` for details.
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor from DLPack
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code constructs a :cpp:class:`~tvm::ffi::TensorObj` from a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_FromDLPack.begin]
+ :end-before: [Tensor_FromDLPack.end]
+
+.. hint::
+ TVM-FFI's Python API automatically wraps framework tensors (e.g., :py:class:`torch.Tensor`) as :cpp:class:`~tvm::ffi::TensorObj`,
+ so manual conversion is typically unnecessary.
+
+Destruct Tensor
+~~~~~~~~~~~~~~~
+
+As a standard TVM-FFI object, :cpp:class:`~tvm::ffi::TensorObj` follows the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+When the reference count reaches zero, the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes.
+
+Export Tensor to DLPack
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To share a :cpp:class:`~tvm::ffi::TensorObj` with other frameworks, export it as a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_ToDLPackVersioned.begin]
+ :end-before: [Tensor_ToDLPackVersioned.end]
+
+.. _abi-function:
+
+Function
+--------
+
+.. seealso::
+
+ :ref:`sec:function` for a detailed description of TVM-FFI functions.
+
+All functions in TVM-FFI follow a unified C calling convention that enables ABI-stable,
+type-erased, and cross-language function calls, defined by :cpp:type:`TVMFFISafeCallType`.
+
+**Calling convention.** The signature includes:
+
+- ``handle`` (``void*``): Optional resource handle passed to the callee; typically ``NULL`` for exported symbols
+- ``args`` (``TVMFFIAny*``) and ``num_args`` (``int``): Array of non-owning :cpp:class:`~tvm::ffi::AnyView` input arguments
+- ``result`` (``TVMFFIAny*``): Owning :cpp:class:`~tvm::ffi::Any` output value
+- Return value: ``0`` for success; ``-1`` or ``-2`` for errors (see :ref:`sec:exception`)
+
+See :ref:`sec:function-calling-convention` for more details.
+
+**Memory layout.** The :cpp:class:`~tvm::ffi::FunctionObj` stores call pointers after the object header.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIFunctionCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIFunctionCell.begin]
+ :end-before: [TVMFFIFunctionCell.end]
+ :caption: tvm/ffi/c_api.h
+
+Construct and Destroy
+~~~~~~~~~~~~~~~~~~~~~
+
+.. important::
+ Dynamic function creation is useful for passing lambdas or closures across language boundaries.
+
+The following C code constructs a :cpp:class:`~tvm::ffi::FunctionObj` from a :cpp:type:`TVMFFISafeCallType` and a ``deleter`` callback.
+The ``deleter`` cleans up resources owned by the function; for global symbols, it is typically ``NULL``.
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.Construct.begin]
+ :end-before: [Function.Construct.end]
+
+Release a :cpp:class:`~tvm::ffi::FunctionObj` using the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+
+Global Registry
+~~~~~~~~~~~~~~~
+
+**Retrieve a global function.** The following C code retrieves a function by name from the global registry:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.GetGlobal.begin]
+ :end-before: [Function.GetGlobal.end]
Review Comment:

The `Function_RetrieveGlobal` example shows how to get a global function, but it omits the important step of resource management. `TVMFFIFunctionGetGlobal` returns an owning handle, which means the caller must call `TVMFFIObjectDecRef` on the returned object to prevent memory leaks. The previous documentation had a good example (`LookupAndCall`) that showed this. Please add a note to clarify this. For example:
```rst
.. note::
`TVMFFIFunctionGetGlobal` returns an owning handle. The caller must release it by calling :cpp:func:`TVMFFIObjectDecRef` when it's no longer needed.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "tqchen (via GitHub)" <gi...@apache.org>.
tqchen commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2687487736
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,527 @@
+.. 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.
+
+ABI Overview
+============
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+.. important::
+ C code is used for clarity, precision and friendliness to compiler builders.
+ And C code can be readily translated into code generators such as LLVM IR builder.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` struct can represent either an owning or a borrowing reference.
+These two ownership patterns are formalized by the C++ wrapper classes :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView`,
+which have identical memory layouts but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+A small **static section** between :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+and :cpp:enumerator:`kTVMFFIDynObjectBegin <TVMFFITypeIndex::kTVMFFIDynObjectBegin>`
+is reserved for static object types, for example,
+
+- Strings (:cpp:enumerator:`kTVMFFIStr <TVMFFITypeIndex::kTVMFFIStr>`) and Bytes (:cpp:enumerator:`kTVMFFIBytes <TVMFFITypeIndex::kTVMFFIBytes>`): Section :ref:`abi-string-and-byte`
+- Errors (:cpp:enumerator:`kTVMFFIError <TVMFFITypeIndex::kTVMFFIError>`): Section :ref:`abi-exception`.
+- Functions (:cpp:enumerator:`kTVMFFIFunction <TVMFFITypeIndex::kTVMFFIFunction>`): Section :ref:`abi-function`.
+- Tensors (:cpp:enumerator:`kTVMFFITensor <TVMFFITypeIndex::kTVMFFITensor>`): Section :ref:`abi-tensor`.
+- Miscellaneous:
+ Modules (:cpp:enumerator:`kTVMFFIModule <TVMFFITypeIndex::kTVMFFIModule>`),
+ Arrays (:cpp:enumerator:`kTVMFFIArray <TVMFFITypeIndex::kTVMFFIArray>`),
+ Maps (:cpp:enumerator:`kTVMFFIMap <TVMFFITypeIndex::kTVMFFIMap>`),
+ Shapes (:cpp:enumerator:`kTVMFFIShape <TVMFFITypeIndex::kTVMFFIShape>`),
+ Opaque Python objects (:cpp:enumerator:`kTVMFFIOpaquePyObject <TVMFFITypeIndex::kTVMFFIOpaquePyObject>`).
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting, which includes both strong and weak references.
+Two C APIs manage strong reference counting:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire strong ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release strong ownership by decrementing the reference count
+
+The ``deleter`` callback (:cpp:member:`TVMFFIObject::deleter`) executes when the strong or weak count reaches zero with different flags.
+See :ref:`object-reference-counting` for details.
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor from DLPack
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code constructs a :cpp:class:`~tvm::ffi::TensorObj` from a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_FromDLPack.begin]
+ :end-before: [Tensor_FromDLPack.end]
+
+.. hint::
+ TVM-FFI's Python API automatically wraps framework tensors (e.g., :py:class:`torch.Tensor`) as :cpp:class:`~tvm::ffi::TensorObj`,
+ so manual conversion is typically unnecessary.
+
+Destruct Tensor
+~~~~~~~~~~~~~~~
+
+As a standard TVM-FFI object, :cpp:class:`~tvm::ffi::TensorObj` follows the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+When the reference count reaches zero, the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes.
+
+Export Tensor to DLPack
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To share a :cpp:class:`~tvm::ffi::TensorObj` with other frameworks, export it as a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_ToDLPackVersioned.begin]
+ :end-before: [Tensor_ToDLPackVersioned.end]
+
+Note that the caller takes ownership of the returned :c:struct:`DLManagedTensorVersioned* <DLManagedTensorVersioned>`
+and must call its ``deleter`` to release the tensor.
+
+.. _abi-function:
+
+Function
+--------
+
+.. seealso::
+
+ :ref:`sec:function` for a detailed description of TVM-FFI functions.
+
+All functions in TVM-FFI follow a unified C calling convention that enables ABI-stable,
+type-erased, and cross-language function calls, defined by :cpp:type:`TVMFFISafeCallType`.
+
+**Calling convention.** The signature includes:
+
+- ``handle`` (``void*``): Optional resource handle passed to the callee; typically ``NULL`` for exported symbols
+- ``args`` (``TVMFFIAny*``) and ``num_args`` (``int``): Array of non-owning :cpp:class:`~tvm::ffi::AnyView` input arguments
+- ``result`` (``TVMFFIAny*``): Owning :cpp:class:`~tvm::ffi::Any` output value
+- Return value: ``0`` for success; ``-1`` or ``-2`` for errors (see :ref:`sec:exception`)
+
+See :ref:`sec:function-calling-convention` for more details.
Review Comment:
need note
```
Before calling the function, caller must set `result->type_index` to be kTVMFFINone, or any type index that do not corresponds to an on-heap object.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "tqchen (via GitHub)" <gi...@apache.org>.
tqchen commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2687246731
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
+The following C code constructs a :cpp:class:`~tvm::ffi::TensorObj` from a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_FromDLPack.begin]
+ :end-before: [Tensor_FromDLPack.end]
+
+.. hint::
+ TVM-FFI's Python API automatically wraps framework tensors (e.g., :py:class:`torch.Tensor`) as :cpp:class:`~tvm::ffi::TensorObj`,
+ so manual conversion is typically unnecessary.
+
+Destruct Tensor
+~~~~~~~~~~~~~~~
+
+As a standard TVM-FFI object, :cpp:class:`~tvm::ffi::TensorObj` follows the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+When the reference count reaches zero, the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes.
+
+Export Tensor to DLPack
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To share a :cpp:class:`~tvm::ffi::TensorObj` with other frameworks, export it as a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_ToDLPackVersioned.begin]
+ :end-before: [Tensor_ToDLPackVersioned.end]
+
+.. _abi-function:
+
+Function
+--------
+
+.. seealso::
+
+ :ref:`sec:function` for a detailed description of TVM-FFI functions.
+
+All functions in TVM-FFI follow a unified C calling convention that enables ABI-stable,
+type-erased, and cross-language function calls, defined by :cpp:type:`TVMFFISafeCallType`.
+
+**Calling convention.** The signature includes:
+
+- ``handle`` (``void*``): Optional resource handle passed to the callee; typically ``NULL`` for exported symbols
+- ``args`` (``TVMFFIAny*``) and ``num_args`` (``int``): Array of non-owning :cpp:class:`~tvm::ffi::AnyView` input arguments
+- ``result`` (``TVMFFIAny*``): Owning :cpp:class:`~tvm::ffi::Any` output value
+- Return value: ``0`` for success; ``-1`` or ``-2`` for errors (see :ref:`sec:exception`)
+
+**Object layout.** The :cpp:class:`~tvm::ffi::FunctionObj` stores call pointers after the object header.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIFunctionCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIFunctionCell.begin]
+ :end-before: [TVMFFIFunctionCell.end]
+ :caption: tvm/ffi/c_api.h
+
+Construct and Destroy
+~~~~~~~~~~~~~~~~~~~~~
+
+.. important::
+ Dynamic function creation is useful for passing lambdas or closures across language boundaries.
+
+The following C code constructs a :cpp:class:`~tvm::ffi::FunctionObj` from a :cpp:type:`TVMFFISafeCallType` and a ``deleter`` callback.
+The ``deleter`` cleans up resources owned by the function; for global symbols, it is typically ``NULL``.
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.Construct.begin]
+ :end-before: [Function.Construct.end]
+
+Release a :cpp:class:`~tvm::ffi::FunctionObj` using the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+
+Global Registry
+~~~~~~~~~~~~~~~
+
+**Retrieve a global function.** The following C code retrieves a function by name from the global registry:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.GetGlobal.begin]
+ :end-before: [Function.GetGlobal.end]
+
+**Register a global function.** The following C code registers a function by name in the global registry:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.SetGlobal.begin]
+ :end-before: [Function.SetGlobal.end]
+
+Call Function
+~~~~~~~~~~~~~
+
+The following C code invokes a :cpp:class:`~tvm::ffi::FunctionObj` with arguments:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.Call.begin]
+ :end-before: [Function.Call.end]
+
+
+.. _abi-exception:
+
+Exception
+---------
+
+.. seealso::
+
+ :ref:`sec:exception` for detailed exception handling patterns.
+
+Exceptions are a central part of TVM-FFI's ABI and calling convention.
+When errors occur, they are stored as objects with a :cpp:class:`TVMFFIErrorCell` payload.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIErrorCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIErrorCell.begin]
+ :end-before: [TVMFFIErrorCell.end]
+ :caption: tvm/ffi/c_api.h
+
+Retrieve Error Object
+~~~~~~~~~~~~~~~~~~~~~
+
+When a function returns ``-1``, an error object is stored in thread-local storage (TLS).
+Retrieve it with :cpp:func:`TVMFFIErrorMoveFromRaised`, which returns a :cpp:class:`tvm::ffi::ErrorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Error.HandleReturnCode.begin]
+ :end-before: [Error.HandleReturnCode.end]
+
+This function transfers ownership to the caller and clears the TLS slot.
+Call :cpp:func:`TVMFFIObjectDecRef` when done to avoid memory leaks.
+
+**Frontend errors (-2).** Error code ``-2`` is reserved for frontend errors.
+It is returned when :cpp:func:`TVMFFIEnvCheckSignals` detects a pending Python signal.
+In this case, do not retrieve the error from TLS; instead, consult the frontend's error mechanism.
+
+Print Error Message
+~~~~~~~~~~~~~~~~~~~
Review Comment:
That is fine, i think the main thing is we need to state this is an example on how one can print
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2687671485
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,527 @@
+.. 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.
+
+ABI Overview
+============
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+.. important::
+ C code is used for clarity, precision and friendliness to compiler builders.
+ And C code can be readily translated into code generators such as LLVM IR builder.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` struct can represent either an owning or a borrowing reference.
+These two ownership patterns are formalized by the C++ wrapper classes :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView`,
+which have identical memory layouts but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+A small **static section** between :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+and :cpp:enumerator:`kTVMFFIDynObjectBegin <TVMFFITypeIndex::kTVMFFIDynObjectBegin>`
+is reserved for static object types, for example,
+
+- Strings (:cpp:enumerator:`kTVMFFIStr <TVMFFITypeIndex::kTVMFFIStr>`) and Bytes (:cpp:enumerator:`kTVMFFIBytes <TVMFFITypeIndex::kTVMFFIBytes>`): Section :ref:`abi-string-and-byte`
+- Errors (:cpp:enumerator:`kTVMFFIError <TVMFFITypeIndex::kTVMFFIError>`): Section :ref:`abi-exception`.
+- Functions (:cpp:enumerator:`kTVMFFIFunction <TVMFFITypeIndex::kTVMFFIFunction>`): Section :ref:`abi-function`.
+- Tensors (:cpp:enumerator:`kTVMFFITensor <TVMFFITypeIndex::kTVMFFITensor>`): Section :ref:`abi-tensor`.
+- Miscellaneous:
+ Modules (:cpp:enumerator:`kTVMFFIModule <TVMFFITypeIndex::kTVMFFIModule>`),
+ Arrays (:cpp:enumerator:`kTVMFFIArray <TVMFFITypeIndex::kTVMFFIArray>`),
+ Maps (:cpp:enumerator:`kTVMFFIMap <TVMFFITypeIndex::kTVMFFIMap>`),
+ Shapes (:cpp:enumerator:`kTVMFFIShape <TVMFFITypeIndex::kTVMFFIShape>`),
+ Opaque Python objects (:cpp:enumerator:`kTVMFFIOpaquePyObject <TVMFFITypeIndex::kTVMFFIOpaquePyObject>`).
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting, which includes both strong and weak references.
+Two C APIs manage strong reference counting:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire strong ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release strong ownership by decrementing the reference count
+
+The ``deleter`` callback (:cpp:member:`TVMFFIObject::deleter`) executes when the strong or weak count reaches zero with different flags.
+See :ref:`object-reference-counting` for details.
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor from DLPack
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code constructs a :cpp:class:`~tvm::ffi::TensorObj` from a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_FromDLPack.begin]
+ :end-before: [Tensor_FromDLPack.end]
+
+.. hint::
+ TVM-FFI's Python API automatically wraps framework tensors (e.g., :py:class:`torch.Tensor`) as :cpp:class:`~tvm::ffi::TensorObj`,
+ so manual conversion is typically unnecessary.
+
+Destruct Tensor
+~~~~~~~~~~~~~~~
+
+As a standard TVM-FFI object, :cpp:class:`~tvm::ffi::TensorObj` follows the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+When the reference count reaches zero, the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes.
+
+Export Tensor to DLPack
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To share a :cpp:class:`~tvm::ffi::TensorObj` with other frameworks, export it as a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_ToDLPackVersioned.begin]
+ :end-before: [Tensor_ToDLPackVersioned.end]
+
+Note that the caller takes ownership of the returned :c:struct:`DLManagedTensorVersioned* <DLManagedTensorVersioned>`
+and must call its ``deleter`` to release the tensor.
+
+.. _abi-function:
+
+Function
+--------
+
+.. seealso::
+
+ :ref:`sec:function` for a detailed description of TVM-FFI functions.
+
+All functions in TVM-FFI follow a unified C calling convention that enables ABI-stable,
+type-erased, and cross-language function calls, defined by :cpp:type:`TVMFFISafeCallType`.
+
+**Calling convention.** The signature includes:
+
+- ``handle`` (``void*``): Optional resource handle passed to the callee; typically ``NULL`` for exported symbols
+- ``args`` (``TVMFFIAny*``) and ``num_args`` (``int``): Array of non-owning :cpp:class:`~tvm::ffi::AnyView` input arguments
+- ``result`` (``TVMFFIAny*``): Owning :cpp:class:`~tvm::ffi::Any` output value
+- Return value: ``0`` for success; ``-1`` or ``-2`` for errors (see :ref:`sec:exception`)
+
+See :ref:`sec:function-calling-convention` for more details.
Review Comment:
It's covered in another doc: https://tvm.apache.org/ffi/concepts/func_module.html#tvm-ffi-c-abi. but happy to emphasize it
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#issuecomment-3737342720
/gemini review
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "gemini-code-assist[bot] (via GitHub)" <gi...@apache.org>.
gemini-code-assist[bot] commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2680813868
##########
examples/abi_overview/example_code.c:
##########
@@ -0,0 +1,185 @@
+/*
+ * 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.
+ */
+
+// NOLINTBEGIN(modernize-deprecated-headers,modernize-use-nullptr)
+#include <assert.h>
+#include <dlpack/dlpack.h>
+#include <tvm/ffi/c_api.h>
+
+int IS_OWNING_ANY = 1;
+
+// [Any_AnyView.FromInt_Float.begin]
+TVMFFIAny Any_AnyView_FromInt(int64_t value) {
+ TVMFFIAny any;
+ any.type_index = kTVMFFIInt;
+ any.zero_padding = 0;
+ any.v_int64 = value;
+ return any;
+}
+
+TVMFFIAny Any_AnyView_FromFloat(double value) {
+ TVMFFIAny any;
+ any.type_index = kTVMFFIFloat;
+ any.zero_padding = 0;
+ any.v_float64 = value;
+ return any;
+}
+// [Any_AnyView.FromInt_Float.end]
+
+// [Any_AnyView.FromObjectPtr.begin]
+TVMFFIAny Any_AnyView_FromObjectPtr(TVMFFIObject* obj) {
+ TVMFFIAny any;
+ assert(obj != NULL);
+ any.type_index = kTVMFFIObject;
+ any.zero_padding = 0;
+ any.v_obj = obj;
+ // Increment refcount if it's Any (owning) instead of AnyView (borrowing)
+ if (IS_OWNING_ANY) {
+ TVMFFIObjectIncRef(obj);
+ }
+ return any;
+}
+// [Any_AnyView.FromObjectPtr.end]
+
+// [Any_AnyView.Destroy.begin]
+void Any_AnyView_Destroy(TVMFFIAny* any) {
+ if (IS_OWNING_ANY) {
+ // Checks if `any` holds a heap-allocated object,
+ // and if so, decrements the reference count
+ if (any->type_index >= kTVMFFIStaticObjectBegin) {
+ TVMFFIObjectDecRef(any->v_obj);
+ }
+ }
+ *any = (TVMFFIAny){0}; // Clears the `any` struct
+}
+// [Any_AnyView.Destroy.end]
+
+// [Any_AnyView.GetInt_Float.begin]
+int64_t Any_AnyView_GetInt(const TVMFFIAny* any) {
+ if (any->type_index == kTVMFFIInt || any->type_index == kTVMFFIBool) {
+ return any->v_int64;
+ } else if (any->type_index == kTVMFFIFloat) {
+ return (int64_t)(any->v_float64);
+ }
+ assert(0); // FAILED to read int
+ return 0;
+}
+
+double Any_AnyView_GetFloat(const TVMFFIAny* any) {
+ if (any->type_index == kTVMFFIInt || any->type_index == kTVMFFIFloat) {
+ return (double)(any->v_int64);
+ } else if (any->type_index == kTVMFFIFloat) {
+ return any->v_float64;
+ }
Review Comment:

There's a bug in this function's logic. If `any->type_index` is `kTVMFFIFloat`, the first `if` condition becomes true, and it incorrectly tries to return `(double)(any->v_int64)`. The `v_int64` field is not valid for a float value. The `else if` block that correctly handles floats is therefore unreachable.
To fix this, the first `if` condition should not check for `kTVMFFIFloat`.
```suggestion
if (any->type_index == kTVMFFIInt || any->type_index == kTVMFFIBool) {
return (double)(any->v_int64);
} else if (any->type_index == kTVMFFIFloat) {
return any->v_float64;
}
```
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,466 @@
+.. 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.
+
+ABI Overview
+============
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+Overall, TVM-FFI ABI is designed is around the following key principles:
Review Comment:

There's a small grammatical error here. It says 'is designed is', which should be 'is designed'.
```suggestion
Overall, TVM-FFI ABI is designed around the following key principles:
```
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,466 @@
+.. 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.
+
+ABI Overview
+============
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+Overall, TVM-FFI ABI is designed is around the following key principles:
+
+- **Minimal and efficient**. Keep things simple when possible and bring close-to-metal efficiency.
+- **Stability guarantee**. The ABI is stable across compiler versions and independent of host languages or frameworks.
+- **Expressive for machine learning** TBA.
+- **Extensible**. The ABI is extensible to support new types and features.
+
+This tutorial covers common concepts and usage patterns with TVM-FFI's ABI with low-level C code for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership**. :cpp:class:`TVMFFIAny` has two variants with exact same layout but different :ref:`ownership semantics <any-ownership>`:
+
+- Managed owning :cpp:class:`tvm::ffi::Any`
+- Unmanaged borrowing :cpp:class:`tvm::ffi::AnyView`
+
+.. note::
+ To switch a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index**. The ``type_index`` field identifies what kind of value is stored.
+
+- :ref:`Atomic POD types <any-atomic-types>`, where ``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`.
+ They are stored in-place in payload union, without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>`, where ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`.
+ They are stored in a heap-allocated, reference-counted TVM-FFI object.
+
+.. important::
+ Type index system in TVM-FFI does not rely on C++ features such as RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**Constructing from atomic POD types**. The C code below constructs an :cpp:class:`TVMFFIAny` from an integer:
+
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Essentially, properly assign ``type_index`` from :cpp:enum:`TVMFFITypeIndex`, and then set the payload field accordingly.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**Construct from object types**. The C code below constructs an :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+For an owning :cpp:class:`~tvm::ffi::Any` where ``IS_OWNING_ANY`` is ``true``, it increments the reference count of the heap-allocated object.
+
+Destruct Any
+~~~~~~~~~~~~
+
+The C code below destroys an :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+For an owning :cpp:class:`~tvm::ffi::Any` where ``IS_OWNING_ANY`` is ``true``, it decrements the reference count of the heap-allocated object.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD**. The C code below extracts an integer or float from an :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+It is possible that casting may happen, for example, in the code above, when trying to get a float and
+:cpp:class:`TVMFFIAny` has an integer value, the integer is casted to a float.
Review Comment:

The word 'casted' is grammatically incorrect; the past participle of 'cast' is 'cast'. Also, the sentence could be rephrased for better clarity.
```suggestion
It is possible that casting may happen. For example, in the code above, when trying to get a float from a :cpp:class:`TVMFFIAny` that holds an integer value, the integer is cast to a float.
```
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,466 @@
+.. 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.
+
+ABI Overview
+============
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+Overall, TVM-FFI ABI is designed is around the following key principles:
+
+- **Minimal and efficient**. Keep things simple when possible and bring close-to-metal efficiency.
+- **Stability guarantee**. The ABI is stable across compiler versions and independent of host languages or frameworks.
+- **Expressive for machine learning** TBA.
Review Comment:

This line contains a 'TBA' (To Be Added) placeholder. It's best to either fill this in with the relevant information or remove the line to avoid shipping incomplete documentation.
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,466 @@
+.. 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.
+
+ABI Overview
+============
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+Overall, TVM-FFI ABI is designed is around the following key principles:
+
+- **Minimal and efficient**. Keep things simple when possible and bring close-to-metal efficiency.
+- **Stability guarantee**. The ABI is stable across compiler versions and independent of host languages or frameworks.
+- **Expressive for machine learning** TBA.
+- **Extensible**. The ABI is extensible to support new types and features.
+
+This tutorial covers common concepts and usage patterns with TVM-FFI's ABI with low-level C code for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership**. :cpp:class:`TVMFFIAny` has two variants with exact same layout but different :ref:`ownership semantics <any-ownership>`:
+
+- Managed owning :cpp:class:`tvm::ffi::Any`
+- Unmanaged borrowing :cpp:class:`tvm::ffi::AnyView`
+
+.. note::
+ To switch a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index**. The ``type_index`` field identifies what kind of value is stored.
+
+- :ref:`Atomic POD types <any-atomic-types>`, where ``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`.
+ They are stored in-place in payload union, without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>`, where ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`.
+ They are stored in a heap-allocated, reference-counted TVM-FFI object.
+
+.. important::
+ Type index system in TVM-FFI does not rely on C++ features such as RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**Constructing from atomic POD types**. The C code below constructs an :cpp:class:`TVMFFIAny` from an integer:
+
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Essentially, properly assign ``type_index`` from :cpp:enum:`TVMFFITypeIndex`, and then set the payload field accordingly.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**Construct from object types**. The C code below constructs an :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+For an owning :cpp:class:`~tvm::ffi::Any` where ``IS_OWNING_ANY`` is ``true``, it increments the reference count of the heap-allocated object.
+
+Destruct Any
+~~~~~~~~~~~~
+
+The C code below destroys an :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+For an owning :cpp:class:`~tvm::ffi::Any` where ``IS_OWNING_ANY`` is ``true``, it decrements the reference count of the heap-allocated object.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD**. The C code below extracts an integer or float from an :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+It is possible that casting may happen, for example, in the code above, when trying to get a float and
+:cpp:class:`TVMFFIAny` has an integer value, the integer is casted to a float.
+
+**Extract a DLTensor**. A DLTensor may come from either a raw pointer or a heap-allocated object :cpp:class:`tvm::ffi::TensorObj`.
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object**. A TVM-FFI object is always heap-allocated, reference-counted, and
+its ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`.
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+Note that if the caller owns the return value, it should increment the reference count via :cpp:func:`TVMFFIObjectIncRef`,
+and release the ownership via :cpp:func:`TVMFFIObjectDecRef`.
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All objects in TVM-FFI share the following characteristics:
+
+- are heap-allocated and reference-counted;
+- have a layout-stable 24-byte header that stores reference counts, type index, and a deleter callback;
+- their type index is always >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`;
+
+**Dynamic Type System.** Classes can be dynamically registered at runtime, and single inheritance is supported
+between classes via :cpp:func:`TVMFFITypeGetOrAllocIndex`. See :ref:`type-checking-and-casting` for how to use the type system.
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed by reference counting. See :ref:`object-reference-counting` for details.
+
+The C code below manages the ownership of a TVM-FFI object via
+
+- :cpp:func:`TVMFFIObjectIncRef`: Grab ownership by incrementing the reference count.
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count. Its deleter callback (:cpp:member:`TVMFFIObject::deleter`) kicks in when the reference count reaches zero.
+
+**Move ownership from Any/AnyView**. The C code below moves ownership of a TVM-FFI object from an owning :cpp:class:`~tvm::ffi::Any` to an Object pointer.
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Note that because :cpp:class:`~tvm::ffi::AnyView` is a non-owning view (where ``IS_OWNING_ANY`` is ``false``),
+obtaining ownership from it requires incrementing the reference count.
+
+**Release ownership**. The C code below releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+Single inheritance relationship can be modeled as a tree, where each node points to its only parent.
+TVM-FFI manages every type with a unique type index, their ancestors, their depths in the inheritance tree, etc.,
+and this information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The C code below checks if a type is a subclass of another type:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides a DLPack-native tensor class :cpp:class:`tvm::ffi::TensorObj`, which is a standard TVM-FFI object,
+meaning it can be managed in the same way as other TVM-FFI objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The C code below accesses the :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+Tensor's shape, dtype, device, data pointer, etc., are accessible via the :c:struct:`DLTensor` pointer.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
+The C code below constructs a :cpp:class:`~tvm::ffi::TensorObj` from a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_FromDLPack.begin]
+ :end-before: [Tensor_FromDLPack.end]
+
+.. hint::
+ TVM-FFI's Python API automatically wraps framework tensors (e.g. :py:class:`torch.Tensor`) to :cpp:class:`~tvm::ffi::TensorObj`,
+ meaning the method above is usually **unnecessary** because conversion is handled already.
+
+Destruct Tensor
+~~~~~~~~~~~~~~~~
+
+The :ref:`standard way <ABI.Object.Destroy>` applies here to release a :cpp:class:`~tvm::ffi::TensorObj`
+because it is a standard TVM-FFI object. Once the reference count reaches zero,
+the deleter callback (:cpp:member:`TVMFFIObject::deleter`) will be called.
+
+Export Tensor to DLPack
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Occasionally, it could be useful to export a :cpp:class:`~tvm::ffi::TensorObj` to :c:struct:`DLManagedTensorVersioned`,
+so that it could potentially be consumed by other frameworks.
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_ToDLPackVersioned.begin]
+ :end-before: [Tensor_ToDLPackVersioned.end]
+
+Function
+--------
+
+.. seealso::
+
+ :doc:`func_module` for function calling and module loading.
+
+Functions in TVM-FFI follow a unified C calling convention that enables type-erased,
+cross-language function calls.
+
+.. dropdown:: C ABI Reference: :cpp:type:`TVMFFISafeCallType`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFISafeCallType.begin]
+ :end-before: [TVMFFISafeCallType.end]
+ :caption: tvm/ffi/c_api.h
+
+**Return Value Convention:**
+
+- ``0``: Success
+- ``-1``: Error occurred, retrievable via :cpp:func:`TVMFFIErrorMoveFromRaised`
+- ``-2``: Frontend error (e.g., Python exception)
+
+**Function Object Layout.** The :cpp:class:`~tvm::ffi::FunctionObj` stores call pointers after the object header.
+Access the function cell by skipping the :cpp:class:`TVMFFIObject` header:
+``TVMFFIFunctionCell* cell = (TVMFFIFunctionCell*)((char*)func_obj + sizeof(TVMFFIObject));``
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIFunctionCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIFunctionCell.begin]
+ :end-before: [TVMFFIFunctionCell.end]
+ :caption: tvm/ffi/c_api.h
+
+**Calling a Function:**
+
+.. code-block:: cpp
+
+ int CallFunction(TVMFFIObjectHandle func, int x, int y) {
+ TVMFFIAny args[2], result;
+
+ // Set up arguments
+ args[0].type_index = kTVMFFIInt;
+ args[0].zero_padding = 0;
+ args[0].v_int64 = x;
+
+ args[1].type_index = kTVMFFIInt;
+ args[1].zero_padding = 0;
+ args[1].v_int64 = y;
+
+ // Initialize result (required!)
+ result.type_index = kTVMFFINone;
+ result.zero_padding = 0;
+ result.v_int64 = 0;
+
+ int rc = TVMFFIFunctionCall(func, args, 2, &result);
+ if (rc != 0) {
+ // Handle error
+ TVMFFIObjectHandle err = NULL;
+ TVMFFIErrorMoveFromRaised(&err);
+ // ... process error ...
+ TVMFFIObjectDecRef(err);
+ return rc;
+ }
+ return result.v_int64;
+ }
+
+Exception
+---------
+
+Exceptions are stored as objects with a :cpp:class:`TVMFFIErrorCell` payload.
+Access the error cell by skipping the :cpp:class:`TVMFFIObject` header:
+``TVMFFIErrorCell* cell = (TVMFFIErrorCell*)((char*)err_obj + sizeof(TVMFFIObject));``
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIErrorCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIErrorCell.begin]
+ :end-before: [TVMFFIErrorCell.end]
+ :caption: tvm/ffi/c_api.h
+
+**Raising an Exception:**
+
+.. code-block:: cpp
+
+ int MyFunction(void* handle, const TVMFFIAny* args,
+ int32_t num_args, TVMFFIAny* result) {
+ if (num_args < 1) {
+ TVMFFIErrorSetRaisedFromCStr("ValueError", "Expected at least 1 argument");
+ return -1;
+ }
+ // ... function implementation ...
+ return 0;
+ }
+
+Module
+------
+
+A :cpp:class:`~tvm::ffi::Module` is a namespace containing functions, typically loaded from a shared library
+or bundled with the executable.
+
+**Loading Shared Libraries.** Functions exported with the ``__tvm_ffi_<name>`` symbol
+convention can be loaded dynamically:
+
+.. code-block:: cpp
+
+ // In shared library (C++):
+ TVM_FFI_DLL_EXPORT_TYPED_FUNC(my_func, MyFunctionImpl);
+ // Creates symbol: __tvm_ffi_my_func
+
+Use :py:func:`tvm_ffi.load_module` in Python or the corresponding C++ API to load.
+
+**System Library.** For statically linked symbols, register during initialization:
+
+.. code-block:: cpp
+
+ #include <tvm/ffi/extra/c_env_api.h>
+
+ // Register symbol for system library lookup
+ TVMFFIEnvModRegisterSystemLibSymbol("__tvm_ffi_my_prefix.my_func", my_func_ptr);
+
+**Looking Up Functions from Imports.** Use :cpp:func:`TVMFFIEnvModLookupFromImports` to
+find functions in a module's import chain:
+
+.. code-block:: cpp
+
+ TVMFFIObjectHandle func = NULL;
+ int rc = TVMFFIEnvModLookupFromImports(library_ctx, "my_function", &func);
+
+String and Byte
+---------------
+
+Strings and bytes have multiple representations identified by ``type_index``:
+
+- :cpp:enumerator:`kTVMFFIRawStr <TVMFFITypeIndex::kTVMFFIRawStr>`: Raw ``const char*`` in ``v_c_str`` (null-terminated, non-owning)
+- :cpp:enumerator:`kTVMFFISmallStr <TVMFFITypeIndex::kTVMFFISmallStr>` / :cpp:enumerator:`kTVMFFISmallBytes <TVMFFITypeIndex::kTVMFFISmallBytes>`: Inline storage in ``v_bytes`` (≤7 bytes)
+- :cpp:enumerator:`kTVMFFIStr <TVMFFITypeIndex::kTVMFFIStr>` / :cpp:enumerator:`kTVMFFIBytes <TVMFFITypeIndex::kTVMFFIBytes>`: Heap-allocated object with :cpp:class:`TVMFFIByteArray` payload
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIByteArray` and :cpp:class:`TVMFFIShapeCell`
Review Comment:

The dropdown title includes `:cpp:class:`TVMFFIShapeCell``, but this section is about 'String and Byte'. `TVMFFIShapeCell` is not directly related to strings or bytes, which might confuse readers. Consider making the dropdown more focused on `TVMFFIByteArray` or clarifying why `TVMFFIShapeCell` is included here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2687662211
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
Review Comment:
Updated to include allocation APIs
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2684015221
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
+The following C code constructs a :cpp:class:`~tvm::ffi::TensorObj` from a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_FromDLPack.begin]
+ :end-before: [Tensor_FromDLPack.end]
+
+.. hint::
+ TVM-FFI's Python API automatically wraps framework tensors (e.g., :py:class:`torch.Tensor`) as :cpp:class:`~tvm::ffi::TensorObj`,
+ so manual conversion is typically unnecessary.
+
+Destruct Tensor
+~~~~~~~~~~~~~~~
+
+As a standard TVM-FFI object, :cpp:class:`~tvm::ffi::TensorObj` follows the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+When the reference count reaches zero, the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes.
+
+Export Tensor to DLPack
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To share a :cpp:class:`~tvm::ffi::TensorObj` with other frameworks, export it as a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_ToDLPackVersioned.begin]
+ :end-before: [Tensor_ToDLPackVersioned.end]
+
+.. _abi-function:
+
+Function
+--------
+
+.. seealso::
+
+ :ref:`sec:function` for a detailed description of TVM-FFI functions.
+
+All functions in TVM-FFI follow a unified C calling convention that enables ABI-stable,
+type-erased, and cross-language function calls, defined by :cpp:type:`TVMFFISafeCallType`.
+
+**Calling convention.** The signature includes:
+
+- ``handle`` (``void*``): Optional resource handle passed to the callee; typically ``NULL`` for exported symbols
+- ``args`` (``TVMFFIAny*``) and ``num_args`` (``int``): Array of non-owning :cpp:class:`~tvm::ffi::AnyView` input arguments
+- ``result`` (``TVMFFIAny*``): Owning :cpp:class:`~tvm::ffi::Any` output value
+- Return value: ``0`` for success; ``-1`` or ``-2`` for errors (see :ref:`sec:exception`)
Review Comment:
```rst
This design is called a **packed function**, because it "packs" all arguments into a single array of type-erased :cpp:type:`tvm::ffi::AnyView`,
and further unifies calling convention across all languages without resorting to JIT compilation.
More specifically, this mechanism enables the following scenarios:
- **Dynamic languages**. Well-optimized bindings are provided for, e.g. Python, to translate arguments into packed function format, and translate return value back to the host language.
- **Static languages**. Metaprogramming techniques, such as C++ templates, are usually available to directly instantiate packed format on stack, saving the need for dynamic examination.
- **Cross-language callbacks**. Language-agnostic :cpp:class:`tvm::ffi::Function` makes it easy to call between languages without depending on languaga-specific features such as GIL.
**Performance Implications**. This approach is in practice highly efficient in machine learning workloads.
- In Python/C++ calls, we can get to microsecond level overhead, which is generally similar to overhead for eager mode;
- When both sides of calls are static languages, the overhead will go down to tens of nanoseconds.
.. note::
Although we found it less necessary in practice, further link time optimization (LTO) is still theoretically possible
in scenarios where both sides are static languages with a known symbol and linked into a single binary.
In this case, the callee can be inlined into caller side and the stack argument memory can be passed into register passing.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao merged PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "tqchen (via GitHub)" <gi...@apache.org>.
tqchen commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2687240867
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
Review Comment:
the most common way is actually https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h#L99 which calls the underlying dlpack allocator
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2683837623
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
+The following C code constructs a :cpp:class:`~tvm::ffi::TensorObj` from a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_FromDLPack.begin]
+ :end-before: [Tensor_FromDLPack.end]
+
+.. hint::
+ TVM-FFI's Python API automatically wraps framework tensors (e.g., :py:class:`torch.Tensor`) as :cpp:class:`~tvm::ffi::TensorObj`,
+ so manual conversion is typically unnecessary.
+
+Destruct Tensor
+~~~~~~~~~~~~~~~
+
+As a standard TVM-FFI object, :cpp:class:`~tvm::ffi::TensorObj` follows the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+When the reference count reaches zero, the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes.
+
+Export Tensor to DLPack
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To share a :cpp:class:`~tvm::ffi::TensorObj` with other frameworks, export it as a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_ToDLPackVersioned.begin]
+ :end-before: [Tensor_ToDLPackVersioned.end]
+
+.. _abi-function:
+
+Function
+--------
+
+.. seealso::
+
+ :ref:`sec:function` for a detailed description of TVM-FFI functions.
+
+All functions in TVM-FFI follow a unified C calling convention that enables ABI-stable,
+type-erased, and cross-language function calls, defined by :cpp:type:`TVMFFISafeCallType`.
+
+**Calling convention.** The signature includes:
+
+- ``handle`` (``void*``): Optional resource handle passed to the callee; typically ``NULL`` for exported symbols
+- ``args`` (``TVMFFIAny*``) and ``num_args`` (``int``): Array of non-owning :cpp:class:`~tvm::ffi::AnyView` input arguments
+- ``result`` (``TVMFFIAny*``): Owning :cpp:class:`~tvm::ffi::Any` output value
+- Return value: ``0`` for success; ``-1`` or ``-2`` for errors (see :ref:`sec:exception`)
+
+**Object layout.** The :cpp:class:`~tvm::ffi::FunctionObj` stores call pointers after the object header.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIFunctionCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIFunctionCell.begin]
+ :end-before: [TVMFFIFunctionCell.end]
+ :caption: tvm/ffi/c_api.h
+
+Construct and Destroy
+~~~~~~~~~~~~~~~~~~~~~
+
+.. important::
+ Dynamic function creation is useful for passing lambdas or closures across language boundaries.
+
+The following C code constructs a :cpp:class:`~tvm::ffi::FunctionObj` from a :cpp:type:`TVMFFISafeCallType` and a ``deleter`` callback.
+The ``deleter`` cleans up resources owned by the function; for global symbols, it is typically ``NULL``.
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.Construct.begin]
+ :end-before: [Function.Construct.end]
+
+Release a :cpp:class:`~tvm::ffi::FunctionObj` using the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+
+Global Registry
+~~~~~~~~~~~~~~~
+
+**Retrieve a global function.** The following C code retrieves a function by name from the global registry:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.GetGlobal.begin]
+ :end-before: [Function.GetGlobal.end]
+
+**Register a global function.** The following C code registers a function by name in the global registry:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.SetGlobal.begin]
+ :end-before: [Function.SetGlobal.end]
+
+Call Function
+~~~~~~~~~~~~~
+
+The following C code invokes a :cpp:class:`~tvm::ffi::FunctionObj` with arguments:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.Call.begin]
+ :end-before: [Function.Call.end]
+
+
+.. _abi-exception:
+
+Exception
+---------
+
+.. seealso::
+
+ :ref:`sec:exception` for detailed exception handling patterns.
+
+Exceptions are a central part of TVM-FFI's ABI and calling convention.
+When errors occur, they are stored as objects with a :cpp:class:`TVMFFIErrorCell` payload.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIErrorCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIErrorCell.begin]
+ :end-before: [TVMFFIErrorCell.end]
+ :caption: tvm/ffi/c_api.h
+
+Retrieve Error Object
+~~~~~~~~~~~~~~~~~~~~~
+
+When a function returns ``-1``, an error object is stored in thread-local storage (TLS).
+Retrieve it with :cpp:func:`TVMFFIErrorMoveFromRaised`, which returns a :cpp:class:`tvm::ffi::ErrorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Error.HandleReturnCode.begin]
+ :end-before: [Error.HandleReturnCode.end]
+
+This function transfers ownership to the caller and clears the TLS slot.
+Call :cpp:func:`TVMFFIObjectDecRef` when done to avoid memory leaks.
+
+**Frontend errors (-2).** Error code ``-2`` is reserved for frontend errors.
+It is returned when :cpp:func:`TVMFFIEnvCheckSignals` detects a pending Python signal.
+In this case, do not retrieve the error from TLS; instead, consult the frontend's error mechanism.
+
+Print Error Message
+~~~~~~~~~~~~~~~~~~~
Review Comment:
How about that: making it an abomination instead of a section
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#issuecomment-3740853638
/gemini Review
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "tqchen (via GitHub)" <gi...@apache.org>.
tqchen commented on PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#issuecomment-3745367988
some followup notes
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2683789448
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
+The following C code constructs a :cpp:class:`~tvm::ffi::TensorObj` from a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_FromDLPack.begin]
+ :end-before: [Tensor_FromDLPack.end]
+
+.. hint::
+ TVM-FFI's Python API automatically wraps framework tensors (e.g., :py:class:`torch.Tensor`) as :cpp:class:`~tvm::ffi::TensorObj`,
+ so manual conversion is typically unnecessary.
+
+Destruct Tensor
+~~~~~~~~~~~~~~~
+
+As a standard TVM-FFI object, :cpp:class:`~tvm::ffi::TensorObj` follows the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+When the reference count reaches zero, the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes.
+
+Export Tensor to DLPack
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To share a :cpp:class:`~tvm::ffi::TensorObj` with other frameworks, export it as a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_ToDLPackVersioned.begin]
+ :end-before: [Tensor_ToDLPackVersioned.end]
+
+.. _abi-function:
+
+Function
+--------
+
+.. seealso::
+
+ :ref:`sec:function` for a detailed description of TVM-FFI functions.
+
+All functions in TVM-FFI follow a unified C calling convention that enables ABI-stable,
+type-erased, and cross-language function calls, defined by :cpp:type:`TVMFFISafeCallType`.
+
+**Calling convention.** The signature includes:
+
+- ``handle`` (``void*``): Optional resource handle passed to the callee; typically ``NULL`` for exported symbols
+- ``args`` (``TVMFFIAny*``) and ``num_args`` (``int``): Array of non-owning :cpp:class:`~tvm::ffi::AnyView` input arguments
+- ``result`` (``TVMFFIAny*``): Owning :cpp:class:`~tvm::ffi::Any` output value
+- Return value: ``0`` for success; ``-1`` or ``-2`` for errors (see :ref:`sec:exception`)
+
+**Object layout.** The :cpp:class:`~tvm::ffi::FunctionObj` stores call pointers after the object header.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIFunctionCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIFunctionCell.begin]
+ :end-before: [TVMFFIFunctionCell.end]
+ :caption: tvm/ffi/c_api.h
+
+Construct and Destroy
+~~~~~~~~~~~~~~~~~~~~~
+
+.. important::
+ Dynamic function creation is useful for passing lambdas or closures across language boundaries.
+
+The following C code constructs a :cpp:class:`~tvm::ffi::FunctionObj` from a :cpp:type:`TVMFFISafeCallType` and a ``deleter`` callback.
+The ``deleter`` cleans up resources owned by the function; for global symbols, it is typically ``NULL``.
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.Construct.begin]
+ :end-before: [Function.Construct.end]
+
+Release a :cpp:class:`~tvm::ffi::FunctionObj` using the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+
+Global Registry
+~~~~~~~~~~~~~~~
+
+**Retrieve a global function.** The following C code retrieves a function by name from the global registry:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.GetGlobal.begin]
+ :end-before: [Function.GetGlobal.end]
+
+**Register a global function.** The following C code registers a function by name in the global registry:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.SetGlobal.begin]
+ :end-before: [Function.SetGlobal.end]
+
+Call Function
+~~~~~~~~~~~~~
+
+The following C code invokes a :cpp:class:`~tvm::ffi::FunctionObj` with arguments:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.Call.begin]
+ :end-before: [Function.Call.end]
+
+
+.. _abi-exception:
+
+Exception
+---------
+
+.. seealso::
+
+ :ref:`sec:exception` for detailed exception handling patterns.
+
+Exceptions are a central part of TVM-FFI's ABI and calling convention.
+When errors occur, they are stored as objects with a :cpp:class:`TVMFFIErrorCell` payload.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIErrorCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIErrorCell.begin]
+ :end-before: [TVMFFIErrorCell.end]
+ :caption: tvm/ffi/c_api.h
+
+Retrieve Error Object
+~~~~~~~~~~~~~~~~~~~~~
+
+When a function returns ``-1``, an error object is stored in thread-local storage (TLS).
+Retrieve it with :cpp:func:`TVMFFIErrorMoveFromRaised`, which returns a :cpp:class:`tvm::ffi::ErrorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Error.HandleReturnCode.begin]
+ :end-before: [Error.HandleReturnCode.end]
+
+This function transfers ownership to the caller and clears the TLS slot.
+Call :cpp:func:`TVMFFIObjectDecRef` when done to avoid memory leaks.
+
+**Frontend errors (-2).** Error code ``-2`` is reserved for frontend errors.
+It is returned when :cpp:func:`TVMFFIEnvCheckSignals` detects a pending Python signal.
+In this case, do not retrieve the error from TLS; instead, consult the frontend's error mechanism.
+
+Print Error Message
+~~~~~~~~~~~~~~~~~~~
Review Comment:
I do think it's important for purpose of debugging compiler codegen. Is it core part of ABI? I'd say perhaps - because it does rely on `ErrorObj`'s layout 🤔
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2683782294
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
Review Comment:
What is the C API for constructing a tensor (w/o DLPack)? I suppose we need to construct a `DLManagedTensor` first, and then use this C API to convert it to `TensorObj*` - is my understanding correct?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "gemini-code-assist[bot] (via GitHub)" <gi...@apache.org>.
gemini-code-assist[bot] commented on PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#issuecomment-3736808168
## Summary of Changes
Hello @junrushao, I'm Gemini Code Assist[^1]! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request significantly enhances the project's documentation by introducing a detailed and structured overview of the TVM-FFI Application Binary Interface. The new documentation clarifies the fundamental design principles, data structures, and interaction patterns of the ABI, supported by concrete C code examples. This addition aims to provide developers with a clearer understanding of how to work with TVM-FFI at a low level, improving the accessibility and maintainability of the system.
### Highlights
* **New ABI Overview Documentation**: A new reStructuredText document (docs/concepts/abi_overview.rst) has been added, providing a comprehensive overview of the TVM-FFI ABI. This document details core principles, data types like Any, Object, Tensor, Function, Exception, Module, and String/Byte types, and their usage patterns.
* **Accompanying C Code Examples**: A new C example file (examples/abi_overview/example_code.c) has been introduced to provide practical, low-level demonstrations for the ABI concepts explained in the new documentation.
* **Documentation Structure Refinement**: The existing docs/index.rst has been updated to include the new ABI overview, and docs/concepts/any.rst and docs/concepts/object_and_class.rst have been modified to add internal cross-reference labels, improving navigability and consistency.
* **Migration of Legacy ABI Doc**: The previous Markdown-based ABI overview (docs/concepts/abi_overview.md) has been renamed to docs/concepts/abi_overview_legacy.rst, indicating a shift towards reStructuredText for core documentation.
* **C API Header Annotations**: The include/tvm/ffi/c_api.h file now includes // [TAG.begin] and // [TAG.end] comments around key ABI structure and enum definitions, facilitating automatic inclusion of code snippets in the new documentation.
🧠**New Feature in Public Preview:** You can now enable **Memory** to help **Gemini Code Assist** learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. **Click [here](https://codeassist.google/code-review/login) to enable Memory in your admin console.**
<details>
<summary><b>Using Gemini Code Assist</b></summary>
<br>
The full guide for Gemini Code Assist can be found on our [documentation page](https://developers.google.com/gemini-code-assist/docs/review-github-code), here are some quick tips.
<b>Invoking Gemini</b>
You can request assistance from Gemini at any point by creating a comment using either `/gemini <command>` or `@gemini-code-assist <command>`. Below is a summary of the supported commands on the current page.
Feature | Command | Description
--- | --- | ---
Code Review | `/gemini review` | Performs a code review for the current pull request in its current state.
Pull Request Summary | `/gemini summary` | Provides a summary of the current pull request in its current state.
Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help | `/gemini help` | Displays a list of available commands.
<b>Customization</b>
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a `.gemini/` folder in the base of the repository. Detailed instructions can be found [here](https://developers.google.com/gemini-code-assist/docs/customize-gemini-behavior-github).
<b>Limitations & Feedback</b>
Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with :thumbsup: and :thumbsdown: on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up [here](https://google.qualtrics.com/jfe/form/SV_2cyuGuTWsEw84yG).
<b>You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the [Gemini Code Assist IDE Extension](https://cloud.google.com/products/gemini/code-assist).</b>
</details>
[^1]: Review the [Privacy Notices](https://policies.google.com/privacy), [Generative AI Prohibited Use Policy](https://policies.google.com/terms/generative-ai/use-policy), [Terms of Service](https://policies.google.com/terms), and learn how to configure Gemini Code Assist in GitHub [here](https://developers.google.com/gemini-code-assist/docs/customize-gemini-behavior-github). Gemini can make mistakes, so double check it and [use code with caution](https://support.google.com/legal/answer/13505487).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "tqchen (via GitHub)" <gi...@apache.org>.
tqchen commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2682484863
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
Review Comment:
this is not accurate, and maybe viewed as an deleter being called once when ref count reaches zero
see text in original doc. Deleter is called in both strong and weak events, worthwhile cross check object reference counting section
`TVMFFIObject` defines a common 24-byte intrusive header that all in-memory objects share:
- `combined_ref_count` packs strong and weak reference counter of the object into a single 64bit field
- The lower 32bits stores the strong atomic reference counter:
`strong_ref_count = combined_ref_count & 0xFFFFFFFF`
- The higher 32bits stores the weak atomic reference counter:
`weak_ref_count = (combined_ref_count >> 32) & 0xFFFFFFFF`
- `type_index` helps us identify the type being stored, which is consistent with `TVMFFIAny.type_index`.
- `deleter` should be called when either the strong or weak ref counter goes to zero.
- The flags are set to indicate the event of either weak or strong going to zero, or both.
- When strong reference counter gets to zero, the deleter needs to call the destructor of the object.
- When weak reference counter gets to zero, the deleter needs to free the memory allocated by self.
**Rationales:** There are several considerations when designing the data structure:
- `type_index` enables runtime dynamic type checking and casting.
- We introduce weak/strong ref counters so we can be compatible with systems that need weak pointers.
- The weak ref counter is kept as 32-bit so we can pack the object header as 24 bytes.
- `deleter` ensures that objects allocated from one language/runtime can be safely deleted in another.
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
Review Comment:
It is useful to mention TVM FFI contains static section of built in types, while also support dynamic type registration
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
+The following C code constructs a :cpp:class:`~tvm::ffi::TensorObj` from a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_FromDLPack.begin]
+ :end-before: [Tensor_FromDLPack.end]
+
+.. hint::
+ TVM-FFI's Python API automatically wraps framework tensors (e.g., :py:class:`torch.Tensor`) as :cpp:class:`~tvm::ffi::TensorObj`,
+ so manual conversion is typically unnecessary.
+
+Destruct Tensor
+~~~~~~~~~~~~~~~
+
+As a standard TVM-FFI object, :cpp:class:`~tvm::ffi::TensorObj` follows the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+When the reference count reaches zero, the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes.
+
+Export Tensor to DLPack
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To share a :cpp:class:`~tvm::ffi::TensorObj` with other frameworks, export it as a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_ToDLPackVersioned.begin]
+ :end-before: [Tensor_ToDLPackVersioned.end]
+
+.. _abi-function:
+
+Function
+--------
+
+.. seealso::
+
+ :ref:`sec:function` for a detailed description of TVM-FFI functions.
+
+All functions in TVM-FFI follow a unified C calling convention that enables ABI-stable,
+type-erased, and cross-language function calls, defined by :cpp:type:`TVMFFISafeCallType`.
+
+**Calling convention.** The signature includes:
+
+- ``handle`` (``void*``): Optional resource handle passed to the callee; typically ``NULL`` for exported symbols
+- ``args`` (``TVMFFIAny*``) and ``num_args`` (``int``): Array of non-owning :cpp:class:`~tvm::ffi::AnyView` input arguments
+- ``result`` (``TVMFFIAny*``): Owning :cpp:class:`~tvm::ffi::Any` output value
+- Return value: ``0`` for success; ``-1`` or ``-2`` for errors (see :ref:`sec:exception`)
Review Comment:
need to elaborate on calling convention and guide from static and dynamic languages
We call this approach a packed function, as it provides a single signature to represent all functions in a "type-erased" way. It saves the need to declare and jit shim for each FFI function call while maintaining reasonable efficiency. This mechanism enables the following scenarios:
- Calling from Dynamic Languages (e.g., Python): we provide a tvm_ffi binding that prepares the args based on dynamically examining Python arguments passed in.
- Calling from Static Languages (e.g., C++): For static languages, we can leverage C++ templates to directly instantiate the arguments on the stack, saving the need for dynamic examination.
- Dynamic language Callbacks: the signature enables us to easily bring dynamic language (Python) callbacks as ffi::Function, as we can take each argument and convert to the dynamic values.
Efficiency: In practice, we find this approach is sufficient for machine learning focused workloads. For example, we can get to microsecond level overhead for Python/C++ calls, which is generally similar to overhead for eager mode. When both sides of calls are static languages, the overhead will go down to tens of nanoseconds. As a side note, although we did not find it necessary, the signature still leaves room for link time optimization (LTO), when both sides are static languages with a known symbol and linked into a single binary when we inline the callee into caller side and the stack argument memory passing into register passing.
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
Review Comment:
Title should be ABI overview
In main text
> For the purposes of clearly describes the ABI behavior, we use C code throughout this document. Note that for compiler builders, these C code can be readily translated into code generators such as LLVM builder to build these code
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
Review Comment:
This should be Import Tensor from DLPack. Note that Tensor can be constructed in manyways, and this may not be the only way
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
+The following C code constructs a :cpp:class:`~tvm::ffi::TensorObj` from a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_FromDLPack.begin]
+ :end-before: [Tensor_FromDLPack.end]
+
+.. hint::
+ TVM-FFI's Python API automatically wraps framework tensors (e.g., :py:class:`torch.Tensor`) as :cpp:class:`~tvm::ffi::TensorObj`,
+ so manual conversion is typically unnecessary.
+
+Destruct Tensor
+~~~~~~~~~~~~~~~
+
+As a standard TVM-FFI object, :cpp:class:`~tvm::ffi::TensorObj` follows the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+When the reference count reaches zero, the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes.
+
+Export Tensor to DLPack
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To share a :cpp:class:`~tvm::ffi::TensorObj` with other frameworks, export it as a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_ToDLPackVersioned.begin]
+ :end-before: [Tensor_ToDLPackVersioned.end]
+
+.. _abi-function:
+
+Function
+--------
+
+.. seealso::
+
+ :ref:`sec:function` for a detailed description of TVM-FFI functions.
+
+All functions in TVM-FFI follow a unified C calling convention that enables ABI-stable,
+type-erased, and cross-language function calls, defined by :cpp:type:`TVMFFISafeCallType`.
+
+**Calling convention.** The signature includes:
+
+- ``handle`` (``void*``): Optional resource handle passed to the callee; typically ``NULL`` for exported symbols
+- ``args`` (``TVMFFIAny*``) and ``num_args`` (``int``): Array of non-owning :cpp:class:`~tvm::ffi::AnyView` input arguments
+- ``result`` (``TVMFFIAny*``): Owning :cpp:class:`~tvm::ffi::Any` output value
+- Return value: ``0`` for success; ``-1`` or ``-2`` for errors (see :ref:`sec:exception`)
+
+**Object layout.** The :cpp:class:`~tvm::ffi::FunctionObj` stores call pointers after the object header.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIFunctionCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIFunctionCell.begin]
+ :end-before: [TVMFFIFunctionCell.end]
+ :caption: tvm/ffi/c_api.h
+
+Construct and Destroy
+~~~~~~~~~~~~~~~~~~~~~
+
+.. important::
+ Dynamic function creation is useful for passing lambdas or closures across language boundaries.
+
+The following C code constructs a :cpp:class:`~tvm::ffi::FunctionObj` from a :cpp:type:`TVMFFISafeCallType` and a ``deleter`` callback.
+The ``deleter`` cleans up resources owned by the function; for global symbols, it is typically ``NULL``.
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.Construct.begin]
+ :end-before: [Function.Construct.end]
+
+Release a :cpp:class:`~tvm::ffi::FunctionObj` using the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+
+Global Registry
+~~~~~~~~~~~~~~~
+
+**Retrieve a global function.** The following C code retrieves a function by name from the global registry:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.GetGlobal.begin]
+ :end-before: [Function.GetGlobal.end]
+
+**Register a global function.** The following C code registers a function by name in the global registry:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.SetGlobal.begin]
+ :end-before: [Function.SetGlobal.end]
+
+Call Function
+~~~~~~~~~~~~~
+
+The following C code invokes a :cpp:class:`~tvm::ffi::FunctionObj` with arguments:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.Call.begin]
+ :end-before: [Function.Call.end]
+
+
+.. _abi-exception:
+
+Exception
+---------
+
+.. seealso::
+
+ :ref:`sec:exception` for detailed exception handling patterns.
+
+Exceptions are a central part of TVM-FFI's ABI and calling convention.
+When errors occur, they are stored as objects with a :cpp:class:`TVMFFIErrorCell` payload.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIErrorCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIErrorCell.begin]
+ :end-before: [TVMFFIErrorCell.end]
+ :caption: tvm/ffi/c_api.h
+
+Retrieve Error Object
+~~~~~~~~~~~~~~~~~~~~~
+
+When a function returns ``-1``, an error object is stored in thread-local storage (TLS).
+Retrieve it with :cpp:func:`TVMFFIErrorMoveFromRaised`, which returns a :cpp:class:`tvm::ffi::ErrorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Error.HandleReturnCode.begin]
+ :end-before: [Error.HandleReturnCode.end]
+
+This function transfers ownership to the caller and clears the TLS slot.
+Call :cpp:func:`TVMFFIObjectDecRef` when done to avoid memory leaks.
+
+**Frontend errors (-2).** Error code ``-2`` is reserved for frontend errors.
+It is returned when :cpp:func:`TVMFFIEnvCheckSignals` detects a pending Python signal.
+In this case, do not retrieve the error from TLS; instead, consult the frontend's error mechanism.
+
+Print Error Message
+~~~~~~~~~~~~~~~~~~~
Review Comment:
remove this section for now as printing is not core part of ABI and may subject to change when we have chaining
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
+The following C code constructs a :cpp:class:`~tvm::ffi::TensorObj` from a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_FromDLPack.begin]
+ :end-before: [Tensor_FromDLPack.end]
+
+.. hint::
+ TVM-FFI's Python API automatically wraps framework tensors (e.g., :py:class:`torch.Tensor`) as :cpp:class:`~tvm::ffi::TensorObj`,
+ so manual conversion is typically unnecessary.
+
+Destruct Tensor
+~~~~~~~~~~~~~~~
+
+As a standard TVM-FFI object, :cpp:class:`~tvm::ffi::TensorObj` follows the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+When the reference count reaches zero, the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes.
+
+Export Tensor to DLPack
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To share a :cpp:class:`~tvm::ffi::TensorObj` with other frameworks, export it as a :c:struct:`DLManagedTensorVersioned`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor_ToDLPackVersioned.begin]
+ :end-before: [Tensor_ToDLPackVersioned.end]
+
+.. _abi-function:
+
+Function
+--------
+
+.. seealso::
+
+ :ref:`sec:function` for a detailed description of TVM-FFI functions.
+
+All functions in TVM-FFI follow a unified C calling convention that enables ABI-stable,
+type-erased, and cross-language function calls, defined by :cpp:type:`TVMFFISafeCallType`.
+
+**Calling convention.** The signature includes:
+
+- ``handle`` (``void*``): Optional resource handle passed to the callee; typically ``NULL`` for exported symbols
+- ``args`` (``TVMFFIAny*``) and ``num_args`` (``int``): Array of non-owning :cpp:class:`~tvm::ffi::AnyView` input arguments
+- ``result`` (``TVMFFIAny*``): Owning :cpp:class:`~tvm::ffi::Any` output value
+- Return value: ``0`` for success; ``-1`` or ``-2`` for errors (see :ref:`sec:exception`)
+
+**Object layout.** The :cpp:class:`~tvm::ffi::FunctionObj` stores call pointers after the object header.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIFunctionCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIFunctionCell.begin]
+ :end-before: [TVMFFIFunctionCell.end]
+ :caption: tvm/ffi/c_api.h
+
+Construct and Destroy
+~~~~~~~~~~~~~~~~~~~~~
+
+.. important::
+ Dynamic function creation is useful for passing lambdas or closures across language boundaries.
+
+The following C code constructs a :cpp:class:`~tvm::ffi::FunctionObj` from a :cpp:type:`TVMFFISafeCallType` and a ``deleter`` callback.
+The ``deleter`` cleans up resources owned by the function; for global symbols, it is typically ``NULL``.
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.Construct.begin]
+ :end-before: [Function.Construct.end]
+
+Release a :cpp:class:`~tvm::ffi::FunctionObj` using the :ref:`standard destruction pattern <ABI.Object.Destroy>`.
+
+Global Registry
+~~~~~~~~~~~~~~~
+
+**Retrieve a global function.** The following C code retrieves a function by name from the global registry:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.GetGlobal.begin]
+ :end-before: [Function.GetGlobal.end]
+
+**Register a global function.** The following C code registers a function by name in the global registry:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.SetGlobal.begin]
+ :end-before: [Function.SetGlobal.end]
+
+Call Function
+~~~~~~~~~~~~~
+
+The following C code invokes a :cpp:class:`~tvm::ffi::FunctionObj` with arguments:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Function.Call.begin]
+ :end-before: [Function.Call.end]
+
+
+.. _abi-exception:
+
+Exception
+---------
+
+.. seealso::
+
+ :ref:`sec:exception` for detailed exception handling patterns.
+
+Exceptions are a central part of TVM-FFI's ABI and calling convention.
+When errors occur, they are stored as objects with a :cpp:class:`TVMFFIErrorCell` payload.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIErrorCell`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIErrorCell.begin]
+ :end-before: [TVMFFIErrorCell.end]
+ :caption: tvm/ffi/c_api.h
+
+Retrieve Error Object
+~~~~~~~~~~~~~~~~~~~~~
+
+When a function returns ``-1``, an error object is stored in thread-local storage (TLS).
+Retrieve it with :cpp:func:`TVMFFIErrorMoveFromRaised`, which returns a :cpp:class:`tvm::ffi::ErrorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Error.HandleReturnCode.begin]
+ :end-before: [Error.HandleReturnCode.end]
+
+This function transfers ownership to the caller and clears the TLS slot.
+Call :cpp:func:`TVMFFIObjectDecRef` when done to avoid memory leaks.
+
+**Frontend errors (-2).** Error code ``-2`` is reserved for frontend errors.
+It is returned when :cpp:func:`TVMFFIEnvCheckSignals` detects a pending Python signal.
+In this case, do not retrieve the error from TLS; instead, consult the frontend's error mechanism.
+
+Print Error Message
+~~~~~~~~~~~~~~~~~~~
+
+The error payload is a :cpp:type:`TVMFFIErrorCell` structure containing the error kind, message, and backtrace.
+Access it by skipping the :cpp:type:`TVMFFIObject` header via pointer arithmetic:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Error.Print.begin]
+ :end-before: [Error.Print.end]
+
+This prints the error message along with its backtrace.
+
+Raise Exception
+~~~~~~~~~~~~~~~
+
+The following C code sets the TLS error and returns ``-1`` via :cpp:func:`TVMFFIErrorSetRaisedFromCStr`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Error.RaiseException.begin]
+ :end-before: [Error.RaiseException.end]
+
+For non-null-terminated strings, use :cpp:func:`TVMFFIErrorSetRaisedFromCStrParts`, which accepts explicit string lengths.
+
+.. note::
+ You rarely need to create a :cpp:class:`~tvm::ffi::ErrorObj` directly.
+ The C APIs :cpp:func:`TVMFFIErrorSetRaisedFromCStr` and :cpp:func:`TVMFFIErrorSetRaisedFromCStrParts` handle this internally.
+
+
+🚧 String and Byte
Review Comment:
String and Bytes
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2683785795
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
+
+**Move ownership from Any/AnyView.** The following C code transfers ownership from an owning :cpp:class:`~tvm::ffi::Any` to an object pointer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.MoveFromAny.begin]
+ :end-before: [Object.MoveFromAny.end]
+
+Since :cpp:class:`~tvm::ffi::AnyView` is non-owning (``IS_OWNING_ANY`` is ``false``),
+acquiring ownership requires explicitly incrementing the reference count.
+
+**Release ownership.** The following C code releases ownership of a TVM-FFI object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :name: ABI.Object.Destroy
+ :start-after: [Object.Destroy.begin]
+ :end-before: [Object.Destroy.end]
+
+Inheritance Checking
+~~~~~~~~~~~~~~~~~~~~
+
+TVM-FFI models single inheritance as a tree where each node points to its parent.
+Each type has a unique type index, and the system tracks ancestors, inheritance depth, and other metadata.
+This information is available via :cpp:func:`TVMFFIGetTypeInfo`.
+
+The following C code checks whether a type is a subclass of another:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Object.IsInstance.begin]
+ :end-before: [Object.IsInstance.end]
+
+.. _abi-tensor:
+
+Tensor
+------
+
+.. seealso::
+
+ :doc:`tensor` for details about TVM-FFI tensors and DLPack interoperability.
+
+TVM-FFI provides :cpp:class:`tvm::ffi::TensorObj`, a DLPack-native tensor class that is also a standard TVM-FFI object.
+This means tensors can be managed using the same reference counting mechanisms as other objects.
+
+.. dropdown:: C ABI Reference: :cpp:class:`tvm::ffi::TensorObj`
+ :icon: code
+
+ .. code-block:: cpp
+ :caption: tvm/ffi/container/tensor.h
+
+ class TensorObj : public Object, public DLTensor {
+ // no other members besides those from Object and DLTensor
+ };
+
+
+Access Tensor Metadata
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following C code obtains a :c:struct:`DLTensor` pointer from a :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Tensor.AccessDLTensor.begin]
+ :end-before: [Tensor.AccessDLTensor.end]
+
+The :c:struct:`DLTensor` pointer provides access to shape, dtype, device, data pointer, and other tensor metadata.
+
+Construct Tensor
+~~~~~~~~~~~~~~~~
+
Review Comment:
I changed the title to "Construct Tensor from DLPack"
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2684044749
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
Review Comment:
Updated the wording a bit to make sure weak RC is also mentioned in ABI overview. Note that there's currently no C API to manage weak reference AFAICT
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2684039175
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,490 @@
+.. 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.
+
+ABI Overview in C
+=================
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+The TVM-FFI ABI is designed around the following key principles:
+
+- **Minimal and efficient.** Keep things simple and deliver close-to-metal performance.
+- **Stability guarantee.** The ABI remains stable across compiler versions and is independent of host languages or frameworks.
+- **Expressive for machine learning.** Native support for tensors, shapes, and data types commonly used in ML workloads.
+- **Extensible.** The ABI supports user-defined types and features through a dynamic type registration system.
+
+This tutorial covers common concepts and usage patterns of the TVM-FFI ABI, with low-level C code examples for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership.** :cpp:class:`TVMFFIAny` has two variants with identical layout but different :ref:`ownership semantics <any-ownership>`:
+
+- **Owning:** :cpp:class:`tvm::ffi::Any` - reference-counted, manages object lifetime
+- **Borrowing:** :cpp:class:`tvm::ffi::AnyView` - non-owning view, caller must ensure validity
+
+.. note::
+ To convert a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index.** The ``type_index`` field identifies what kind of value is stored:
+
+- :ref:`Atomic POD types <any-atomic-types>` (``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored inline in the payload union without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>` (``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`):
+ Stored as pointers to heap-allocated, reference-counted TVM-FFI objects.
+
+.. important::
+ The TVM-FFI type index system does not rely on C++ RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**From atomic POD types.** The following C code constructs a :cpp:class:`TVMFFIAny` from an integer:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Set the ``type_index`` from :cpp:enum:`TVMFFITypeIndex` and assign the corresponding payload field.
+
+.. important::
+
+ Always zero the ``zero_padding`` field and any unused bytes in the value union.
+ This invariant enables direct byte comparison and hashing of :cpp:class:`TVMFFIAny` values.
+
+**From object types.** The following C code constructs a :cpp:class:`TVMFFIAny` from a heap-allocated object:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromObjectPtr.begin]
+ :end-before: [Any_AnyView.FromObjectPtr.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this increments the object's reference count.
+
+.. _abi-destruct-any:
+
+Destruct Any
+~~~~~~~~~~~~
+
+The following C code destroys a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.Destroy.begin]
+ :end-before: [Any_AnyView.Destroy.end]
+
+When ``IS_OWNING_ANY`` is ``true`` (owning :cpp:class:`~tvm::ffi::Any`), this decrements the object's reference count.
+
+Extract from Any
+~~~~~~~~~~~~~~~~
+
+**Extract an atomic POD.** The following C code extracts an integer or float from a :cpp:class:`TVMFFIAny`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetInt_Float.begin]
+ :end-before: [Any_AnyView.GetInt_Float.end]
+
+Implicit type conversion may occur. For example, when extracting a float from a :cpp:class:`TVMFFIAny`
+that holds an integer, the integer is cast to a float.
+
+**Extract a DLTensor.** A :c:struct:`DLTensor` may originate from either a raw pointer or a heap-allocated :cpp:class:`~tvm::ffi::TensorObj`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetDLTensor.begin]
+ :end-before: [Any_AnyView.GetDLTensor.end]
+
+**Extract a TVM-FFI object.** TVM-FFI objects are always heap-allocated and reference-counted,
+with ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`:
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.GetObject.begin]
+ :end-before: [Any_AnyView.GetObject.end]
+
+To take ownership of the returned value, increment the reference count via :cpp:func:`TVMFFIObjectIncRef`.
+Release ownership later via :cpp:func:`TVMFFIObjectDecRef`.
+
+.. _abi-object:
+
+Object
+------
+
+.. seealso::
+
+ :doc:`object_and_class` for the object system and reflection.
+
+TVM-FFI Object (:cpp:class:`TVMFFIObject`) is the cornerstone of TVM-FFI's stable yet extensible type system.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIObject`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIObject.begin]
+ :end-before: [TVMFFIObject.end]
+ :caption: tvm/ffi/c_api.h
+
+All TVM-FFI objects share these characteristics:
+
+- Heap-allocated and reference-counted
+- Layout-stable 24-byte header containing reference counts, type index, and deleter callback
+- Type index >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`
+
+**Dynamic Type System.** Classes can be registered at runtime via :cpp:func:`TVMFFITypeGetOrAllocIndex`,
+with support for single inheritance. See :ref:`type-checking-and-casting` for usage details.
+
+.. _abi-object-ownership:
+
+Ownership Management
+~~~~~~~~~~~~~~~~~~~~
+
+Ownership is managed via reference counting. See :ref:`object-reference-counting` for details.
+
+Two C APIs manage object ownership:
+
+- :cpp:func:`TVMFFIObjectIncRef`: Acquire ownership by incrementing the reference count
+- :cpp:func:`TVMFFIObjectDecRef`: Release ownership by decrementing the reference count; the deleter callback (:cpp:member:`TVMFFIObject::deleter`) executes when the count reaches zero
Review Comment:
Note: this section is moved to Object: https://tvm.apache.org/ffi/concepts/object_and_class.html#reference-counting
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "gemini-code-assist[bot] (via GitHub)" <gi...@apache.org>.
gemini-code-assist[bot] commented on code in PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#discussion_r2680809673
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,466 @@
+.. 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.
+
+ABI Overview
+============
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+Overall, TVM-FFI ABI is designed is around the following key principles:
+
+- **Minimal and efficient**. Keep things simple when possible and bring close-to-metal efficiency.
+- **Stability guarantee**. The ABI is stable across compiler versions and independent of host languages or frameworks.
+- **Expressive for machine learning** TBA.
Review Comment:

This principle is marked as 'TBA'. Please either fill in the details or remove this point to avoid shipping incomplete documentation.
##########
examples/abi_overview/example_code.c:
##########
@@ -0,0 +1,185 @@
+/*
+ * 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.
+ */
+
+// NOLINTBEGIN(modernize-deprecated-headers,modernize-use-nullptr)
+#include <assert.h>
+#include <dlpack/dlpack.h>
+#include <tvm/ffi/c_api.h>
+
+int IS_OWNING_ANY = 1;
+
+// [Any_AnyView.FromInt_Float.begin]
+TVMFFIAny Any_AnyView_FromInt(int64_t value) {
+ TVMFFIAny any;
+ any.type_index = kTVMFFIInt;
+ any.zero_padding = 0;
+ any.v_int64 = value;
+ return any;
+}
+
+TVMFFIAny Any_AnyView_FromFloat(double value) {
+ TVMFFIAny any;
+ any.type_index = kTVMFFIFloat;
+ any.zero_padding = 0;
+ any.v_float64 = value;
+ return any;
+}
+// [Any_AnyView.FromInt_Float.end]
+
+// [Any_AnyView.FromObjectPtr.begin]
+TVMFFIAny Any_AnyView_FromObjectPtr(TVMFFIObject* obj) {
+ TVMFFIAny any;
+ assert(obj != NULL);
+ any.type_index = kTVMFFIObject;
+ any.zero_padding = 0;
+ any.v_obj = obj;
+ // Increment refcount if it's Any (owning) instead of AnyView (borrowing)
+ if (IS_OWNING_ANY) {
+ TVMFFIObjectIncRef(obj);
+ }
+ return any;
+}
+// [Any_AnyView.FromObjectPtr.end]
+
+// [Any_AnyView.Destroy.begin]
+void Any_AnyView_Destroy(TVMFFIAny* any) {
+ if (IS_OWNING_ANY) {
+ // Checks if `any` holds a heap-allocated object,
+ // and if so, decrements the reference count
+ if (any->type_index >= kTVMFFIStaticObjectBegin) {
+ TVMFFIObjectDecRef(any->v_obj);
+ }
+ }
+ *any = (TVMFFIAny){0}; // Clears the `any` struct
+}
+// [Any_AnyView.Destroy.end]
+
+// [Any_AnyView.GetInt_Float.begin]
+int64_t Any_AnyView_GetInt(const TVMFFIAny* any) {
+ if (any->type_index == kTVMFFIInt || any->type_index == kTVMFFIBool) {
+ return any->v_int64;
+ } else if (any->type_index == kTVMFFIFloat) {
+ return (int64_t)(any->v_float64);
+ }
+ assert(0); // FAILED to read int
+ return 0;
+}
+
+double Any_AnyView_GetFloat(const TVMFFIAny* any) {
+ if (any->type_index == kTVMFFIInt || any->type_index == kTVMFFIFloat) {
+ return (double)(any->v_int64);
+ } else if (any->type_index == kTVMFFIFloat) {
+ return any->v_float64;
+ }
Review Comment:

There is a logical error in this function. If `any->type_index` is `kTVMFFIFloat`, the first `if` condition is met, and the function incorrectly returns `(double)(any->v_int64)`. The `else if` block is unreachable. You should separate the checks for `kTVMFFIInt` and `kTVMFFIFloat`.
```suggestion
if (any->type_index == kTVMFFIInt) {
return (double)(any->v_int64);
} else if (any->type_index == kTVMFFIFloat) {
return any->v_float64;
}
```
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,466 @@
+.. 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.
+
+ABI Overview
+============
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+Overall, TVM-FFI ABI is designed is around the following key principles:
+
+- **Minimal and efficient**. Keep things simple when possible and bring close-to-metal efficiency.
+- **Stability guarantee**. The ABI is stable across compiler versions and independent of host languages or frameworks.
+- **Expressive for machine learning** TBA.
+- **Extensible**. The ABI is extensible to support new types and features.
+
+This tutorial covers common concepts and usage patterns with TVM-FFI's ABI with low-level C code for precise reference.
+
+Any and AnyView
+---------------
+
+.. seealso::
+
+ :doc:`any` for :cpp:class:`~tvm::ffi::Any` and :cpp:class:`~tvm::ffi::AnyView` usage patterns.
+
+At the core of TVM-FFI is :cpp:class:`TVMFFIAny`, a 16-byte tagged union that can hold any value
+recognized by the FFI system. It enables type-erased value passing across language boundaries.
+
+.. dropdown:: C ABI Reference: :cpp:class:`TVMFFIAny`
+ :icon: code
+
+ .. literalinclude:: ../../include/tvm/ffi/c_api.h
+ :language: c
+ :start-after: [TVMFFIAny.begin]
+ :end-before: [TVMFFIAny.end]
+ :caption: tvm/ffi/c_api.h
+
+**Ownership**. :cpp:class:`TVMFFIAny` has two variants with exact same layout but different :ref:`ownership semantics <any-ownership>`:
+
+- Managed owning :cpp:class:`tvm::ffi::Any`
+- Unmanaged borrowing :cpp:class:`tvm::ffi::AnyView`
+
+.. note::
+ To switch a borrowing :cpp:class:`~tvm::ffi::AnyView` to an owning :cpp:class:`~tvm::ffi::Any`, use :cpp:func:`TVMFFIAnyViewToOwnedAny`.
+
+**Runtime Type Index**. The ``type_index`` field identifies what kind of value is stored.
+
+- :ref:`Atomic POD types <any-atomic-types>`, where ``type_index`` < :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`.
+ They are stored in-place in payload union, without heap allocation or reference counting.
+- :ref:`Object types <any-heap-allocated-objects>`, where ``type_index`` >= :cpp:enumerator:`kTVMFFIStaticObjectBegin <TVMFFITypeIndex::kTVMFFIStaticObjectBegin>`.
+ They are stored in a heap-allocated, reference-counted TVM-FFI object.
+
+.. important::
+ Type index system in TVM-FFI does not rely on C++ features such as RTTI.
+
+
+Construct Any
+~~~~~~~~~~~~~
+
+**Constructing from atomic POD types**. The C code below constructs an :cpp:class:`TVMFFIAny` from an integer:
+
+
+.. literalinclude:: ../../examples/abi_overview/example_code.c
+ :language: c
+ :start-after: [Any_AnyView.FromInt_Float.begin]
+ :end-before: [Any_AnyView.FromInt_Float.end]
+
+Essentially, properly assign ``type_index`` from :cpp:enum:`TVMFFITypeIndex`, and then set the payload field accordingly.
Review Comment:

The reference to `TVMFFITypeIndex` is not a link. To make it a link and be consistent with other references in this document, you should use the explicit target syntax.
```suggestion
Essentially, properly assign ``type_index`` from :cpp:enum:`TVMFFITypeIndex <TVMFFITypeIndex>`, and then set the payload field accordingly.
```
##########
examples/abi_overview/example_code.c:
##########
@@ -0,0 +1,185 @@
+/*
+ * 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.
+ */
+
+// NOLINTBEGIN(modernize-deprecated-headers,modernize-use-nullptr)
+#include <assert.h>
+#include <dlpack/dlpack.h>
+#include <tvm/ffi/c_api.h>
+
+int IS_OWNING_ANY = 1;
Review Comment:

This global variable is used to control behavior in example functions. It's better to make it `static` to limit its scope to this file. This prevents potential name clashes if other files are added to this example directory.
```suggestion
static int IS_OWNING_ANY = 1;
```
##########
docs/concepts/abi_overview.rst:
##########
@@ -0,0 +1,466 @@
+.. 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.
+
+ABI Overview
+============
+
+.. hint::
+
+ Authoritative ABI specifications are defined in
+
+ - C header `tvm/ffi/c_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/c_api.h>`_, which contains the core ABI, and
+ - C header `tvm/ffi/extra/c_env_api.h <https://github.com/apache/tvm-ffi/blob/main/include/tvm/ffi/extra/c_env_api.h>`_, which contains extra support features.
+
+Overall, TVM-FFI ABI is designed is around the following key principles:
Review Comment:

There's a minor grammatical error here. It should be "is designed around" instead of "is designed is around".
```suggestion
Overall, TVM-FFI ABI is designed around the following key principles:
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org
Re: [PR] doc: abi overview [tvm-ffi]
Posted by "gemini-code-assist[bot] (via GitHub)" <gi...@apache.org>.
gemini-code-assist[bot] commented on PR #402:
URL: https://github.com/apache/tvm-ffi/pull/402#issuecomment-3736810233
## Summary of Changes
Hello @junrushao, I'm Gemini Code Assist[^1]! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request significantly enhances the TVM-FFI documentation by introducing a new, comprehensive overview of its Application Binary Interface (ABI). The new document, written in reStructuredText and supported by concrete C code examples, aims to clarify the fundamental principles, data structures, and interaction patterns of the FFI system. This change improves the accessibility and understanding of TVM-FFI's low-level mechanisms for developers, ensuring a more robust and maintainable codebase.
### Highlights
* **New ABI Overview Documentation**: A comprehensive reStructuredText document, `docs/concepts/abi_overview.rst`, has been added. This document provides a detailed overview of the TVM-FFI Application Binary Interface (ABI), covering its core principles, data types (`Any`, `Object`, `Tensor`, `Function`, `Exception`, `Module`, `String`, and `Byte`), and usage patterns with low-level C code examples.
* **Accompanying C Code Examples**: A new C example file, `examples/abi_overview/example_code.c`, has been introduced. This file contains practical code snippets that are directly referenced within the `abi_overview.rst` document, illustrating how to interact with the TVM-FFI ABI concepts in C.
* **Documentation Structure and Cross-Referencing Improvements**: The main documentation index (`docs/index.rst`) has been updated to include the new ABI overview. Additionally, existing documentation files (`docs/concepts/any.rst`, `docs/concepts/object_and_class.rst`) have been modified to add specific cross-reference targets, enhancing navigation and linking within the documentation set.
* **C API Header Annotations**: The `include/tvm/ffi/c_api.h` file has been augmented with `// [TAG.begin]` and `// [TAG.end]` markers around key C ABI struct and enum definitions. These annotations are crucial for documentation generation tools, allowing specific code sections to be directly embedded and referenced in the new ABI overview.
* **Legacy Document Handling**: The previous ABI overview document, `docs/concepts/abi_overview.md`, has been renamed to `docs/concepts/abi_overview_legacy.rst`. This indicates a transition to a new, more detailed, and structured ABI documentation approach.
🧠**New Feature in Public Preview:** You can now enable **Memory** to help **Gemini Code Assist** learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. **Click [here](https://codeassist.google/code-review/login) to enable Memory in your admin console.**
<details>
<summary><b>Using Gemini Code Assist</b></summary>
<br>
The full guide for Gemini Code Assist can be found on our [documentation page](https://developers.google.com/gemini-code-assist/docs/review-github-code), here are some quick tips.
<b>Invoking Gemini</b>
You can request assistance from Gemini at any point by creating a comment using either `/gemini <command>` or `@gemini-code-assist <command>`. Below is a summary of the supported commands on the current page.
Feature | Command | Description
--- | --- | ---
Code Review | `/gemini review` | Performs a code review for the current pull request in its current state.
Pull Request Summary | `/gemini summary` | Provides a summary of the current pull request in its current state.
Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help | `/gemini help` | Displays a list of available commands.
<b>Customization</b>
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a `.gemini/` folder in the base of the repository. Detailed instructions can be found [here](https://developers.google.com/gemini-code-assist/docs/customize-gemini-behavior-github).
<b>Limitations & Feedback</b>
Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with :thumbsup: and :thumbsdown: on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up [here](https://google.qualtrics.com/jfe/form/SV_2cyuGuTWsEw84yG).
<b>You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the [Gemini Code Assist IDE Extension](https://cloud.google.com/products/gemini/code-assist).</b>
</details>
[^1]: Review the [Privacy Notices](https://policies.google.com/privacy), [Generative AI Prohibited Use Policy](https://policies.google.com/terms/generative-ai/use-policy), [Terms of Service](https://policies.google.com/terms), and learn how to configure Gemini Code Assist in GitHub [here](https://developers.google.com/gemini-code-assist/docs/customize-gemini-behavior-github). Gemini can make mistakes, so double check it and [use code with caution](https://support.google.com/legal/answer/13505487).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org