首页 / knowledge/代码解析/net

ems_download.h

本页目录1. 文件职责 2. 关键数据结构与宏 3. 函数清单 4. 核心逻辑解析 5. 对外接口本文件导出本文件调用的外部函数 / 变量 6. 依赖关系 7. 备注与风险点

源文件路径：net/ems_download.h 所属模块：net（网络应用层 — EMS 固件下载与升级）代码行数：44

1. 文件职责

本文件是 EMS 应用固件在外挂 SPI Flash 上的地址分区表与下载/升级状态查询接口的声明头。

它定义了 4 个关键 Flash 区域（主用/备份 × 配置/固件）的起止地址，以及 APP 固件长度的上下限，是 net/ems_download.c、net/upd_download.c 乃至 net/server.c 落盘时共同遵循的"磁盘分区表"。

同时它导出 7 个状态查询/动作函数声明，供 HMI、LED、BMS、以太网等模块判断整机升级状态。

它的地址宏被 net/server.c:3451 通过 APP_MIN_SIZE / APP_MAX_SIZE 用于校验服务器下发的固件长度是否合法，属于升级流程的前置门禁。

本头文件不包含任何实现，也不定义结构体，是纯常量 + 声明的接口描述文件。

2. 关键数据结构与宏

名称	类型	说明
`__EMS_DOWNLOAD_H__`	宏（include guard）	头文件保护宏（`:9-10`）
`START_ADDR_SPI_FLASH_EMS_FW_CFG_INFO`	宏	`0x00000000`，主用 EMS 升级配置信息区起始（`:17`）
`END_ADDR_SPI_FLASH_EMS_FW_CFG_INFO`	宏	`0x00000FFF`，该区结束，共 4KB（`:18`）
`START_ADDR_SPI_FLASH_EMS_FW`	宏	`0x00003000`，主用 EMS 固件下载区起始（`:21`）
`END_ADDR_SPI_FLASH_EMS_FW`	宏	`0x00102FFF`，该区结束，约 1MB（`:22`）
`START_ADDR_SPI_FLASH_EMS_APP2_FW_CFG_INFO`	宏	`0x00103000`，备份 EMS 升级配置信息区起始（`:25`）
`END_ADDR_SPI_FLASH_EMS_APP2_FW_CFG_INFO`	宏	`0x00103FFF`，该区结束，共 4KB（`:26`）
`START_ADDR_SPI_FLASH_EMS_APP2_FW`	宏	`0x00106000`，备份 EMS 固件下载区起始（`:29`）
`END_ADDR_SPI_FLASH_EMS_APP2_FW`	宏	`0x00205FFF`，该区结束，约 1MB（`:30`）
`APP_MIN_SIZE`	宏	`100 * 1024`（102400），APP 固件最小合法字节数（`:32`）
`APP_MAX_SIZE`	宏	`(CHIP_FLASH_SIZE - 32) * 1024`，APP 固件最大合法字节数（`:33`）
`CHIP_FLASH_SIZE`	宏（外部 `system/sys/chip.h:180`）	`(volatile uint16_t)(0x1FFF7A22)`，运行时从芯片 UID 区读出的 Flash 容量（单位 KB），故 `APP_MAX_SIZE` 是运行期才确定的表达式

本文件未定义结构体、枚举、联合体或位域。

3. 函数清单

本文件不含函数定义，只含函数声明。

函数名	作用域	说明
`save_updt_config_info_to_external_flash(u8 *pBuff, u32 Len)`	全局（声明，定义在 `net/ems_download.c:63`）	将升级配置表写入外挂 SPI Flash 的 CFG_INFO 区
`calculate_ems_flash_md5(void)`	全局（声明，定义在 `net/ems_download.c:120`）	EMS 固件整包 MD5 校核并可触发复位升级
`save_ems_server_update_info(void)`	全局（声明，定义在 `net/ems_download.c:47`，空实现）	EMS 服务器升级信息保存（历史桩函数）
`IsDownloadEMS(void)`	全局（声明，定义在 `net/ems_download.c:217`）	返回 EMS 强制/正在下载标志
`GetPercentDownloadEMS(void)`	全局（声明，定义在 `net/ems_download.c:228`）	返回 EMS 下载百分比（0~100）
`IsSystemDownload(void)`	全局（声明，定义在 `net/ems_download.c:252`）	聚合查询：整机是否有任一设备正在下载固件
`IsSystemUpgrade(void)`	全局（声明，定义在 `net/ems_download.c:274`）	聚合查询：整机是否有任一设备下载完成待升级

注意：net/ems_download.c 中另有 calculate_ems_flash_md5_read_data（:93）与 GetPercentUpgradeEMS（:239）两个全局函数未在此声明，属于接口遗漏。

4. 核心逻辑解析

本文件无逻辑代码。相关实现逻辑说明见 docs/knowledge/代码解析/net/ems_download.c.md 的第 4 节。

头文件层面的要点：

Flash 分区布局（外挂 SPI Flash，字节偏移）

区域	起始	结束	大小	用途
主用配置	`0x00000000`	`0x00000FFF`	4KB	主区 `STUpdateTab`
保留空洞	`0x00001000`	`0x00002FFF`	8KB	未定义
主用固件	`0x00003000`	`0x00102FFF`	≈1020KB	APP1 EMS 固件镜像
保留空洞	`0x00103000` 之前	—	1KB	`0x102FFF` → `0x103000` 无缝衔接，无空洞
备份配置	`0x00103000`	`0x00103FFF`	4KB	备份区 `STUpdateTab`
保留空洞	`0x00104000`	`0x00105FFF`	8KB	未定义
备份固件	`0x00106000`	`0x00205FFF`	≈1020KB	APP2 EMS 固件镜像

主区与备份区的内部结构完全镜像（配置 4KB + 空洞 8KB + 固件 ≈1MB），便于双分区回滚。

APP_MAX_SIZE 是运行期表达式：CHIP_FLASH_SIZE 从系统存储区地址 0x1FFF7A22 读取（system/sys/chip.h:180），因此 APP_MAX_SIZE 不能直接用于 #if 预处理判断，只能用于运行期比较。net/server.c:3451 即把它作为实参传给 set_file_updating_info_for_dev() 做长度合法性校验。

与 upd_download.h 的重复定义：net/upd_download.h:16-21 重复定义了 START_ADDR_SPI_FLASH_EMS_FW、END_ADDR_SPI_FLASH_EMS_FW、START_ADDR_SPI_FLASH_EMS_APP2_FW、END_ADDR_SPI_FLASH_EMS_APP2_FW 四个宏，取值与本文件完全一致，但没有 include guard 之外的任何去重机制，两处必须同步修改。

5. 对外接口

本文件导出

符号	使用者
`START_ADDR_SPI_FLASH_EMS_FW_CFG_INFO`	`net/ems_download.c:76`
`START_ADDR_SPI_FLASH_EMS_APP2_FW_CFG_INFO`	`net/ems_download.c:80`
`START_ADDR_SPI_FLASH_EMS_FW`	`net/ems_download.c:97`
`START_ADDR_SPI_FLASH_EMS_APP2_FW`	`net/ems_download.c:97`
`APP_MIN_SIZE` / `APP_MAX_SIZE`	`net/server.c:3451`（传给 `set_file_updating_info_for_dev`）
`save_updt_config_info_to_external_flash`	仅 `net/ems_download.c:184` 内部调用，无外部调用方
`calculate_ems_flash_md5`	`net/server.c:3785`、`midware/interface/modbus/modbus.c:9336`
`save_ems_server_update_info`	`net/server.c:3234`
`IsDownloadEMS`	`hmi/ui/ui_main.c:782`、`data/fault_warn_log/fault_warn_log.c:1540`、`data/resume_data/flash/flash_data_store.c:2806`
`GetPercentDownloadEMS`	`hmi/ui/ui_main.c:788`
`IsSystemDownload`	`hmi/led.c`、`midware/bms/bms.c`、`midware/ethernt/ethernet.c`、`midware/ethernt/wireless/wireless_driver.c`、`net/ems.c`
`IsSystemUpgrade`	`hmi/led.c`、`midware/bms/bms.c`、`midware/ethernt/ethernet.c`、`net/ems.c`
`END_ADDR_SPI_FLASH_EMS_FW_CFG_INFO` / `END_ADDR_SPI_FLASH_EMS_APP2_FW_CFG_INFO` / `END_ADDR_SPI_FLASH_EMS_APP2_FW`	全工程搜索无引用，仅作文档用途

本文件调用的外部函数 / 变量

无（仅 #include <includes.h>，类型与 CHIP_FLASH_SIZE 由使用者自行 include chip.h）。

6. 依赖关系

依赖：UCOSII/uCOS-CONFIG/includes.h（:12）；APP_MAX_SIZE 间接依赖 system/sys/chip.h 的 CHIP_FLASH_SIZE，但本头文件未 include chip.h。
被依赖：
- net/ems_download.c（:16）
- net/ems_boot_handle.c（:15，仅为地址宏）
- 其它 include net/server.h → 间接引入本头文件声明的使用者（net/server.c 等）依赖 APP_MIN_SIZE / APP_MAX_SIZE

7. 备注与风险点

APP_MAX_SIZE 依赖未 include 的头：APP_MAX_SIZE 使用了 CHIP_FLASH_SIZE（:33），但本文件只 include 了 includes.h（:12），没有 include system/sys/chip.h。任何直接 #include "ems_download.h" 而不先引入 chip.h 的编译单元，一旦用到 APP_MAX_SIZE 就会因未定义标识符报错；当前能编译通过依赖了 include 顺序，属隐式耦合。
与 upd_download.h 宏重复：START/END_ADDR_SPI_FLASH_EMS_FW、START/END_ADDR_SPI_FLASH_EMS_APP2_FW 四个宏在两个头文件中重复定义且取值相同，改动时极易只改一处而导致主/备份分区错位。
分区边界宏未使用：END_ADDR_SPI_FLASH_EMS_FW、END_ADDR_SPI_FLASH_EMS_FW_CFG_INFO、END_ADDR_SPI_FLASH_EMS_APP2_FW_CFG_INFO、END_ADDR_SPI_FLASH_EMS_APP2_FW 定义了但全工程无引用；写入路径（net/upd_download.c:203-210）只用 START 地址 + 偏移，没有用 END 做越界保护，固件长度超出分区会静默覆写相邻区域。
文件头注释错误：:2 写的是 @file :BMSUpdate.h，:3 的作者字段为 Alpha g_stEMSInfo Team（把全局变量名误写进作者），与实际文件名和内容不符，是历史拷改遗留。
save_ems_server_update_info / GetPercentUpgradeEMS 相关：头文件导出了 save_ems_server_update_info 但实现为空；GetPercentUpgradeEMS 实现存在却未导出，接口与实现不对称。
u8 返回类型用于布尔语义：IsDownloadEMS / IsSystemDownload / IsSystemUpgrade 返回 u8 而非 BOOLEAN，与 net/upd_download.h 中 BOOLEAN get_flag_force_update(...) 风格不一致，调用方若用 == TRUE 比较（hmi/led.c:180、:191 即如此）依赖 TRUE 恰为 1。