[Docs] 增加 DSL 框架对接协议文档：上层如何对接 TileLang/DSL 生成 VPTO IR

[Zhendong404]

Background

当前仓内已经有一部分与 TileLang / TileLib 扩展路径相关的设计说明，例如：

• docs/designs/ptoas-tileop-expand-design.md
• docs/designs/tilelang-st-framework.md
• open issue #114 [Docs] Update user guide of TileLang DSL

但这些信息目前更偏向 PTOAS 内部实现或 ST 使用说明，缺少一份面向“上层框架 / DSL 框架集成方”的协议文档，来回答一个更基础的问题：

上层框架要如何组织输入、调用 DSL / TileLib，并稳定地产生 VPTO IR？

现在这部分边界主要散落在设计文档和 ExpandTileOp 实现里。例如：

• ExpandTileOp 当前通过 python -m tilelang_dsl.expand_helper --target <arch> --op pto.<op> --operand-specs <JSON> [--context-attrs <JSON>] 调 DSL helper 做模板选择和实例化
• operand-specs 里区分 tile / view / scalar 三类操作数，不同 kind 带的字段不同
• DSL 输出的 MLIR 函数还需要满足 pto.tilelang.instance、参数类型、intrinsic 使用方式等约束，才能被 PTOAS 后续 pass 正确接住

这些实际上已经构成了“接口协议”，但目前没有一份正式文档把协议边界固定下来。

Problem

缺少协议文档会带来几个具体问题：

• 上层框架在接 DSL 时，不清楚应该把哪些信息视为输入契约，哪些只是 PTOAS 当前内部实现细节
• 设计文档里有流程说明，但没有沉淀成一个稳定的 integration contract，后续改实现时容易把集成方一起带崩
• 目前很难回答“是框架应该传这个字段，还是 PTOAS 内部推导即可”这类边界问题
• DSL / PTOAS / 框架三方在 cache key、模板选择、动态 view 约束、输出函数要求上的理解容易不一致

Suggestion

建议补一份专门的集成协议文档，建议主题是：

DSL integration protocol: framework -> TileLang DSL / TileLib -> VPTO IR

建议至少覆盖下面几部分：

1. 对接目标与分层边界

明确谁负责什么：

• 上层框架负责提供哪些 op / operand / context 信息
• DSL / TileLib 负责哪些模板匹配与实例化责任
• PTOAS 负责哪些 IR 接入、校验、inline / fold / lowering 责任

2. 输入协议

明确 expand_helper / DSL 侧看到的最小输入集合：

• target
• op
• operand-specs
• context-attrs

并说明 operand-specs 中三类操作数的字段语义：

• tile: dtype / shape / valid_shape / memory_space / config
• view: dtype / shape / strides / memory_space
• scalar: dtype

要明确哪些字段：

• 参与模板实例特化
• 只参与约束检查
• 属于调用侧必须提供
• 可以由 PTOAS 推导

3. Specialization / cache key 边界

把当前实现语义写清楚，而不是只留在代码里：

• Tile 操作数哪些字段进入 specialization key
• View 为什么当前只按 dtype 特化，而 shape/strides/memory_space 只用于约束检查
• valid_shape 当前是否属于实例边界
• context_attrs 如何参与模板选择 / 命名 / cache

4. 输出协议

明确 DSL 产出的 MLIR / VPTO authoring IR 需要满足哪些约束，PTOAS 才能继续处理：

• 入口函数和 helper 函数的组织方式
• pto.tilelang.instance 属性要求
• 允许的参数类型
• 允许使用的 intrinsic / op 子集
• tile_buf / partition_tensor_view 的取数方式
• View 参数桥接与后续 fold 的预期

5. 错误诊断协议

建议说明当模板匹配失败、约束不满足、输出 IR 非法时，错误应该挂在哪一层，以及调用侧应该拿到什么结构化信息。

6. 典型端到端例子

最好补 1~2 个 concrete case：

• pto.tadd 这类纯 tile -> tile 的例子
• pto.tload / pto.tstore 这类包含 view 的例子

从上层传入的逻辑信息一路展开到 DSL 输入 JSON，再到输出的实例化函数结构。

Expected outcome

• 能有一份可以给框架 / DSL 集成方直接参考的协议文档，而不是只靠读 PTOAS 源码和零散设计文档拼装
• 后续 DSL / PTOAS 迭代时，集成边界有文档可对齐
• [Docs] Update user guide of TileLang DSL #114 可以继续聚焦一般 DSL 用户指南；这里单独补齐“框架如何对接生成 VPTO IR”的协议层文档

Additional context

当前仓内已经有足够多的现成信息可沉淀成该文档，主要来源包括：

• docs/designs/ptoas-tileop-expand-design.md 中 3.2 节关于 ExpandTileOp、SpecKey、operand-specs、模板实例化和输出函数约束的说明
• lib/PTO/Transforms/ExpandTileOp.cpp 中 buildOperandSpecsJson() / buildContextAttrsJson() / invokeTilelangDSL() 的实际实现
• docs/designs/tilelang-st-framework.md 中当前 .pto -> ptoas -> VPTO/LLVM 端到端执行链路