CANN/runtime设计文档模板

简介【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime目的这部分要描述文档的目的并明确读者对象。说明本文档描述的是 Runtime 仓某个需求、特性或接口变更的软件需求与设计。范围本节应描述文档所包括和不包括的内容明确哪些模块、接口、平台、测试和文档同步工作在本次设计范围内。总体概述本节描述影响产品和产品需求的一般因素。这里不描述具体需求细节而是为后续的具体需求、设计和测试建立上下文。软件概述项目介绍描述本设计对应的背景。例如本需求是现有 Runtime 能力增强、某个子模块重构、公共 API 扩展还是为新平台/新场景新增能力。产品环境介绍描述 Runtime 与其它组件、产品和平台共同构成的整体环境。如果本能力是独立且自包含的在此说明。如果本能力属于更大系统中的一部分应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”作为功能名。介绍逐条列出与本特性相关的功能需求包括正常流程、错误输入、非法状态和无效输入下的预期行为。需求应该简明、完整、不含糊、可验证。信息不确定时可标注“待定”。输入本子段落应包含A. 对所有输入数据的详细描述包括来源、数量、单位、时序、范围、精度和容忍度。B. 对接口规格或接口控制文档的引用。处理本子段落应描述A. 输入合法性校验。B. 关键操作步骤和事件时序。C. 异常场景处理例如溢出、通信失败、driver 返回异常、资源申请失败、能力不支持等。D. 任何输入到输出的转换方法、状态机或关键算法。E. 输出结果的有效性检测。输出本子段落应包含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/modeldump/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/zh/api_ref/25_data_types_and_operation_APIs.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/zh/api_ref/docs/zh/dev_guide/example/迁移说明、FAQ、发布说明DT设计测试边界测试入口基于什么接口或组件做测试、测试出口做哪些数据校验、打桩模块、依赖环境和清理范围。测试设计说明需要设计哪几类用例可导出到用例列表。用例类型一般包括 UT、ST必要时包括兼容性测试、性能测试和专项回归。测试类别关键测试项测试方法用例类型功能异常处理性能兼容性资源与泄漏特性交叉测试框架设计测试实现补充检查项检查项检查项说明是否涉及断言完整性每个测试用例必须有EXPECT/ASSERT断言验证结果不能只调用接口不校验Mock 清理每个测试类是否在TearDown中verify或resetmock 对象确保测试隔离私有成员访问是否避免不必要地使用#define private public/#define protected publicSetChipType是否尽量减少在 UT 中直接调用SetChipType若必须使用是否有恢复逻辑指针成员恢复如果测试修改了类的指针成员、全局指针或单例状态退出时是否恢复原值【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考