已关闭
[Requirement|需求建议]: 【资料】SIMT API 手册头文件描述与 SIMD API 对齐 #1626
baixueyan创建于  9月3日关闭于  9月3日
baixueyan成员
9月3日 创建

Thanks for sending an requirement! Please fill in the following template to help quickly solve your problem.

Background(背景信息)

SIMD API 参考手册的接口页已统一把头文件信息前移到 ## 功能说明 首行,形式为「头文件路径为:"..."。」,## 调用示例 的每个 cpp 代码块也在首行给出 #include。SIMT API 参考手册仍是旧写法:头文件信息独占一个 ## 需要包含的头文件 二级段落,段落内重复一遍头文件名再列 #include 语句;## 调用示例 的 cpp 代码块直接以 kernel 函数定义开头,不带任何 #include。两套手册同属一份资料,读者在 SIMD 与 SIMT 之间切换时看到的信息位置不一致,且 SIMT 示例代码不自包含,复制后无法直接编译,只能回到上一节去找头文件。

本需求把 SIMT API 手册的头文件描述改成与 SIMD 一致的形式:删掉独立段落、头文件路径前移至功能说明首行、各调用示例代码块首行补齐 #include,示例代码本身不改。

Origin(信息来源)

SIMT 资料需求。

Benefit / Necessity (价值/作用)

  • 消除 SIMD 与 SIMT 两套手册在头文件信息位置上的差异,读者跨手册查阅时无需重新适应版式。
  • 调用示例自包含,读者复制代码块即可编译,不必回退到上一节查头文件。
  • 每页少一个二级段落,接口页目录更短,功能说明与头文件信息集中在同一处。

Design(设计方案)

改写形式

以 docs/zh/api/SIMT-API/Warp_functions/Warp_vote_functions/asc_all.md 为例。

修改前:

## 功能说明

判断是否所有活跃线程的输入均不为0。

## 需要包含的头文件

使用该接口需要包含`simt_api/device_warp_functions.h`头文件。

```cpp
#include "simt_api/device_warp_functions.h"
```

## 调用示例

-   SIMT编程场景:

    ```cpp
    __global__ __launch_bounds__(1024) void KernelAll(
        const int32_t* input1, const int32_t* input2, int32_t* equal_flags, uint64_t total_length)
    ```

修改后:

## 功能说明

头文件路径为:`"simt_api/device_warp_functions.h"`。

判断是否所有活跃线程的输入均不为0。

## 调用示例

-   SIMT编程场景:

    ```cpp
    #include "simt_api/device_warp_functions.h"

    __global__ __launch_bounds__(1024) void KernelAll(
        const int32_t* input1, const int32_t* input2, int32_t* equal_flags, uint64_t total_length)
    ```

整改细则

  1. 删除 ## 需要包含的头文件 整段,头文件路径写成 ## 功能说明 的首行,反引号包裹路径,空行后接原功能描述正文。
  2. ## 调用示例 内每个 cpp 代码块首行补 #include,空行后接原代码;SIMT 编程场景与 SIMD/SIMT 混合编程场景各自独立,同一场景下有多个代码块(如整型数学函数、shfl 类接口的多组示例)时逐块补。
  3. 补的头文件与本页功能说明首行一致;多头文件页在每个代码块补该块实际用到的头文件,原文「完整样例请参考 xxx」的内容和位置不变。
  4. 保持代码块原有缩进:挂在列表项下的代码块整体缩进 4 空格,#include 行同缩进;未挂列表项的代码块(如地址空间谓词函数、fp8/half/bfloat16 饱和转换类页面)不缩进。
  5. 示例正文已说明需另外包含其他头文件时(如 lanemask 类页面引用 asc_shfl),该头文件一并写入 #include 列表。
  6. 非 cpp 代码块不改:输出结果块(无语言标注)、## 函数原型 的原型代码块保持原样。

覆盖范围

  • 覆盖 docs/zh/api/SIMT-API/ 下的数学函数 / Warp 函数 / 原子操作 / 访存函数 / 地址空间转换函数 / 地址空间谓词函数 / 同步与内存栅栏,共 683 个接口页、1322 个调用示例 cpp 代码块。

交付件

683 个接口页的正文修改(删段落 + 前移 + 示例补 #include)。

出口标准

  • 版本:主线。
  • 验证方式:脚本核对 + 人工检视。核对项为 docs/zh/api/SIMT-API/ 下不再有 ## 需要包含的头文件 段落;683 页功能说明首行均为「头文件路径为:...。」;1322 个 cpp 代码块首行均为 #include 且与本页功能说明一致,多头文件页 17 个数量不变;代码块缩进与围栏层级不变,示例代码零改动。
likedislike
Bbaixueyan成员
9月3日 添加了label:requirement
baixueyan成员
9月3日 评论:

你好,感谢指出问题,当前SIMT API 手册头文件描述和SIMD API 手册中头文件描述确实存在差异,我们会尽快修复。

likedislike
CANN-robotCANN-robot成员
9月3日 关闭了 issue
Bbaixueyan成员
9月4日 关联了pull request:docs: SIMT协作组头文件描述与SIMD对齐并为调用示例补齐#include
Bbaixueyan成员
9月4日 添加了label:resolved