整理 App 与 test 目录：按职责分子目录并同步全库引用

2026-09-26 12:51:07 +08:00
parent 39bd06adea
commit 22559365b9
90 changed files with 2650 additions and 2487 deletions
@@ -0,0 +1,113 @@
+/*
+ * 模块名称：cfg_file_store
+ * 模块功能：cfg_file 平台存储后端接口——带路径的文件操作抽象；
+ *           MCU 实现 = NAND 上 FatFS（cfg_file_store_mcu.c），
+ *           模拟器实现 = 宿主文件系统（cfg_file_store_sim.c）
+ * 适用平台：双端接口（实现分居两端）
+ * 作者：王建锋
+ * 创建日期：2026-09-14
+ * 修改记录：
+ *     v1.0  2026-09-14  王建锋  创建初始版本
+ */
+
+#ifndef CFG_FILE_STORE_H
+#define CFG_FILE_STORE_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdint.h>
+
+#include <stddef.h>
+
+/*
+ * 文件变更基线：size + mtime 变更令牌
+ * mtime 仅作等值比较（不等 = 可能变更）：
+ *   MCU 端 = FAT 打包时间（fdate<<16 | fmtime，分钟级粒度）
+ *   模拟器 = 宿主文件 mtime（秒级）
+ */
+typedef struct {
+    uint32_t size;
+    uint32_t mtime;
+} cfg_file_stat_t;
+
+/*
+ * 函数功能：分配共享核心临时缓冲（由平台后端提供：MCU = FreeRTOS 堆 pvPortMalloc，
+ *           模拟器 = 宿主 CRT malloc）
+ * 入口参数：size - 字节数  size_t
+ * 返回值：缓冲指针（内容未清零）；失败返回 NULL  void *
+ * 限定条件：必须与 cfg_store_free 配对；共享核心（cfg_file.c / net_cfg.c）禁止直接
+ *          调用 C 库 malloc——MCU 端 MicroLIB C 堆仅 512 B（startup Heap_Size=0x200），
+ *          KB 级分配必然失败，一律经本接口取 FreeRTOS 堆
+ */
+void *cfg_store_alloc(size_t size);
+
+/*
+ * 函数功能：释放 cfg_store_alloc 分配的临时缓冲
+ * 入口参数：p_buf - 缓冲指针（NULL 安全）  void *
+ * 返回值：无
+ * 限定条件：p_buf 必须来自 cfg_store_alloc（不得跨分配器释放、不得释放栈地址）
+ */
+void cfg_store_free(void *p_buf);
+
+/*
+ * 函数功能：当前空闲堆字节数（分配失败诊断用，非精确预算）
+ * 入口参数：无
+ * 返回值：空闲字节数；模拟器不跟踪宿主堆，恒返回 0  uint32_t
+ * 限定条件：无
+ */
+uint32_t cfg_store_heap_free(void);
+
+/*
+ * 函数功能：读文件（最多 cap 字节）
+ * 入口参数：p_path - 文件路径  const char *
+ *           p_buf  - 接收缓冲（不可为 NULL）  uint8_t *
+ *           cap    - 缓冲容量  size_t
+ *           p_nread- 实际读字节数输出（不可为 NULL）  size_t *
+ * 返回值：0 - 成功；-1 - 文件缺失/读失败  int
+ * 限定条件：调用方保证 p_buf 容量 ≥ 所需长度（引擎读上限 CFG_FILE_MAX_LEN）
+ */
+int cfg_store_read(const char *p_path, uint8_t *p_buf, size_t cap, size_t *p_nread);
+
+/*
+ * 函数功能：原子写文件（先写临时文件，成功后改名覆盖目标）
+ * 入口参数：p_path - 目标文件路径  const char *
+ *           p_buf  - 待写数据（不可为 NULL）  const uint8_t *
+ *           len    - 数据长度  size_t
+ * 返回值：0 - 成功；-1 - 写/改名失败（目标文件保持不动，临时文件清理）  int
+ * 限定条件：中途失败不得损坏目标文件（掉电安全）
+ */
+int cfg_store_write_atomic(const char *p_path, const uint8_t *p_buf, size_t len);
+
+/*
+ * 函数功能：文件状态（size + mtime 变更令牌）
+ * 入口参数：p_path - 文件路径  const char *
+ *           p_st   - 输出（不可为 NULL）  cfg_file_stat_t *
+ * 返回值：0 - 成功；-1 - 文件缺失/读失败  int
+ * 限定条件：无
+ */
+int cfg_store_stat(const char *p_path, cfg_file_stat_t *p_st);
+
+/*
+ * 函数功能：删除文件
+ * 入口参数：p_path - 文件路径  const char *
+ * 返回值：0 - 成功；-1 - 文件缺失/删除失败  int
+ * 限定条件：无
+ */
+int cfg_store_remove(const char *p_path);
+
+/* 函数功能：取配置文件路径（如 MCU "/config.ini"、模拟器 "sim_config.ini"） */
+const char *cfg_store_config_path(void);
+
+/* 函数功能：取配置文件临时文件路径（write_atomic 内部用） */
+const char *cfg_store_tmp_path(void);
+
+/* 函数功能：取旧版配置遗留文件路径（net_cfg_legacy 迁移用） */
+const char *cfg_store_legacy_path(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* CFG_FILE_STORE_H */