已合并
docs: 优化C API调用示例的同步、VF循环及变量命名 #6846
GRJ_XIDUO创建于 16 天前
docs: 优化C API调用示例的同步、VF循环及变量命名 #6846
已合并
Pull Request已成功合入, 合并人@CANN-robot
（感谢 GRJ_XIDUO 的贡献）
atomgit-bot
16 天前 评论：
16 天前 评论：
变更摘要
本 PR 为纯文档更新，集中优化 C API 调用示例的同步正确性、VF 循环完整性与变量命名，涉及 docs/zh/api/SIMD-API 下大量接口文档及 dual_issue_optimization.md 指南。核心是把易用性同步接口 asc_sync_mte2、asc_sync_mte3、asc_sync_vec 替换为显式的流水线同步接口 asc_sync_notify/asc_sync_wait，在 Reg 计算示例中以 asc_lock/asc_unlock 串联数据搬入、计算与搬出，并补充 VF 循环、地址偏移和尾块掩码处理以覆盖非 VL 整数倍长度。
主要改动
- 同步接口替换为显式流水线同步: 文档示例中
asc_sync_mte2(0)、asc_sync_mte3(0)、asc_sync_vec(0)被改为asc_sync_notify(PIPE_MTE2, PIPE_MTE3, EVENT_ID0)+asc_sync_wait(...)或asc_sync_pipe(PIPE_ALL)形式，明确展示生产者与消费者依赖。 - Reg 计算示例引入
asc_lock/asc_unlock: 通过统一MUTEX_ID串联搬入（PIPE_MTE2）、计算（PIPE_V）与搬出（PIPE_MTE3）阶段，替代原asc_sync_notify/asc_sync_wait配对，并强调 lock/unlock 成对。 - 补充 VF 循环与尾块掩码处理: 示例数据长度改为非 VL 整数倍（如 517、260、133 等），引入
ELEMENTS_PER_REGISTER、REPEAT_COUNT、PADDED_ELEMENT_COUNT等常量，循环内使用asc_update_mask_b8/b16/b32(remaining_length)处理剩余元素，并为填充区补零/哨兵值。 - 类型转换示例补充写后读同步与复用 UB 处理: 在复用同一 UB 的多寄存器场景插入
asc_mem_bar(VST_VLD)并加注释说明「不同目的寄存器复用同一段 UB，等前一次写入完成后再读取」，同时修正asc_bfloat162half、asc_float2half等示例的 golden 校验范围。 - 变量命名与文档说明修正: 统一
ELEMENT_COUNT/TOTAL_LENGTH/REMAINING_LENGTH等命名以区分元素数与字节数，LocalMemBar.md中地址变量名改为dstAddr/src0Addr，dual_issue_optimization.md补充双发射循环间需插入LocalMemBar<VEC_STORE, VEC_LOAD>的说明。
不准确？
atomgit-bot
16 天前 评论：
16 天前 评论：
代码审查
审查结论
- [建议]
docs/zh/api/SIMD-API/c_api/reg_compute/load/asc_loadalign_brc_elem.md:216fix: brc_elem示例UB局部数组仅3字节却按517字节搬入，存在缓冲区溢出 - [建议]
docs/zh/api/SIMD-API/c_api/reg_compute/store/asc_storealign_pack_quarter.md:238fix: input_local 数组按 ELEMENT_COUNT=67 声明却拷贝 512 字节，UB 越界写入 - [建议]
docs/zh/api/SIMD-API/c_api/reg_compute/store/asc_storealign_pack_quarter_postupdate.md:157fix: input_local 数组按 ELEMENT_COUNT=67 声明却拷贝 512 字节，UB 越界写入
| 类型 | 数量 |
|---|---|
| 🔴 阻塞 | 0 |
| 🟡 建议 | 3 |
💬 仅评论
不准确？
16 天前 添加了label：cann-cla/yes
CANN-robot
16 天前 评论：
16 天前 评论：
Thanks for your pull-request.
The full list of commands accepted by me can be found at here.
You can get sig-info at here.
You can self-configure the PR merge rules for this repository. For more details, please refer to Here.
For more, you also can visit HICANN.
PR Approval Progress
✅ Congratulations! All modules have met the lgtm and approve requirements.
Module Approval Details
| module | lgtm status | approve status |
|---|---|---|
| docs | ✅ munanhw, Lycheeeee (2/2) | ✅ munanhw (1/1) |
| examples | ✅ munanhw, Lycheeeee (2/2) | ✅ munanhw (1/1) |
💡 Tip:
- Committer can comment
/approveor/lgtm- Commenting
/approveimplies both code review (lgtm) and intent to merge (approve)
CLA Signature Pass
GRJ_XIDUO, thanks for your pull request. All authors of the commits have signed the CLA. 👍
此处折叠了83条消息 查看更多
13 天前 添加了label：approved
13 天前 添加了label：lgtm
13 天前 合入了pull request
12 天前 修改了pull request 的描述
描述
优化C API调用示例的参考性与同步正确性，共更新279个文档。同一文档可能涉及多个优化点，以下按具体改动各自列出三个典型示例，便于对照审阅。
1. 将易用性同步替换为明确的流水线同步
将asc_sync_mte2、asc_sync_mte3、asc_sync_vec等易用性接口替换为明确的同步接口，展示生产者与消费者之间的依赖。
2. 使用lock/unlock串联搬运与计算
在Reg计算示例中，通过同一MUTEX_ID下成对的asc_lock/asc_unlock串联PIPE_MTE2、PIPE_V和PIPE_MTE3三个阶段。
3. 补充VF循环、地址偏移及尾块处理
覆盖非VL整数倍的数据长度，在VF内按轮次更新地址和掩码，并为UB缓冲区预留对齐后的存储空间。
4. VF内部补齐UB写后读同步
vf内部同一UB区域先写后读时，插入同步以确保前次写入完成。
5. 统一变量命名并明确长度单位
统一部分示例中的长度和循环参数命名，区分有效数据长度、字节数及对齐后的缓冲区大小，并修正说明中的变量名称。
6. 使用asc_vf_call调用SIMD VF函数
将部分示例中对__simd_vf__函数的直接调用改为asc_vf_call<函数名>(...)，统一SIMD VF函数的调用方式，并传入循环所需的参数。
7.使用AscendC::Std::ceil_div替换示例内自定义的向上取整函数：ceil_division。
8.kernel末尾用asc_sync()替换asc_sync_pipe(PIPE_ALL)
关联的Issue
无。
测试
文档更新
更新205个C API接口文档的调用示例、LocalMemBar文档及指令双发优化指南，共207个文档。
类型标签