首页 / knowledge/代码解析/net
upd_download.h
源文件路径：
net/upd_download.h所属模块：net（网络应用层 — 通用设备固件升级） 代码行数：44
1. 文件职责
本文件是 EMS 整机固件升级"通用状态表服务层"（net/upd_download.c）的公开接口头，对外导出 19 个 STUpdateTab 读写接口和 2 个落盘接口。
它同时重复定义了主用/备份两个 EMS 固件下载区的起止地址宏，供落盘路径计算目标地址。
它是 net 任务（TCP 云端升级）与 Modbus 任务（Modbus 升级）共用的唯一升级状态访问契约，也是 BMS、逆变器、充电桩、AFCI、电表等各设备升级模块判断"是否要升级"的入口声明。
本文件不含实现、不定义结构体，但它声明的接口全部以 ENUpdateType 枚举和 STUpdateTab 结构体为参数，因此隐含依赖 net/server.h。
2. 关键数据结构与宏
| 名称 | 类型 | 说明 |
|---|---|---|
__UPD_DOWNLOAD_H__ | 宏（include guard） | 头文件保护宏（:9-10） |
START_ADDR_SPI_FLASH_EMS_FW | 宏 | 0x00003000，主用 EMS 固件下载区起始（:16） |
END_ADDR_SPI_FLASH_EMS_FW | 宏 | 0x00102FFF，该区结束，约 1MB（:17） |
START_ADDR_SPI_FLASH_EMS_APP2_FW | 宏 | 0x00106000，备份 EMS 固件下载区起始（:20） |
END_ADDR_SPI_FLASH_EMS_APP2_FW | 宏 | 0x00205FFF，该区结束，约 1MB（:21） |
本文件未定义结构体、枚举或联合体。使用的类型说明：
| 类型 | 来源 | 说明 |
|---|---|---|
ENUpdateType | net/server.h:186-198 | 升级目标枚举：UPDT_EMS=0, UPDT_BMS, UPDT_INV1, UPDT_INV2, UPDT_INV3, UPDT_Meter, UPDT_EVC, UPDT_AFCI, UPDT_MAX |
STUpdateTab | net/server.h:216-236 | 单个升级目标的描述表（掩码、版本、MD5、长度、偏移、各标志位、CRC） |
BOOLEAN | uCOS-II | 布尔类型，用于 4 个标志位接口 |
u8 / u32 / char | includes.h | 基础类型 |
ENInfoType | net/ems.h:247-272 | 仅出现在 calculate_dev_FW_Flash_MD5 的第三参数声明中 |
CHIP_FLASH_SIZE | system/sys/chip.h:180 | 本文件未使用（APP_MAX_SIZE 只在 net/ems_download.h:33 使用） |
3. 函数清单
本文件不含函数定义，只含 19 条函数声明（:23-41）。
| 函数名 | 作用域 | 说明 |
|---|---|---|
set_response_force_upd_status(ENUpdateType updType, BOOLEAN set) | 全局（声明，定义在 net/upd_download.c:41） | 设置"已应答服务器强制升级请求"标志 |
get_response_force_upd_status(ENUpdateType updType) | 全局（声明，定义在 net/upd_download.c:57） | 读取上述标志 |
set_flag_force_update(ENUpdateType updType, BOOLEAN bSet) | 全局（声明，定义在 net/upd_download.c:73） | 设置设备的强制/主动升级标志 |
get_flag_force_update(ENUpdateType updType) | 全局（声明，定义在 net/upd_download.c:89） | 读取上述标志 |
clear_curr_offset_file_request(ENUpdateType updType) | 全局（声明，定义在 net/upd_download.c:105） | 把下载偏移归零 |
get_curr_offset_file_request(ENUpdateType updType) | 全局（声明，定义在 net/upd_download.c:121） | 读取下载偏移 |
Save_Data_To_FW_Area_InSdram(ENUpdateType updType, u8 *fw_Bin, u32 Len, u8 *fw_sdram_baseaddr) | 全局（声明，定义在 net/upd_download.c:137） | 按当前偏移把一块固件写入 SDRAM 固件区，0 成功 / 1 失败 |
save_data_to_fw_area_inFlash(ENUpdateType updType, u8 *fw_Bin, u32 Len) | 全局（声明，定义在 net/upd_download.c:194） | 按当前偏移把一块固件写入 SPI Flash 主/备固件区，0 成功 / 1 失败 |
get_save_firm_in_app_flash_flag(void) | 全局（声明，定义在 net/upd_download.c:166） | 读取分区选择标志（APP1 / APP2） |
set_save_firm_in_app_flash_flag(u8 flag) | 全局（声明，定义在 net/upd_download.c:178） | 设置分区选择标志 |
set_status_update_file_info(ENUpdateType updType, u8 value) | 全局（声明，定义在 net/upd_download.c:237） | 设置"已取得升级文件信息"标志 |
set_updt_file_mask(ENUpdateType updType, char *fileMask) | 全局（声明，定义在 net/upd_download.c:253） | 写入升级文件掩码 |
set_ver_from_server(ENUpdateType updType, char *ver, u8 len) | 全局（声明，定义在 net/upd_download.c:269） | 写入服务器下发的目标软件版本 |
set_id_code_for_updt_cmd(ENUpdateType updType, u8 *buff, u32 len) | 全局（声明，定义在 net/upd_download.c:304） | 写入特殊升级指令码 |
get_length_file_updating(ENUpdateType updType) | 全局（声明，定义在 net/upd_download.c:327） | 读取升级文件总长度 |
get_curr_md5_code_fw_file(ENUpdateType updType) | 全局（声明，定义在 net/upd_download.c:343） | 返回服务器下发的 MD5 十六进制串指针 |
Set_Status_Is_Updated_From_Server(ENUpdateType updType, u8 bSet) | 全局（声明，定义在 net/upd_download.c:359） | 置位"固件已就绪待升级" |
Get_Status_Is_Updated_From_Server(ENUpdateType updType) | 全局（声明，定义在 net/upd_download.c:375） | 读取"固件已就绪待升级"标志 |
calculate_dev_FW_Flash_MD5(ENUpdateType updType, u8 *g_u8_fw_sdram, ENInfoType type) | 全局（声明，定义在 net/upd_download.c:391） | 对 SDRAM 中固件做整包 MD5 并与服务器值比对 |
声明总数（19 条，:23-41）与 net/upd_download.c 中的函数定义总数（19 个）完全一致，接口契约完整，无遗漏或多声明。
4. 核心逻辑解析
本文件无逻辑代码。相关实现逻辑说明见 docs/knowledge/代码解析/net/upd_download.c.md 的第 4 节。
头文件层面的要点：
分区地址宏与外挂 SPI Flash 布局
| 宏 | 值 | 区域 |
|---|---|---|
START_ADDR_SPI_FLASH_EMS_FW | 0x00003000 | 主用固件区起始 |
END_ADDR_SPI_FLASH_EMS_FW | 0x00102FFF | 主用固件区结束（≈1020KB） |
START_ADDR_SPI_FLASH_EMS_APP2_FW | 0x00106000 | 备份固件区起始 |
END_ADDR_SPI_FLASH_EMS_APP2_FW | 0x00205FFF | 备份固件区结束（≈1020KB） |
四个宏的取值与 net/ems_download.h:21-30 中的同名定义完全一致，属于双份定义。两个头文件的配置区宏（START/END_ADDR_SPI_FLASH_EMS_FW_CFG_INFO、START/END_ADDR_SPI_FLASH_EMS_APP2_FW_CFG_INFO）只在 net/ems_download.h 中定义。
接口分层
19 个接口按职责分为三类：
- 标志/状态读写（10 个）：
set/get_response_force_upd_status、set/get_flag_force_update、set/get_curr_offset_file_request、clear_curr_offset_file_request、set_status_update_file_info、Set/Get_Status_Is_Updated_From_Server - 元信息写入（3 个）：
set_updt_file_mask、set_ver_from_server、set_id_code_for_updt_cmd - 落盘与校核（5 个）：
Save_Data_To_FW_Area_InSdram、save_data_to_fw_area_inFlash、get/set_save_firm_in_app_flash_flag、calculate_dev_FW_Flash_MD5 - 只读查询（1 个）：
get_length_file_updating、get_curr_md5_code_fw_file
注意 get_save_firm_in_app_flash_flag 与 set_save_firm_in_app_flash_flag 管理的是 net/upd_download.c:27 的文件级静态变量而非 STUpdateTab 字段，跨文件可见但作用域仅限本模块。
5. 对外接口
本文件导出
| 符号 | 使用者 |
|---|---|
START_ADDR_SPI_FLASH_EMS_FW | net/upd_download.c:205、net/ems_download.c:97 |
START_ADDR_SPI_FLASH_EMS_APP2_FW | net/upd_download.c:209、net/ems_download.c:97 |
END_ADDR_SPI_FLASH_EMS_FW / END_ADDR_SPI_FLASH_EMS_APP2_FW | 全工程无引用（仅文档用途） |
set_response_force_upd_status / get_response_force_upd_status | net/ems.c:2882、net/server.c:149、:151、:2370、:2382 |
set_flag_force_update / get_flag_force_update | net/ems_download.c:219、net/server.c:2412、midware/afci/afci_upgrade.c:406、:452、midware/inverter/alphaess/alphaess_upgrade.c:538-539、:587-588 |
clear_curr_offset_file_request / get_curr_offset_file_request | net/server.c:3236、:3778、net/ems_download.c:230 |
Save_Data_To_FW_Area_InSdram | net/server.c:3589、:3598 |
save_data_to_fw_area_inFlash | net/server.c:3613、:3622 |
get_save_firm_in_app_flash_flag / set_save_firm_in_app_flash_flag | net/ems_download.c:74、:97；net/ems.c:4660；midware/interface/modbus/modbus.c:8992、:9002 |
set_status_update_file_info | net/server.c:2405、:3232 |
set_updt_file_mask | net/server.c:2418、:2430、:2439 |
set_ver_from_server | net/server.c:2422 |
set_id_code_for_updt_cmd | net/server.c:2358、:2359、:2361 |
get_length_file_updating | net/ems_download.c:129-130、:172、net/ems_boot_handle.c:222、net/server.c:3786、midware/afci/afci_upgrade.c:263-271、net/upd_download.c:398 |
get_curr_md5_code_fw_file | net/ems_download.c:164/167/206、midware/inverter/alphaess/alphaess_upgrade.c:105/107、net/upd_download.c:407/410/425 |
Set_Status_Is_Updated_From_Server / Get_Status_Is_Updated_From_Server | net/ems_download.c:180、:276-283、midware/bms/bms.c:2751/2758、midware/bms/alpha/battery_upgrade.c:751、midware/evc/evc_upgrade.c:677、midware/interface/interface.c:318、midware/afci/afci_upgrade.c:405/451/517、midware/debug/ate.c:132-134/166 |
calculate_dev_FW_Flash_MD5 | net/server.c:3789-3813、midware/interface/modbus/modbus.c:9340-9352 |
本文件直接使用的类型（隐含依赖）
ENUpdateType、STUpdateTab（net/server.h），ENInfoType（net/ems.h），BOOLEAN（uCOS-II）。本文件已 include net/ems.h（:13），net/ems.h 内部 include net/server.h，因此类型可见性依赖这条链路。
本文件调用的外部函数 / 变量
无（仅声明；:12 的 #include <includes.h> 提供基础类型，:13 的 #include "ems.h" 提供 ENUpdateType / STUpdateTab / ENInfoType）。
6. 依赖关系
- 依赖：
UCOSII/uCOS-CONFIG/includes.h（:12）、net/ems.h（:13，进而引入net/server.h中的ENUpdateType/STUpdateTab） - 被依赖（include 本头文件的文件）：
net/upd_download.c（:22）— 自身实现net/ems_download.c（:15）net/ems_boot_handle.c（:14）net/server.c、net/ems.c、midware/interface/modbus/modbus.c、各设备升级模块（BMS / INV / EVC / AFCI / Meter）通过各自头文件间接引入
7. 备注与风险点
- 宏与
net/ems_download.h重复定义：START/END_ADDR_SPI_FLASH_EMS_FW、START/END_ADDR_SPI_FLASH_EMS_APP2_FW四个宏在net/ems_download.h:21-30与net/upd_download.h:16-21中各定义一份。由于两者都在 include guard 之外、且都是#define，谁先被 include 谁生效，重定义不会报错（取值相同），但改地址时只改一处会造成主/备份分区错位，且不会编译报错。 END_ADDR_SPI_FLASH_*定义了但全工程无引用：写入路径只用 START + 偏移（net/upd_download.c:203-210），固件长度超出分区会静默覆写相邻区域，END_ADDR未起到任何保护作用。- 返回值语义不在头文件体现：
Save_Data_To_FW_Area_InSdram与save_data_to_fw_area_inFlash返回char（net/upd_download.h:29、:30），约定是0=成功 / 1=失败，但头文件完全没有注释说明；而同族的set_response_force_upd_status等用BOOLEAN。调用方net/server.c:3589写!= 0判断正确，但这是靠约定而非类型约束。 - 头文件注释错误：
:2写的是@file :BMSUpdate.h（与实际文件名不符），:3的作者字段为Alpha g_stEMSInfo Team（把全局变量名误写进作者），:5的日期2025/06/24与内容无关，是历史拷改遗留。 updType无范围约束：头文件的所有接口第一参数是ENUpdateType，但没有注释提示"必须< UPDT_MAX"；C 语言下传任意整数值都能编译通过，实现里直接做数组下标（见net/upd_download.c备注）。- 参数命名不一致：
calculate_dev_FW_Flash_MD5的第二参数在头文件里叫g_u8_fw_sdram（：41），g_前缀本应表示全局变量，此处却是一个形参，与工程命名约定冲突；实现文件net/upd_download.c:391沿用了同样的名字。 save_data_to_fw_area_inFlash命名风格混用：同文件内既有Save_Data_To_FW_Area_InSdram的驼峰式，也有save_data_to_fw_area_inFlash的下划线式，两者语义对应但风格不统一。