首页 / knowledge/代码解析/net
inv_download.h
本页目录1. 文件职责2. 关键数据结构与宏3. 函数清单4. 核心逻辑解析4.1 三个升级目标与接口对应关系4.2 “完成”语义的两套判据4.3 写入类接口的契约4.4 通信协议 / 定时 / uCOS-II5. 对外接口6. 依赖关系7. 备注与风险点
源文件路径：
net/inv_download.h所属模块：net（网络应用层 / 设备固件升级下载） 代码行数：42
1. 文件职责
本文件是 net/inv_download.c 的对外接口头文件，声明逆变器（及配套充电机）云端固件下载流程的状态查询与写入接口：三个升级目标（UPDT_INV1 主机 / UPDT_INV2 从机 / UPDT_INV3 ARM）各自的“是否强制下载”与“下载百分比”，以及“整机固件是否已下载完成”“贝瓦单核板判据”“INV3 固件写入 SDRAM”“INV2 版本串写入”等接口。
它在工程中属于被广泛引入的公共头（18 个文件 include），因为几乎所有逆变器厂商协议模块都要用 is_inverter_firm_download_finished() 判断“固件已就绪 → 只传固件、停发常规帧”。
本文件不含逻辑与状态，只含 include guard、一个未使用的宏常量、一个 include 和 15 个函数原型；其中 5 个原型在工程中没有实现（见第 3、7 节）。
2. 关键数据结构与宏
| 名称 | 类型 | 说明 |
|---|---|---|
__INV_DOWNLOAD_H__ | 宏 | include guard（第 13-14 行） |
SIZE_KB_500 | 宏 | 第 21 行，值 (1024 * 500)（500 KB）。全工程无任何引用，是已过期的固件长度上限常量（实际上限见 SDRAM_3M，net/server.c:3455-3463） |
set_flag_inv1_force_update | 函数原型 | void set_flag_inv1_force_update(BOOLEAN bSet)，全工程无定义、无调用点 |
get_flag_inv1_force_update | 函数原型 | BOOLEAN get_flag_inv1_force_update(void)，全工程无定义、无调用点 |
Clear_Inv2_Update_Info | 函数原型 | void Clear_Inv2_Update_Info(void)，全工程无定义、无调用点 |
Set_Inv2_Ver_From_Server | 函数原型 | void Set_Inv2_Ver_From_Server(char *ver, u8 len)，定义于 inv_download.c:88，但无调用点 |
set_flag_inv3_force_update | 函数原型 | void set_flag_inv3_force_update(BOOLEAN bSet)，全工程无定义、无调用点 |
get_flag_inv3_force_update | 函数原型 | BOOLEAN get_flag_inv3_force_update(void)，全工程无定义、无调用点 |
Save_Data_To_Inv3_FW_Area | 函数原型 | char Save_Data_To_Inv3_FW_Area(u8 *fw_Bin, u32 Len)，定义于 inv_download.c:55，但无调用点 |
is_inverter_firm_download_finished | 函数原型 | u8 is_inverter_firm_download_finished(void)，定义于 inv_download.c:182 |
is_bwinv_firm_download_finished | 函数原型 | u8 is_bwinv_firm_download_finished(void)，定义于 inv_download.c:192 |
IsDownloadINV / IsDownloadCHG / IsDownloadInv3 | 函数原型 | 分别对应 inv_download.c:116 / :138 / :160 |
GetPercentDownloadINV / GetPercentDownloadCHG / GetPercentDownloadInv3 | 函数原型 | 分别对应 inv_download.c:127 / :149 / :171 |
本文件不定义结构体、枚举、联合体或位域。u8 / u32 / BOOLEAN 来自第 17 行 #include <includes.h>；第 18 行额外 #include "upd_download.h"，但本文件的 15 个原型都没有用到其中的类型或宏，属于转发式冗余 include。
3. 函数清单
| 函数名 | 作用域 | 说明 |
|---|---|---|
set_flag_inv1_force_update | 全局（原型声明） | 语义应为“置位主机强制更新标志”，无定义，已被 set_flag_force_update(UPDT_INV1, ...)（upd_download.c:73）取代 |
get_flag_inv1_force_update | 全局（原型声明） | 语义应为“读取主机强制更新标志”，无定义，已被 get_flag_force_update(UPDT_INV1) 取代 |
Clear_Inv2_Update_Info | 全局（原型声明） | 语义应为“清空从机升级信息”，无定义、无调用 |
Set_Inv2_Ver_From_Server | 全局（原型声明） | 把服务器版本串写入 stUpt[UPDT_INV2].as8SoftVer（带 MAX_LEN_SOFT_VER 截断保护），定义于 inv_download.c:88，无调用点 |
set_flag_inv3_force_update | 全局（原型声明） | 语义应为“置位 ARM 强制更新标志”，无定义，已被 set_flag_force_update(UPDT_INV3, ...) 取代 |
get_flag_inv3_force_update | 全局（原型声明） | 语义应为“读取 ARM 强制更新标志”，无定义，已被 get_flag_force_update(UPDT_INV3) 取代 |
Save_Data_To_Inv3_FW_Area | 全局（原型声明） | 把一包 INV3 固件写入 g_u8_fw_sdram1 + offset，重试 3 次，返回 0 成功 / 1 失败，定义于 inv_download.c:55，无调用点 |
is_inverter_firm_download_finished | 全局（原型声明） | 主机与从机固件是否都已从服务器更新完成，定义于 inv_download.c:182 |
is_bwinv_firm_download_finished | 全局（原型声明） | 实现为 get_board_type() == BOARD_EMS3_6_3_E（贝瓦单核板判据，与命名不符），定义于 inv_download.c:192 |
IsDownloadINV | 全局（原型声明） | 云端是否要求强制下载主机（INV1）固件，定义于 inv_download.c:116 |
IsDownloadCHG | 全局（原型声明） | 云端是否要求强制下载从机 / 充电机（INV2）固件，定义于 inv_download.c:138 |
IsDownloadInv3 | 全局（原型声明） | 云端是否要求强制下载 ARM（INV3）固件，定义于 inv_download.c:160 |
GetPercentDownloadINV | 全局（原型声明） | INV1 下载百分比，定义于 inv_download.c:127 |
GetPercentDownloadCHG | 全局（原型声明） | INV2 下载百分比，定义于 inv_download.c:149 |
GetPercentDownloadInv3 | 全局（原型声明） | INV3 下载百分比，定义于 inv_download.c:171 |
共 15 个原型声明：8 个有实现、5 个无实现（set_flag_inv1_force_update、get_flag_inv1_force_update、Clear_Inv2_Update_Info、set_flag_inv3_force_update、get_flag_inv3_force_update）、2 个既有实现又无调用点（Set_Inv2_Ver_From_Server、Save_Data_To_Inv3_FW_Area）。无 static 函数、无函数指针、无回调、无宏函数。
反向缺口：inv_download.c:39 定义的 Get_Response_For_Inv3_Force_Update() 在本头文件中没有声明（缺原型），无法被其他编译单元正常调用。
4. 核心逻辑解析
本文件是纯声明文件，不含可执行逻辑。接口契约要点：
4.1 三个升级目标与接口对应关系
ENUpdateType（net/server.h:186）中逆变器占 3 个槽位，本头文件为每个槽位提供「标志 + 百分比」两个接口，命名上混用了 INV / CHG 两种叫法：
| 枚举（值） | 本头文件的标志接口 | 本头文件的百分比接口 | HMI 文案 |
|---|---|---|---|
UPDT_INV1(2) | IsDownloadINV() | GetPercentDownloadINV() | INVC(M) 主机 |
UPDT_INV2(3) | IsDownloadCHG() | GetPercentDownloadCHG() | INVC(S) 从机 |
UPDT_INV3(4) | IsDownloadInv3() | GetPercentDownloadInv3() | INVC(ARM) |
IsDownloadINV 与 IsDownloadCHG 是同族异名的典型：前者用“逆变器”命名，后者用“充电机（CHG）”命名，实际都指向逆变器体系的槽位，只有读 .c 才能确定映射。
4.2 “完成”语义的两套判据
| 接口 | 实现 | 语义 |
|---|---|---|
is_inverter_firm_download_finished() | Get_Status_Is_Updated_From_Server(UPDT_INV1) && Get_Status_Is_Updated_From_Server(UPDT_INV2) | 主/从机固件均已收妥且 MD5 校验通过 |
is_bwinv_firm_download_finished() | get_board_type() == BOARD_EMS3_6_3_E | 纯板型判据，与升级状态无关 |
后者名实不符（详见 inv_download.c.md 备注 3），调用方不应把它当作升级完成标志使用。
4.3 写入类接口的契约
Save_Data_To_Inv3_FW_Area(u8 *fw_Bin, u32 Len)：返回char，0表示成功、1表示失败（与net/upd_download.c:137的通用版一致，与 C 惯例相反）。写入地址由内部通过get_curr_offset_file_request(UPDT_INV3)计算，调用方不传地址。函数不做越界检查，保护依赖云端上报的文件长度落在(5 KB, 3 MB)区间内。Set_Inv2_Ver_From_Server(char *ver, u8 len)：ver == NULL或len == 0时静默返回（不改动原值）；len >= 16（MAX_LEN_SOFT_VER）时只保留前 15 字符并强补'\0'。
4.4 通信协议 / 定时 / uCOS-II
均不涉及。本文件不定义帧格式、起始码、长度、命令字、校验方式或超时重试参数，不声明信号量、消息邮箱或任务，也不引用 uCOS-II API。所声明的函数由调用方在自己的任务上下文同步调用（IsDownload* 系列被 HMI 任务与网络任务读，is_inverter_firm_download_finished 被各厂商逆变器通信任务读）。
5. 对外接口
导出（供外部使用，按调用点数量排序）：
| 名称 | 使用方 |
|---|---|
is_inverter_firm_download_finished | midware/inverter/alphaess/alphaess_comm_can.c:1189、alphaess_comm_usart.c:5337/:5434、ginlong/ginlong_comm_can.c:301、ginlong_comm_usart.c:4863、goodwe/goodwe_comm.c:2448、inovance/inovance_comm_can.c:599、inovance_comm_usart.c:2575、inovance_upgrade.c:414、kelong/kelong_comm.c:1365、set/set_comm_can.c:685、set/set_upgrade_s5.c:164、net/ems.c:6681 |
IsDownloadINV | hmi/ui/ui_main.c:791、:795、net/ems_download.c:255 |
IsDownloadCHG | hmi/ui/ui_main.c:791、:802、net/ems_download.c:256 |
IsDownloadInv3 | hmi/ui/ui_main.c:791、net/ems_download.c:257 |
GetPercentDownloadINV | hmi/ui/ui_main.c:799 |
GetPercentDownloadCHG | hmi/ui/ui_main.c:806 |
GetPercentDownloadInv3 | hmi/ui/ui_main.c:813 |
is_bwinv_firm_download_finished | midware/inverter/alphaess/alphaess_upgrade.c:410 |
Set_Inv2_Ver_From_Server | 无调用点（实现存在但无人使用） |
Save_Data_To_Inv3_FW_Area | 无调用点（实现存在但无人使用） |
set_flag_inv1_force_update / get_flag_inv1_force_update | 无（无定义、无调用） |
Clear_Inv2_Update_Info | 无（无定义、无调用） |
set_flag_inv3_force_update / get_flag_inv3_force_update | 无（无定义、无调用） |
SIZE_KB_500 | 无（无第二次引用） |
被调用（本文件引用的外部符号）：
| 名称 | 来源 |
|---|---|
includes.h | 第 17 行 #include <includes.h>，提供 u8 / u32 / BOOLEAN 等基础类型，并间接引入 uCOS-II 与 GD32 头文件 |
upd_download.h | 第 18 行 include，但本文件原型未使用其类型或宏（冗余） |
本文件不导出全局变量，也不引用外部全局变量。
6. 依赖关系
依赖：
UCOSII/uCOS-CONFIG/includes.h（第 17 行，尖括号形式）——提供基础类型；net/upd_download.h（第 18 行）——冗余，仅扩大编译依赖面（upd_download.h自身又 includeems.h）。
被依赖（include 本头文件的文件，共 18 处，是本批次里最广的一个）：
net/inv_download.c:19、net/ems.c:20、net/server.c:22、net/ems_download.c:19hmi/ui/ui_main.c:24midware/interface/modbus/modbus.c:34midware/debug/ate.c:18（纯冗余，未使用任何符号）midware/inverter/parallel.c:22midware/inverter/alphaess/alphaess_comm_can.c:18、alphaess_comm_usart.c:26、alphaess_upgrade.c:17midware/inverter/ginlong/ginlong_comm_can.c:20、ginlong_comm_usart.c:23、ginlong_upgrade.c:15midware/inverter/goodwe/goodwe_comm.c:24、goodwe_upgrade.c:15midware/inverter/inovance/inovance_comm_can.c:10、inovance_comm_usart.c:20、inovance_upgrade.c:15midware/inverter/kelong/kelong_comm.c:22、kelong_upgrade.c:15midware/inverter/set/set_comm_can.c:20、set_comm_usart_s5.c:20、set_upgrade_s5.c:16
7. 备注与风险点
- 5 个原型没有实现：
set_flag_inv1_force_update、get_flag_inv1_force_update、Clear_Inv2_Update_Info、set_flag_inv3_force_update、get_flag_inv3_force_update在工程任何.c中都找不到定义，也没有调用点（已用全工程grep -rn确认）。它们的功能已被net/upd_download.c:73/89的通用接口set_flag_force_update/get_flag_force_update覆盖。任何未来调用都会在链接期报未解析符号，应删除。 - 1 个实现没有原型：
inv_download.c:39的Get_Response_For_Inv3_Force_Update()未在本头文件声明，导致该全局符号对其他编译单元不可见（C99 下隐式声明会告警）。声明集合与实现集合双向不匹配。 SIZE_KB_500是死宏且已过期：第 21 行的 500 KB 上限全工程无引用；当前逆变器固件长度上限取自SDRAM_3M（3 MB，见net/server.c:3455-3463）。若维护者按此宏估算缓冲区大小会严重低估。is_bwinv_firm_download_finished名实不符：头文件无任何注释揭示它其实是板型判据（get_board_type() == BOARD_EMS3_6_3_E）。唯一调用点midware/inverter/alphaess/alphaess_upgrade.c:410还叠加了恒真的&& get_board_type() != BOARD_EMS3_6_4_E，进一步掩盖了真实语义。- 文件名 + 注释问题：
@date为2017/05/18（与bms/evc/meter三个 download 头文件同源）；第 22 行的分隔注释为空的/**/段落，实际未写任何内容。 BOOLEAN与u8类型混用：5 个已废弃原型用BOOLEAN，而现存接口用u8（IsDownloadINV等）与char（Save_Data_To_Inv3_FW_Area的返回值）。这种混用是历史分层的痕迹，不利于类型自解释。- 冗余 include：第 18 行
upd_download.h未被本文件原型使用；midware/debug/ate.c:18引入本头文件后也未使用任何符号。 Save_Data_To_Inv3_FW_Area缺少const与越界校验：inv_download.c:44-46的注释签名写const u8 *fw_Bin，实际原型与实现都是u8 *fw_Bin（去掉了const）；函数内部不做offset + Len ≤ SDRAM_3M校验，越界防护完全依赖云端上报值的区间检查。