ptoas (PTO Assembler & Optimizer)

1. 项目简介 (Introduction)

ptoas (ptoas) 是一个基于 LinxISA 受控 LLVM/MLIR （ISA release linxisa-v0.58.3，LLVM commit b7c83f68bf84125e696a70bec4b665c70a3b584d）构建的专用编译器工具链，专为 PTO Bytecode (Programming Tiling Operator Bytecode) 设计。

作为连接上层 AI 框架与底层各类NPU/GPGPU/CPU硬件，ptoas 采用 Out-of-Tree 架构构建，提供了完整的 C++ 与 Python 接口，主要职责包括：

IR 解析与验证：解析 .pto 输入文件，验证 PTO Dialect 操作（Ops）的语义正确性。
编译优化 (Passes)：执行针对达芬奇架构（Da Vinci Architecture）的特定优化 Pass，如算子融合、自动同步插入策略等。
代码生成 (Lowering)：支持将 PTO IR 下降（Lowering）到 EmitC / Linalg Dialect，最终生成可调用 pto-isa C++ 库的代码。
Python 绑定 (Python Bindings)：提供无缝集成的 Python 模块。通过与 MLIR Core 绑定集成，支持 PyPTO、TileLang、CuTile 等框架在 Python 端直接构建、操作和编译 PTO Bytecode。

2. 目录结构 (Directory Structure)

PTOAS/
├── include/
│   └── PTO/               # PTO Dialect 的头文件与 TableGen 定义 (.td)
├── lib/
│   ├── PTO/               # Dialect 核心实现 (IR) 与 Pass 逻辑 (Transforms)
│   ├── CAPI/              # C 语言接口暴露
│   └── Bindings/Python/   # Python Binding C++ 实现 (Pybind11)
├── python/                # Python 模块构建脚本与辅助代码
├── test/
│   └── samples/           # 测试用例
├── tools/
│   ├── ptoas/             # ptoas 命令行工具入口 (Output: ptoas)
│   └── ptobc/             # ptobc 命令行工具入口 (Output: ptobc)
└── CMakeLists.txt         # 顶级构建配置

3. 构建指南 (Build Instructions)

⚠️ 重要提示：本项目严格依赖 LinxISA LLVM b7c83f68bf84125e696a70bec4b665c70a3b584d。linxisa-v0.58.3 是 ISA release tag，不是 PTOAS 产品版本；不要替换为同名上游 LLVM tag。

3.0 环境变量配置 (Configuration)

为了简化构建流程，请首先根据您的实际环境修改并运行以下命令。后续步骤将直接引用这些变量。

# ================= 配置区域 (请修改这里) =================
# 设置您的工作根目录 (建议创建一个专门的目录存放 LLVM 和 PTOAS)
export WORKSPACE_DIR=$HOME/llvm-workspace

# LLVM 源码与构建路径
export LLVM_SOURCE_DIR=$WORKSPACE_DIR/llvm-project
export LLVM_BUILD_DIR=$LLVM_SOURCE_DIR/build-shared

# PTOAS 源码与安装路径
export PTO_SOURCE_DIR=$WORKSPACE_DIR/PTOAS
export PTO_INSTALL_DIR=$PTO_SOURCE_DIR/install
# =======================================================

# 创建工作目录
mkdir -p $WORKSPACE_DIR

3.1 环境准备 (Prerequisites)

OS: Linux (Ubuntu 20.04+ 推荐)
Compiler: GCC >= 9 或 Clang (支持 C++17)
Build System: CMake >= 3.20, Ninja
Python: 3.8+
Python Packages: nanobind, numpy

python3 -m pip install nanobind numpy

3.2 第一步：构建 LLVM/MLIR (Dependency)

我们需要下载受控 LinxISA LLVM 源码，切换到上文的精确 SHA，并以 动态库 (Shared Libs) 模式编译，以确保 Python Binding 的正确链接。

# 1. 下载 LLVM 源码
cd $WORKSPACE_DIR
git clone https://github.com/LinxISA/llvm-project.git
cd $LLVM_SOURCE_DIR
git checkout --detach b7c83f68bf84125e696a70bec4b665c70a3b584d

# 2. 配置 CMake (构建动态库并启用 Python 绑定)
cmake -G Ninja -S llvm -B $LLVM_BUILD_DIR \
    -DLLVM_ENABLE_PROJECTS="mlir;clang" \
    -DBUILD_SHARED_LIBS=ON \
    -DMLIR_ENABLE_BINDINGS_PYTHON=ON \
    -DPython3_EXECUTABLE=$(which python3) \
    -DCMAKE_BUILD_TYPE=Release \
    -DLLVM_TARGETS_TO_BUILD="host"

# 3. 编译 LLVM (这一步耗时较长)
ninja -C $LLVM_BUILD_DIR

3.3 第二步：构建 PTOAS (Out-of-Tree)

下载 PTOAS 源码并基于刚刚编译好的受控 LinxISA LLVM 进行构建。

# 1. 下载 PTOAS 源码
cd $WORKSPACE_DIR
git clone https://gitcode.com/cann/pto-as.git PTOAS
cd $PTO_SOURCE_DIR

# 2. 获取 nanobind 的 CMake 路径
export NANOBIND_CMAKE_DIR=$(python3 -m nanobind --cmake_dir)

# 3. 配置 CMake
# 注意：此处直接使用了 3.0 章节中定义的变量，无需手动修改
cmake -G Ninja \
    -S . \
    -B build \
    -DLLVM_DIR=$LLVM_BUILD_DIR/lib/cmake/llvm \
    -DMLIR_DIR=$LLVM_BUILD_DIR/lib/cmake/mlir \
    -DPython3_EXECUTABLE=$(which python3) \
    -DPython_EXECUTABLE=$(which python3) \
    -DPython3_FIND_STRATEGY=LOCATION \
    -Dnanobind_DIR="${NANOBIND_CMAKE_DIR}" \
    -DMLIR_ENABLE_BINDINGS_PYTHON=ON \
    -DMLIR_PYTHON_PACKAGE_DIR=$LLVM_BUILD_DIR/tools/mlir/python_packages/mlir_core \
    -DPTOAS_ENABLE_WERROR=OFF \
    -DCMAKE_INSTALL_PREFIX="$PTO_INSTALL_DIR"

# 4. 编译并安装
ninja -C build
ninja -C build install

# 5. 检查构建产物
# build 输出（便于本地开发/调试）
$PTO_SOURCE_DIR/build/python/
├── mlir
│   ├── _mlir_libs
│   │   └── _pto.cpython-*.so
│   └── dialects
│       ├── pto.py
│       └── _pto_ops_gen.py

# install 输出（Python 方言文件）
$PTO_INSTALL_DIR/
└── mlir
    └── dialects
        ├── pto.py
        └── _pto_ops_gen.py

# 安装到 MLIR Python 包中的原生扩展
$LLVM_BUILD_DIR/tools/mlir/python_packages/mlir_core/
└── mlir
    └── _mlir_libs
        └── _pto.cpython-*.so

# CLI 工具
$PTO_SOURCE_DIR/build/tools/ptoas/ptoas
$PTO_SOURCE_DIR/build/tools/ptobc/ptobc

4. 运行环境配置 (Runtime Environment)

构建完成后，需要配置环境变量以便系统能找到 Python 包和动态库。您可以将以下命令添加到 .bashrc 或启动脚本中。

# --- 运行时变量配置 (基于之前定义的路径) ---

# 1. Python Path: 拼接 MLIR Core 和 PTO Core
#    这样在 python 中 import mlir.dialects.pto 时能正确找到
export MLIR_PYTHON_ROOT=$LLVM_BUILD_DIR/tools/mlir/python_packages/mlir_core
export PTO_PYTHON_ROOT=$PTO_INSTALL_DIR/
export PYTHONPATH=$MLIR_PYTHON_ROOT:$PTO_PYTHON_ROOT:$PYTHONPATH

# 2. Library Path: 确保能加载 LLVM 和 PTO 的动态库
export LD_LIBRARY_PATH=$LLVM_BUILD_DIR/lib:$PTO_INSTALL_DIR/lib:$LD_LIBRARY_PATH

# 3. PATH: 将 ptoas / ptobc 添加到命令行路径
export PATH=$PTO_SOURCE_DIR/build/tools/ptoas:$PTO_SOURCE_DIR/build/tools/ptobc:$PATH

5. 使用方法 (Usage)

5.1 命令行工具 (CLI)

# 解析并打印 PTO IR
ptoas test/lit/pto/empty_func.pto

# 运行 AutoSyncInsert Pass
ptoas test/lit/pto/empty_func.pto --enable-insert-sync -o outputfile.cpp

# 指定目标硬件架构（A3 / A5）
ptoas test/lit/pto/empty_func.pto --pto-arch=a5 -o outputfile.cpp

# LinxISA v0.58 必须使用独立 Linx target，不得借用 A3/A5 target
ptoas test/lit/pto/v058_linx_target.pto --pto-arch=linx -o outputfile.cpp

# 指定构建 Level（level3 会禁用 PlanMemory/InsertSync）
ptoas test/lit/pto/empty_func.pto --pto-level=level3 -o outputfile.cpp

# 查看 PTOAS 产品版本及其 PTO ISA contract 版本
ptoas --version

ptoas --version 中的 0.41 是 PTOAS 产品版本；括号中的 PTO ISA 0.58.3 是独立的 ISA contract 版本。linx target 对齐受管的 Linx-TileOP-API：生成代码包含 jcore/template_asm.hpp，只接受 v0.58 公共 PTO 操作目录，并在 lowering 前拒绝仅属于 A3/A5 方言面的操作。

5.2 Python 接口 (Python API)

配置好环境变量后，PTO Dialect 将作为 mlir.dialects 的一部分被加载。

from mlir.ir import Context, Module, Location
# [关键] 从 mlir.dialects 导入 pto，这是 Out-of-tree 绑定的标准用法
from mlir.dialects import pto

with Context() as ctx, Location.unknown():
    pto.register_dialect(ctx, load=True)
    module = Module.create()
    print("PTO Dialect registered successfully!")

5.3 运行测试

# 运行python binding 测试
cd $PTO_SOURCE_DIR/test/samples/MatMul/
python3 ./tmatmulk.py > ./tmatmulk.pto

# 运行ptoas 测试
$PTO_SOURCE_DIR/build/tools/ptoas/ptoas ./tmatmulk.pto -o ./tmatmulk.cpp

Linx MX 的真实 C++ 集成门禁默认不启用，因为它必须同时绑定精确的 Linx LLVM 构建、musl+libc++ sysroot 和 Linx-TileOP-API checkout。该门禁不会使用 host shim 或替换 jcore/template_asm.hpp 的 stub。依赖准备好后，使用已审核并合并的 commit/tree 配置独立构建目录：

cmake -G Ninja -S . -B build-linx-integration \
  -DLLVM_DIR=$LLVM_BUILD_DIR/lib/cmake/llvm \
  -DMLIR_DIR=$LLVM_BUILD_DIR/lib/cmake/mlir \
  -DPTOAS_ENABLE_LINX_TILEOP_INTEGRATION=ON \
  -DPTOAS_LINX_LLVM_BUILD=$LINX_LLVM_BUILD \
  -DPTOAS_LINX_SYSROOT=$LINX_SYSROOT \
  -DPTOAS_LINX_TILEOP_ROOT=$TILEOP_ROOT \
  -DPTOAS_EXPECTED_LLVM_COMMIT=b7c83f68bf84125e696a70bec4b665c70a3b584d \
  -DPTOAS_EXPECTED_LLVM_TREE=c11bd80c7dd34ed4438de1da6bde0a01eae8c76d \
  -DPTOAS_EXPECTED_TILEOP_COMMIT=bd1ecca97ca47da0edc462c1ce19749c6940780e \
  -DPTOAS_EXPECTED_TILEOP_TREE=854c463c21f9b758186b718105f4b035019cdd30
ninja -C build-linx-integration ptoas
ctest --test-dir build-linx-integration \
  -L linx-target-integration --output-on-failure

门禁先核对两个 checkout 的 commit/tree，再由真实 Linx clang++ 和指定 sysroot 对 PTOAS 生成的 TMATMUL/TGEMV base、ACC、BIAS 的 zero/A-only/ B-only/both 四种形式分别执行 -fsyntax-only 和目标对象编译。缺少路径、 identity 不匹配或真实 TileOP 签名/约束不接受生成代码时，门禁都会失败。门禁最后还运行 TileOP 的 phase-C link smoke，并用 verify_pto_identity.py 核对每个 Linx ELF 中唯一且精确的 PTO 0.58.3 identity note。

5.4 上板验证

该流程用于将 test/samples 下生成的 .cpp（ptoas 输出）自动生成 NPU 验证用例，并在 NPU 上运行。下面示例直接复用 5.3 里生成的 MatMul/tmatmulk.cpp。

只想在无卡机器上做 host-side compile-only，请先看 docs/no_npu_compile_only_guide_zh.md。

# 1) 生成 npu_validation 测试目录（会在当前 sample 目录下创建 npu_validation/）
# A2/A3 示例：
python3 test/npu_validation/scripts/generate_testcase.py \
  --input test/samples/MatMul/tmatmulk.cpp \
  --run-mode npu \
  --soc-version Ascend910B1

# A5 示例:
python3 test/npu_validation/scripts/generate_testcase.py \
  --input test/samples/MatMul/tmatmulk.cpp \
  --run-mode npu \
  --soc-version Ascend950

# 2) 运行验证（run.sh 无需额外参数）
test/samples/MatMul/npu_validation/tmatmulk/run.sh

说明：

test/samples/MatMul/npu_validation/tmatmulk/ 下会生成 tmatmulk_kernel.cpp / main.cpp / golden.py / compare.py / run.sh / CMakeLists.txt
golden.py 默认生成随机输入，输出默认全零（只保证输入/输出数量、shape、datatype 与 kernel 参数一致）
compare.py 负责对比 golden*.bin 与 output*.bin，不一致时会报错

Name		Name	Last commit message	Last commit date
.claude		.claude
.codex		.codex
.github		.github
cmake		cmake
docker		docker
docs		docs
include		include
lib		lib
python		python
test		test
tools		tools
.dockerignore		.dockerignore
.gitignore		.gitignore
CMakeLists.txt		CMakeLists.txt
README.md		README.md
ReleaseNotes.md		ReleaseNotes.md
install.sh		install.sh
pyproject.toml		pyproject.toml

Navigation Menu

Uh oh!

Repository files navigation

ptoas (PTO Assembler & Optimizer)

1. 项目简介 (Introduction)

2. 目录结构 (Directory Structure)

3. 构建指南 (Build Instructions)

3.0 环境变量配置 (Configuration)

3.1 环境准备 (Prerequisites)

3.2 第一步：构建 LLVM/MLIR (Dependency)

3.3 第二步：构建 PTOAS (Out-of-Tree)

4. 运行环境配置 (Runtime Environment)

5. 使用方法 (Usage)

5.1 命令行工具 (CLI)

5.2 Python 接口 (Python API)

5.3 运行测试

5.4 上板验证

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

ptoas (PTO Assembler & Optimizer)

1. 项目简介 (Introduction)

2. 目录结构 (Directory Structure)

3. 构建指南 (Build Instructions)

3.0 环境变量配置 (Configuration)

3.1 环境准备 (Prerequisites)

3.2 第一步：构建 LLVM/MLIR (Dependency)

3.3 第二步：构建 PTOAS (Out-of-Tree)

4. 运行环境配置 (Runtime Environment)

5. 使用方法 (Usage)

5.1 命令行工具 (CLI)

5.2 Python 接口 (Python API)

5.3 运行测试

5.4 上板验证

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages