简介：这份嵌入式系统开发软件设计说明书模板面向嵌入式软件工程师、项目开发人员及高校相关专业学生，用于规范软件详细设计文档的编写流程。模板围绕嵌入式系统开发的核心环节展开，涵盖系统定义与组成、应用对象分析、设计约束、设计描述、文档管理、项目管理、质量管理与配置管理等多个知识点，并给出引言、软件设计约束、软件设计描述等章节的完整框架，包含编写目的、读者对象、功能框图、接口说明、程序编写与源文件列表等条目，可直接套用或按项目裁剪。资源包共1个doc文件，约64KB，为可编辑的Word模板，便于团队按内部规范填写与归档。目前已有2568人学习下载，适合需要快速建立设计文档体系、统一团队文档格式或作为课程设计参考的开发者使用。
1. 一份“没人看”的文档，为什么能决定嵌入式项目的生死
很多做嵌入式的人都有个错觉：代码能跑、板子能亮，项目就算成了。直到某天硬件改版、同事离职、客户要加功能，你翻开三个月前自己写的工程，发现连当初为什么把串口波特率设成 115200 都想不起来。这时候你才会意识到，真正让项目“死掉”的往往不是技术难题，而是那份被所有人忽略的《嵌入式系统开发软件设计说明书》。
这份文档模板要解决的，正是“代码之外的那一半工程”。它面向的是需要交付、需要协作、需要过评审的嵌入式软件项目——小到一个基于单片机的采集板，大到多任务调度的综合系统。它不教你写代码，而是教你把“为什么这么写、怎么验证、边界在哪”固化下来。如果你正被“文档写什么、写到什么颗粒度、评审怎么过”折磨，这篇笔记就是给你看的。
2. 设计说明书到底写什么：从模板骨架到可评审的章节映射
2.1 先分清“设计说明”和“需求说明”的边界
很多团队翻车，是因为把设计说明书写成了需求文档的复读机。需求文档回答“做什么”，设计说明书回答“怎么做”。在嵌入式语境里，这个边界尤其重要：需求可能只写“系统需支持 3 路串口通信”，而设计说明书必须落到“使用哪两个 UART 外设、DMA 还是中断、缓冲区多大、波特率误差如何补偿”。
我一般会把模板骨架拆成四块：系统概述、硬件接口设计、软件架构设计、关键流程与异常处理。系统概述里只写约束和假设，比如主频上限、内存预算、实时性要求；硬件接口设计要落到引脚分配、电平匹配、时序余量；软件架构设计是重头戏，要写清任务划分、通信机制、状态机；关键流程与异常处理则要覆盖上电初始化、故障恢复、看门狗策略。
提示：如果一份设计说明书里出现了“系统应具备良好的人机交互”这种句子，直接打回去重写。设计文档里不允许出现不可验证的形容词。
2.2 用一张“追溯表”把需求和设计锁死
评审时最怕听到“这个设计对应哪条需求”。解决办法是在文档里嵌一张追溯表，左边是需求编号，右边是设计章节号，中间是验证方法。这张表不需要多复杂，但必须每行都能点回去。
| 需求编号 | 需求描述 | 设计章节 | 验证方法 |
|---|---|---|---|
| REQ-001 | 支持 3 路串口，波特率可配 | 3.2 串口外设分配 | 示波器测波形 + 回环测试 |
| REQ-002 | 上电后 500ms 内进入主循环 | 4.1 启动流程 | GPIO 翻转 + 逻辑分析仪 |
| REQ-003 | 通信中断后 2s 内自动恢复 | 5.3 异常恢复状态机 | 注入故障 + 日志时间戳 |
这张表的价值在于：它逼着你在写设计的时候就想清楚“这条需求将来怎么测”。如果某条需求找不到验证方法，要么是需求本身有问题，要么是你的设计还没落到可执行层面。
2.3 软件架构章节的颗粒度：写到“函数级”还是“模块级”
这是被问得最多的问题。我的经验是：对实时性敏感、涉及硬件寄存器的部分，写到函数级；对上层业务逻辑，写到模块级即可。比如一个 PID 控制环，你要写清采样周期、积分限幅、输出饱和处理，甚至给出伪代码；但一个菜单显示模块，写到“状态机驱动，支持三级页面跳转”就够了。
模板里通常会预留“接口定义”小节。这里不要只写函数名，要写清参数范围、返回值含义、调用上下文。比如：
/** * @brief 读取指定通道的 ADC 滤波值 * @param ch 通道号，范围 0-3，超出返回 -1 * @param pVal 输出指针，不得为 NULL * @return 0 成功，-1 参数错误，-2 硬件未就绪 * @note 该函数在 1ms 任务中调用，不可阻塞 */ int adc_read_filtered(uint8_t ch, uint16_t *pVal);逻辑说明：这段注释就是设计说明书的一部分。参数范围、错误码、调用约束全在里面。参数说明：ch的范围限制来自硬件多路复用器的物理通道数；pVal的 NULL 检查是防御性编程，评审时会被问到；-2错误码用于区分“硬件还没初始化完”和“参数传错”两种情况，方便上层做不同处理。
2.4 把“时序”和“资源预算”写进文档，而不是留在脑子里
嵌入式设计说明书和普通软件设计文档最大的区别，就是必须包含时序和资源预算。我见过太多项目因为“没想到中断嵌套导致栈溢出”而翻车。模板里应该有一节专门写“中断优先级分配”和“栈深度估算”。
常见做法是列一张表：中断源、优先级、最大执行时间、是否允许嵌套。然后根据最坏情况估算栈使用。比如：
| 中断源 | 优先级 | 最大执行时间 | 栈消耗估算 |
|---|---|---|---|
| 串口接收 | 2 | 15us | 32 字节 |
| 定时器 | 1 | 8us | 16 字节 |
| 外部触发 | 0 | 5us | 12 字节 |
这张表写进文档后，任何新增中断都要重新评估。这就是设计说明书的“后悔药”作用——它让你在改代码前先改文档，改文档时就会被迫想清楚影响面。
3. 从模板到落地：把一份 doc 变成可执行的工程约束
3.1 模板不是填空题，先建立“设计决策记录”习惯
拿到一份设计说明书模板，新手最容易犯的错是把它当填空题：每个空都填上字，但彼此之间没有逻辑关联。我一般会先建一个“设计决策记录”清单，每做一个关键选择就记一条：背景、选项、决定、理由。这些记录最终会自然填充到模板的各个章节里。
比如选型 RTOS 还是裸机循环，决策记录会写：背景是系统有 5 个任务且对响应时间有要求；选项是裸机前后台、时间片轮询、RTOS；决定用 RTOS；理由是任务间有优先级差异且需要阻塞式同步。这段内容直接放进“软件架构设计”章节，评审时没人会挑战你。
# 我常用的决策记录模板（纯文本，放在工程 docs/decisions/ 下） # 文件名：ADR-001-use-rtos.md # 状态：已采纳 # 背景：系统需同时处理串口命令、ADC 采样、PWM 输出、状态灯、看门狗喂狗 # 选项：1. 裸机前后台 2. 时间片轮询 3. 抢占式 RTOS # 决定：选项 3 # 理由：ADC 采样和串口命令有硬实时要求，裸机轮询无法保证抖动 < 50us # 后果：需增加栈深度预算，中断优先级需重新分配逻辑说明：这个纯文本文件不依赖任何工具，放在工程目录里，和代码一起版本管理。参数说明：ADR-001是编号，方便引用；状态字段用于标记是否被后续决策取代；后果字段逼你写出选型的代价，避免只写好处。
3.2 用“接口契约”代替口头约定
嵌入式团队经常出现“硬件说软件没配好，软件说硬件时序不对”的扯皮。设计说明书里应该有一节“接口契约”，把软硬件交界面的时序、电平、协议格式写死。比如 SPI 通信，要写清时钟极性、相位、片选建立时间、数据建立保持时间。
// 接口契约示例：SPI 从设备时序要求（写进设计说明书 3.4 节） // 时钟极性 CPOL = 0，相位 CPHA = 0 // 片选有效到第一个时钟沿：最小 100ns // 最后一个时钟沿到片选无效：最小 50ns // 数据建立时间：最小 20ns // 数据保持时间：最小 10ns // 以上参数来自从设备手册，软件配置 SPI 时必须满足逻辑说明：这段不是代码，是写进文档的约束。参数说明：这些时间参数直接来自器件手册，软件工程师配置 SPI 分频时必须反推时钟频率是否满足。如果满足不了，就要在文档里记录“已知偏差”并给出补偿方案，而不是等调试时抓瞎。
3.3 评审 checklist：让文档可被“攻击”
设计说明书评审不是朗读会。我一般会准备一份 checklist，评审时逐条过。checklist 不写在文档正文里，而是作为评审记录附件。常见条目包括：每个中断的优先级是否明确？每个缓冲区的溢出策略是否定义？每个状态机是否有超时退出？每个错误码是否有唯一含义？
注意：如果评审时有人问“这个缓冲区满了怎么办”，而文档里只写了“缓冲区大小 256 字节”，那这份文档就是不合格的。必须写清“满时丢弃最旧数据”还是“阻塞等待”还是“返回错误”。
3.4 版本变更：文档和代码必须同源
最怕的是代码改了，文档没改。我的做法是把设计说明书拆成多个 Markdown 文件，和代码放在同一个仓库里。每次改代码涉及接口、时序、任务划分的，必须同时改对应文档文件，否则 CI 里加一条检查：文档目录有变更才允许合并。
# 简易 CI 检查脚本（放在仓库根目录 scripts/check_docs.sh） # 检查最近一次提交是否同时修改了 src/ 和 docs/design/ CHANGED_SRC=$(git diff --name-only HEAD~1 HEAD | grep '^src/' | wc -l) CHANGED_DOC=$(git diff --name-only HEAD~1 HEAD | grep '^docs/design/' | wc -l) if [ "$CHANGED_SRC" -gt 0 ] && [ "$CHANGED_DOC" -eq 0 ]; then echo "错误：修改了源码但未更新设计文档，请同步 docs/design/" exit 1 fi逻辑说明：这个脚本不复杂，但能拦住大部分“忘了改文档”的情况。参数说明：HEAD~1是比较上一次提交，实际使用时可以根据分支策略调整；docs/design/是设计说明书存放路径，按团队习惯改。
4. 避坑：设计说明书里最容易翻车的五个地方
4.1 把“待定”写进文档，然后就没有然后了
现象：文档里出现“具体引脚待硬件确认”“通信协议待定”等字样，评审时大家觉得“后面再说”，结果到了联调阶段发现引脚冲突、协议不兼容。原因：待定项没有责任人、没有截止时间、没有跟踪机制。解决：所有待定项必须写进文档的“开放问题”表格，包含责任人、计划关闭时间、影响范围。每次评审先过这张表，超过两次评审未关闭的升级处理。
4.2 时序图只画正常流程，异常路径全靠脑补
现象：文档里的流程图只有“初始化→采集→处理→输出”一条直线，没有超时、没有重试、没有错误分支。原因：画图的人只想着功能实现，没想异常。解决：强制要求每个状态机至少画出三条异常路径：超时、校验失败、资源不可用。每条异常路径要写清恢复策略和最大恢复时间。
4.3 资源预算只算 RAM 不算 Flash 和栈
现象：代码编译通过，运行一段时间后死机。原因：设计文档只估了全局变量和堆，没估栈深度和 Flash 占用。中断嵌套一深，栈就溢出了。解决：文档里必须有一节“资源预算表”，包含 RAM、Flash、栈（按最坏中断嵌套估算）、堆。栈的估算方法：每个中断的最大栈消耗相加，再乘 1.5 倍安全系数。
4.4 接口定义只写函数名，不写调用上下文
现象：A 模块调用了 B 模块的函数，但 A 在中断里调，B 的函数里有阻塞操作，导致系统卡死。原因：接口定义没写“是否可在中断中调用”。解决：每个接口必须标注调用上下文：仅任务、仅中断、两者皆可。如果两者皆可，必须说明内部是否关中断、是否可重入。
4.5 文档版本和代码版本对不上
现象：客户拿到的文档是 V1.2，实际代码是 V1.5，中间改了三个接口但文档没更新。原因：文档和代码分开管理，没有强制同步机制。解决：文档和代码同仓库，用 Git 标签统一版本。每次发布，文档和代码打同一个标签。CI 里加检查，标签对应的文档目录必须存在且非空。
5. 进阶：让设计说明书成为团队资产而不是负担
5.1 用“设计模式卡片”沉淀可复用决策
当团队做过几个项目后，会发现很多设计决策是重复的：串口 DMA 配置、看门狗策略、低功耗唤醒流程。我习惯把这些沉淀成“设计模式卡片”，每张卡片写清适用场景、约束、参考实现、已知问题。新项目启动时，先翻卡片，能复用就直接引用，不能复用再重新决策。
卡片不写在设计说明书正文里，而是作为附录或独立文档库。设计说明书里只需要写“本设计采用卡片 X 的串口 DMA 方案，差异点如下”。这样既保持了文档的可追溯性，又避免了重复描述。
5.2 把“验证方法”写进设计阶段，而不是测试阶段
很多团队的设计说明书只写“怎么做”，不写“怎么验”。结果测试工程师拿到文档后不知道该怎么测，只能凭经验。我的做法是在每个关键设计章节后面加一小节“验证要点”，写清测试条件、激励方式、预期结果、判定依据。
比如看门狗设计，验证要点会写：测试条件为系统正常运行时，激励方式为手动触发看门狗复位引脚，预期结果为 10ms 内系统复位且复位原因寄存器置位，判定依据为读取复位状态寄存器。这样测试工程师可以直接照着写测试用例，不需要再问设计者。
5.3 一个具体技巧：用“变更影响矩阵”控制修改范围
项目后期最怕改一处崩三处。我一般会在设计说明书里维护一张“变更影响矩阵”，横轴是模块，纵轴是变更类型（接口、时序、资源、状态机）。每次要改东西，先查矩阵，看会影响哪些模块，然后评估是否需要同步修改。
| 变更类型 | 通信模块 | 控制模块 | 存储模块 |
|---|---|---|---|
| 接口变更 | 高 | 中 | 低 |
| 时序变更 | 高 | 高 | 低 |
| 资源变更 | 中 | 中 | 高 |
| 状态机变更 | 低 | 高 | 中 |
这张表不需要很精确，它的作用是逼你在改代码前先想一圈。高影响意味着必须同步评审和更新文档，中影响意味着需要通知相关模块负责人，低影响意味着可以独立修改但仍需记录。
5.4 最后一条血泪经验：文档是写给自己三个月后看的
我踩过最大的坑，是曾经花两周写了一份自认为完美的设计说明书，结果三个月后自己都看不懂里面的缩写和简写。后来我定了一条规矩：文档里出现的每一个缩写，第一次出现时必须写全称；每一个自定义术语，必须在术语表里定义；每一个“参见”必须带章节号。
这份模板的价值不在于它有多规范，而在于它能让你在深夜被叫起来改 bug 时，快速找回当初的设计意图。如果你现在手里正有一份这样的模板，别把它当负担，把它当成给未来自己留的后悔药。希望帮到你。
本文还有配套的精品资源，点击获取
