★ FEATURED ARTICLE 简介面向嵌入式系统课程综合设计与项目文档编写场景的软件设计说明书模板适合电子、计算机及相关专业学生、初入行的嵌入式开发者和需要规范交付文档的小型团队参考。压缩包共1个doc文件约64KB以可直接套用的Word文档形式提供封面、版本历史、目录、编写目的、读者对象、软件项目概述、参考资料、设计目标和原则、设计约束、总体设计、功能说明、功能框图、接口说明、程序编写、源文件列表等章节骨架。内容覆盖嵌入式系统定义与组成、典型应用对象、资源与时序约束、文档管理、项目管理、质量管理及配置管理等知识点读者可据此快速搭建说明书结构补充需求与设计细节统一团队文档格式。已有2574人学习下载适合用作课程设计、毕业设计或企业嵌入式项目设计文档的起步模板。1. 一份没人愿意填的表为什么是嵌入式项目的定心丸装修过的朋友大概都有这个体验工人师傅凭经验干活你嘴上说“这里要个插座”他点头说好等墙砌完、瓷砖贴好你才发现插座被柜子挡住了。返工的成本比当初画一张图纸贵十倍。嵌入式系统开发有点像这种装修——只不过场地更小、返工更贵。通俗地说嵌入式系统就是那些“不是电脑的电脑”手机、掌上电脑、机电设备、家电控制板、车载模块里面都藏着一颗微处理器在干活。它一般由嵌入式微处理器、外围硬件设备、嵌入式操作系统和用户应用程序四部分组成特点是体积小、功耗低、实时性强、可靠性高。而这份“嵌入式系统开发软件设计说明书模板”就是给这四部分怎么咬合、谁调谁、参数怎么传提前画好的那张施工图。它不解决技术难题解决的是“想清楚了再动手”这件事。2. 为什么小设备反而更需要一份写清楚的文档很多人第一反应是大系统才需要文档几块板子、几百行代码脑子里记着不就行了恰恰相反。越小的设备容错空间越窄口头约定失效得越快。2.1 资源就那么一点想清楚才能省下来嵌入式系统最典型的约束不是“能不能做”而是“在这么点资源里能不能做”。一颗主频不高的微处理器、几 KB 的 RAM、一块写着容量上限的 Flash外加一条必须满足的功耗曲线——这些都是硬边界。写代码的时候随手多开一个缓冲区、多挂一个定时器编译能过跑起来就翻车现象还特别玄学偶尔死机、偶尔丢数据、偶尔重启。设计说明书里的“设计约束”章节作用就是把这些硬边界提前摊在桌面上硬件平台是什么、操作系统要求是什么、开发语言和工具链是什么、容量和性能指标是多少、灵活性和配置要求到什么程度。写下来之后后面的每一个设计决定都有了一个可以对照的尺子。打个比方这就像小户型装修。房子大你随便买家具塞得进去就行房子小你必须先量尺寸、先定布局再去买。嵌入式开发的“量尺寸”就是把这些约束写进文档。更实际的一点是约束写下来之后会反向逼出设计。比如容量指标写死了 64KB你在画功能框图的时候就会主动去想这个模块的缓存能不能复用这条日志要不要常驻这些问题在写文档时想成本是一支笔在调试时想成本是几个通宵。设计目标和设计原则那一段看起来最像套话实际上是给后面所有取舍定调子——是优先保证实时性还是优先保证可扩充性这两条路画出来的框图不一样。2.2 那一页签字栏责任边界与协作成本模板的开头有一页很容易被跳过的东西文档编号、产品版本、密级、作者、开发/测试经理、项目经理每人一行后面跟着日期栏。很多人觉得这是形式主义实际上它是整个文档里最便宜、也最有用的一页。先说文档编号。像“项目代号-文档类型-年份-序号-版本”这样一串编号作用不是好看而是让这份文档在整个项目里有一个唯一身份。项目做久了同一份设计会衍生出草稿、评审版、发布版、修改版没有编号你在共享目录里翻到第三个“设计说明_final_v2_改”根本分不清哪份是准的。文件状态那一栏勾选“草稿 / 正式发布 / 正在修改”也是同一个目的让人一眼知道能不能拿它当依据。再说那三行签字。作者签字代表“我写的内容我负责”开发/测试经理签字代表“这份设计我审过、测试能照着它做用例”项目经理签字代表“范围、进度、资源对得上”。三个人站在三个角度看同一份东西签字之前必然要吵几句而吵架的成本远低于联调时发现接口对不上的成本。这里有个血泪经验签字栏空着的文档等于没有文档。大家口头说“看过了”真出问题时谁也说不清当初约定的是什么。签字这个动作本身不值钱值钱的是它强制了一次认真阅读。2.3 半年后的自己是最难沟通的读者模板 1.2 节要求写“读者对象”很多人填一句“项目组成员”就过去了。这个栏目的真实用途是提醒你这份文档的读者里有一个半年后的你自己。半年后的你已经忘了当时为什么把采样周期定成 20 毫秒忘了那个全局变量为什么要加锁忘了某个函数为什么要多传一个看起来没用的参数。这时候你翻回设计说明书如果 3.3 节里写清了主程序的功能、入口参数、出口参数、局部变量、函数调用关系你五分钟就能找回上下文如果那里只有一句“此处加入功能”你只能重新读代码而读代码理解意图的成本是写文档的十倍。所以这份模板的填空位不是给人交差的是给未来的自己留的后悔药。写得越具体将来吃得越少。还有一类读者常被忽略接手维护的人。产品卖出去三年原班人马早换了新来的人拿到的是代码和一箱文档。代码告诉你“是什么”文档告诉你“为什么”。没有“为什么”维护者只敢在最外层打补丁不敢动结构系统就这样一点点僵掉。3. 拆开骨架一份设计说明书的三段式把这份模板从头翻到尾结构其实非常干净引言、设计约束、设计描述。三段的顺序不是随便排的它是“先交代背景再划定边界最后描述方案”的认知顺序跟工程师思考问题的顺序是一致的。3.1 引言把项目坐标钉死第一章“引言”下面有六个小节编写目的、读者对象、软件项目概述、文档概述、定义、参考资料。看起来都是软性内容但它们解决的是一个很硬的问题让任何一个拿到文档的人在五分钟内知道自己在看什么。“软件项目概述”要求写清项目名称、简称、项目代号、用户单位、开发单位主管部门以及软件的大致功能和性能要求。这一节是整份文档的坐标原点。后面所有的设计描述都是在这个原点上展开的。如果这里写的是“本软件用于某设备的控制与数据采集”但没写清采集什么信号、控制什么动作、性能到什么量级那后面的功能框图就只能靠读者猜。“定义”这一节看似可有可无实际上是团队沟通的润滑剂。嵌入式项目里充满了容易引起歧义的词采样周期到底指中断间隔还是任务周期复位是指硬件复位还是逻辑复位缓冲区长度含不含头尾指针这些词在每个人的脑子里含义都略有不同写进术语表等于给全组统一了口径。模板里特意写了“容易引起歧义的概念、关键词缩写”这句话是真经验。“参考资料”要求以列表或排序方式给出名称、作者、单位、出版日期。它的价值在于可追溯设计里引用的芯片手册版本、协议标准号、内部规范编号全都落在这里将来出了争议能顺着这条线找回原始依据。提示引言部分最好在项目早期就写完然后随项目推进不断回填。等到项目结束再补写出来的多半是“事后合理化”不是真实的设计意图。3.2 设计约束把“不能动的”先写下来第二章只有两节设计目标和原则、设计约束。字数不多但分量最重。“设计目标”回答的是“这个设计想达到什么”比如完整实现用户需求、系统具备良好的可扩充性、关键路径的响应时间控制在一定范围内。“设计原则”回答的是“为了达到目标我们遵循什么规矩”比如模块之间只通过明确定义的接口通信、不在中断里做耗时操作、所有硬件访问集中到一个抽象层。这两段话是后面所有设计决定的裁判规则。评审的时候一句“这个写法违反了本项目的设计原则”比十句“我觉得这样不好”有效得多。“设计约束”列的是那些不由你决定的条件硬件平台、操作系统要求、开发语言、开发工具、容量和性能要求、灵活性和配置要求。这些条件一旦写下来设计空间就被框住了而框住的空间反而更容易做决策。举个具体的例子。假设约束里写着“操作系统要求某实时操作系统任务栈总和不超过 8KB”。那么在设计描述阶段你划分任务的时候就会自然地合并一些小任务而不是每个功能开一个任务。如果没有这条约束你可能先画出五个任务等到链接阶段发现内存不够再回头拆——这时候改的不是一行代码是整个任务间的通信结构。约束写得越具体返工越少。反过来如果这一章只写“硬件平台待定”那这份文档基本等于没写因为最大的变量还悬在空中。3.3 设计描述总体设计、接口说明、程序编写第三章是整份模板的主体也是最容易写空的地方。它分成三块总体设计、接口说明、程序编写外加源文件列表和相关参考资料。总体设计部分先给功能说明再给功能框图。模板对总体设计提了五条要求值得逐条说要求含义没做到会怎样完全覆盖所有用户需求联调时才发现漏了一个功能准确文字与图形多视角精确描述图和文字对不上实现者各取所需一致无二义同一概念用同一术语同一个模块在三处有三个名字直观简洁描述精炼、言简意赅文档越写越厚没人看得完可追踪每项设计都能追回某条需求需求变更时不知道要改哪里“可追踪”这一条最容易被低估。它的意思是功能框图里的每一个方框都应该能对应到一条具体的用户需求反过来每一条需求都应该能在设计里找到落点。做到这一点需求一变你立刻知道要动哪几个模块做不到需求一变只能全盘重读。模板还很贴心地给了两种表述方式的建议面向数据流的建模方法用层次图、HIPO 图、结构图配文字说明面向对象的建模方法用类图、对象图、状态图、顺序图、活动图配文字说明。这个提示的潜台词是图不是装饰是主要表达手段文字负责解释图里画不出来的东西比如时序假设、异常分支、边界条件。接口说明部分要求“详细描述软件接口”。这里的接口不止是函数签名还包括模块之间的调用约定、数据格式、时序要求、异常返回。一个常见的踩坑是只写了正常路径的参数含义没写参数非法时返回什么结果调用方和被调用方各自实现了一套错误处理对接时全靠猜。程序编写部分分成主程序和子程序两块每块都有固定的描述项功能、入口参数、出口参数、局部变量、函数调用、对象调用、流程图。这套模板的价值就在于它把“描述一个函数”拆成了几个必须回答的问题逼着你把函数的边界想清楚。第 5 章会专门展开这套七要素。4. 几个最容易混淆的概念别把设计说明书写成需求文档模板用起来最常出现的偏差不是填得不够多而是填错了地方。下面这几组概念初学时几乎必然混淆。4.1 需求文档与设计说明书一个说“要什么”一个说“怎么给”易混点两者都在描述系统都在项目早期产出章节结构甚至有点像。为什么混因为很多项目的需求写得像设计——“系统应提供 100ms 周期的数据刷新”这句话既可以读成需求也可以读成设计。边界一模糊两份文档就开始互相抄。怎么区分看这句话能不能被替换。需求回答“用户要什么”是站在外部视角描述可观察的行为比如“设备应在 2 秒内完成上电自检并进入待机”。设计回答“我们打算怎么做”是站在内部视角描述实现方案比如“自检由主程序在初始化阶段调用三个子程序完成依次检查存储、传感器和通信链路”。同一个功能需求只有一句设计可以有一页。判断方法很简单如果一句话里出现了具体的模块名、函数名、变量名它大概率属于设计不该出现在需求里。4.2 概要设计与详细设计同一份文档的两层楼易混点模板标题写的是“软件详细设计报告”但里面又有“总体设计”看起来自相矛盾。为什么混因为很多小项目把两层合并成一份文档写久而久之就分不清哪部分属于哪层。怎么区分看描述粒度。总体设计回答“系统分成几个子系统、模块之间怎么划分、数据怎么流动”颗粒度到模块详细设计回答“每个函数做什么、参数怎么传、内部怎么算”颗粒度到函数。模板里的处理方式很务实一份文档里既有 3.1 总体设计的框图又有 3.3 程序编写的逐个函数说明等于把两层楼画在了同一张图纸上。项目小的时候这样合并是合理的但心里要清楚哪段属于哪层——评审的时候总体设计该由架构角色把关程序编写该由实现角色把关责任人不一样的。4.3 接口说明与协议文档一个是“我们之间怎么调”一个是“线路上怎么传”易混点都叫“接口”都涉及通信。为什么混嵌入式系统里模块之间的软件接口和设备之间的通信协议经常交织在一起一个函数内部可能同时处理两件事。怎么区分看它约束的是谁。软件接口约束的是代码之间的关系谁调用谁、传什么参数、返回什么、出错怎么办改它只需要两边一起改代码。通信协议约束的是设备之间的关系帧格式、校验方式、超时重传规则改它可能牵动外部设备甚至已出货的产品。设计说明书里的“接口说明”主要指前者但通常会把后者作为约束条件引用进来。写的时候分开写将来改动时才知道动了哪一层。4.4 填模板与做设计表格填满了不等于设计做完了易混点模板有固定栏目填完看上去就完整了。为什么混模板的栏目本身有暗示性人会本能地把格子填满而不是把问题想透。怎么区分看栏目之间是否互相印证。功能框图里的每个方框在程序编写部分应该能找到对应的主程序或子程序说明设计约束里写的容量指标在总体设计里应该能找到对应的取舍理由参考资料里列的芯片手册版本应该和设计约束里的硬件平台一致。如果这些对不上说明表格是分开填的设计没有真正贯通。一份好的设计说明书从头读到尾应该是一条线而不是一堆互不相干的段落。注意这四组混淆里第一种最常见危害也最大。设计说明书写成需求文档会导致实现阶段没有依据最后所有人都回去读需求设计文档变成摆设。5. 那些“填空位”的门道主程序七要素与功能框图模板里最像“填空题”的部分是 3.3.1 主程序和 3.3.2 子程序的七个描述项。很多人觉得这就是走流程实际上这七项是一套很聪明的检查清单。5.1 主程序七要素把函数的边界想清楚七个描述项分别是功能、入口参数、出口参数、局部变量、函数调用、对象调用、流程图。它们不是随便列的而是沿着“这个函数对外承诺什么、内部用到什么、依赖谁”的顺序展开。先看一个照着这套模板写的函数说明示例/* * 功能按固定周期采集一次温度写入环形缓冲区 * 入口参数period_ms 采样周期单位毫秒取值范围 10 ~ 1000 * buf 环形缓冲区首地址调用方保证非空 * buf_len 缓冲区长度单位字节必须是 2 的整数次幂 * 出口参数返回值 实际写入的样本数缓冲区满时返回 0不阻塞 * 局部变量raw_adc 当前通道的原始采样值 * temp_x10 换算后的温度值放大 10 倍以整数保存 * 函数调用adc_read_once()、temp_convert() * 对象调用无 */ int temp_sample_once(uint16_t period_ms, int16_t *buf, uint8_t buf_len) { int16_t raw_adc 0; if (buf 0 || buf_len 0) { return 0; /* 参数非法直接返回由调用方处理 */ } if (adc_read_once(raw_adc) ! 0) { return 0; /* 硬件读取失败本次采样作废 */ } return ringbuf_write(buf, buf_len, temp_convert(raw_adc)); }这段代码本身很简单重点是它上面的注释块和模板七个栏目的对应关系。功能一栏写的是“做什么”不是“怎么实现”入口参数一栏不只是列名字还给出了取值范围和调用方的前置责任——缓冲区必须非空这个约定如果没写在文档里实现者就可能省掉判空调用方就可能传空指针两边都觉得对方会处理。出口参数一栏写清了“缓冲区满时返回 0不阻塞”这一句非常关键。它定义了函数在极端情况下的行为而这个行为会直接影响调用方的设计如果调用方是周期任务返回 0 时可以下个周期再来如果调用方是中断就必须准备一个降级路径。这类约定写到文档里联调时能省掉一整天。局部变量那一栏看起来最没营养其实是给资源核算用的。嵌入式的栈空间是按字节算的一个函数里开了多大的局部数组、用了几个临时变量累积起来就是栈深度。这项写清楚将来算最坏栈用量时才有依据。函数调用和对象调用两栏本质是在画依赖图。谁依赖谁一目了然。哪天底层驱动要换接口顺着这份文档就能找出所有受影响的函数不至于改完一个漏一个。流程图那一栏则是给复杂分支用的简单的顺序逻辑可以不画但只要函数里有三种以上的状态转移画出来比写十行文字都清楚。七项写全等于把这个函数的对外契约、内部开销、依赖关系全部固定下来了。这就是模板真正的用处它逼你在写代码之前先想清楚函数的“合同条款”。5.2 功能框图与可追踪性每根线都要能追回一条需求3.1.2 要求画功能框图模板没有规定必须用什么画法只给了两类建议数据流方法用层次图、HIPO 图、结构图面向对象方法用类图、对象图、状态图、顺序图、活动图。选哪种不重要重要的是图要能回答三个问题。第一个问题是分层。一个系统拆成几个子系统子系统下面拆成几个模块层次要清晰。层次混乱的框图画出来像蜘蛛网看着很全实际上没人能从里面读出结构。第二个问题是连线含义。两个方框之间那条线是调用关系、数据流向还是依赖关系同一个图里不能混用。混用的后果是读者按调用关系去理解结果发现方向反了。第三个问题是可追踪。这是模板在总体设计里明确提出的要求所有的设计内容都是对某项或者某些用户需求的软件实现。执行方法很朴素给每条需求编个号在功能说明里标注这个模块对应哪几条需求。将来需求变更先查这张对照表就知道要动哪一块。没有这张表需求变更就只能靠人肉回忆而人肉回忆在项目后期基本不可靠。5.3 源文件列表配置管理的第一张底账3.4 节要求给出源文件列表。这一栏在很多模板里被当成凑数的实际上它是版本管理的第一张底账。源文件列表至少应该包含文件名、所属模块、大致行数、对应的功能点、是否有第三方来源。有了这份清单打包发布时能核对有没有漏文件代码交接时能估算工作量做配置管理时能确定哪些文件纳入版本控制。嵌入式项目还有一个特殊之处经常混用第三方库和自研代码。把来源标清楚将来出了问题才能界定责任范围也才知道升级第三方组件时会影响哪些模块。这份清单不需要多精细但必须有而且要随代码同步更新——写完就不管的清单比没有更误导人。6. 什么时候该掏出这份模板什么时候别硬套模板是好东西但它有明确的适用边界。用错了地方它就是一叠废纸。适合用的场景有个共同特征项目有人交接、有时间跨度、有协作方。比如课程里的综合设计三五个人一组各自写一块最后要合起来跑通——这种场景下设计说明书能把接口和数据流提前对齐省掉大量联调扯皮。再比如小批量交付的机电控制项目硬件已经定型软件要迭代几轮文档就是每轮迭代的起点。还有一种是需要评审或归档的项目签字栏、版本历史、密级那一套流程本身就是交付物的一部分这时候模板的规范性直接等于合规性。不太适合硬套的场景也很清楚。一是探索性验证比如花两天验证某个传感器能不能用这时候写完整的设计说明书纯属浪费写一页纸的记录就够了。二是极小规模的单人项目一个文件几百行改动全靠记忆模板的签字和评审流程会变成空转。三是需求还在剧烈变动的阶段这时候写出来的“详细设计”大概率两周后就作废不如先写一页纸的总体设计等方向稳了再补细节。判断标准可以简化成一句话这份文档未来会不会被第二个人包括半年后的你当作依据来读会就写不会就别写。场景特征建议做法多人协作、模块要对接完整填写重点写接口说明和功能框图需要交付或归档完整填写签字栏和版本历史不能空需求稳定、要迭代多轮完整填写重点写设计约束和源文件列表单人短期验证只写项目概述和设计约束其余留空需求剧烈变动期先写总体设计和功能框图详细设计后补有一个具体的例子值得说。某开发小组做过一个采集控制类的小系统硬件是现成的评估板软件四个模块分给四个人写。开工前花半天把模板里的引言和设计约束填了功能框图手绘了一版拍照贴进去接口说明只写了每个模块对外暴露的三个函数及其参数含义。就这半天的投入在后面联调时省下了至少两天的扯皮——因为四个人对“采样周期从哪来”“缓冲区满了怎么办”这两个问题有统一答案不需要每次碰到就吵一遍。反倒是程序编写那一章当时几乎留空等代码写完才回填效果也不差因为那时候细节才真正定型。反过来也有教训。另一个项目一开始就想把模板填满程序编写部分在代码还没写的时候硬编了一堆函数说明结果实现方案改了三次文档跟着改三次最后谁都不信文档里的内容了。文档一旦失去可信度后面写什么都没人看。从那以后我每次拿到这类模板都强制走一遍这个顺序先填引言和设计约束把边界钉死再画功能框图把结构定下来接口说明跟着框图走一边画一边写程序编写那一章留到最后代码定型了再回填。顺序对了模板就是脚手架顺序反了模板就是负担。这份嵌入式系统开发软件设计说明书模板价值不在于那些表格本身而在于它替你问出了那些容易忘记问的问题约束是什么、接口怎么定、这个函数对调用方承诺了什么、半年后的人能不能看懂。需要的话资源里就是完整的一份可以直接拿来改。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
