Star461
580
代码
代码
Issues22
Pull Requests107
流水线
讨论
Wiki
分析
Star461
580
cann-robotcann-robotdocs: rename guideline files from Chinese to English
9c2df526创建于 5月28日历史提交

简介

目的

这部分要描述文档的目的，并明确读者对象。说明本文档描述的是 Runtime 仓某个需求、特性或接口变更的软件需求与设计。

范围

本节应描述文档所包括和不包括的内容，明确哪些模块、接口、平台、测试和文档同步工作在本次设计范围内。

总体概述

本节描述影响产品和产品需求的一般因素。这里不描述具体需求细节，而是为后续的具体需求、设计和测试建立上下文。

软件概述

项目介绍

描述本设计对应的背景。例如：本需求是现有 Runtime 能力增强、某个子模块重构、公共 API 扩展，还是为新平台/新场景新增能力。

产品环境介绍

描述 Runtime 与其它组件、产品和平台共同构成的整体环境。

  1. 如果本能力是独立且自包含的，在此说明。
  2. 如果本能力属于更大系统中的一部分，应：

A. 描述相关组件的职责边界，并标识接口边界。

B. 确定本需求涉及的主要外部接口，例如 aclrt*、rt*、driver、toolchain、profiling、dump 等。

C. 描述相关硬件平台、芯片能力、Host 环境、外部依赖和设备侧限制。

建议使用方块图描述组件关系、调用方向和外部接口。

软件功能

概述本次需求必须实现的主要功能。这里只做高层说明，详细设计放在后续章节。建议按功能域组织，如：

  • ACL 对外接口
  • Runtime 核心能力（device/context/stream/event/notify/memory/model）
  • 维测能力（profiling/dump/log）
  • 工具链或平台适配能力

设计约束

描述限制开发选择的事项，例如：

  • 平台能力限制
  • 公共 API/ABI 兼容性要求
  • 目录边界约束
  • 构建宏约束
  • 性能、内存、日志、线程模型限制

假设和依赖关系

描述本迭代依赖的上下游版本、驱动能力、第三方组件、公共库、测试环境和文档前置条件。

特性1需求分析&设计

整体介绍

功能需求

功能需求1

用简短词汇作为功能需求名，不要用“功能需求（1）”作为功能名。

  1. 介绍

逐条列出与本特性相关的功能需求，包括正常流程、错误输入、非法状态和无效输入下的预期行为。需求应该简明、完整、不含糊、可验证。信息不确定时可标注“待定”。

  1. 输入

本子段落应包含：

A. 对所有输入数据的详细描述，包括来源、数量、单位、时序、范围、精度和容忍度。

B. 对接口规格或接口控制文档的引用。

  1. 处理

本子段落应描述：

A. 输入合法性校验。

B. 关键操作步骤和事件时序。

C. 异常场景处理，例如溢出、通信失败、driver 返回异常、资源申请失败、能力不支持等。

D. 任何输入到输出的转换方法、状态机或关键算法。

E. 输出结果的有效性检测。

  1. 输出

本子段落应包含：

A. 对所有输出数据、返回值、副作用、日志、文件、回调或状态变更的详细描述。

B. 对接口规格或接口控制文档的引用。

功能需求2

非功能需求

可维护性

可测试性

可移植性

可靠性

平台化要求

Runtime 需要兼容多 SoC、多 driver 能力和多运行环境。公共路径设计中应优先通过能力查询、配置注册和平台隔离目录处理差异，避免在通用逻辑中直接硬编码平台分支。

特性交叉分析

本节直接列出本需求对以下典型域的影响评估，至少说明“涉及/不涉及”及原因：

  • include/external/acl/ 对外接口
  • pkg_inc/runtime/ 对外发布头文件
  • src/runtime/api/ 与 src/runtime/core|feature/ 边界
  • device/context/stream/event/notify/memory/model
  • dump/profiling/log/toolchain
  • 平台适配目录和 driver 交互
  • 测试工程、文档和样例

性能

接口调用时延

涉及对外接口或高频内部接口的需求，必须评估新增逻辑对接口时延的影响，重点识别热路径中的额外分支、锁、字符串处理、日志和内存申请。

内存与资源占用

需要评估新增特性对内存、stream、event、context、线程、句柄等资源占用的影响。新增常驻资源原则上应说明生命周期、上限和释放时机。

执行性能

所有执行态相关代码都需要评估对任务提交、调度、同步、拷贝和设备执行路径的影响。若影响发生在高频路径，需要尽量量化到微秒/纳秒级。

可维与日志开销

profiling、dump、trace、日志相关改动需要评估是否引入额外的采集开销、IO 抖动或海量日志。

接口设计

新增/修改接口描述

涉及新增/修改接口时，需要明确接口原型、参数约束、返回值、线程安全要求、生命周期要求和版本兼容策略。

接口检查项

检查项 子检查项 是否涉及
接口说明 接口是否需要评审，评审需重点关注接口兼容、调用约束和资源生命周期
接口说明 是否需要补充资料说明、样例或迁移说明
接口说明 接口文档中是否明确接口原型、功能、返回值和错误码
接口兼容 include/、include/external/acl/、pkg_inc/runtime/ 下的修改是否保持向后兼容
接口兼容 接口签名是否发生 breaking change
接口兼容 废弃接口是否通过标记而非直接删除
接口兼容 枚举是否新增 XX_MAX 或影响多版本匹配兼容性
接口约束 接口是否涉及调用时序、线程上下文、device/context、内存所有权等约束
接口约束 接口调用不满足约束条件时是否能清晰报错
目录规范 pkg_inc/runtime/runtime 是否误新增内容，是否应该放到 pkg_inc/runtime/rt_external* 或其它对外边界
文档同步 修改 include/external/acl/acl_rt.h 时，是否同步更新 docs/ 对应文档
文档同步 修改 include/external/acl/error_codes/rt_error_codes.h 时，是否同步更新 docs/03_api_ref/25_数据类型及其操作接口.md
测试 是否需要新增单独的 UT/ST/兼容性用例

软件设计

关键数据结构

关键技术/算法

流程设计

对子模块的修改

如果涉及子模块主流程、目录边界或调用方向调整，需要明确说明责任边界变化和受影响模块。

错误处理

系统错误

描述内存申请失败、driver 失败、资源创建失败、线程创建失败、文件/目录失败等系统级错误如何处理。

接口错误

描述会暴露给外部实体的错误码、错误消息和传播策略。

Runtime 设计补充检查项

检查项 检查项说明 是否涉及
架构边界 src/runtime 中非 api 目录不应调用 api 目录的方法，例如 feature 目录不应访问 Api::Instance
编译宏 src/runtime 目录仅允许使用 STATIC_RT_LIB、RUNTIME_API、CFG_DEV_PLATFORM_PC 及编译器内置宏；禁止新增其他编译宏
外部输入校验 用户 API 参数、driver 返回值、配置文件、环境变量、外部文件路径是否都定义了校验策略
资源生命周期 新增内存、句柄、线程、回调、缓存、单例资源时，是否明确生命周期、释放路径和异常回收策略
跨 SO 析构风险 是否存在静态/全局对象在析构阶段做跨 SO 调用、释放跨 SO 对象或依赖卸载顺序
热路径日志 是否评估了热路径中新增日志、字符串拼接和可维打点的性能影响

安全检查

编码规范

参考 coding-guidelines.md

设计检查项

检查项 检查项说明 是否涉及
资源生命周期管理 生命周期过长的资源可能导致资源不足、响应变慢和系统崩溃；需明确资源是进程级、device 级、context 级还是调用级
线程创建 新线程是否需要拷贝 ThreadLocalContext、ErrorContext 等上下文信息；是否需要设置线程名称
全局状态恢复 设计是否会修改 SoC 类型、device、环境变量、单例状态、静态缓存；若会，测试和异常路径如何恢复
外部数据使用 外部输入是否可能作为数组索引、长度、偏移、内存申请大小或枚举值参与关键逻辑
日志与敏感信息 是否存在敏感信息打印、错误日志级别不当或热路径日志过多风险

兼容性检查

重点关注以下兼容性问题：

  • 老版本应用或老接口在新版本 Runtime 上是否仍能工作
  • include/、pkg_inc/ 对外边界是否引入 ABI/API 不兼容
  • 新增枚举值、结构体字段、保留参数启用后是否影响旧逻辑
  • 文档、样例和测试是否覆盖兼容性场景

文档同步

如果本次设计涉及对外接口、错误码或用户可见行为变化，需要明确同步更新的文档列表，例如：

  • docs/03_api_ref/
  • docs/02_dev_guide/
  • example/
  • 迁移说明、FAQ、发布说明

DT设计

测试边界

测试入口（基于什么接口或组件做测试）、测试出口（做哪些数据校验）、打桩模块、依赖环境和清理范围。

测试设计

说明需要设计哪几类用例，可导出到用例列表。用例类型一般包括 UT、ST，必要时包括兼容性测试、性能测试和专项回归。

测试类别 关键测试项 测试方法 用例类型
功能
异常处理
性能
兼容性
资源与泄漏
特性交叉

测试框架设计

测试实现补充检查项

检查项 检查项说明 是否涉及
断言完整性 每个测试用例必须有 EXPECT/ASSERT 断言验证结果，不能只调用接口不校验
Mock 清理 每个测试类是否在 TearDown 中 verify 或 reset mock 对象，确保测试隔离
私有成员访问 是否避免不必要地使用 #define private public / #define protected public
SetChipType 是否尽量减少在 UT 中直接调用 SetChipType，若必须使用是否有恢复逻辑
指针成员恢复 如果测试修改了类的指针成员、全局指针或单例状态，退出时是否恢复原值