# https://github.com/apache/tvm 项目说明书

生成时间：2026-06-17 07:09:26 UTC

## 目录

- [项目概览](#page-overview)
- [Src 模块](#page-jvm-core-src)
- [Src 模块](#page-apps-android_rpc-app-src)
- [Src 模块](#page-web-src)

<a id='page-overview'></a>

## 项目概览

### 相关页面

相关主题：[Src 模块](#page-jvm-core-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/apache/tvm/blob/main/README.md)
- [web/README.md](https://github.com/apache/tvm/blob/main/web/README.md)
- [web/package.json](https://github.com/apache/tvm/blob/main/web/package.json)
- [python/tvm/relax/backend/contrib/example_npu/README.md](https://github.com/apache/tvm/blob/main/python/tvm/relax/backend/contrib/example_npu/README.md)
- [jvm/README.md](https://github.com/apache/tvm/blob/main/jvm/README.md)
- [src/backend/vulkan/runtime/README.md](https://github.com/apache/tvm/blob/main/src/backend/vulkan/runtime/README.md)
- [src/backend/hexagon/runtime/README.md](https://github.com/apache/tvm/blob/main/src/backend/hexagon/runtime/README.md)
- [src/backend/opencl/runtime/opencl_wrapper/README.md](https://github.com/apache/tvm/blob/main/src/backend/opencl/runtime/opencl_wrapper/README.md)
- [apps/cpp_rpc/README.md](https://github.com/apache/tvm/blob/main/apps/cpp_rpc/README.md)
- [apps/android_rpc/README.md](https://github.com/apache/tvm/blob/main/apps/android_rpc/README.md)
- [apps/ios_rpc/README.md](https://github.com/apache/tvm/blob/main/apps/ios_rpc/README.md)
- [ci/README.md](https://github.com/apache/tvm/blob/main/ci/README.md)
- [ci/jenkins/README.md](https://github.com/apache/tvm/blob/main/ci/jenkins/README.md)
- [ci/scripts/package/README.md](https://github.com/apache/tvm/blob/main/ci/scripts/package/README.md)
- [docker/README.md](https://github.com/apache/tvm/blob/main/docker/README.md)
</details>

# 项目概览

## 项目定位与设计原则

Apache TVM 是一个开源的机器学习编译框架，旨在将来自不同前端框架的深度学习模型高效地编译并部署到各种硬件后端上。根据 [README.md](https://github.com/apache/tvm/blob/main/README.md) 的描述，TVM 遵循两大核心设计原则：

- **Python 优先的开发体验**：使用户能够快速定制机器学习编译流程中的各个环节。
- **通用化部署**：将训练好的模型编译为可独立运行的最小化部署模块。

项目本身以 Apache-2.0 协议进行分发，并采用 Apache 提交者治理模型，由社区共同维护。资料来源：[README.md](https://github.com/apache/tvm/blob/main/README.md)

TVM 的雏形源于深度学习编译方向的研究项目，其第一版的设计借鉴了多个成熟的编译器与符号计算系统，包括 Halide 的 TIR 与算术简化模块、Loopy 的整数集合分析与循环变换原语，以及 Theano 中符号化 scan 算子带来的灵感。资料来源：[README.md](https://github.com/apache/tvm/blob/main/README.md)

经过多轮迭代后，当前的 TVM 采用了基于 TensorIR 的跨层级设计，这与社区中 ML 编译器的整体演进趋势保持一致。

## 整体架构与组件构成

TVM 的代码组织呈现出多语言、多层次的特点，可大致分为 Python 前端、C++ 编译器与运行时，以及面向多种目标平台的运行时后端。

```mermaid
graph TB
    subgraph Frontend[Python 前端与编译流水线]
        PY[Python API / Relax / TIR]
    end
    subgraph Core[核心编译器]
        TIR[TensorIR 调度]
        Relax[Relax IR]
        BYOC[BYOC 后端集成]
    end
    subgraph Backends[运行时后端]
        CUDA[CUDA / LLVM]
        Vulkan[Vulkan]
        OpenCL[OpenCL]
        Hexagon[Hexagon DSP]
        Metal[Metal / iOS]
        Web[WebAssembly / WebGPU]
        JVM[JVM / TVM4J]
        NPU[示例 NPU]
    end
    PY --> TIR
    PY --> Relax
    TIR --> BYOC
    Relax --> BYOC
    BYOC --> Backends
```

Python 前端是用户接触 TVM 的主要入口，编译流水线的拼装、算子调度以及后端分发都通过 Python API 完成。核心 IR 层提供 TensorIR 进行可调度的低级表示，并辅以 Relax 表达函数级别语义；后端既包含通用 CPU/GPU 编译路径，也包括使用 BYOC（Bring Your Own Codegen）模式接入的自定义加速器。

在 WebAssembly 方向上，`web/` 目录提供了基于 emscripten 的运行时与 TypeScript 绑定 [web/README.md](https://github.com/apache/tvm/blob/main/web/README.md)；在 JVM 方向上，`jvm/` 目录下的 TVM4J 模块通过 JNI 将 C++ 运行时暴露到 Java 虚拟机中 [jvm/README.md](https://github.com/apache/tvm/blob/main/jvm/README.md)。

## 多平台运行时后端

TVM 在目标后端的覆盖范围上非常广泛，下表列出了几个具有代表性的后端实现及其关键特征。

| 后端 | 位置 | 关键能力 |
|------|------|----------|
| Vulkan | [src/backend/vulkan/runtime/README.md](https://github.com/apache/tvm/blob/main/src/backend/vulkan/runtime/README.md) | 通过 `VulkanDeviceAPI`、`VulkanThreadEntry`、`VulkanWrappedFunc` 实现 DeviceAPI、线程局部状态与算子下发 |
| OpenCL | [src/backend/opencl/runtime/opencl_wrapper/README.md](https://github.com/apache/tvm/blob/main/src/backend/opencl/runtime/opencl_wrapper/README.md) | 动态加载 OpenCL 库，避免在主机/手机端手动注入 SDK |
| Hexagon | [src/backend/hexagon/runtime/README.md](https://github.com/apache/tvm/blob/main/src/backend/hexagon/runtime/README.md) | 在 x86 主机上交叉编译到 Hexagon DSP，需 Hexagon SDK ≥ 4.0 与 LLVM ≥ 7.0 |
| WebAssembly | [web/README.md](https://github.com/apache/tvm/blob/main/web/README.md) | 浏览器内运行模型，支持 WASI 变体，需 `libtvm_runtime.bc` 链接 |
| JVM | [jvm/README.md](https://github.com/apache/tvm/blob/main/jvm/README.md) | `core`、`native`、`assembly` 三个 Maven 模块，Java 端可注册并调用 TVM 函数 |
| 示例 NPU | [python/tvm/relax/backend/contrib/example_npu/README.md](https://github.com/apache/tvm/blob/main/python/tvm/relax/backend/contrib/example_npu/README.md) | 演示如何通过 BYOC 模式为固定算子集的 NPU 构建后端 |

对于 RPC 通道，TVM 提供了 C++ 服务端 [apps/cpp_rpc/README.md](https://github.com/apache/tvm/blob/main/apps/cpp_rpc/README.md)、Android RPC 应用 [apps/android_rpc/README.md](https://github.com/apache/tvm/blob/main/apps/android_rpc/README.md) 以及 iOS RPC 应用 [apps/ios_rpc/README.md](https://github.com/apache/tvm/blob/main/apps/ios_rpc/README.md)，配合 `USE_CPP_RPC` 等 CMake 开关即可在不同设备上启动代理或独立 RPC 服务。

## 构建、CI 与社区治理

TVM 的构建以 CMake 为主，并提供 Docker 镜像作为标准开发与 CI 环境。`docker/bash.sh` 可在容器内挂载当前工作目录并切换到调用方用户身份，从而简化本地与远端构建。资料来源：[docker/README.md](https://github.com/apache/tvm/blob/main/docker/README.md)

持续集成分为两条主线：Jenkins 负责 Linux 平台及 GPU 加速硬件相关的大部分合并阻塞测试 [ci/jenkins/README.md](https://github.com/apache/tvm/blob/main/ci/jenkins/README.md)；GitHub Actions 则承担 Windows、macOS 任务以及各种仓库内自动化。Lint 脚本、任务定义和辅助脚本分别位于 `tests/lint`、`tests/scripts` 与 `ci/scripts`。资料来源：[ci/README.md](https://github.com/apache/tvm/blob/main/ci/README.md)

发行版方面，TVM 通过 `cibuildwheel` 流程发布 Python wheel，配置位于 `.github/workflows/publish_wheel.yml` 与 `pyproject.toml`；其中 `manylinux_build_libtvm_runtime_cuda.sh` 在预装 CUDA 工具链的 `quay.io/manylinux_cuda` 镜像中构建 `libtvm_runtime_cuda.so` 伴生库。资料来源：[ci/scripts/package/README.md](https://github.com/apache/tvm/blob/main/ci/scripts/package/README.md)

在社区治理层面，社区多次通过投票与 RFC 推动重大演进。Issue #16368 提出了将主线迁移到 Unity 版本的方案，以适应大模型与生成式 AI 的发展 [Issue #16368](https://github.com/apache/tvm/issues/16368)；Issue #7527 则跟踪 TensorIR 调度的落地情况 [Issue #7527](https://github.com/apache/tvm/issues/7527)。当前最新预发布版本为 v0.25.0.rc1，发行说明中已出现与之相关的回退与回填 PR。早期路线图（如 v0.5、v0.8）显示，TVM 的演进始终以“路线图公开讨论 + RFC 提案”为核心机制。

## See Also

- [TIR 与 TensorIR 调度原语]()
- [BYOC 后端集成指南]()
- [RPC 通道与设备端部署]()
- [JVM 前端 TVM4J]()
- [WebAssembly / WebGPU 运行时]()
- [持续集成与发布流程]()

---

<a id='page-jvm-core-src'></a>

## Src 模块

### 相关页面

相关主题：[项目概览](#page-overview), [Src 模块](#page-apps-android_rpc-app-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/apache/tvm/blob/main/README.md)
- [src/backend/vulkan/runtime/README.md](https://github.com/apache/tvm/blob/main/src/backend/vulkan/runtime/README.md)
- [src/backend/opencl/runtime/opencl_wrapper/README.md](https://github.com/apache/tvm/blob/main/src/backend/opencl/runtime/opencl_wrapper/README.md)
- [src/backend/hexagon/runtime/README.md](https://github.com/apache/tvm/blob/main/src/backend/hexagon/runtime/README.md)
- [jvm/README.md](https://github.com/apache/tvm/blob/main/jvm/README.md)
- [jvm/core/src/main/java/org/apache/tvm/Function.java](https://github.com/apache/tvm/blob/main/jvm/core/src/main/java/org/apache/tvm/Function.java)
- [jvm/core/src/main/java/org/apache/tvm/TVMValueNull.java](https://github.com/apache/tvm/blob/main/jvm/core/src/main/java/org/apache/tvm/TVMValueNull.java)
</details>

# Src 模块

## 概述

`src/` 是 Apache TVM 仓库中 C++ 核心源码的根目录,涵盖了编译器栈、设备抽象层以及多后端运行时的实现。该目录是 TVM "Python 优先" 原则(详见 [README.md](https://github.com/apache/tvm/blob/main/README.md))下方的 C++ 基座,负责把高层 IR 调度、算子融合等 Python 端能力,落地到各类硬件可执行模块中。除主 `src/` 外,JVM 前端在 `jvm/core/src/main/java/org/apache/tvm/` 下也遵循 `src/main/java` 的标准 Maven 目录约定,用于提供与 C++ 运行时交互的 Java 绑定。

`src/` 的总体设计目标是 **"一套编译栈,多种部署形态"**:同一份经过 Relax/TIR 编译产生的 Artifact,可以通过不同子目录下的后端 runtime 加载到 CPU、GPU、Vulkan 设备、OpenCL 设备、Hexagon DSP 等多种目标上。社区在 [#16368](https://github.com/apache/tvm/issues/16368) 中讨论的 Unity 过渡,以及在 [#7527](https://github.com/apache/tvm/issues/7527) 中推进的 TensorIR 调度,也都会反映到 `src/` 下各个 codegen 与 runtime 模块。

## 后端运行时子目录

`src/backend/` 是 `src/` 中负责设备端执行的核心子模块,每个目标硬件有独立的 `runtime/` 目录,实现统一的 `DeviceAPI` 接口。

### Vulkan 后端

`src/backend/vulkan/runtime/` 实现了 TVM 在 Vulkan 设备上的 DeviceAPI。其内部组件划分清晰:

| 组件 | 职责 |
| --- | --- |
| `VulkanDeviceAPI` | 实现 TVM `DeviceAPI` 接口,负责 Vulkan 实例与设备的初始化、扩展能力查询 |
| `VulkanThreadEntry` | 线程局部状态,维护用于跨设备拷贝的暂存缓冲区与 `VulkanStream` |
| `VulkanWrappedFunc` | 负责从 `VulkanModuleNode` 获取 `VulkanPipeline`,在活动 `VulkanStream` 上以立即或延迟模式发射 kernel |

资料来源:[src/backend/vulkan/runtime/README.md]()

Vulkan 运行时遵循类似 CUDA 的 stream 执行模型(在 `VulkanWrappedFunc` 中表现为 kernel 发射),因此可以复用 TVM 现有 device API 抽象,不需要在调用端做特殊适配。

### OpenCL 后端

`src/backend/opencl/runtime/opencl_wrapper/` 提供 OpenCL 库的动态加载包装层。它解决的问题是:在手机等嵌入式设备上,无需将 OpenCL 库复制到 host 端,也不需要再额外安装 OpenCL SDK。包装层对标准 OpenCL 函数集做安全封装,函数数量有限且不会随 OpenCL 演进而显著增长,从而保证 ABI 稳定性。

资料来源:[src/backend/opencl/runtime/opencl_wrapper/README.md]()

### Hexagon 后端

`src/backend/hexagon/runtime/` 面向 Qualcomm Hexagon DSP,提供模型在该硬件(或其模拟器)上执行所需的功能。构建要求包括:Hexagon SDK ≥ 4.0.0,以及 LLVM ≥ 7.0.0(社区反馈 7.0.0 为最低可用版本,推荐使用尽量新的 LLVM)。Host(x86)上的 TVM 既可作为交叉编译器生成 Hexagon 机器码,又可作为 runtime 加载这些模块,其中的 Hexagon 特定功能分别落在 codegen 和模块表示两侧。

资料来源:[src/backend/hexagon/runtime/README.md]()

## JVM 前端源码结构

TVM 同时提供 Java 绑定 TVM4J,其源码同样以 `src/main/java` 的 Maven 约定组织,入口在 `jvm/core/src/main/java/org/apache/tvm/`。

- `Function.java` 封装 TVM 的 Packed Function 抽象,提供 `getFunction(String name)` 获取已注册函数、`listGlobalFuncNames()` 枚举所有全局函数等能力,底层通过 JNI 调用 `Base._LIB.tvmFFIFunctionListGlobalNames` 拉取名字列表。资料来源:[jvm/core/src/main/java/org/apache/tvm/Function.java]()
- `TVMValueNull.java` 作为 `TVMValue` 的空值子类,用于在 JNI 边界上表示 `null` 类型的 TVM 值。

JVM 模块分为 `core`(Java 接口)、`native`(JNI 库编译)、`assembly`(将 core、native 与 TVM runtime 打包为可直接依赖的工件)三层,构建产物是 `libtvm_runtime.so` / `libtvm_runtime.dylib` 等共享库,被 `assembly` 模块在加载时自动抽取到临时文件并 `System.load`。

资料来源:[jvm/README.md]()

## 构建与典型使用模式

### C++ 端的交叉与本地构建

`src/` 下不同后端通常通过顶层 `config.cmake` 中的开关启用。例如构建 Android 端 C++ RPC server 时,需在 `config.cmake` 中设置 `USE_CPP_RPC=ON`,并通过 `CMAKE_TOOLCHAIN_FILE` 指向 Android NDK 工具链,再指定 `ANDROID_ABI` 与目标平台。Hexagon 后端则需在 LLVM 与 Hexagon SDK 齐全的环境下打开相应 `USE_HEXAGON` 开关。

### Web 端构建

WebAssembly runtime 与普通 `src/backend/` 路径不同,使用 emscripten 编译产物位于 `web/`,而 C++ 部分仍复用 `src/` 内的运行时实现。`web/README.md` 描述了通过 `make` 生成 `dist/wasm/libtvm_runtime.bc`、`tvmjs_runtime.wasm` 与 `tvmjs_runtime.wasi.js` 的流程;前端 JS 库则通过 `npm run bundle` 打包。

### 常见失败模式

- **Vulkan 扩展不可用**:如果 `VulkanDeviceAPI` 在初始化时未找到所需扩展,会导致 stream 创建失败,此时应检查驱动版本与 `VK_*` 扩展启用情况。资料来源:[src/backend/vulkan/runtime/README.md]()
- **OpenCL 库未装载**:`opencl_wrapper` 假设平台已存在 OpenCL ICD,在桌面 GPU 上一般可用,但在某些嵌入式 SoC 上需要厂商 ICD。
- **Hexagon SDK / LLVM 版本过旧**:低于 4.0.0 / 7.0.0 的组合会导致 codegen 缺指令或 runtime 缺 intrinsic,应按社区建议升级。
- **JVM 端 `libtvm_runtime` 未在 `LD_LIBRARY_PATH` 中**:`assembly` 模块抽取并加载 native 库时,如系统无法解析符号会抛出 `UnsatisfiedLinkError`,需在启动脚本中提前 export。

## See Also

- [README.md](https://github.com/apache/tvm/blob/main/README.md) — 项目总体介绍与设计原则
- [jvm/README.md](https://github.com/apache/tvm/blob/main/jvm/README.md) — TVM4J Java 前端详细说明
- [web/README.md](https://github.com/apache/tvm/blob/main/web/README.md) — WebAssembly runtime 构建与运行
- 社区讨论:[#16368 Unity 过渡](https://github.com/apache/tvm/issues/16368)、[#7527 TensorIR 调度](https://github.com/apache/tvm/issues/7527)、[#4105 Auto TensorCore CodeGen](https://github.com/apache/tvm/issues/4105)

---

<a id='page-apps-android_rpc-app-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-jvm-core-src), [Src 模块](#page-web-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [web/src/index.ts](https://github.com/apache/tvm/blob/main/web/src/index.ts)
- [src/backend/vulkan/runtime/README.md](https://github.com/apache/tvm/blob/main/src/backend/vulkan/runtime/README.md)
- [src/backend/opencl/runtime/opencl_wrapper/README.md](https://github.com/apache/tvm/blob/main/src/backend/opencl/runtime/opencl_wrapper/README.md)
- [src/backend/hexagon/runtime/README.md](https://github.com/apache/tvm/blob/main/src/backend/hexagon/runtime/README.md)
- [apps/ios_rpc/README.md](https://github.com/apache/tvm/blob/main/apps/ios_rpc/README.md)
- [apps/cpp_rpc/README.md](https://github.com/apache/tvm/blob/main/apps/cpp_rpc/README.md)
- [apps/android_rpc/README.md](https://github.com/apache/tvm/blob/main/apps/android_rpc/README.md)
- [jvm/README.md](https://github.com/apache/tvm/blob/main/jvm/README.md)
- [jvm/core/src/main/java/org/apache/tvm/Function.java](https://github.com/apache/tvm/blob/main/jvm/core/src/main/java/org/apache/tvm/Function.java)
- [jvm/core/src/main/java/org/apache/tvm/TVMValueNull.java](https://github.com/apache/tvm/blob/main/jvm/core/src/main/java/org/apache/tvm/TVMValueNull.java)
- [web/README.md](https://github.com/apache/tvm/blob/main/web/README.md)
</details>

# Src 模块

## 1. 概述

在 Apache TVM 仓库中,`Src` 并非单一目录,而是若干个承担不同职责的源代码根目录的统称。这些 `src` 目录分别承载 TVM 的后端运行时实现、WebAssembly 前端胶水代码、JVM 绑定,以及各 RPC 应用的本地源码。本质上,`src` 模块是 TVM"Python-first 编译 + 通用部署"原则中"通用部署"一侧的具体载体——把模型编译产物落到 CPU、GPU、移动端 NPU、浏览器乃至 Java 虚拟机上,都依赖于这些 `src` 子树中相应的 C++/TypeScript/Java 实现。

资料来源：[README.md:13-18](https://github.com/apache/tvm/blob/main/README.md)

## 2. 主要 Src 子树划分

TVM 仓库中的 `src` 目录呈现"按部署目标纵向切分"的结构,各子目录之间相对独立,但都遵循统一的 `DeviceAPI` 抽象与 `PackedFunc` 调用约定。

```mermaid
graph TB
    A[TVM 仓库 src 体系] --> B[src/backend/<br/>原生 C++ 后端]
    A --> C[web/src/<br/>WASM 浏览器前端]
    A --> D[jvm/core/src/<br/>Java 绑定]
    A --> E[apps/*/app/src/<br/>RPC 应用源码]

    B --> B1[vulkan/runtime]
    B --> B2[opencl/runtime/opencl_wrapper]
    B --> B3[hexagon/runtime]

    C --> C1[index.ts<br/>统一导出]
    C --> C2[artifact_cache]
    C --> C3[rpc_server]
    C --> C4[cache_state]

    D --> D1[Function.java]
    D --> D2[TVMValueNull.java]
```

各子目录的职责如下表所示。

| 子树路径 | 语言 | 核心职责 |
| --- | --- | --- |
| `src/backend/*/runtime/` | C++ | 各类加速器后端 `DeviceAPI` 与运行时 |
| `web/src/` | TypeScript | 浏览器侧 WASM 运行时的对外 API 封装 |
| `jvm/core/src/main/java/org/apache/tvm/` | Java | TVM 运行时的 Java 入口与 Packed Function |
| `apps/*/app/src/` | Java/Obj-C/C++ | 移动端与桌面端 RPC Server 应用 |

资料来源：[web/src/index.ts:1-22](https://github.com/apache/tvm/blob/main/web/src/index.ts)、[jvm/README.md:18-32](https://github.com/apache/tvm/blob/main/jvm/README.md)

## 3. 后端运行时 Src: Vulkan / OpenCL / Hexagon

`src/backend/` 下的各运行时共同实现 TVM 统一的 `DeviceAPI` 接口,使得上层 IR 与调度无需关心硬件差异。

**Vulkan 后端**由三类核心组件构成。`VulkanDeviceAPI` 负责初始化 Vulkan 实例、查询可用扩展并管理核心数据结构;`VulkanThreadEntry` 维护线程局部状态,包括用于数据搬运的暂存缓冲区以及每个设备一个的 `VulkanStream`;`VulkanWrappedFunc` 负责从 `VulkanModuleNode` 中获取 `VulkanPipeline` 并以 immediate 或 deferred 模式在当前 `VulkanStream` 上启动 kernel。其流执行模型沿用 CUDA API 的隐式/显式流风格。

资料来源：[src/backend/vulkan/runtime/README.md:11-37](https://github.com/apache/tvm/blob/main/src/backend/vulkan/runtime/README.md)

**OpenCL 后端**通过 `opencl_wrapper` 动态加载 OpenCL 库,避免在部署到手机等设备时需要将 OpenCL SDK 复制到宿主机。该模块对 OpenCL 标准 API 进行安全包装,函数数量有限且不会增长。

资料来源：[src/backend/opencl/runtime/opencl_wrapper/README.md:14-19](https://github.com/apache/tvm/blob/main/src/backend/opencl/runtime/opencl_wrapper/README.md)

**Hexagon 后端**为 Hexagon DSP(以及其模拟器)执行 ML 模型提供运行时支持,前置依赖包括 Hexagon SDK 4.0.0+ 与 LLVM 7.0.0+。在 x86 主机上,TVM 可作为交叉编译器生成 Hexagon 机器码。

资料来源：[src/backend/hexagon/runtime/README.md:13-22](https://github.com/apache/tvm/blob/main/src/backend/hexagon/runtime/README.md)

## 4. WebAssembly 前端 Src

`web/src/index.ts` 是 TVM 浏览器运行时的 TypeScript 入口,集中重新导出构建 TVMS.js 应用所需的全部模块:缓存层(`artifact_cache`、`cache_state`)、远程过程调用(`rpc_server`)、浏览器侧支持工具(`support`,提供 `assert`、`wasmPath`、`LinearCongruentialGenerator`)、WebGPU 检测(`webgpu`)、类型定义(`types` 中的 `Disposable` 与 `LibraryProvider`),以及 WASI 兼容垫片(`compact` 中的 `createPolyfillWASI`)。

其构建产物为 `dist/wasm/libtvm_runtime.bc`、`tvmjs_runtime.wasm`、`tvmjs_runtime.wasi.js`,通过 Emscripten 链入 emcc 编译流程。

资料来源：[web/src/index.ts:1-22](https://github.com/apache/tvm/blob/main/web/src/index.ts)、[web/README.md:28-49](https://github.com/apache/tvm/blob/main/web/README.md)

## 5. JVM 绑定 Src

`jvm/core/src/main/java/org/apache/tvm/` 提供 TVM 的 Java 前端,与 C++ `libtvm_runtime` 通过 JNI 对接。其中 `Function` 类代表 TVM Packed Function,可通过 `getFunction(String name)` 获取已注册函数,并通过 `listGlobalFuncNames()` 列出所有全局函数名;`TVMValueNull` 则作为 `TVMValue` 体系中的空值哨兵类型,用于在跨语言调用中表示 None/Nil 语义。

整个 TVM4J 由 `core`、`native`、`assembly` 三个 Maven 模块组成,推荐通过 `assembly` 模块以"自动解压并加载"的方式集成,以避免手动配置 `LD_LIBRARY_PATH`。

资料来源：[jvm/core/src/main/java/org/apache/tvm/Function.java:23-43](https://github.com/apache/tvm/blob/main/jvm/core/src/main/java/org/apache/tvm/Function.java)、[jvm/core/src/main/java/org/apache/tvm/TVMValueNull.java:19-21](https://github.com/apache/tvm/blob/main/jvm/core/src/main/java/org/apache/tvm/TVMValueNull.java)、[jvm/README.md:18-58](https://github.com/apache/tvm/blob/main/jvm/README.md)

## 6. RPC 应用 Src

`apps/` 目录下的三个 RPC Server 各自携带 `app/src` 子树,提供在目标设备上启动 TVM RPC Server 的本地实现:

- **Android RPC**(`apps/android_rpc/app/src/main/java/...`)使用 Gradle 构建,需配合 `tvm4j` 与 Android NDK。
- **iOS RPC**(`apps/ios_rpc/...`)基于 XCode 工程,把 TVM 运行时打入 iOS 应用。
- **C++ RPC**(`apps/cpp_rpc/`)为跨平台 C++ 实现的 RPC Server,通过 CMake 的 `USE_CPP_RPC=ON` 启用,可与 Android NDK 工具链组合进行交叉编译。

资料来源：[apps/android_rpc/README.md:10-24](https://github.com/apache/tvm/blob/main/apps/android_rpc/README.md)、[apps/ios_rpc/README.md:7-12](https://github.com/apache/tvm/blob/main/apps/ios_rpc/README.md)、[apps/cpp_rpc/README.md:5-22](https://github.com/apache/tvm/blob/main/apps/cpp_rpc/README.md)

## See Also

- [TVM 主仓库概览与编译流程](https://tvm.apache.org/docs/)
- [Relax BYOC: Example NPU Backend](https://github.com/apache/tvm/blob/main/python/tvm/relax/backend/contrib/example_npu/README.md)
- [CI 持续集成体系](https://github.com/apache/tvm/blob/main/ci/README.md)

---

<a id='page-web-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-apps-android_rpc-app-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/apache/tvm/blob/main/README.md)
- [src/backend/vulkan/runtime/README.md](https://github.com/apache/tvm/blob/main/src/backend/vulkan/runtime/README.md)
- [src/backend/opencl/runtime/opencl_wrapper/README.md](https://github.com/apache/tvm/blob/main/src/backend/opencl/runtime/opencl_wrapper/README.md)
- [src/backend/hexagon/runtime/README.md](https://github.com/apache/tvm/blob/main/src/backend/hexagon/runtime/README.md)
- [apps/cpp_rpc/README.md](https://github.com/apache/tvm/blob/main/apps/cpp_rpc/README.md)
- [apps/ios_rpc/README.md](https://github.com/apache/tvm/blob/main/apps/ios_rpc/README.md)
- [apps/android_rpc/README.md](https://github.com/apache/tvm/blob/main/apps/android_rpc/README.md)
- [jvm/README.md](https://github.com/apache/tvm/blob/main/jvm/README.md)
- [jvm/core/src/main/java/org/apache/tvm/Function.java](https://github.com/apache/tvm/blob/main/jvm/core/src/main/java/org/apache/tvm/Function.java)
- [web/README.md](https://github.com/apache/tvm/blob/main/web/README.md)
- [ci/README.md](https://github.com/apache/tvm/blob/main/ci/README.md)
- [python/tvm/relax/backend/contrib/example_npu/README.md](https://github.com/apache/tvm/blob/main/python/tvm/relax/backend/contrib/example_npu/README.md)
</details>

# Src 模块

## 1. 概述与设计原则

`src/` 目录是 Apache TVM 的 C++ 核心源码模块，集中了编译器的后端代码生成、设备运行时、跨设备驱动适配等底层实现。该模块遵循 **Python-first 优先开发** 与 **通用部署（Universal Deployment）** 两大原则，向下对接各类加速硬件（CPU、GPU、NPU、DSP），向上通过 FFI/ABI 为 Python 前端、Java 前端（JVM）以及 WebAssembly 运行时提供统一的编译与执行能力 [README.md](https://github.com/apache/tvm/blob/main/README.md)。

`src/` 模块在 TVM 整体架构中位于 **IR → CodeGen → Runtime** 流水线的下游，负责把高层 IR（Relax、TIR、TensorIR）变换为具体硬件可执行的二进制或中间表示。它的内部按子目录进一步划分为：

- `src/relay/`、`src/relax/`：高层图 IR 与函数式 IR。
- `src/tir/`：TensorIR 调度原语与底层循环 IR。
- `src/target/source/`：通用代码生成框架（CUDA、C、LLVM IR 等）。
- `src/runtime/`：设备无关的运行时抽象（NDArray、Module、RPC、Graph Executor）。
- `src/backend/<device>/runtime/`：各后端 DeviceAPI、驱动加载、Kernel 启动器。

## 2. 设备后端子系统

`src/backend/` 子树实现了 TVM 的 `DeviceAPI` 接口，让上层运行时可同时调度 CPU 与多种加速器。

### 2.1 Vulkan 后端

Vulkan 后端以 `VulkanDeviceAPI`、`VulkanThreadEntry`、`VulkanWrappedFunc` 三个核心类构成。`VulkanDeviceAPI` 负责初始化 Vulkan 实例与设备，并查询可用扩展；`VulkanThreadEntry` 维护线程本地状态（staging buffer、每个设备的 `VulkanStream`）；`VulkanWrappedFunc` 从 `VulkanModuleNode` 获取 `VulkanPipeline` 并以 **immediate** 或 **deferred** 模式发射 kernel [src/backend/vulkan/runtime/README.md](https://github.com/apache/tvm/blob/main/src/backend/vulkan/runtime/README.md)。

### 2.2 OpenCL 后端

OpenCL 包装器通过 **动态加载** OpenCL 库，避免在主机/手机间手动复制 SDK 文件；因为 OpenCL 是标准 API，函数集数量有限，包装后不会显著增加二进制体积 [src/backend/opencl/runtime/opencl_wrapper/README.md](https://github.com/apache/tvm/blob/main/src/backend/opencl/runtime/opencl_wrapper/README.md)。

### 2.3 Hexagon 后端

Hexagon 后端面向高通 Hexagon DSP。运行时的先决条件包括：Hexagon SDK ≥ 4.0.0，LLVM ≥ 7.0.0（社区反馈更优）。在 x86 主机上，TVM 可作为 **交叉编译器** 生成 Hexagon 机器码，同时需要包含 Hexagon 特定的代码生成路径与运行时模块表示 [src/backend/hexagon/runtime/README.md](https://github.com/apache/tvm/blob/main/src/backend/hexagon/runtime/README.md)。

### 2.4 NPU 示例后端

`python/tvm/relax/backend/contrib/example_npu/` 提供了一个 **BYOC（Bring Your Own Codegen）** 的 NPU 后端参考实现，演示如何为移动 NPU（AMD XDNA、Edge TPU、Samsung NPU）、专用 AI 芯片（Intel Movidius、Qualcomm Hexagon、MediaTek APU）以及云端加速器（AWS Inferentia、Google TPU、Azure Maia）构建外接代码生成 [python/tvm/relax/backend/contrib/example_npu/README.md](https://github.com/apache/tvm/blob/main/python/tvm/relax/backend/contrib/example_npu/README.md)。

```mermaid
graph LR
  FE[Python/Relax Frontend] --> IR[IR: Relax / TIR]
  IR --> CG[src/target/source Codegen]
  CG --> CUDA[CUDA Module]
  CG --> VULKAN[src/backend/vulkan]
  CG --> OPENCL[src/backend/opencl]
  CG --> HEXAGON[src/backend/hexagon]
  CG --> NPU[BYOC NPU Codegen]
  VULKAN --> RUNTIME[src/runtime: Module / NDArray / RPC]
  OPENCL --> RUNTIME
  HEXAGON --> RUNTIME
  CUDA --> RUNTIME
  NPU --> RUNTIME
  RUNTIME --> DEPLOY[Deploy: JVM / WASM / C++ RPC / iOS / Android]
```

## 3. 部署与跨语言绑定

`src/` 模块产出的库不仅由 Python 直接加载，也通过 **RPC Server** 与 **JVM 绑定** 在异构环境中运行。

### 3.1 RPC Server

C++ RPC Server 由 `apps/cpp_rpc/` 提供，通过 CMake 变量 `USE_CPP_RPC=ON` 启用；交叉编译到 Android 时需配合 `CMAKE_TOOLCHAIN_FILE` 与 `ANDROID_ABI` 等参数。Android 端进一步封装为 APK，依赖 `jvm/` 模块的 TVM4J 与 JDK/NDK [apps/cpp_rpc/README.md](https://github.com/apache/tvm/blob/main/apps/cpp_rpc/README.md) [apps/android_rpc/README.md](https://github.com/apache/tvm/blob/main/apps/android_rpc/README.md)。iOS 端则需配合 XCode 构建 [apps/ios_rpc/README.md](https://github.com/apache/tvm/blob/main/apps/ios_rpc/README.md)。

### 3.2 JVM/TVM4J 绑定

TVM4J 把 C++ 运行时暴露到 JVM：可通过 `Function.getFunction(name)` 拿到已注册的 Packed Function，并通过 `listGlobalFuncNames()` 列出所有全局函数，便于 Java 端直接复用 TVM 后端 [jvm/core/src/main/java/org/apache/tvm/Function.java](https://github.com/apache/tvm/blob/main/jvm/core/src/main/java/org/apache/tvm/Function.java)。`TVMValueNull` 则是 FFI 值系统中表示空值的标记类型 [jvm/core/src/main/java/org/apache/tvm/TVMValueNull.java](https://github.com/apache/tvm/blob/main/jvm/core/src/main/java/org/apache/tvm/TVMValueNull.java)。完整模块包含 `core`（Java 接口）、`native`（JNI 库）、`assembly`（打包三者的统一 Maven 工件）[jvm/README.md](https://github.com/apache/tvm/blob/main/jvm/README.md)。

### 3.3 WebAssembly 运行时

`web/` 目录使用 Emscripten 把 `src/runtime` 编译为 `libtvm_runtime.bc`、`tvmjs_runtime.wasm`、`tvmjs_runtime.wasi.js`；前端通过 `npm run bundle` 生成 `tvmjs` 库与 WASM 运行时通信 [web/README.md](https://github.com/apache/tvm/blob/main/web/README.md)。

## 4. 构建、CI 与扩展模式

`src/` 模块的构建由根目录 CMake 与 `ci/` 工具链驱动。CI 系统由 Lint（`tests/lint`）、测试集（`tests/`）、任务脚本（`tests/scripts/task_*`）、CI 自动化（`ci/scripts`）以及 Jenkinsfile 描述的 Linux 流水线组成，并在 GitHub Actions 上运行 Windows 与 macOS 任务 [ci/README.md](https://github.com/apache/tvm/blob/main/ci/README.md) [ci/jenkins/README.md](https://github.com/apache/tvm/blob/main/ci/jenkins/README.md)。Wheel 打包由 `cibuildwheel` 流程负责，CUDA runtime 侧车库在 `manylinux_cuda` 镜像中构建 [ci/scripts/package/README.md](https://github.com/apache/tvm/blob/main/ci/scripts/package/README.md)。

扩展新后端时，开发者通常的步骤是：(1) 在 `src/backend/<device>/runtime/` 中实现 `DeviceAPI`；(2) 在 `src/target/source/` 添加 CodeGen 路径或通过 BYOC 注入；(3) 在 CMake 中增加编译开关；(4) 在 `ci/` 中添加相应的 Docker 镜像与任务脚本。该模式在社区广泛讨论的 **Unity 过渡**（#16368）、**TensorIR 调度**（#7527）以及 **TensorCore CodeGen**（#4105）等 RFC 中均有所体现。

## See Also

- [README.md](https://github.com/apache/tvm/blob/main/README.md) — 项目总览
- [src/backend/vulkan/runtime/README.md](https://github.com/apache/tvm/blob/main/src/backend/vulkan/runtime/README.md) — Vulkan 设备 API
- [src/backend/hexagon/runtime/README.md](https://github.com/apache/tvm/blob/main/src/backend/hexagon/runtime/README.md) — Hexagon DSP 后端
- [jvm/README.md](https://github.com/apache/tvm/blob/main/jvm/README.md) — TVM4J Java 绑定
- [web/README.md](https://github.com/apache/tvm/blob/main/web/README.md) — WebAssembly 运行时
- [python/tvm/relax/backend/contrib/example_npu/README.md](https://github.com/apache/tvm/blob/main/python/tvm/relax/backend/contrib/example_npu/README.md) — BYOC NPU 参考实现

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：apache/tvm

摘要：发现 8 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[VOTE] Release Apache TVM v0.25.0.rc1。

## 1. 安全/权限坑 · 来源证据：[VOTE] Release Apache TVM v0.25.0.rc1

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[VOTE] Release Apache TVM v0.25.0.rc1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/apache/tvm/issues/19802 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/apache/tvm | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/apache/tvm | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/apache/tvm | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/apache/tvm | no_demo; severity=medium

## 6. 安全/权限坑 · 来源证据：[VOTE] Release Apache TVM v0.25.0.rc0

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[VOTE] Release Apache TVM v0.25.0.rc0
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/apache/tvm/issues/19702 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 7. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/apache/tvm | issue_or_pr_quality=unknown

## 8. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/apache/tvm | release_recency=unknown

<!-- canonical_name: apache/tvm; human_manual_source: deepwiki_human_wiki -->