USB升级模块软件详细设计书.docx

1、USB升级模块软件详细设计书文 档 编 号版本号密级JL-TD01-XMBH-KHBH-DSDV1.00机密USB升级模块软件详细设计书文档作者：朱海峰日期：2011-10-20项目经理：日期：审 核：日期：批 准：日期：文档历史发放及记录序号变更（+/-）说明作者版本号日期批准1创建朱海峰1.02011-10-20文档简要功能及适用范围1. 文档的简要功能本文档的简要功能说明。文档详细说明了USB升级模块的设计内容。为代码实现以及测试提供依据，方便维护。2. 文档的适用范围本文档适用于哪些人员、哪些项目、哪些领域等。本文档适用于公司内部所有开发人员。1、 引言1.1 背景简要说明该产品的市场

2、背景和主要特点。目前，我们的软件中有USB升级模块，但是功能上、设计上都没有很好的规划过。这使得在实际应用中，我们还是会不断的做重复的工作。同时，相关文档、代码质量等指标，都没有达到一定的要求。USB升级模块需求阶段通过。1.2 产品信息产品名称：USB升级模块1.3 软件名称说明本文档对应的软件模块的正式名称和版本号。USB升级模块USBUpgradeProc1.4 术语和缩略语对文中使用的术语和缩略语进行说明。缩略语/术语全 称说 明1.5 参考资料编写本文档时引用或参考的文档资料、有关标准等。USB升级模块需求报告.doc2、 模块系统结构2.1 功能需求详细说明本软件模块应实现的所有功

3、能。1、从U盘指定路径读取升级文件（*.img/*.IMG），并存储到内存。2、校验读取到的升级文件的IMG头信息，同Loader的相关版本信息做比较。提供强制升级和限制升级两种升级方式的校验处理。 强制升级：比较OUI、厂商号和硬件版本号。 限制升级：比较OUI、厂商号、硬件版本号、软件版本号。其他条件暂时不作考虑，有实际需求时再处理。3、对升级文件进行CRC校验，若有附加数据，则对第一个IMG数据进行校验。4、判断升级文件IMG头Flag标志位，进行升级数据是否去IMG头的处理。(适用于素材、字库等情况)5、判断升级文件IMG头中的文件数据类型Image_type，来处理升级多Flash情

4、况时（高清平台），写在哪个Flash上，调用相应的Flash处理函数。6、满足可以升级附加数据要求，即在升级过程中，不再以升级文件头部的IMG头信息（如长度，CRC值）为升级数据量大小的依据，而以整个文件的大小来计算存储的数据量。7、将正确的升级文件数据保存到Flash中。8、显示升级过程。9、若升级过程中出错，显示相应的错误信息。10、升级完成后，自动重启机顶盒。11、预留平台级别的外部接口：Flash相关读写调用接口，前面板显示接口。使模块同平台分享。12、预留菜单显示级别的外部接口，将菜单分享出来。13、提供模块测试接口。14、预留对其它升级文件格式的支持空间。2.2 模块在系统中的位置

5、采用图形表示该软件模块在系统中的位置，以说明其在系统中的作用。如图示，USB升级模块属于应用层的一个通用功能模块，在实际项目中应用比较广泛。模块内部实现相关升级的功能，对外提供相关接口，为功能模块提供平台、菜单等级别的功能支持。2.3 子模块划分用图表列出本模块系统内的每个项（包括子模块、子程序和函数）的名称、标识符和它们之间的层次结构关系。 USBUpgrade子模块为USB升级功能模块的主功能模块，升级流程控制均在该子模块中控制。 CRC子模块：为USBUpgrade子模块提供CRC校验接口。 USBUpgrade_cfg子模块：从USB升级模块中分离出来的，与平台和菜单相关的功能部分，如

6、Flash操作、菜单等。因为这些在实际应用中，要求都会不同，所以独立开来由用户去配置。2.4 子模块间关系说明各子模块、子程序、函数之间的控制、顺序、消息传递等耦合关系，并简要说明有关的重要数据结构或对象在这些耦合关系中所起的作用。如图示： USBUpgrade子模块：为外部提供唯一USBUpgrade_Start()接口，调用该功能模块； CRC子模块：为USBUpgrade子模块提供初始化接口和CRC校验接口； USBUpgrade_cfg子模块：为USBUpgrade子模块提供VerifyImgHeader()、WriteImg2Flash()和MsgProc()三个接口。 Verify

7、ImgHeader()和WriteImg2Flash ()均返回处理结果的状态码； MsgProc ()处理升级过程中的所有错误状态码，并显示在OSD上。3. 数据类型说明给出本软件使用的每一个公共数据结构的类型定义、存储方式，以及其内部各元素项的类型定义、初始取值、可能取值范围及相应的含义，必要的话，应说明具体的操作方法。如果是面向对象的设计，应详细阐述所有类和对象的外部行为特征和内部实现细节，还有所有类的继承关系和多态性实现，以及其他有关的对象设计细节。3.1 类型1类型定义：typedef struct UI32 uwFileLength; UI32 uwFileAddr; UI32 u

8、wFileCrc; UI8 *pubImgHeader; UI8 *pubImgBuf; UI8 ubImageType; UI8 ubDelHeadFlg; UI16 uhwUserDataLen;IMG_INFO;头文件：含义：数据项含义UI32 uwFileLength;升级文件长度UI32 uwFileAddr;升级文件写入Flash地址UI32 uwFileCrc;升级文件CRC值UI8 *pubImgHeader;升级文件IMG头部UI8 *pubImgBuf;升级文件数据缓冲区UI8 ubImageType;升级文件IMG类型UI8 ubDelHeadFlg;升级文件去IMG头标

9、志UI16 uhwUserDataLen;升级用户自定义数据长度存储方式：模块内全局变量。初始取值：数据项初始值uwFileAddr0x00uwFileCrc0x00uwFileLength0x00pubImgHeaderNULLpubImgBufNULLubImageType0x00ubDelHeadFlg0x00uhwUserDataLen0x00可能取值范围及含义：数据项取值范围含义uwFileAddrFlash大小Flash地址uwFileCrc自然数CRC32计算结果uwFileLengthFlash大小Flash大小，为Flash的最大存储量pubImgHeader有效内存地址指向

10、存储升级文件IMG头部的内存地址pubImgBuf有效内存地址指向存储升级文件数据的内存地址ubImageType0LOADER1APP2BOOT3FONT4LOGO5BACKGROUND6MENU7未定义ubDelHeadFlg0存储IMG数据时，保留IMG头部及UserData1存储IMG数据时，不保留IMG头部及UserDatauhwUserDataLen自然数应用自定义数据长度3.2 类型1类型定义：typedef enum USBMSG_OK, USBMSG_CANT_OPEN_USB, USBMSG_CANT_OPEN_DIR, USBMSG_CANT_OPEN_IMG, USBM

11、SG_FILE_NOT_EXIST, USBMSG_FILE_READ_ERROR, USBMSG_OUI_ERROR, USBMSG_MID_ERROR, USBMSG_HW_ERROR, USBMSG_CRC_ERROR, USBMSG_ERASE_ERROR, USBMSG_WRITE_ERROR, USBMSG_OTHER_ERRORUSBMSG_E;头文件：USBUpgradeproc.h含义：数据项含义USBMSG_OK,OKUSBMSG_CANT_OPEN_USB,无法打开U盘USBMSG_CANT_OPEN_DIR,无法打开文件夹USBMSG_CANT_OPEN_IMG,无法打

12、开IMG文件USBMSG_FILE_NOT_EXIST,文件不存在USBMSG_FILE_READ_ERROR,文件读取出错USBMSG_OUI_ERROR,升级文件OUI错误USBMSG_MID_ERROR,升级文件厂商号错误USBMSG_HW_ERROR,升级文件硬件版本号错误USBMSG_CRC_ERROR,升级文件CRC校验错误USBMSG_ERASE_ERROR,擦除Flash出错USBMSG_WRITE_ERROR,写Flash出错USBMSG_OTHER_ERROR其它错误存储方式：初始取值：数据项初始化值USBMSG_OK,0USBMSG_CANT_OPEN_USB,1USBM

13、SG_CANT_OPEN_DIR,2USBMSG_CANT_OPEN_IMG,3USBMSG_FILE_NOT_EXIST,4USBMSG_FILE_READ_ERROR,5USBMSG_OUI_ERROR,6USBMSG_MID_ERROR,7USBMSG_HW_ERROR,8USBMSG_CRC_ERROR,9USBMSG_ERASE_ERROR,10USBMSG_WRITE_ERROR,11USBMSG_OTHER_ERROR12可能取值范围及含义：4. 函数说明4.1 函数14.1.1 原型定义void USBUpgrade_Start(void)4.1.2 头文件USBUpgrade

14、proc.hvoid USBUpgrade_Start(void)4.1.3 功能和性能说明对该函数的全部功能和性能（包括精度、灵活性和时间特性等）的要求本函数为外部接口，供外部调用该模块。本函数调用初始化函数和USB升级主函数，实现USB升级功能。4.1.4 设计特点说明本函数的特点（如，是常驻内存还是非常驻？是可重入的还是不可重入的？有无覆盖要求？是顺序处理还是并发处理等）。4.1.5 输入参数逐个说明每一个输入参数的特性，包括名称、标识、数据的类型和格式、数据值的有效范围、参数值的意义、输入的形式、特殊取值的定义（如跟硬件相关的取值）。4.1.6 输出参数给出对每一个输出参数的特性，包括

15、名称、标识、数据的类型和格式、数据值的有效范围、参数值的意义、输出的形式等。4.1.7 返回值返回值的说明，成功、失败类型的定义4.1.8 算法详细说明本函数所选用的算法，具体的计算公式和计算步骤。4.1.9 逻辑流程用图表辅以必要的说明来表示本函数的逻辑流程。4.1.10 与其他函数关系说明本函数与其他函数之间的关系，说明参数赋值和调用方式，说明与本函数相直接关联的数据结构。本函数调用初始化函数，进行模块数据结构、CRC初始化，置初始化标志位： USBUpgrade_Initialize()调用升级主函数，处理升级流程： USBUpgradeProc()本函数供外部调用，调用USB升级功能。

16、4.1.11 存储分配根据需要，说明本函数的存储分配。4.1.12 限制条件说明本函数运行中所受到的限制条件。4.1.13 调试方法说明对本函数进行调试的基本方法。4.2 函数24.2.1 原型定义static void USBUpgrade_Initialize(void)4.2.2 头文件static void USBUpgrade_Initialize(void)4.2.3 功能和性能说明对该函数的全部功能和性能（包括精度、灵活性和时间特性等）的要求本函数初始化升级过程中要用到的数据结构，进行CRC初始化，以及置模块初始化标志位。4.2.4 设计特点说明本函数的特点（如，是常驻内存还是非

17、常驻？是可重入的还是不可重入的？有无覆盖要求？是顺序处理还是并发处理等）。本函数非常驻内容，但是初始化的数据结构体与模块初始化标志位会常驻内存。4.2.5 输入参数逐个说明每一个输入参数的特性，包括名称、标识、数据的类型和格式、数据值的有效范围、参数值的意义、输入的形式、特殊取值的定义（如跟硬件相关的取值）。4.2.6 输出参数给出对每一个输出参数的特性，包括名称、标识、数据的类型和格式、数据值的有效范围、参数值的意义、输出的形式等。4.2.7 返回值返回值的说明，成功、失败类型的定义4.2.8 算法详细说明本函数所选用的算法，具体的计算公式和计算步骤。4.2.9 逻辑流程用图表辅以必要的说明

18、来表示本函数的逻辑流程。 初始化数据结构体； 初始化CRC模块； 置模块初始化标志位。4.2.10 与其他函数关系说明本函数与其他函数之间的关系，说明参数赋值和调用方式，说明与本函数相直接关联的数据结构。本函数调用CRC子模块初始化接口函数对CRC子模块进行初始化操作： Init_Crc_32_Tab() 本函数供模块外部调用接口函数USBUpgrade_Start()调用4.2.11 存储分配根据需要，说明本函数的存储分配。4.2.12 限制条件说明本函数运行中所受到的限制条件。4.2.13 调试方法说明对本函数进行调试的基本方法。4.3 函数34.3.1 原型定义static void U

19、SBUpgradeProc(void)4.3.2 头文件static void USBUpgradeProc(void)4.3.3 功能和性能说明对该函数的全部功能和性能（包括精度、灵活性和时间特性等）的要求本函数为功能模块的主流程处理函数，升级过程中的各个处理过程均本函数中控制。若升级过程中产生错误，本函数将调用USBUpgrade_MsgProc ()函数，在OSD上显示错误信息。4.3.4 设计特点说明本函数的特点（如，是常驻内存还是非常驻？是可重入的还是不可重入的？有无覆盖要求？是顺序处理还是并发处理等）。本函数为顺序处理过程。4.3.5 输入参数逐个说明每一个输入参数的特性，包括名称

20、、标识、数据的类型和格式、数据值的有效范围、参数值的意义、输入的形式、特殊取值的定义（如跟硬件相关的取值）。4.3.6 输出参数给出对每一个输出参数的特性，包括名称、标识、数据的类型和格式、数据值的有效范围、参数值的意义、输出的形式等。4.3.7 返回值返回值的说明，成功、失败类型的定义4.3.8 算法详细说明本函数所选用的算法，具体的计算公式和计算步骤。4.3.9 逻辑流程用图表辅以必要的说明来表示本函数的逻辑流程。4.3.10 与其他函数关系说明本函数与其他函数之间的关系，说明参数赋值和调用方式，说明与本函数相直接关联的数据结构。本函数控制整个升级模块的升级流程，调用各个功能函数处理各个过

21、程： USBUpgrade_Initialize() USBUpgrade_GetImgFile() USBUpgrade_ReadImgFile() USBUpgrade_VerifyImgHeader() USBUpgrade_VerifyImgCRC() USBUpgrade_WriteImg() USBUpgrade_Restart()调用错误处理函数，处理升级过程中产生的错误，并在OSD上显示错误信息：USBUpgrade_ErrorCodeProc()本函数供模块外部调用接口函数USBUpgrade_Start()调用4.3.11 存储分配根据需要，说明本函数的存储分配。4.3.1

22、2 限制条件说明本函数运行中所受到的限制条件。模块初始化函数已经正常运行。本函数运行前，应该确保STB正常运行，并且留有可观的内存供使用。通常情况下，会需要数M的内存空间供使用，根据不同的项目、不同的平台，会有不同的软件大小，因此需要的内存空间也就不同。Flash、USB、文件系统驱动均可正常使用。4.3.13 调试方法说明对本函数进行调试的基本方法。4.4 函数4类似函数1，说明函数2的设计考虑要点。4.4.1 原型定义static USBMSG_E USBUpgrade_GetImgFile(const I8 *pubRootPath)4.4.2 头文件static USBMSG_E US

23、BUpgrade_GetImgFile(const I8 *pubRootPath)4.4.3 功能和性能说明对该函数的全部功能和性能（包括精度、灵活性和时间特性等）的要求本函数将到指定的路径（U盘根目录:/update）下去查找升级文件，并得到升级文件的相关信息，如文件名、文件类型等。4.4.4 设计特点说明本函数的特点（如，是常驻内存还是非常驻？是可重入的还是不可重入的？有无覆盖要求？是顺序处理还是并发处理等）。 4.4.5 输入参数逐个说明每一个输入参数的特性，包括名称、标识、数据的类型和格式、数据值的有效范围、参数值的意义、输入的形式、特殊取值的定义（如跟硬件相关的取值）。const

24、I8 *pubRootPath ：指定的升级文件查找路径，这字符常量，如：A:/update4.4.6 输出参数给出对每一个输出参数的特性，包括名称、标识、数据的类型和格式、数据值的有效范围、参数值的意义、输出的形式等。4.4.7 返回值返回值的说明，成功、失败类型的定义 数据类型：USBMSG_E4.4.8 算法详细说明本函数所选用的算法，具体的计算公式和计算步骤。4.4.9 逻辑流程用图表辅以必要的说明来表示本函数的逻辑流程。4.4.10 与其他函数关系说明本函数与其他函数之间的关系，说明参数赋值和调用方式，说明与本函数相直接关联的数据结构。本函数主要调用FS功能函数，来查找U盘中的升级文

25、件： DVD_FS_OpenFileSystem() DVD_FS_OpenDir() DVD_FS_GetDirCount() DVD_FS_ReadDir()调用系统函数申请和释放文件列表的内存空间： DOS_FreeMemory() DOS_AllocMemory()本函数供模块主流程函数USBUpgradeProc()调用。4.4.11 存储分配根据需要，说明本函数的存储分配。4.4.12 限制条件说明本函数运行中所受到的限制条件。指定路径应该有效。4.4.13 调试方法说明对本函数进行调试的基本方法。4.5 函数54.5.1 原型定义static USBMSG_E USBUpgrad

26、e_ReadImgFile(const UI8 *pubRootPath)4.5.2 头文件static USBMSG_E USBUpgrade_ReadImgFile(const UI8 *pubRootPath)4.5.3 功能和性能说明对该函数的全部功能和性能（包括精度、灵活性和时间特性等）的要求本函数根据函数USBUpgrade_GetImgFile()所查找到的升级文件信息，读取升级文件的数据到内存中，并获取文件的相关IMG头部信息。4.5.4 设计特点说明本函数的特点（如，是常驻内存还是非常驻？是可重入的还是不可重入的？有无覆盖要求？是顺序处理还是并发处理等）。升级过程的数据结构体

27、将常驻内存，数据结构体中包含升级文件数据和升级文件IMG头部等信息。这些内存空间只有在升级完成或者升级失败时才会被释放。4.5.5 输入参数逐个说明每一个输入参数的特性，包括名称、标识、数据的类型和格式、数据值的有效范围、参数值的意义、输入的形式、特殊取值的定义（如跟硬件相关的取值）。 const I8 *pubRootPath ：指定的升级文件查找路径，为字符常量，如：A:/update4.5.6 输出参数给出对每一个输出参数的特性，包括名称、标识、数据的类型和格式、数据值的有效范围、参数值的意义、输出的形式等。4.5.7 返回值返回值的说明，成功、失败类型的定义数据类型：USBMSG_E4

28、.5.8 算法详细说明本函数所选用的算法，具体的计算公式和计算步骤。4.5.9 逻辑流程用图表辅以必要的说明来表示本函数的逻辑流程。4.5.10 与其他函数关系说明本函数与其他函数之间的关系，说明参数赋值和调用方式，说明与本函数相直接关联的数据结构。本函数调用FS功能函数，读取升级文件数据，并存储在内存中： DVD_FS_Open() DVD_FS_GetLength() DVD_FS_Read()调用系统函数，为升级文件数据申请内存空间： DOS_AllocAlignMemory()本函数供模块主流程函数USBUpgradeProc()调用。4.5.11 存储分配根据需要，说明本函数的存储分配。4.5.12 限制条件说明本函数运行中所受到的限制条件。指定路径应该有效。4.5.13 调试方法说明对本函数进行调试的基本方法。4.6 函数64.6.1 原型定义USBMSG_E USBUpgrade_VerifyImgHeader(void *ptIMGHeader)4.6.2 头文件USBUpgrade_cfg.hUSBMSG_E USBUpgrade_VerifyImgHeader(void *ptIMGHeader)4.6.3 功能和性能说明对该函数的全部功能和性能（包括精度、灵活性和时间特性等）的要求本函数为USBUpgrade_cfg子模块中的函数。