版本兼容性说明¶
本文档详细说明 PTO-ISA 的版本兼容性策略、不同版本间的差异、平台支持情况以及迁移指南。
目录¶
1. 版本策略¶
1.1 语义化版本¶
PTO-ISA 遵循语义化版本规范（Semantic Versioning 2.0.0）：
主版本号.次版本号.修订号 (MAJOR.MINOR.PATCH)
示例：v1.2.3
├─ 1: 主版本号
├─ 2: 次版本号
└─ 3: 修订号
版本号递增规则：
- 主版本号（MAJOR）：不兼容的 API 变更
- 移除或重命名公共 API
- 改变 API 行为语义
- 修改数据结构布局
-
示例：v1.x.x → v2.0.0
-
次版本号（MINOR）：向后兼容的功能新增
- 添加新的 API 函数
- 添加新的算子支持
- 性能优化（不改变行为）
-
示例：v1.2.x → v1.3.0
-
修订号（PATCH）：向后兼容的问题修正
- Bug 修复
- 文档更新
- 内部重构（不影响 API）
- 示例：v1.2.3 → v1.2.4
1.2 当前版本¶
- 最新稳定版本：v1.0.0
- 发布日期：2025-12-27
- 支持状态：✅ 长期支持（LTS）
1.3 版本支持周期¶
| 版本类型 | 支持周期 | 说明 |
|---|---|---|
| LTS（长期支持） | 2 年 | 主要版本，提供完整支持和安全更新 |
| 稳定版 | 1 年 | 次要版本，提供 Bug 修复 |
| 开发版 | 3 个月 | 实验性功能，不保证稳定性 |
当前支持的版本： - v1.0.x（LTS）：支持至 2027-12-27 - v0.9.x（稳定版）：支持至 2026-06-27
2. 平台兼容性¶
2.1 硬件平台¶
| 平台 | 架构 | 支持状态 | 最低版本 | 推荐版本 | 备注 |
|---|---|---|---|---|---|
| Ascend A2 | 910B1 | ✅ 完全支持 | v1.0.0 | v1.0.0 | 24 核，512 KB L1/核 |
| Ascend A3 | 910B2 | ✅ 完全支持 | v1.0.0 | v1.0.0 | 24 核，512 KB L1/核 |
| Ascend A5 | 910_9599 | ✅ 完全支持 | v1.0.0 | v1.0.0 | 32 核，1 MB L1/核 |
| CPU (x86_64) | x86-64 | ✅ 仿真支持 | v1.0.0 | v1.0.0 | 用于开发调试 |
| CPU (AArch64) | ARM64 | ✅ 仿真支持 | v1.0.0 | v1.0.0 | 用于开发调试 |
平台特性对比：
| 特性 | A2 | A3 | A5 |
|---|---|---|---|
| 核心数 | 24 | 24 | 32 |
| L1 容量/核 | 512 KB | 512 KB | 1 MB |
| 最大 Tile 尺寸 | 16×512 | 16×512 | 16×1024 |
| FP16 支持 | ✅ | ✅ | ✅ |
| BF16 支持 | ❌ | ✅ | ✅ |
| INT8 支持 | ✅ | ✅ | ✅ |
2.2 操作系统¶
| 操作系统 | 版本 | 架构 | 支持状态 |
|---|---|---|---|
| Ubuntu | 20.04, 22.04 | x86_64, aarch64 | ✅ 完全支持 |
| CentOS | 7.6+, 8.x | x86_64, aarch64 | ✅ 完全支持 |
| openEuler | 20.03 LTS+ | x86_64, aarch64 | ✅ 完全支持 |
| Kylin | V10 | x86_64, aarch64 | ✅ 完全支持 |
| Windows | 10, 11 | x86_64 | ⚠️ 实验性支持 |
2.3 软件依赖¶
核心依赖¶
| 组件 | 最低版本 | 推荐版本 | 必需 | 说明 |
|---|---|---|---|---|
| CANN | 8.5.0 | 8.5.0+ | ✅ | 华为 AI 计算框架 |
| CMake | 3.16 | 3.20+ | ✅ | 构建系统 |
| C++ 编译器 | - | - | ✅ | 见下表 |
| Python | 3.8 | 3.10+ | ⚠️ | 用于构建脚本和测试 |
C++ 编译器¶
| 编译器 | 最低版本 | 推荐版本 | C++20 支持 |
|---|---|---|---|
| GCC | 7.3.0 | 13.0+ | 13.0+ |
| Clang | 10.0 | 15.0+ | 15.0+ |
| MSVC | 2019 (16.0) | 2022 (17.0+) | 2022+ |
可选依赖¶
| 组件 | 版本 | 用途 |
|---|---|---|
| PyTorch | 2.0+ | 框架集成 |
| torch_npu | 2.0+ | NPU 后端 |
| TensorFlow | 2.10+ | 框架集成 |
| ONNX Runtime | 1.14+ | 推理框架集成 |
| Ninja | 1.10+ | 加速构建 |
| ccache | 4.0+ | 编译缓存 |
2.4 框架兼容性¶
| 框架 | 版本 | 集成方式 | 支持状态 |
|---|---|---|---|
| PyTorch | 2.0+ | torch_npu | ✅ 完全支持 |
| TensorFlow | 2.10+ | 自定义 Op | ✅ 完全支持 |
| ONNX Runtime | 1.14+ | 自定义 EP | ✅ 完全支持 |
| MindSpore | 2.0+ | 自定义算子 | ⚠️ 实验性支持 |
| PaddlePaddle | 2.5+ | 自定义算子 | ⚠️ 实验性支持 |
3. API 兼容性¶
3.1 稳定 API（保证向后兼容）¶
以下 API 在主版本内保证向后兼容：
核心 Tile 操作¶
// ✅ 稳定 API
TLOAD(tile, global_tensor)
TSTORE(global_tensor, tile)
TADD(out, a, b)
TSUB(out, a, b)
TMUL(out, a, b)
TDIV(out, a, b)
TMATMUL(out, a, b)
TMATMUL_ACC(acc, a, b)
GlobalTensor 接口¶
// ✅ 稳定 API
GlobalTensor<T>(ptr)
GlobalTensor<T>(ptr, size)
GlobalTensor<T>(ptr, shape)
Event 同步机制¶
// ✅ 稳定 API
Event e;
TLOAD(tile, input, e);
WAIT(e);
基础数据类型¶
// ✅ 稳定 API
Tile<TileType::Vec, float, H, W>
Tile<TileType::Cube, half, H, W>
TileAcc<float, H, W>
TileLeft<half, H, K>
TileRight<half, K, W>
3.2 实验性 API（可能变更）¶
以下 API 标记为实验性，可能在未来版本中变更：
// ⚠️ 实验性 API
#pragma pto_fusion // 自动融合（未来版本）
#pragma pto_autotune // 自动调优（未来版本）
3.3 已废弃 API¶
| API | 废弃版本 | 移除版本 | 替代方案 |
|---|---|---|---|
TLOAD_OLD |
v0.9.0 | v2.0.0 | TLOAD |
Event<T> |
v0.9.0 | v2.0.0 | Event |
4. 版本历史¶
v1.0.0（2025-12-27）- LTS¶
新特性： - ✨ 首个稳定版本发布 - ✨ 完整的 Tile 编程模型 - ✨ 支持 A2/A3/A5 平台 - ✨ PyTorch/TensorFlow 集成 - ✨ 完整的文档和示例
改进： - 🚀 性能优化：相比 v0.9 提升 20% - 📝 完善的 API 文档 - 🧪 完整的测试覆盖
Bug 修复： - 🐛 修复 L1 内存计算错误 - 🐛 修复 Event 同步问题 - 🐛 修复 Tile 对齐检查
v0.9.0（2025-06-15）- Beta¶
新特性： - ✨ Beta 版本发布 - ✨ 基础 Tile 操作 - ✨ 实验性 A5 支持
已知问题： - ⚠️ A5 平台性能未优化 - ⚠️ 部分 API 可能变更
5. 迁移指南¶
5.1 从 v0.9.x 迁移到 v1.0.x¶
主要变更¶
1. Tile 构造函数参数顺序调整
// ❌ v0.9.x（已废弃）
Tile<float, 16, 256, TileType::Vec> tile;
// ✅ v1.0.x（新语法）
Tile<TileType::Vec, float, 16, 256> tile;
2. Event 模板参数简化
// ❌ v0.9.x（已废弃）
Event<TileType::Vec> e;
// ✅ v1.0.x（新语法）
Event e; // 不再需要模板参数
3. TLOAD/TSTORE 语法统一
// ❌ v0.9.x（旧语法）
TLOAD(tile, input.data(), size);
// ✅ v1.0.x（新语法）
TLOAD(tile, GlobalTensor(input.data(), size));
4. 指令重命名
| v0.9.x | v1.0.x | 说明 |
|---|---|---|
TADD_S |
TADDS |
标量加法 |
TMUL_S |
TMULS |
标量乘法 |
TMATMUL_ACCUM |
TMATMUL_ACC |
矩阵乘累加 |
迁移步骤¶
步骤1：更新依赖
# 更新 PTO-ISA
git pull origin main
git checkout v1.0.0
# 更新 CANN
# 确保 CANN >= 8.5.0
步骤2：修改代码
# 使用自动迁移脚本
python scripts/migrate_v0_to_v1.py --input src/ --output src_v1/
# 或手动修改
# 1. 替换 Tile 构造函数
# 2. 移除 Event 模板参数
# 3. 更新 TLOAD/TSTORE 调用
# 4. 重命名指令
步骤3：重新编译
# 清理旧构建
rm -rf build/
# 重新配置和编译
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
步骤4：测试验证
# 运行测试
ctest --test-dir build --output-on-failure
# 验证数值正确性
./build/my_operator --verify
# 性能基准测试
./build/my_operator --benchmark
5.2 兼容性检查清单¶
迁移完成后，请检查以下项目：
- [ ] 所有 Tile 构造函数已更新
- [ ] Event 模板参数已移除
- [ ] TLOAD/TSTORE 使用 GlobalTensor
- [ ] 指令名称已更新
- [ ] 编译无警告
- [ ] 所有测试通过
- [ ] 数值正确性验证通过
- [ ] 性能无明显下降
6. 已知问题¶
v1.0.0 已知问题¶
问题1：A5 平台部分算子性能未达最优 - 影响：部分算子在 A5 上性能低于预期 - 状态：计划在 v1.1.0 修复 - 临时方案：使用 A3 平台或手动优化
问题2：Windows 平台编译警告 - 影响：MSVC 编译时产生警告（不影响功能） - 状态：计划在 v1.0.1 修复 - 临时方案：忽略警告或使用 MinGW
问题3：PyTorch 2.2+ 兼容性 - 影响：PyTorch 2.2+ 部分 API 变更 - 状态：计划在 v1.0.1 修复 - 临时方案：使用 PyTorch 2.0-2.1
7. 兼容性测试¶
7.1 测试矩阵¶
我们在以下配置上进行了完整测试：
| 平台 | OS | 编译器 | CANN | 状态 |
|---|---|---|---|---|
| A2 | Ubuntu 20.04 | GCC 13 | 8.5.0 | ✅ 通过 |
| A3 | Ubuntu 22.04 | GCC 13 | 8.5.0 | ✅ 通过 |
| A5 | openEuler 20.03 | GCC 13 | 8.5.0 | ✅ 通过 |
| CPU | Ubuntu 22.04 | Clang 15 | - | ✅ 通过 |
7.2 运行兼容性测试¶
# 克隆仓库
git clone https://github.com/your-org/pto-isa.git
cd pto-isa
# 运行兼容性测试套件
python scripts/test_compatibility.py \
--platform A3 \
--cann-version 8.5.0 \
--compiler gcc-13
# 查看测试报告
cat compatibility_report.txt