已开启
docs(ain): 统一 Put/Get 单次传输长度约束 #229
docs(ain): 统一 Put/Get 单次传输长度约束 #229
已开启
little_apple_12创建于 12 天前
12 天前

描述

Ain Put/Get 的中文和英文文档都将单次 bytes == 256 * 1024 * 1024 标记为有效,但对应实现把该值直接传给底层 Hcomm WriteNbi/ReadNbi,其公开契约要求长度严格小于 256 MB。本 PR 仅将中英文四处 Ain 文档范围从 <= 改为 <,不改接口、实现或运行时行为。

开放 PR #202 只对齐英文 AIN 窗口句柄类型与公共头文件;本 PR 修正的是不同的单次传输长度约束。

关联的Issue

关联Issue #43

测试

本地静态验证实际输出如下。

边界检索命令:

rg -n '0 < bytes < 256 \* 1024 \* 1024' docs/zh/api/aicore/ain/Put.md docs/zh/api/aicore/ain/Get.md docs/en/api/aicore/ain/Put.md docs/en/api/aicore/ain/Get.md

该命令找到四处约束,结果均为严格小于:

docs/en/api/aicore/ain/Get.md:60:- Currently, only the `COMM_PROTOCOL_UBC_CTP` protocol path is supported. For a single `Get` call, the valid range of the input parameter `bytes` is `0 < bytes < 256 * 1024 * 1024`.
docs/en/api/aicore/ain/Put.md:73:- Currently, only the `COMM_PROTOCOL_UBC_CTP` protocol path is supported. For a single `Put` call, the valid range of the input parameter `bytes` is `0 < bytes < 256 * 1024 * 1024`.
docs/zh/api/aicore/ain/Get.md:85:- 当前只支持`COMM_PROTOCOL_UB_CTP`协议路径。单次调用`Get`的入参`bytes`取值范围为`0 < bytes < 256 * 1024 * 1024`。
docs/zh/api/aicore/ain/Put.md:100:- 当前只支持`COMM_PROTOCOL_UB_CTP`协议路径。单次调用`Put`的入参`bytes`取值范围为`0 < bytes < 256 * 1024 * 1024`。

反向检索旧的 <= 范围没有命中,输出为 PASS: no inclusive 256 MiB Ain bound remains。四个修改文件均通过 UTF-8 严格解码、无 BOM、LF 换行、无 U+FFFD 和连续问号检查;本地 Markdown 链接目标 0 个,缺失目标 0 个。仓库环境未安装 Markdown lint/parser;本次只改纯文本边界表达式,未运行 NPU 测试。

git diff --check 退出码为 0、无输出。git diff --stat 实际结果:4 个文件变更,4 行新增、4 行删除;完整逐 hunk 对账见 case 留痕 verify/diff-audit.txt。

文档更新

  • docs/zh/api/aicore/ain/Put.md:将单次长度上界改为严格小于 256 MiB。
  • docs/zh/api/aicore/ain/Get.md:将单次长度上界改为严格小于 256 MiB。
  • docs/en/api/aicore/ain/Put.md:将单次长度上界改为严格小于 256 MiB。
  • docs/en/api/aicore/ain/Get.md:将单次长度上界改为严格小于 256 MiB。

类型标签

当前PR是否有AI参与:

[] 否
[x] 是
__1. Agent平台信息: Codex CLI 0.153.4
__2. 模型信息: gpt-5.6-luna
__3. Prompt摘要: 独立复核 Ain Put/Get 单次长度边界,核对中英文文档、底层 Hcomm 契约及源码传参路径,完成全量 issue/PR 分页去重,并评估最小文档修复范围。

希望检视人员了解:

  1. 提交者提供了候选报告和三道闸门要求;本轮独立核对指定 commit、四处中英文文档、源码传参、全量分页去重及实际静态检查输出,未运行 NPU。
  2. 改动只涉及描述同一长度边界的四个 Ain 文档位置;不改变实现、接口或运行时行为。
  3. PR #202 修正的是英文窗口句柄类型,与本 PR 的长度边界差异已在正文说明。
likedislike
合并受阻
Llittle_apple_12
12 天前 创建了 pull request,commit c16299d8
Llittle_apple_12
12 天前 关联了issue:[Documentation|文档反馈]: Ain Put/Get 中英文档将 256 MiB 单次长度标为有效,与 Hcomm 契约不一致
atomgit-bot
atomgit-bot
12 天前 评论:

变更摘要

本 PR 是一次纯文档边界修正:针对 Ain 的 Put/Get 接口,中文与英文文档原先都将单次传输入参 bytes 的有效范围写为包含上界的 256 MiB,而底层 Hcomm 的 WriteNbi/ReadNbi 公开契约要求长度严格小于 256 MB,且实现将该值直接透传。因此本次仅把四处 Ain 文档中的范围表达式由 <= 256 * 1024 * 1024 改为严格小于 256 * 1024 * 1024,使文档与底层契约一致,不涉及接口、实现或运行时行为变更。

主要改动

  • 中文 Put 文档边界对齐: docs/zh/api/aicore/ain/Put.md 中单次调用 Put 的入参 bytes 取值范围改为 0 < bytes < 256 * 1024 * 1024,与底层 Hcomm 严格小于 256 MB 的约束保持一致。
  • 中文 Get 文档边界对齐: docs/zh/api/aicore/ain/Get.md 中单次调用 Get 的入参 bytes 取值范围同样改为严格小于 256 MiB。
  • 英文 Put 文档边界对齐: docs/en/api/aicore/ain/Put.md 中单次 Put 调用 bytes 的合法范围由包含上界改为 0 < bytes < 256 * 1024 * 1024。
  • 英文 Get 文档边界对齐: docs/en/api/aicore/ain/Get.md 中单次 Get 调用 bytes 的合法范围同步改为严格小于 256 MiB,确保中英文四处描述统一。
likedislike
不准确?
atomgit-bot
atomgit-bot
12 天前 评论:

🤖 本次改动均为数据 / 生成 / 二进制文件(如测试用例、锁文件、媒体资源),没有可审查的代码逻辑,已跳过 AI 代码审查。

likedislike
不准确?
CANN-robotCANN-robot成员
12 天前 添加了label:ai-co-authored
CANN-robotCANN-robot成员
12 天前 添加了label:cann-cla/yes
CANN-robot
CANN-robot成员
12 天前 评论:

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

⚠️ This PR does not yet meet the following requirements:lgtm (requires ≥ 2 person(s) per module)、approve (requires ≥ 1 person(s) per module)

Module Approval Details

module lgtm status approve status
docs ❌ (0/2)(You can also ask: 肖婷, 李东锋, munanhw, bluesky901, qin437231) ❌ (0/1)(You can also ask: 肖婷, zhanghao_0689, 李东锋, munanhw, 苏建加)

💡 Tip:

  • Committer can comment /approve or /lgtm
  • Commenting /approve implies both code review (lgtm) and intent to merge (approve)

CLA Signature Pass

little_apple_12, thanks for your pull request. All authors of the commits have signed the CLA. 👍

likedislike
little_apple_12
12 天前 评论:

compile

likedislike
Llittle_apple_12
12 天前 预合并成功(commit_id: f5b08c36c60e5d03510cb4e125ff0eea48da1dd3)
CANN-robot
CANN-robot成员
12 天前 评论:
🚀 CI 流水线已启动
📋 执行详情: 点击查看流水线
likedislike
CANN-robotCANN-robot成员
12 天前 添加了label:ci-pipeline-running
CANN-robotCANN-robot成员
12 天前 删除了label:ci-pipeline-running
CANN-robotCANN-robot成员
12 天前 添加了label:ci-pipeline-passed