当前位置：首页>python>TVM FFI 深度剖析:Python 如何调用 C++

TVM FFI 深度剖析:Python 如何调用 C++

2026-06-23 16:43:00

从 Apache TVM 源码逐层拆解 Foreign Function Interface 的完整架构

TVM 的核心编译器、runtime、内存管理全部由 C++ 实现，而用户接口层是 Python。两者之间通过 tvm-ffi^[1] 这个独立的 FFI（Foreign Function Interface）库连接。要理解 TVM 的工作方式，必须先理解这个桥梁。

整体架构图

Layer 6 — 物理根基：编译产物（多库拆分）

最底层的基础 — TVM 的 C++ 代码在编译期（cmake --build 阶段）就编译好了。

编译过程

#   Step 1: CMake 配置（根据 config.cmake 选择后端）cmake .. -DUSE_LLVM=ON -DUSE_CUDA=ON#   Step 2: 编译cmake --build . --parallel#   Step 3: 产物（不是单一 libtvm.so，而是拆分为三个库）build/lib/libtvm_compiler.dylib   #  编译器核心（含所有 IR/Pass/Operator/Codegen）build/lib/libtvm_runtime.dylib    #  轻量级 runtime（仅推理执行所需）build/lib/libtvm_ffi.dylib        #  FFI 桥接库（Python ↔ C++ 的函数注册/调用）build/lib/libtvm_ffi_static.a     #  FFI 静态库（用于 MicroTVM 等嵌入式场景）

为什么拆成三个库？

库	用途	场景
`libtvm_compiler`	完整编译器栈（IR/Pass/Codegen）	开发 / 训练 / 调优
`libtvm_runtime`	最小化推理运行时	生产部署（体积小）
`libtvm_ffi`	C ABI + C++17 API + Python 绑定	所有跨语言功能
`libtvm_ffi_static.a`	FFI 静态库	MicroTVM 嵌入式

Python 侧加载（`tvm_ffi` Cython 扩展）

#   base.pxi 通过 cdef extern 声明 libtvm_ffi.dylib 中的 C API 符号:#   int TVMFFIFunctionGetGlobal(TVMFFIByteArray* name, TVMFFIObjectHandle* out)#   int TVMFFIFunctionSetGlobal(TVMFFIByteArray* name, TVMFFIObjectHandle f, int override)#   int TVMFFIObjectDecRef(TVMFFIObjectHandle obj)#   ... 等等

当 Python 执行 import tvm_ffi 时，Cython 编译生成的 C 扩展自动 load，进而可以调用 libtvm_compiler.dylib 和 libtvm_runtime.dylib 中暴露的所有 C++ API。

关键理解：C++ 不是在 Python 调用时才编译的，而是在 pip install tvm 或 cmake --build 时就已经编译成 build/lib/ 下的 .dylib/.so 了。Python 只是通过 tvm-ffi 的 Cython 扩展访问这些已存在的库。

Layer 5 — C++ API 实现层：全局注册表 + 类型擦除

FFI 在 C++ 侧的"接线板"，由 tvm-ffi 库提供（3rdparty/tvm-ffi/src/ffi/）。两个核心机制：

全局函数注册表

tvm-ffi 在 C++ 侧维护一个全局的函数表：

  全局注册表（tvm::ffi 内部）┌──────────────────────────────────────────────────┐│  "ir.conv2d"                          → Function ││  "relax.op.nn.matmul"                 → Function ││  "tirx.build"                         → Function ││  "ffi.FunctionListGlobalNamesFunctor" → Function ││  "ffi.Array"                          → Function ││  ...                                             │└──────────────────────────────────────────────────┘

C++ 侧注册

//  方式1: 通过 tvm::ffi C++ APItvm::ffi::Function::RegisterGlobal("ir.conv2d")    .set_body_typed([](Expr data, Expr weight, ...) {        return conv2d(data, weight, ...);    });//  方式2: 通过反射注册表自动注册 (tvm::ffi::reflection)// 在静态初始化阶段，注册表条目自动调用 TVMFFIFunctionSetGlobalFromMethodInfo

Python 侧注册

import tvm_ffi@tvm_ffi.register_global_func("my.echo")def echo(x):    return x#  内部调用 TVMFFIFunctionSetGlobal("my.echo", packed_func, override=0)

双向 FFI — 之后 Python 注册的函数可以直接被 C++ 或其他语言调用。

静态初始化：当 libtvm_compiler.dylib 被 dlopen 加载时，所有 C++ static 初始化代码自动执行，注册表就已填满。Python 侧不需要任何手动注册。

类型擦除的 Function 对象

tvm-ffi 的核心类型是 Function，定义在 include/tvm/ffi/function.h：

  任何 callable 都可以包装成 Function:    C++ lambda:  通过 make_function_wrapper    C 函数指针:  通过 TVMFFIFunctionCreate    Python 函数: 通过 _convert_to_ffi_func (Cython)  统一的调用约定:    (const AnyView* args, int32_t num_args, Any* rv) → void  其中 AnyView 是类型擦除的值容器:    int, float, string, ObjectRef, DLTensor*, ...

Layer 4 — Cython C-API 桥接层：零拷贝穿越

最精细、性能最关键的一层。位于 3rdparty/tvm-ffi/python/tvm_ffi/cython/。

为什么用 Cython 而不是纯 ctypes？

维度	ctypes ❌	Cython ✅
性能	每次调用都有 Python↔C 开销	编译成 C 扩展，接近原生速度
类型安全	运行时检查，弱	编译期检查，强
GIL	默认持有 GIL	可精细控制 `nogil`
对象管理	手动管理 C++ 生命周期	自动 ref-counting

关键文件与职责

  cython/ 目录结构├──   base.pxi          ← cdef extern: 声明 C API 符号├──   core.pyx          ← Cython 主模块: 导入时触发加载├──   function.pxi      ← Function 类 + 查找/注册逻辑├──   object.pxi        ← CObject 类: 句柄 + ref-counting├──   tensor.pxi        ← Tensor/DLTensor: DLPack 协议└──   tvm_ffi_python_helpers.h ← TVMFFIPyFuncCall C 实现

base.pxi — C 函数声明

#  这不是实现，只是声明 "libtvm_ffi.dylib 中有这些 C API 符号"cdef extern from "tvm/ffi/c_api.h":    intTVMFFIFunctionGetGlobal(TVMFFIByteArray* name, TVMFFIObjectHandle* out) nogil    int TVMFFIFunctionSetGlobal(TVMFFIByteArray* name, TVMFFIObjectHandle f, intoverride) nogil    int TVMFFIObjectDecRef(TVMFFIObjectHandle obj) nogil    ...#  Python helper (在 tvm_ffi_python_helpers.h 中实现):cdef extern from "tvm_ffi_python_helpers.h":    int TVMFFIPyFuncCall(void* func_handle, PyObject* py_arg_tuple,                         TVMFFIAny* result, int* c_api_ret_code,                         int release_gil, const DLPackExchangeAPI** c_ctx_dlpack_api)    ...

function.pxi — Function 类（实际调用入口）

cdef class Function(CObject):    cdef int c_release_gil    def __call__(self, *args:Any) -> Any:        cdef TVMFFIAny result        cdef int c_api_ret_code        cdef const DLPackExchangeAPI* c_ctx_dlpack_api = NULL        #   Step 1: 初始化返回值        result.type_index = kTVMFFINone        result.v_int64 = 0        #   Step 2: 调用 Python helper —— PyObject* 直接传入，C 层完成转换        TVMFFIPyFuncCall(            (<CObject>self).chandle, <PyObject*>args,            &result, &c_api_ret_code,            self.release_gil,            &c_ctx_dlpack_api        )        #   Step 3: 检查错误码        if c_api_ret_code == 0:            return make_ret(result, c_ctx_dlpack_api)        if c_api_ret_code == -2:            raise raise_existing_error()        error = move_from_last_error()        raise error.py_error()

Function.__call__() = 穿越点 — Python 调用在此进入 libtvm_ffi.dylib 地址空间，路由到 libtvm_compiler.dylib 中的 C++ 函数。

关键性能设计：TVMFFIPyFuncCall 接受 PyObject* 元组并在 C 层遍历转换（PyArgDispatcher），整个参数列表只需一次语言边界穿越。

`_get_global_func` 实现

def _get_global_func(name: str, allow_missing: bool):    cdef TVMFFIObjectHandle chandle    cdef ByteArrayArg name_arg = ByteArrayArg(c_str(name))    #  调用 C API 查找全局函数    CHECK_CALL(TVMFFIFunctionGetGlobal(name_arg.cptr(), &chandle))    if chandle != NULL:        ret = Function.__new__(Function)        (<CObject>ret).chandle = chandle  #  包装 C++ 句柄        return ret    if allow_missing:        return None    raise ValueError("Cannot find global function %s" % name)

`_register_global_func` 实现

def _register_global_func(name: str, pyfunc, override: bool) -> Function:    if not isinstance(pyfunc, Function):        pyfunc = _convert_to_ffi_func(pyfunc)  #  Python → Function    CHECK_CALL(TVMFFIFunctionSetGlobal(name_arg.cptr(), pyfunc.chandle, override))    return pyfunc

对象引用计数

双向绑定 — Python GC 自动触发 C++ 释放。

cdef class CObject:    cdef void* chandle    def __dealloc__(self):        if self.chandle != NULL:            CHECK_CALL(TVMFFIObjectDecRef(self.chandle))  #   C++ refcount--            self.chandle = NULL

Layer 3 — 注册表层：`get_global_func()` 与 `init_ffi_api()`

核心文件：3rdparty/tvm-ffi/python/tvm_ffi/registry.py^[2] — Python 代码中最常打交道的入口。

`get_global_func()` — 按名查找

def get_global_func(name, allow_missing=False):    """按名称从 C++ 全局注册表中查找函数"""    return core._get_global_func(name, allow_missing)    #  core._get_global_func 调用 TVMFFIFunctionGetGlobal    #  返回 Function 对象（Python 侧的 C++ Function 包装）

`register_global_func()` — Python → C++ 注册

def register_global_func(func_name, f=None, override=False):    """将 Python 函数注册到 C++ 全局注册表"""    #  内部调用 core._register_global_func    #  → TVMFFIFunctionSetGlobal(name, packed_func, override)

双向 FFI — C++ 也可以反过来调用 Python 注册的函数（常见于 callback）。

`register_object()` — Python 类 ↔ C++ 类型绑定

@register_object("tvm.ir.GlobalVar")class GlobalVar(Object):    pass

绑定后的效果：

•C++ 返回的 GlobalVar 对象自动包装成 Python GlobalVar•Python 子类自动获得所有 C++ 反射字段的 property 访问

`list_global_func_names()` — 列出所有函数

def list_global_func_names() -> list[str]:    """列出 C++ 侧注册的所有函数名"""    name_functor = get_global_func("ffi.FunctionListGlobalNamesFunctor")()    num_names = name_functor(-1)    return [name_functor(i) for i in range(num_names)]

`init_ffi_api()` — 批量绑定（关键！）

def init_ffi_api(namespace: str, target_module_name: str | None = None) -> None:    target_module_name = target_module_name if target_module_name else namespace    #  去掉可选的 "tvm." 前缀    if namespace.startswith("tvm."):        prefix = namespace[4:]    else:        prefix = namespace    target_module = sys.modules[target_module_name]    #  遍历所有已注册的全局函数    for name in list_global_func_names():        if not name.startswith(prefix):            continue        fname = name[len(prefix) + 1:]   #  提取函数短名        if fname.find(".") != -1:         #  跳过子命名空间            continue        f = get_global_func(name)        setattr(f, "__name__", fname)        setattr(target_module, fname, f)  #  挂载为 Python 模块属性

源码验证：3rdparty/tvm-ffi/registry.py:305-352^[3]

⚠️ 注意：这是 eager（立即）加载，不是懒加载。init_ffi_api 在 import 时立即遍历所有全局函数名并 setattr。

实际调用示例

#  python/tvm/ir/_ffi_api.py (实际源码)import tvm_ffitvm_ffi.init_ffi_api("ir", __name__)#  namespace="ir" → prefix="ir" → 挂载所有 "ir.*" 函数

from tvm.ir import _ffi_api#  _ffi_api.conv2d → 直接是 Function 对象（已在 import 时挂载）result = _ffi_api.conv2d(data, weight)

Layer 2 — 模块级批量绑定层

每个 TVM 子模块一个 _ffi_api.py（共 49 个_ffi_*.py），按模块组织 C++ 函数入口。

python/tvm/├──   ir/_ffi_api.py              # init_ffi_api("ir", __name__)├──   ir/_ffi_analysis_api.py     # init_ffi_api("ir.analysis", __name__)├──   ir/_ffi_transform_api.py    # init_ffi_api("transform", __name__)├──   ir/_ffi_instrument_api.py   # init_ffi_api("instrument", __name__)├──   relax/_ffi_api.py           # init_ffi_api("relax", __name__)├──   tirx/_ffi_api.py            # init_ffi_api("tirx", __name__)├──   s_tir/_ffi_api.py           # init_ffi_api("s_tir", __name__)├──   driver/_ffi_api.py          # init_ffi_api("driver", __name__)├──   target/_ffi_api.py          # init_ffi_api("target", __name__)├──   arith/_ffi_api.py           # init_ffi_api("arith", __name__)├──   runtime/_ffi_api.py         # init_ffi_api("runtime", __name__)├──   runtime/_ffi_node_api.py    # init_ffi_api("node", __name__)├──   support.py                  # init_ffi_api("support", __name__)├──   topi/cpp/generic.py         # init_ffi_api("topi.generic", ...)├──   topi/cpp/cuda.py            # init_ffi_api("topi.cuda", ...)├──   topi/cpp/x86.py             # init_ffi_api("topi.x86", ...)└──   ...（共 49 个）

设计优点：C++ 侧新增函数注册后，Python 侧零改动即可调用 — namespace 前缀匹配即自动挂载。

Layer 1 — 公共 API 层

用户可见的入口。python/tvm/ffi.py 直接重导出 tvm_ffi 全部 API。

#  python/tvm/ffi.py (实际源码)"""Redirects to tvm_ffi"""from tvm_ffi import *

#  python/tvm/__init__.py (实际源码)from tvm_ffi import register_object, register_global_func, get_global_func

用户典型用法：

import tvm#  方式 1: 按名查找f = tvm.get_global_func("relax.op.nn.conv2d")result = f(data, weight)#  方式 2: 通过 _ffi_api（更常用）from tvm.ir import _ffi_apiresult = _ffi_api.conv2d(data, weight)

⏱ 完整调用时序图

以一个真实调用 _ffi_api.conv2d(data, weight) 为例：

═══════════════════════════════════════════════════════════════════════  阶段 A: Import 绑定（仅执行一次）═══════════════════════════════════════════════════════════════════════t=0     Python: import tvm.ir._ffi_api        │       ↓ init_ffi_api("ir", __name__)t=1     Python: list_global_func_names() → 遍历 C++ 注册表        │       → get_global_func("ir.conv2d") → setattr "conv2d"        │       → get_global_func("ir.matmul")  → setattr "matmul"        │       → ... (所有 "ir.*" 一次性挂载)        │       ↓ 就绪: _ffi_api.conv2d 已是 Function 对象═══════════════════════════════════════════════════════════════════════  阶段 B: 函数调用（每次调用执行）═══════════════════════════════════════════════════════════════════════t=2    Python: _ffi_api.conv2d(data, weight)       │        ↓ 进入 Cythont=3    Cython: Function.__call__(self, data, weight)       │        result.type_index = kTVMFFINone       │        ↓ TVMFFIPyFuncCall(...)t=4      C:   PyArgDispatcher 遍历 args 元组，逐元素转换       │       Python int→C int, Python Tensor→DLTensor*, ...       │       ↓ 构建 AnyView[] 传给 C++t=5     C++:  tvm::ffi::Function::Call(args, &ret)       │        → 解包 AnyView 参数       │        → 调用注册的 lambda: conv2d(Expr, Expr, ...)       │        → 返回结果到 Any* ret       │        ↓t=6      C:   返回 ret_code=0t=7    Cython: make_ret(result, dlpack_api)       │        → type_index switch: Tensor→DLPack, Object→PyClass, ...       │        ↓t=8    Python: result = ...

关键性能特点

特点	说明
仅绑定一次	Import 阶段执行，之后 `_ffi_api.xxx` 是模块属性，不再查表
一次穿越	所有参数打包成 `PyObject*` 在 C 层批量转换，只穿越语言边界一次
零拷贝	ObjectRef 传递 `void* chandle` 裸指针，无序列化
原生速度	Cython 编译为 C 扩展模块，调用路径极短
按类型分发	`make_ret()` 通过 `type_index` switch 精确创建 Python 对象

总结

层	位置	职责	关键 API
6	`build/lib/`	编译产物（三个库拆分）	cmake build
5	`tvm-ffi/src/ffi/`	C++ 注册表 + 类型擦除	`Function::RegisterGlobal`
4	`cython/function.pxi`	Cython 桥接，穿越语言边界	`TVMFFIPyFuncCall`
3	`tvm_ffi/registry.py`	Python 注册表 API	`get_global_func` , `init_ffi_api`
2	`python/tvm/*/_ffi_api.py`	批量绑定 (49 文件)	`init_ffi_api("ir", __name__)`
1	`python/tvm/__init__.py`	公共 API 入口	`from tvm_ffi import ...`

一句话概括：libtvm_compiler + libtvm_runtime + libtvm_ffi 三个库在编译期就已包含所有 C++ 代码和静态初始化的注册表，Python 通过 tvm_ffi 独立 Cython 扩展以原生速度跨过语言边界，init_ffi_api 提供了 zero-boilerplate 的自动函数绑定，用户通过 tvm.get_global_func() 或 _ffi_api.xxx() 透明调用 C++ 函数，全程零序列化开销。

•基于 Apache TVM 源码逐行走读验证编写*

References

[1] tvm-ffi: 3rdparty/tvm-ffi/[2]: 3rdparty/tvm-ffi/python/tvm_ffi/registry.py[3] 3rdparty/tvm-ffi/registry.py:305-352: 3rdparty/tvm-ffi/python/tvm_ffi/registry.py#L305-L352

本文来自网友投稿或网络内容，如有侵犯您的权益请联系我们删除，联系邮箱：wyl860211@qq.com 。

TVM FFI 深度剖析:Python 如何调用 C++

整体架构图

Layer 6 — 物理根基：编译产物（多库拆分）

编译过程

为什么拆成三个库？

Python 侧加载（`tvm_ffi` Cython 扩展）

Layer 5 — C++ API 实现层：全局注册表 + 类型擦除

全局函数注册表

C++ 侧注册

Python 侧注册

类型擦除的 Function 对象

Layer 4 — Cython C-API 桥接层：零拷贝穿越

为什么用 Cython 而不是纯 ctypes？

关键文件与职责

base.pxi — C 函数声明

function.pxi — Function 类（实际调用入口）

`_get_global_func` 实现

`_register_global_func` 实现

对象引用计数

Layer 3 — 注册表层：`get_global_func()` 与 `init_ffi_api()`

`get_global_func()` — 按名查找

`register_global_func()` — Python → C++ 注册

`register_object()` — Python 类 ↔ C++ 类型绑定

`list_global_func_names()` — 列出所有函数

`init_ffi_api()` — 批量绑定（关键！）

实际调用示例

Layer 2 — 模块级批量绑定层

Layer 1 — 公共 API 层

⏱ 完整调用时序图

关键性能特点

总结

References

最新文章

热门文章

随机文章

TVM FFI 深度剖析:Python 如何调用 C++

整体架构图

Layer 6 — 物理根基：编译产物（多库拆分）

编译过程

为什么拆成三个库？

Python 侧加载（tvm_ffi Cython 扩展）

Layer 5 — C++ API 实现层：全局注册表 + 类型擦除

全局函数注册表

C++ 侧注册

Python 侧注册

类型擦除的 Function 对象

Layer 4 — Cython C-API 桥接层：零拷贝穿越

为什么用 Cython 而不是纯 ctypes？

关键文件与职责

base.pxi — C 函数声明

function.pxi — Function 类（实际调用入口）

_get_global_func 实现

_register_global_func 实现

对象引用计数

Layer 3 — 注册表层：get_global_func() 与 init_ffi_api()

get_global_func() — 按名查找

register_global_func() — Python → C++ 注册

register_object() — Python 类 ↔ C++ 类型绑定

list_global_func_names() — 列出所有函数

init_ffi_api() — 批量绑定（关键！）

实际调用示例

Layer 2 — 模块级批量绑定层

Layer 1 — 公共 API 层

⏱ 完整调用时序图

关键性能特点

总结

References

Linux操作命令(四)--tree命令以及拷贝命令

嵌入式Linux--LinuxI2C驱动开发全流程详解

最新文章

热门文章

随机文章

Python 侧加载（`tvm_ffi` Cython 扩展）

`_get_global_func` 实现

`_register_global_func` 实现

Layer 3 — 注册表层：`get_global_func()` 与 `init_ffi_api()`

`get_global_func()` — 按名查找

`register_global_func()` — Python → C++ 注册

`register_object()` — Python 类 ↔ C++ 类型绑定

`list_global_func_names()` — 列出所有函数

`init_ffi_api()` — 批量绑定（关键！）