HIXL SRS 设计文档编写指南基于仓库模板与源码的软件需求规格说明实战【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl导读本文以 CANN/hixl 仓库内置的 HIXL SRS 模板 为主体结合仓库中已落地的真实设计文档如 FabricMem 传输模式需求、LLM-DataDist 支持 HIXL 传输后端以及 hixl-srs-doc-generator skill 的生成规则系统讲解如何在 HIXL/ADXL 项目里写出一份结构规范、事实准确、可落地评审的 SRS软件需求规格说明文档。读完本文你将掌握 SRS 五大一级章节的编排方法、功能要点的提炼粒度、Mermaid 类图/时序图的使用时机、测试方案三列表格的组织方式以及如何借助 HIXL/ADXL 代码地图 从源码中获取事实依据。SRS 模板的整体骨架五大固定一级章节模板 开篇即声明了硬性规则一级章节固定为「需求描述、功能要点、技术方案、相关文档、测试方案」不允许擅自增删或另起一级章节。这一约束保证了仓库内所有设计文档的检索一致性和评审效率——评审者无论打开哪份 SRS都能在同一位置找到对应内容。模板还给出了若干贯穿全文的表述规范需求描述用短段落避免整段堆叠技术方案和测试方案用清晰小节或列表展开功能要点必须使用 Markdown 复选框- [ ]聚焦 2~4 个核心主要功能不把类名、函数名、测试点等实现细节拆成大量功能点不确定内容集中写在「假设与待确认」并说明其影响不得散落成隐含风险涉及跨模块调用、双端交互、异步/并发或状态流转时必须包含 Mermaid 时序图纯文档、配置或局部结构变更可省略并说明原因大量类、组件、服务或核心结构变更时必须包含 Mermaid 类图简单局部改动不要硬塞类图伪代码按需保留避免把设计文档写成实现代码测试方案每个小节用表格列出测试场景固定包含「测试场景、测试功能、验证点」三列。模板骨架如下使用text代码块展示其结构实际书写时以 Markdown 呈现# 需求名称 SRS ## 需求描述 背景、特性目标、要解决的问题 ### 假设与待确认 - 假设或待确认项原因 影响的设计/兼容性/性能/验收范围 ## 功能要点 - [ ] 核心功能点 1用户可见行为或主要能力 - [ ] 核心功能点 2关键内部能力或流程 ## 技术方案 ### 设计思路 ### 模块关系  ### 功能点 1 #### 核心流程  #### 关键伪代码 ## 相关文档 ## 测试方案 ### 单元测试 ### 系统/集成测试这份模板的灵魂在于要求设计者把每个功能点都落到技术方案与测试方案的闭环验证这一点在 skill 的处理流程 中同样被强调每个功能点都要在技术方案和测试方案中有对应验证。需求描述背景、目标与假设的写法「需求描述」用于交代本需求背景、要实现的特性、期望解决的问题用短段落表达。仓库中的真实范例 FabricMem 传输模式需求 给出了一个清晰的三段式背景写法业务驱动大语言模型推理规模扩大后 KV Cache 规模快速增长Mooncake store 等分布式 DRAM 缓存池场景对 NPU 到 DRAMD2RH传输性能提出更高要求硬件机会A3 服务器提供 FabricMemory 技术支持超节点内 DRAM 统一编址可借助 HCCS 链路进行 D2RH/RH2D 传输现状限制底层调用 HCCL 接口的 HCCS 传输模式不支持 D2RH中转模式在 A3 上占用 HBM 带宽对模型推理影响较大。这种业务背景 → 技术机会 → 现有方案缺口的叙事逻辑能帮助评审者快速理解需求存在的合理性。「假设与待确认」是模板中专门收纳不确定信息的节点位于需求描述之下。规则要求每一条都要说明不确认的原因以及它会影响的设计、兼容性、性能或验收范围而不是把待确认当成逃避分析的挡箭牌。例如当需求涉及公开 API/ABI 变更时需对照 ABI 兼容性编码规范 中的变更构成清单符号增删/改名、结构体大小/字段偏移、枚举值、公开 constexpr 常量值、vtable 布局、默认参数值逐项核对凡无法确认的项都应写入该小节并标注影响面。功能要点复选框 2~4 条核心功能功能要点是 SRS 的验收锚点模板规定必须用 Markdown 复选框书写通常 2~4 条粒度聚焦在用户可见行为或主要能力、关键内部能力或流程两级不把类名、函数名或测试点拆散。以 LLM-DataDist 支持 HIXL 传输后端 为例其功能要点只有一条但覆盖完整- [ ] LLM-DataDist提供对接HCCL单边通信API能力。 支持解析本地通信资源option通过Hixl提供链路管理与传输能力并兼容原生能力。 需要对建链、断链、内存注册、注销以及数据传输流程进行抽象同时支持基于Hixl和Hccl通信域实现相关能力。注意它的写法功能点本身是对接单边通信 API这一个核心能力而建链/断链/内存注册等则是该能力下的行为描述并不拆成 5 个独立复选框。这就是模板所说的聚焦几个核心主要功能。技术方案设计思路、模块关系与功能点展开「技术方案」是 SRS 的信息密度核心模板要求按功能要点逐项说明技术实现思路覆盖关键模块、类/函数、数据结构、调用关系、状态流转、线程/资源生命周期、异常处理和兼容策略。同时按需补入两类 Mermaid 图。设计思路从功能点到模块落点设计思路应将每个功能要点映射到具体模块与文件。这一步可以借助 HIXL/ADXL 代码地图 快速定位事实该地图给出了核心路径的职责划分src/hixl/engine/HIXL Engine 对外引擎、client/server、factory、endpoint 生成src/hixl/cs/控制面服务、endpoint、channel、连接/内存消息处理、transfer poolsrc/hixl/common/日志、校验、segment、thread pool、ctrl msg 等通用能力src/hixl/profiling/profiling 注册与上报src/hixl/proxy/hcomm/hccp proxy 适配层src/llm_datadist/adxl/ADXL 内部引擎、channel 管理、控制消息、buffer/fabric mem 传输、segment table、virtual memory、stream pool、统计。代码地图还给出推荐的检索命令便于在写技术方案前用rg核对类名、接口、配置与错误码避免凭空虚构rg -n 需求关键词|类名|接口名 src/hixl src/llm_datadist/adxl include docs tests/cpp rg -n class|struct|enum|Status|Error|Init|Finalize|Transfer|Malloc|Free src/hixl src/llm_datadist/adxl include模块关系何时必须上类图模板规定当需求创建或改动大量类、组件、服务或核心结构时技术方案必须包含 Mermaid 类图说明它们之间的关系简单局部改动不要硬塞无意义类图。FabricMem 传输模式需求 是教科书式的类图范例——它用一张classDiagram完整呈现了EngineFactory按EnableUseFabricMem1创建FabricMemEngine的路由以及FabricMemEngine与FabricMemTransferService、FabricMemControlServer、FabricMemLocalMemory、FabricMemStatistic的持有关系还向下延伸出FabricMemChannelManager → FabricMemChannel → FabricMemRemoteMemory的连接链与VirtualMemoryManager的映射依赖。核心关系用注释/箭头说明这样一张图就能让评审者在一分钟内看懂新增引擎与既有组件的边界同时印证了设计中FabricMem 由独立 FabricMemEngine 承载、不侵入 HixlEngine/AdxlInnerEngine/ChannelMsgHandler/Channel的解耦主张。功能点展开核心流程时序图 关键伪代码模板要求涉及跨模块调用、双端交互、异步/并发或状态流转时每个功能点下必须包含 Mermaid 时序图描述核心时序。FabricMem 文档的时序图贯穿「初始化 → 内存注册 → 建链 → 传输」四个阶段摘录其骨架「关键伪代码」则是把核心分支用少量代码固化下来。模板强调只写核心分支避免把设计文档写成实现代码。仓库中的实际风格可参考 LLM-DataDist 传输后端设计该文档用伪代码给出了 C 调用流程LlmDataDist llm_datadist_p(1U, LlmRole::kPrompt); std::mapAscendString, AscendString options_p; options_p[llm_datadist::OPTION_LISTEN_IP_INFO] 127.0.0.1:26000; options_p[llm_datadist::OPTION_DEVICE_ID] 0; options_p[llm_datadist::OPTION_TRANSFER_BACKEND] hixl; options_p[llm_datadist::OPTION_LOCAL_COMM_RES] R({version: 1.3, ...}); llm_datadist_p.Initialize(options_p);技术方案中的两张附加信息表锁设计与关键检查点技术方案除了模板规定的类图、时序图、伪代码还可以视需求复杂度补充辅助表格。FabricMem 文档提供了两个值得借鉴的范例并发与锁设计表——当设计涉及多线程并发时用组件 / 锁 / 保护对象三列表格逐组件说明锁职责并给出固定加锁顺序与典型并发场景如多线程 TransferSync 同一 remote拷贝在submit_gate共享锁下并行下发。其设计前提也很值得参考不考虑 Finalize 与对外 API 并发对外 API 入口仅做is_initialized_检查——把并发边界提前声明清楚避免评审反复追问。关键检查点列表——FabricMem 文档以编号列表给出 Engine 路由检查OPTION_ENABLE_USE_FABRIC_MEM1时必须由EngineFactory创建FabricMemEngine、配置合法性检查如transfer_config.max_transfer_count_per_batch范围为[1, 1920]、默认1920、内存类型检查、传输参数检查、流资源管理检查、异步请求状态检查、映射清理检查、并发安全检查、对端异常下线清理等并单列性能关键点流池管理、多流并发、异步操作与兼容性考虑默认不启用、统计归属隔离。这些检查点直接为后续测试方案的用例设计提供了输入。相关文档接口与设计文档的联动「相关文档」小节要求列出新增或更新的文档路径模板给出了三条指引新增/更新的设计文档路径例如docs/design/需求名.md公开接口变更时同步docs/cpp/或docs/python/的条目若不涉及文档写明不涉及新增文档如公开行为变化需同步接口文档。结合 代码地图 的公开接口与文档边界HIXL/ADXL 系列文档的映射关系是HIXL 对应include/hixl/hixl.h、include/hixl/hixl_types.h与docs/zh/api/cpp/HIXL-interface.md、HIXL-data-structure.md、HIXL-error-code.mdHIXL CS 对应include/cs/hixl_cs.h与docs/zh/api/cpp/HIXL_CS-interface.mdADXL 对应include/adxl/与docs/zh/api/cpp/deprecated_ADXL-*.mdLLM-DataDist 对应include/llm_datadist/与docs/zh/api/cpp/LLM-DataDist-*.md。涉及哪个模块就同步哪份文档并在相关文档小节写清预期文件路径如docs/design/需求名SRS.md。测试方案三列表格与 UT 优先原则「测试方案」是模板对格式要求最严的小节每个小节用表格列出测试场景固定包含「测试场景、测试功能、验证点」三列。模板给出单元测试与系统/集成测试两类示例。单元测试默认覆盖四类场景测试场景测试功能验证点正常路径待验证功能返回值、状态变化、资源生命周期或调用结果符合预期边界参数待验证功能边界输入被正确处理不发生越界或资源泄漏失败分支待验证功能错误码、日志、回滚和资源释放符合设计非法参数参数校验返回明确错误不触发未定义行为系统/集成测试则覆盖端到端调用链与传输模式覆盖FabricMem/HCCL/Buffer 等路径的按设计选择、执行与回退。skill 的测试规划原则可帮助填充表格测试优先级为 UT ST/轻量系统测试 上机集成测试能用 UT/ST 覆盖的场景不要规划上机集成测试只有依赖真实硬件资源、跨进程/跨节点链路、CANN/HCCL 运行时、真实传输路径或真实性能数据时才规划上机集成测试并说明为什么不能替代。测试文件的落点可参照 代码地图 的测试映射HIXL Engine 测试在tests/cpp/hixl/engine/HIXL CS 在tests/cpp/hixl/cs/ADXL/LLM-DataDist 在tests/cpp/llm_datadist/重点参考adxl_engine_api_unittest.cc、fabric_mem_transfer_service_unittest.cc、segment_table_unittest.cc等Python API 变化对应tests/python/test_*.py。从模板到成品skill 的生成流程与写作检查点skill 把写 SRS 规范化为五步流程解析用户意图 → 核对仓库依据 → 决定是否追问 → 生成 SRS → 自检输出。其中有三条值得所有写作者内化的经验优先补齐不轻易把整份模板反问给用户能从代码、现有文档、测试和上下文推断的内容直接写入只有缺失信息会影响架构选择、兼容性、安全、性能或验收标准时才向用户提问且一次最多问 3 个高价值问题。不虚构事实不虚构类名、API、错误码、配置项、性能数据或硬件能力引用代码路径前必须在仓库中核对这正是 hixl-code-map.md 存在的意义。写文件而非空谈默认将文档写入docs/design/需求名SRS.md写入前必须检查目标文件是否已存在已存在且未获允许时不覆盖只有用户明确要求只预览/直接输出时才在回复中给出正文。最终自检时可以对照如下清单逐项核验每个功能点是否都在技术方案与测试方案中有对应验证所有待确认项是否集中收在「需求描述」的「假设与待确认」涉及新增/更新docs/、include/、tests/时是否写明预期文件路径Mermaid 块是否使用合法 fenced code block 且语言标识为mermaid。结语HIXL 的 SRS 模板 是一份约束刚、填充活的写作规范一级章节固定、表述方式明确但内容深度完全取决于写作者对src/hixl、src/llm_datadist/adxl、include/与tests/的把握程度。以仓库中 FabricMem 传输模式需求 与 LLM-DataDist 支持 HIXL 传输后端 为范本配合 代码地图 检索事实任何 HIXL/ADXL 功能需求都能沉淀为一份可评审、可验收、可回溯的 SRS 文档。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考