Add tilelang_maca_install_guide.md

tilelang_maca_install_guide.md

@@ -0,0 +1,97 @@
+# TileLang MACA 安装与验证指南
+
+> 环境：MetaX C500 / MACA 3.7.2.1 / Python 3.12 / Conda
+>
+> 源码：`/data/tilelang-metax`（dev 分支）
+
+---
+
+## 1. 前置条件
+
+- MACA 已安装在 `/opt/maca`（包含 `libmcruntime.so` 等运行时库）
+- Python 3.12 + Conda 环境
+
+---
+
+## 2. 编译安装 tilelang（启用 MACA 后端）
+
+```bash
+cd /data/tilelang-metax
+rm -rf build
+export USE_MACA=ON
+pip install -e . -v
+```
+
+编译产物位于 `build/lib/`，包含：
+- `libtilelang.so` — 注册 maca target kind
+- `libtvm.so` — TVM 运行时
+
+---
+
+## 3. 修复 `.pth` 文件（关键步骤）
+
+tilelang 的 editable install 生成的 `.pth` 文件缺少 `tvm` Python 包的正确路径。
+
+**文件位置**：`/opt/conda/lib/python3.12/site-packages/_tilelang_editable.pth`
+
+**修改**：将其中一行 `/data/tilelang-metax/3rdparty/tvm` 改为：
+
+```
+/data/tilelang-metax/3rdparty/tvm/python
+```
+
+修改后的文件内容应为：
+
+```
+import _tilelang_editable
+/data/tilelang-metax
+/data/tilelang-metax
+/data/tilelang-metax/3rdparty/tvm/python
+/data/tilelang-metax/3rdparty/tvm
+/data/tilelang-metax/3rdparty/tvm
+/data/tilelang-metax/3rdparty/tvm/3rdparty/dmlc-core
+/data/tilelang-metax/3rdparty/tvm
+/data/tilelang-metax/3rdparty/cutlass
+/data/tilelang-metax/3rdparty/cutlass
+/data/tilelang-metax/3rdparty/composable_kernel
+/data/tilelang-metax/3rdparty/composable_kernel
+```
+
+---
+
+## 4. 验证
+
+### 4.1 基础导入
+
+```bash
+python -c "import tilelang; print(tilelang.__version__)"
+# 预期输出：0.1.9+maca.gitee6db437
+```
+
+### 4.2 MACA Target 验证
+
+**必须先 `import tilelang`**，因为它会加载 `libtilelang.so`（注册 maca target）：
+
+```bash
+python -c "
+import tilelang
+from tvm.target import Target
+t = Target('maca')
+print(t)
+"
+# 预期输出：
+# maca -keys=maca,gpu -max_local_memory_per_block=4095 -max_num_threads=1024
+#   -max_shared_memory_per_block=65536 -max_threads_per_block=1024
+#   -mcpu=xcore1000 -mtriple=mxc-metax-macahca -thread_warp_size=64
+```
+
+---
+
+## 5. 常见问题
+
+| 问题 | 原因 | 解决 |
+|------|------|------|
+| `ModuleNotFoundError: No module named 'tvm'` | `.pth` 文件缺少 `3rdparty/tvm/python` 路径 | 修改 `.pth` 文件（见步骤 3） |
+| `Target kind "maca" is not defined` | 未先 `import tilelang`，`libtilelang.so` 未加载 | 先 `import tilelang` 再使用 `Target('maca')` |
+| `Target kind "maca" is not defined`（已 import tilelang） | 编译时未启用 MACA | 用 `USE_MACA=ON` 重新编译（见步骤 2） |
+| 编译报 `ninja: error: Makefile` | `build/` 目录残留旧 Makefile | `rm -rf build` 后重新编译 |