Boot loader + APP + 上位机 GUI 代码功能说明与移植指南

源代码下载关键字：BOOT_GUI_APP_260421

功能说明与移植指南

1. 文档目的

本文档用于说明当前公开代码包的功能边界、目录职责、模块关系、典型升级流程以及移植步骤。

这份公开包的定位不是完整产品工程，而是一个可参考、可裁剪、可移植的 Boot 升级链路示例，重点覆盖：

Bootloader 固件入口与升级主流程
SCI Boot 协议与 Flash 写入流程
双 metadata 状态管理
Boot / APP 版本信息识别
Host GUI 的 Boot 升级部分
APP 侧进入 Boot 与版本信息的模板桩

明确不包含：

APP 控制算法
功率级业务逻辑
产品规格、参数阈值和完整状态机
完整运行态 GUI、遥测、业务参数页、故障页

2. 代码包目录说明

public_boot_gui_release/├── README_CN.md├── docs/│   ├── PUBLIC_SCOPE_CN.md│   ├── PORTING_GUIDE_CN.md│   └── FUNCTION_AND_PORTING_GUIDE_CN.md├── bootloader/│   ├── inc/│   │   ├── boot_protocol.h│   │   └── boot_mode.h│   ├── src/│   │   ├── boot_main.c│   │   ├── boot_sci.c│   │   ├── boot_flash.c│   │   ├── boot_jump.c│   │   └── boot_version_info.c│   └── linker/│       ├── f28003x_bootloader_flash_lnk.cmd│       ├── f28003x_app_flash_lnk.cmd│       └── app_info_section_snippet.cmd├── system/│   ├── inc/│   │   ├── boot_meta_v2.h│   │   ├── boot_diag_status.h│   │   └── version_info.h│   └── src/│       ├── boot_meta_v2.c│       ├── boot_diag_status.c│       └── version_info.c├── host_gui_boot/│   ├── bootloader_protocol.py│   ├── bootloader_worker.py│   ├── firmware_image.py│   ├── main_boot_gui.py│   ├── requirements.txt│   └── README_CN.md└── app_port_stub/    ├── boot_request_porting_template.h    ├── boot_request_porting_template.c    ├── app_device_info_template.h    ├── app_device_info_template.c    └── app_version_info_template.c

2.1 `bootloader/`

这一层是 Boot 固件主体，负责：

上电后进入 Boot 主流程
通过 SCI 接收升级命令与固件数据
擦除 APP 区、写入镜像、校验 CRC
根据 metadata 状态决定是否跳转 APP

2.2 `system/`

这一层是 Boot / APP 共享的通用组件，负责：

双 metadata 结构定义与状态管理
Boot 状态快照与状态响应打包
版本信息结构定义与格式化

2.3 `host_gui_boot/`

这一层是最小上位机升级工具，负责：

串口打开与 Boot 协议收发
固件文件加载与版本提取
分块升级、日志显示、状态显示

2.4 `app_port_stub/`

这一层不是完整 APP，只是模板桩，负责说明：

APP 如何安全切换到 Boot
APP 如何提供设备信息与版本信息
.app_info 段如何放入 APP 镜像

3. 整体功能概览

3.1 这套代码解决了什么问题

这套公开代码主要解决以下问题：

DSP 设备如何进入 Boot 升级态
Bootloader 如何与上位机完成握手、下载、校验和复位
升级后如何判断 APP 是否可跳转
Boot 态如何回报当前已安装 APP 的版本和状态
Host GUI 如何加载镜像并完成 Boot 升级

3.2 当前已经实现的能力

SCI Boot 协议
固件镜像下载
Flash 擦除与分块编程
镜像 CRC32 校验
RAM Boot 请求标志
双 metadata 副本选择
TEST_PENDING / CONFIRMED 状态模型
Boot 错误码与停留原因
Boot Version / APP Version 识别
最小 GUI 升级工具
APP 侧进入 Boot 的模板

4. Bootloader 侧功能说明

4.1 `boot_protocol.h`

这是 Bootloader 的公共协议与常量头文件，主要定义：

串口参数：BOOT_SCI_BAUD_RATE
帧格式参数：SOF / EOF / 版本号 / 最大 Payload
Boot 命令码：HELLO / BEGIN / DATA / END / GET_STATUS
错误码：BOOT_ERR_*
旧版 metadata 结构 boot_app_meta_t

说明：当前 Boot 主体代码里仍保留了一套基础 boot_app_meta_t / BOOT_APP_STATUS_* 兼容结构，而 system/boot_meta_v2.* 提供的是更完整的双 metadata V2 机制。实际移植时建议统一到 V2 方案，不建议长期维持两套状态体系并存。

4.2 `boot_main.c`

这是 Bootloader 主入口，核心职责是：

初始化芯片、GPIO、中断、Flash、SCI
读取 Boot 请求标志
判断是否进入强制升级模式
等待 HELLO_REQ
若收到上位机握手，则进入下载会话
下载结束后校验 APP 并跳转
若无有效 APP，则留在 Boot

典型流程如下：

上电/复位  -> Device_init()  -> boot_flash_init()  -> boot_sci_init()  -> 读取 metadata  -> 读取 RAM Boot Flag      -> 强制升级：持续等待 HELLO      -> 普通启动：等待 HELLO 超时  -> 若收到 HELLO：执行下载会话  -> 否则检查 APP 是否有效      -> 有效：jump to app      -> 无效：留在 boot

4.3 `boot_sci.c`

负责 Boot 协议串口收发，主要功能：

SCI 初始化
接收帧、校验帧、解析 payload
发送响应帧
计算 CRC16 / CRC32

这部分和业务 APP 无关，属于通用 Boot 通信层。

4.4 `boot_flash.c`

负责 Flash 相关操作，主要功能：

Flash 模块初始化
加载 metadata
判断 APP 是否存在 / 是否可跳 / 是否 CRC 正确
擦除 APP 区
按块写入 APP 镜像
校验 APP CRC

重要注意

boot_flash.c 依赖 F28003x Flash API 与 .TI.ramfunc 机制。

移植时必须确认：

FAPI 函数从 RAM 执行
链接脚本中 .TI.ramfunc 和 FAPI 子 section 被正确放入 RAM
APP 区和 metadata 区地址与你的芯片实际布局一致

4.5 `boot_jump.c`

负责从 Boot 切换到 APP。通常只做：

关中断
清状态
跳转到 APP 入口地址

这里不涉及业务逻辑。

4.6 `boot_version_info.c`

负责导出 Boot 自身版本记录，供 GET_STATUS 或握手信息回读。

5. System 公共模块说明

5.1 `boot_meta_v2.h/.c`

这是这套代码里最重要的公共模块之一，用于管理升级状态与 APP 状态。

核心设计点

双 metadata 副本：SLOT_A / SLOT_B
用 seq 决定当前 active 副本
metadata 内含 APP 长度、CRC、版本、状态、错误码、停留原因

APP 状态枚举

BOOT_APP_STATE_INVALID
BOOT_APP_STATE_UPDATING
BOOT_APP_STATE_TEST_PENDING
BOOT_APP_STATE_CONFIRMED

Boot 诊断信息

bootErrorCode
bootStayReason
pendingBootCount

主要能力

计算 metadata 结构体 CRC
判断 metadata 是否有效
判断 APP 信息是否有效
选择 active / inactive metadata
构造 UPDATING / PENDING / CONFIRMED 状态
向 inactive 副本写入新 metadata

你需要实现的 Port Hook

以下函数只声明，不在公开包中绑定具体 Flash 驱动：

BootMeta_Port_ReadSlot()
BootMeta_Port_WriteSlot()
BootMeta_Port_VerifyAppCrc()

也就是说：

V2 metadata 的状态机已经给出，但你仍需把它接到自己的 Flash 读写接口上。

5.2 `boot_diag_status.h/.c`

负责将当前 Boot / metadata 状态整理成可读的快照与响应结构。

功能

错误码转字符串
停留原因转字符串
APP 状态转字符串
生成 BootStatusSnapshot_t
生成 BootStatusRespV2_t

GUI 侧如果要显示：

当前 active slot
当前 seq
安装的 APP 版本
上次错误
当前 stay reason

就是用这层数据。

5.3 `version_info.h/.c`

负责定义统一的版本记录格式。

包含两类信息

VersionInfoRecord_t

Boot / APP 的版本记录

AppImageInfo_t

放入 .app_info section 的镜像内信息

作用

GUI 读取设备当前版本
GUI 从固件镜像中提取目标 APP 版本
升级前比较当前版本和目标版本
升级后再次读取版本确认是否真正升级成功

6. APP 模板桩说明

公开包不含完整 APP，仅保留模板。

6.1 `boot_request_porting_template.*`

这是 APP 进入 Boot 的最小模板。

提供的能力

BootRequest_Init()
BootRequest_BeginUpdateSequence()
BootRequest_Service1kHz()
BootRequest_PlatformSafeOff()（弱符号模板）

典型使用方式

APP 收到“进入升级”命令
调用 BootRequest_BeginUpdateSequence()
业务层执行 BootRequest_PlatformSafeOff()：

关闭 PWM
拉低驱动使能
清启动命令
清控制环积分器 / 软启动状态
让功率级进入明确 OFF 状态

1kHz 任务中调用 BootRequest_Service1kHz()
延时 20ms 后写入 RAM flag 并复位

这个模板的重点不是控制算法，而是说明：

APP 进入 Boot 前必须先做 deterministic safe-off。

6.2 `app_device_info_template.*`

用于填充 APP 侧设备信息响应结构。主要回报：

appVersionU32
appProtocolVersion
deviceModelId
calibDataVersion
bootMetaVersion
buildDateBcd
buildTimeBcd
flags

如果你要实现 APP 运行态的 GET_DEVICE_INFO，直接从这里扩展即可。

6.3 `app_version_info_template.c`

这个文件提供了两个关键对象：

g_appVersionInfo
g_appImageInfo

其中 g_appImageInfo 被放到 .app_info section，用于让 Host 直接从固件镜像中提取版本信息。

这一步非常关键

如果你的 APP 链接脚本没有保留 .app_info：

GUI 可能无法从固件镜像识别目标版本
升级页就无法比较“当前版本 vs 目标版本”

因此必须把 bootloader/linker/app_info_section_snippet.cmd 合入你的 APP 链接脚本。

7. Host GUI 侧功能说明

7.1 `bootloader_protocol.py`

负责 Boot 协议的帧封装与解析，主要功能：

定义命令码与错误码
生成 HELLO / BEGIN / DATA / END / GET_STATUS 帧
解析响应帧
进行 CRC16 校验

这是 GUI 与设备通信的协议核心。

7.2 `bootloader_worker.py`

这是升级线程主体，负责：

打开串口
加载镜像
读取 Boot 状态
发起握手
分块发送固件
等待并解析响应
输出日志与状态

它的角色

这层相当于 GUI 背后的升级状态机，main_boot_gui.py 只是 UI 壳。

7.3 `firmware_image.py`

负责固件文件加载和版本识别，支持的输入通常包括：

.out
.bin
.hex
.txt

主要能力

读取固件镜像字节流
从 .app_info 中提取目标 APP 版本
必要时调用 TI 工具链做格式转换

如果你要支持更复杂的固件包格式，这里是首选扩展点。

7.4 `main_boot_gui.py`

这是最小 GUI 示例，只保留：

串口选择
波特率输入
固件文件选择
目标版本输入
启动升级 / 停止升级
状态显示
日志显示

明确不包含：

运行态遥测
业务参数
故障页
校准页

因此这个 GUI 更接近“Boot 升级工具”，不是完整产品 HMI。

8. 典型升级流程说明

8.1 普通升级路径

APP 运行中  -> 用户下发进入升级命令  -> APP safe-off  -> APP 写 RAM boot flag  -> APP 复位  -> Boot 启动  -> GUI 发送 HELLO / BEGIN / DATA / END  -> Boot 擦写 APP  -> Boot 写 metadata(TEST_PENDING)  -> Boot 复位 / 跳转 APP  -> APP 运行稳定后确认 CONFIRMED

8.2 Boot 状态读取路径

GUI 连接串口  -> 发送 GET_STATUS  -> Boot 返回：     - bootVersionU32     - installedAppVersionU32     - appState     - metaVersion     - lastErrorCode     - stayReason     - activeMetaSlot     - activeSeq

8.3 版本比较路径

GUI 打开固件  -> firmware_image.py 提取目标版本GUI 连接设备  -> GET_STATUS / GET_DEVICE_INFO 读取当前版本GUI 比较：  -> 当前设备版本  -> 目标固件版本再决定是否升级

9. 推荐移植顺序

为了减少联调复杂度，建议按下面顺序导入。

第 1 步：先接 `system/`

先把这些接进工程：

boot_meta_v2.*
boot_diag_status.*
version_info.*

目标

先把：

metadata 结构
版本结构
状态响应结构

这几类底层数据模型固定下来。

第 2 步：再接 `bootloader/`

接入：

boot_main.c
boot_sci.c
boot_flash.c
boot_jump.c
boot_version_info.c
对应 linker 片段

目标

先让 Boot 工程具备：

可编译
可启动
可停留在 Boot
可接收协议帧

第 3 步：接入 APP 模板

接入：

boot_request_porting_template.*
app_device_info_template.*
app_version_info_template.c

目标

先打通：

APP -> Boot 的安全切换
APP 版本信息导出
.app_info 进入镜像

第 4 步：再接 Host GUI

接入：

bootloader_protocol.py
bootloader_worker.py
firmware_image.py
main_boot_gui.py

目标

最后再验证：

串口握手
固件下载
版本识别
状态显示

这个顺序的好处是：

先稳设备侧，再稳主机侧，不会一开始 GUI 和 DSP 同时乱。

10. 必须修改的移植点

10.1 地址布局

你必须按目标工程修改：

BOOT_META_SLOT_A_ADDR
BOOT_META_SLOT_B_ADDR
BOOT_APP_BASE_ADDR_V2
BOOT_APP_MAX_SIZE_BYTES_V2
BOOT_REQUEST_FLAG_ADDR

这些都不应直接照搬。

10.2 Linker 脚本

必须确认：

Boot 工程的 Flash / RAM 分区符合你目标芯片
.TI.ramfunc 正确映射
FAPI 相关 section 放入 RAM
APP 工程保留 .app_info

10.3 BootMeta Port Hook

你需要实现：

BootMeta_Port_ReadSlot()
BootMeta_Port_WriteSlot()
BootMeta_Port_VerifyAppCrc()

这几项是真正把 metadata V2 接到你工程 Flash 驱动上的关键。

10.4 APP Safe-Off

必须自己实现：

BootRequest_PlatformSafeOff()

这部分和你的产品控制架构强相关，公开包故意没有给真实实现。

10.5 GUI 串口与依赖

Host GUI 依赖：

Python 3.x
PySide6
pyserial

必要时还依赖 TI 工具链，用于处理 .out。

11. 推荐的联调检查项

11.1 Boot 侧

无 Host 时，Boot 能按预期跳 APP
有强制标志时，Boot 能留在升级态
GET_STATUS 返回字段合理
metadata A/B 选择正确
TEST_PENDING / CONFIRMED 状态变化正确

11.2 APP 侧

进入升级前 safe-off 是否完整
复位前 RAM flag 是否正确写入
1kHz 服务是否正常触发复位
.app_info 是否真实进入镜像

11.3 Host 侧

能识别串口
能读取目标固件版本
能读取当前设备版本 / 状态
BEGIN / DATA / END 流程正确
升级失败时日志和错误提示可读

12. 公开包的使用边界

最后再强调一次边界。

这份代码适合做什么

学习 Boot 升级链路
作为 F28003x Boot 参考骨架
作为自研产品 Boot / Host 的起点
作为内部工程的脱敏迁移模板

这份代码不适合直接做什么

直接替代你的完整产品 Boot 工程
直接替代你的完整 APP 工程
直接作为完整量产工具交付
直接反映任何真实产品算法或规格

也就是说：

它更像“升级链路参考实现 + 移植骨架”，而不是“完整产品源码”。

13. 一句话总结

这份公开代码包最核心的价值是：

在不暴露 APP 算法和产品规格的前提下，保留了一条完整、可理解、可移植的 Boot 升级链路。

如果你在自己的工程里移植，优先顺序应当是：

先固定地址和链接脚本，再接 metadata / version / boot 主流程，再接 APP safe-off 模板，最后再接 GUI。

功能说明与移植指南

1. 文档目的

2. 代码包目录说明

2.1 bootloader/

2.2 system/

2.3 host_gui_boot/

2.4 app_port_stub/

3. 整体功能概览

3.1 这套代码解决了什么问题

3.2 当前已经实现的能力

4. Bootloader 侧功能说明

4.1 boot_protocol.h

4.2 boot_main.c

4.3 boot_sci.c

4.4 boot_flash.c

重要注意

4.5 boot_jump.c

4.6 boot_version_info.c

5. System 公共模块说明

5.1 boot_meta_v2.h/.c

核心设计点

APP 状态枚举

Boot 诊断信息

主要能力

你需要实现的 Port Hook

5.2 boot_diag_status.h/.c

功能

5.3 version_info.h/.c

包含两类信息

作用

6. APP 模板桩说明

6.1 boot_request_porting_template.*

提供的能力

典型使用方式

6.2 app_device_info_template.*

6.3 app_version_info_template.c

这一步非常关键

7. Host GUI 侧功能说明

7.1 bootloader_protocol.py

7.2 bootloader_worker.py

它的角色

7.3 firmware_image.py

主要能力

7.4 main_boot_gui.py

8. 典型升级流程说明

8.1 普通升级路径

8.2 Boot 状态读取路径

8.3 版本比较路径

9. 推荐移植顺序

第 1 步：先接 system/

目标

第 2 步：再接 bootloader/

目标

第 3 步：接入 APP 模板

目标

第 4 步：再接 Host GUI

目标

10. 必须修改的移植点

10.1 地址布局

10.2 Linker 脚本

10.3 BootMeta Port Hook

10.4 APP Safe-Off

10.5 GUI 串口与依赖

11. 推荐的联调检查项

11.1 Boot 侧

11.2 APP 侧

11.3 Host 侧

12. 公开包的使用边界

这份代码适合做什么

这份代码不适合直接做什么

13. 一句话总结

2.1 `bootloader/`

2.2 `system/`

2.3 `host_gui_boot/`

2.4 `app_port_stub/`

4.1 `boot_protocol.h`

4.2 `boot_main.c`

4.3 `boot_sci.c`

4.4 `boot_flash.c`

4.5 `boot_jump.c`

4.6 `boot_version_info.c`

5.1 `boot_meta_v2.h/.c`

5.2 `boot_diag_status.h/.c`

5.3 `version_info.h/.c`

6.1 `boot_request_porting_template.*`

6.2 `app_device_info_template.*`

6.3 `app_version_info_template.c`

7.1 `bootloader_protocol.py`

7.2 `bootloader_worker.py`

7.3 `firmware_image.py`

7.4 `main_boot_gui.py`

第 1 步：先接 `system/`

第 2 步：再接 `bootloader/`