=========================================
Triton-distributed-ascend 文档
=========================================

Triton-distributed-ascend 是一个由 Triton 语言扩展而来、面向昇腾 AI 处理器优化的分布式
计算框架。它在昇腾 NPU 上实现高效的分布式计算，提供通信原语以及计算通信掩盖优化，
面向大规模分布式训练与推理场景。

本项目基于 MLIR 的多层抽象能力，将使用 Triton 编写的分布式算子映射到昇腾 AI 处理器上，
并暴露细粒度接口用于控制片上内存与流水线同步。

快速入门
--------

建议按以下顺序阅读：

- :doc:`getting-started/installation` —— 硬件与软件前置要求、CANN 安装以及
  Python 依赖。
- :doc:`getting-started/build` —— 从源码构建 Triton-distributed-ascend、
  AscendNPU-IR 与 shmem。
- :doc:`getting-started/quick-start` —— 运行第一个分布式 kernel 并验证安装结果。

关于版本策略、分支生命周期与兼容性矩阵，请参阅 :doc:`getting-started/release_note`。

主要特性
--------

- **分布式通信原语** —— AllReduce、AllGather、ReduceScatter、All2All。
- **计算通信掩盖** —— 通过重叠执行提升吞吐量。
- **基于 AscendNPU IR 的编译优化** —— 直接利用昇腾硬件特性的优化。
- **友好的 Python 接口** —— 简洁的 Python API，可集成到现有深度学习框架中。

架构
----

- :doc:`architecture` —— 分布式架构设计、术语表、编译流程与通信引擎详解。

API 参考
--------

API 文档涵盖六个主要部分：

- :doc:`api/triton_dist_semantics` —— 设计理念、语义模型与以块为中心的
  计算通信掩盖编程模式。
- :doc:`api/triton_dist_language` —— 用于 Triton kernel 的分布式操作（``wait``、
  ``consume_token``、``rank``、``num_ranks``、``symm_at``、``notify``、``extern_call``）。
- :doc:`api/shmem_device` —— 在 kernel 内使用的设备端 ACLSHMEM API（RMA 操作、
  信号、屏障与同步）。
- :doc:`api/shmem_host` —— 用于初始化、内存管理与主机发起通信的主机端 ACLSHMEM API。
- :doc:`api/helper` —— 用于 GEMM 与通信 tile 调度的 Swizzle 辅助接口。
- :doc:`api/autotune_api` —— 用于多设备 kernel 调优的分布式 autotune API。

开发者指南
----------

- :doc:`developer-guide/kernel_debugging` —— 提取 IR、打印编译器 pass 以及
  使用 ``bishengir-compile`` 标志调试同步问题。
- :doc:`developer-guide/environment_variable` —— 用于调试和优化的环境变量与编译器选项。
- :doc:`developer-guide/kernel-debugging/precision` —— 多卡融合算子精度验证。
- :doc:`developer-guide/kernel-development/td_kernel_dev` —— 使用分布式 kernel
  进行单算子开发。
- :doc:`developer-guide/kernel-performance/performance_optimization` —— 性能优化
  技术与最佳实践。
- :doc:`developer-guide/kernel-performance/operator_performance_testing_and_tuning_autotune_guide` ——
  算子性能测试与 autotune 功能使用指南。
- :doc:`developer-guide/kernel-performance/profiling` —— Kernel 性能分析指南。

教程
----

- :doc:`tutorial/allgather_gemm` —— AllGather+GEMM 融合优化教程。
- :doc:`tutorial/autotune_optimization_example` —— Autotune 示例与优化实践。
- :doc:`tutorial/reverse_all2all` —— 用于 MoE 分布式 kernel 的反向 All2All。

常见问题
--------

- :doc:`FAQ` —— 常见问题与故障排除。

.. toctree::
   :maxdepth: 1
   :caption: 快速入门
   :hidden:

   getting-started/installation
   getting-started/build
   getting-started/quick-start
   getting-started/release_note

.. toctree::
   :maxdepth: 1
   :caption: 架构
   :hidden:

   architecture

.. toctree::
   :maxdepth: 1
   :caption: API 参考
   :hidden:

   api/triton_dist_semantics
   api/triton_dist_language
   api/shmem_device
   api/shmem_host
   api/helper
   api/autotune_api

.. toctree::
   :maxdepth: 1
   :caption: 开发者指南
   :hidden:

   developer-guide/kernel_debugging
   developer-guide/environment_variable
   developer-guide/kernel-debugging/precision
   developer-guide/kernel-development/td_kernel_dev
   developer-guide/kernel-performance/performance_optimization
   developer-guide/kernel-performance/operator_performance_testing_and_tuning_autotune_guide
   developer-guide/kernel-performance/profiling

.. toctree::
   :maxdepth: 1
   :caption: 教程
   :hidden:

   tutorial/allgather_gemm
   tutorial/autotune_optimization_example
   tutorial/reverse_all2all

.. toctree::
   :maxdepth: 1
   :caption: 常见问题
   :hidden:

   FAQ