首页 / knowledge/代码解析/logic

math_tools.h

本页目录1. 文件职责 2. 关键数据结构与宏 3. 函数清单 4. 核心逻辑解析 4.1 接口签名与语义约定 4.2 头文件自身的类型依赖 4.3 通信协议帧格式 4.4 定时 / uCOS-II 配合 5. 对外接口 6. 依赖关系 7. 备注与风险点

源文件路径：logic/math_tools.h 所属模块：logic（能量调度核心，实为通用数据处理工具接口）代码行数：18

1. 文件职责

本文件是 logic/math_tools.c 的对外接口头文件，只声明三个纯数据处理函数：定点整数格式化 fmt_fixed()、浮点字符串解析 parse_fixed()、调度参数字符串解析 parse_dispatch_para()。它不含任何类型定义、宏或全局变量，属最薄的一层接口。使用方是网络层与存储层——net/ems.c（拼装上报 JSON）、net/server.c（解析下行配置与调度指令）、data/resume_data/flash/flash_data_store.c（写历史 CSV），也就是说这个「logic 模块的头文件」实际被 net/ 和 data/ 两个模块引用，是跨层共享的字符串处理工具契约。

2. 关键数据结构与宏

名称	类型	说明
`__MATH_TOOLS_H__`	宏	include guard

除此之外本文件不定义任何结构体、枚举、联合体、位域或常量宏，也没有 #include 任何头文件。

3. 函数清单

函数名	作用域	说明
`fmt_fixed`	全局（原型声明）	把定点整数按 `scale` 格式化为 `"整数.小数"` 字符串，定义于 `math_tools.c:26`
`parse_fixed`	全局（原型声明）	把浮点字符串按 `scale` 解析为定点值，定义于 `math_tools.c:56`
`parse_dispatch_para`	全局（原型声明）	解析 `Parameter2":"` 后的逗号分隔数字列表，定义于 `math_tools.c:94`

共 3 个原型声明，全部对应 math_tools.c 中的全局定义；无 static 函数、无函数指针、无回调。

4. 核心逻辑解析

本文件是纯声明文件，无可执行逻辑。与实现相关的关键契约要点如下：

4.1 接口签名与语义约定

原型	参数含义	返回语义	备注
`const char *fmt_fixed(s64 raw, u32 scale)`	`raw`：定点原始值（有效范围仅 32 位）；`scale`：缩小倍数，必须是 10 的幂（1/10/100/1000）	指向 `math_tools.c` 内 16 槽环形静态缓冲区的指针	同一条语句最多调用 16 次，第 17 次开始覆盖已有结果；返回值不可长期保存
`u32 parse_fixed(const char *s, u32 scale)`	`s`：形如 `"-3.3"` 的浮点字符串，可为 `NULL` 之外任意内容（不校验）；`scale` 同上	定点值，返回类型为 `u32` 但内部按 `s32` 计算，负值以补码形式回绕	调用方须自行判断是否需要按 `s32` 使用
`int parse_dispatch_para(const char s, u32 out, int max_fields)`	`s` 必须正好指向 `Parameter2":"` 的起始字符；`out` 输出数组；`max_fields` 最多解析字段数	成功解析的字段个数（函数内不校验 `out` 容量）	小数被直接截断；常用于返回 8 / 7 / 4 以区分调度指令格式

4.2 头文件自身的类型依赖

头文件里用到了 s64、u32 三种平台类型，但没有 include 任何提供这些类型的头文件（无 chip.h、无 includes.h）。它之所以能编译通过，完全依赖「包含者先包含类型头文件」这一隐式约定：math_tools.c 里先 #include "chip.h" 再 #include "math_tools.h"；net/ems.c、net/server.c、flash_data_store.c 也都是先引入 includes.h 链再引入本头文件。这是一个隐式的包含顺序契约（见备注 2）。

4.3 通信协议帧格式

本文件不涉及通信。但它声明的 parse_dispatch_para() 隐含了一处协议约定：云端调度指令的下行 JSON 中，参数字段必须名为 Parameter2，且必须是紧邻的 Parameter2":" 形式、值为逗号分隔的十进制数字串。

4.4 定时 / uCOS-II 配合

无。本文件不声明任何任务、信号量、事件标志或消息邮箱句柄，也不包含 uCOS-II 头文件。

5. 对外接口

导出（供外部使用）——三个函数原型，实际调用分布：

名称	调用方
`fmt_fixed`	`net/ems.c`（约 136 处）、`data/resume_data/flash/flash_data_store.c`（27 处）
`parse_fixed`	`net/server.c`（67 处）
`parse_dispatch_para`	`net/server.c:806`、`server.c:810`、`server.c:814`

本头文件不导出任何全局变量、常量或类型。

被调用（本文件引用的符号）：无。头文件本身不含 include，也不引用任何符号。

6. 依赖关系

依赖：

无直接 include。
隐式依赖包含者提供 s64、u32 等基础类型（通常来自 system/sys/chip.h / UCOSII/uCOS-CONFIG/includes.h 链）。

被依赖（全部 include 点）：

logic/math_tools.c:16
net/ems.c:59
net/server.c:60
data/resume_data/flash/flash_data_store.c:32

值得注意的是：本文件虽位于 logic/ 目录，却没有任何 logic 层的文件使用它；实际使用方全在网络层与数据存储层，模块归属与使用位置不一致。

7. 备注与风险点

头文件不自包含（not self-contained）：s64 / u32 未在文件内引入定义，依赖包含顺序。这类头文件在单独做编译检查（例如被某个只 include 它的新文件包含）时会直接报类型未定义，属于典型的头文件卫生问题。建议改为 #include "chip.h"（与 handle_priority.h 的做法一致）。
fmt_fixed 的返回值生命周期是接口的一部分，但没有写进头文件：返回的是共享静态缓冲区指针，头文件里完全看不到这一约束。任何把返回值存起来、跨语句使用，或在一条语句里调用超过 16 次的用法都会出错，而这只能靠阅读 .c 里的注释才能发现。建议在头文件里补注释，或改用调用方传缓冲区。
parse_fixed 返回类型与实际语义不匹配：u32 返回类型配内部 s32 计算，负值回绕语义只能靠阅读实现得知。头文件是维护者唯一的「契约来源」，此处签名具有误导性，建议改为 s32。
parse_dispatch_para 未声明缓冲区容量约定：签名只给了 out 指针与 max_fields，没有注释说明 out 至少要能放下 max_fields 个元素。当前唯一调用方传 8 而目标数组正是 f_para[8]，属于巧合安全，新调用点极易越界。
缺少入参有效性说明：三个函数的头文件声明处均无参数范围、错误码或异常返回的注释（例如 scale 必须为 10 的幂、s 不可为 NULL、parse_fixed 失败时返回 0 与真实值 0 无法区分）。这类约定目前只散落在 math_tools.c 的函数头注释里，且部分注释（如 fmt_fixed 的 s32 raw）已与实现不符。
文件头信息为占位内容：@author :Make、@version 与 @date 为空，与工程内其他文件的填写规范不一致，无功能影响。