wandering1
ad0fd53389
阶段 D（验证与卫生）离线可完成项收口；台架依赖项 D2/D5/D6 保留登记。 - D4 P3 卫生六项： - P3-1 cfg_file.c s_encode：STR 型 len==0 回绕（p_key->len - 1u）直接拒绝 - P3-2 cfg_file_store_mcu.c：原子写临时名由 p_path 同目录推导（s_build_tmp_path） - P3-4 rs485.c：模块描述订正为实际实现（HAL_Delay(1)，非 DWT µs） - P3-6 ch395f_get_socket_status：补 p_status NULL 检查 - P3-8 build.md：退出码契约订正为 0/1/2 三档 - P3-11 adc_task/rs485_task：注明"预留桩（未启用）" - D3 S-2：新增 docs/测试说明/boot_log_data/（快照存档目录 + 流程）， 并在 测试开发标准流程.md §7.3 登记沉淀约定 - 登记簿销项：删 P3-1/2/4/6/8/11、S-2；阶段 D 表移除 D3/D4； §1 计数更新（P3 6→0、登记簿 10→9）；§3 章节重排 （登记簿→§3.2、专项→§3.3）；清理 App/cfg/README.md 等对已销编号的引用 - 同步刷新内存快照：Flash 266,632 B / ROM 合计 267,372 B 验证：@build 0 错 0 警；cfg_file 主机单测 149/149； pre-commit --all-files 17/17 通过。
278 lines
9.9 KiB
C
278 lines
9.9 KiB
C
/*
|
||
* 模块名称：cfg_file_store (MCU 后端)
|
||
* 模块功能：cfg_file 存储后端——NAND 上 FatFS 文件 /config.ini（卷根，8.3 合规）；
|
||
* 原子写 = 临时文件 config.TMP（与目标同目录）+ f_rename；mtime 变更令牌 =
|
||
* (fdate << 16) | fmtime；旧版遗留文件 /cfg/netcfg.bin 供迁移读取
|
||
* 适用平台：STM32F407ZGTx
|
||
* 作者：王建锋
|
||
* 创建日期：2026-09-14
|
||
* 修改记录：
|
||
* v1.0 2026-09-14 王建锋 创建初始版本
|
||
* v1.1 2026-09-18 王建锋 增 cfg_store_alloc / cfg_store_free / cfg_store_heap_free：
|
||
* 共享核心临时缓冲改走 FreeRTOS 堆（P0-1，MicroLIB C 堆仅 512B）
|
||
* v1.2 2026-09-22 王建锋 原子写修复：rename 前先 unlink 已存在目标——本 FatFs
|
||
* 移植 f_rename 不覆盖既有目标（FR_EXIST），旧实现一切
|
||
* "目标存在的覆盖写"必然失败（E-01 台架验证暴露）
|
||
* v1.3 2026-10-02 王建锋 四个后端函数纳入卷锁 try 语义（vol_lock_wait(0)）：
|
||
* 与 ftpTask 的 lftpd 文件操作互斥（并发 FTL 写 →
|
||
* dhara journal 竞争实证）；busy 返回 -1 由调用方
|
||
* 按既有失败语义处理（poll 保留 RAM/保存待重试），
|
||
* 本任务 = 看门狗喂狗点，绝不阻塞等锁
|
||
* v1.4 2026-10-05 王建锋 原子写临时文件由 p_path 推导（P3-2）：与目标同目录的
|
||
* 固定 8.3 名 config.TMP，不再硬编码卷根；目标恒为
|
||
* "/config.ini" 时推导结果与旧值逐字节一致
|
||
*/
|
||
|
||
/* 头文件包含区 */
|
||
#include <string.h>
|
||
|
||
#include "FreeRTOS.h"
|
||
|
||
#include "cfg_file_store.h"
|
||
|
||
#include "ff.h"
|
||
#include "vol_lock.h"
|
||
|
||
/* 静态变量定义区 */
|
||
|
||
static const char s_path[] = "/config.ini";
|
||
static const char s_path_tmp[] = "/config.TMP";
|
||
static const char s_path_legacy[] = "/cfg/netcfg.bin";
|
||
|
||
/* 函数定义区 */
|
||
|
||
/*
|
||
* 函数功能：读文件（最多 cap 字节）
|
||
* 入口参数：p_path - 文件路径 const char *
|
||
* p_buf - 接收缓冲（不可为 NULL） uint8_t *
|
||
* cap - 缓冲容量 size_t
|
||
* p_nread - 实际读字节数输出（不可为 NULL） size_t *
|
||
* 返回值：0 - 成功；-1 - 文件缺失/读失败 int
|
||
* 限定条件：卷已挂载（未挂载时 f_open 返回 FR_NO_SYSTEM，转 -1）
|
||
*/
|
||
int cfg_store_read(const char *p_path, uint8_t *p_buf, size_t cap, size_t *p_nread) {
|
||
FIL f;
|
||
FRESULT fr;
|
||
UINT br = 0u;
|
||
|
||
if (p_buf == NULL || p_nread == NULL) {
|
||
return -1;
|
||
}
|
||
if (vol_lock_wait(0u) == 0u) {
|
||
return -1; /* 卷被占用：本轮跳过（调用方按读失败语义处理） */
|
||
}
|
||
fr = f_open(&f, p_path, FA_READ);
|
||
if (fr != FR_OK) {
|
||
vol_lock_release();
|
||
return -1;
|
||
}
|
||
fr = f_read(&f, p_buf, (UINT)cap, &br);
|
||
(void)f_close(&f);
|
||
if (fr != FR_OK) {
|
||
vol_lock_release();
|
||
return -1;
|
||
}
|
||
*p_nread = (size_t)br;
|
||
vol_lock_release();
|
||
return 0;
|
||
}
|
||
|
||
/* 临时文件名（8.3 合规）与路径缓冲上限 */
|
||
#define CFG_STORE_TMP_NAME "config.TMP"
|
||
#define CFG_STORE_TMP_PATH_MAX 24u
|
||
|
||
/*
|
||
* 函数功能：由目标路径推导同目录的临时文件路径（P3-2）
|
||
* 入口参数：p_path - 目标文件路径 const char *
|
||
* p_out - 输出缓冲 char *
|
||
* cap - 缓冲容量 size_t
|
||
* 返回值：0 - 成功；-1 - 参数非法/缓冲不足 int
|
||
* 函数说明：取 p_path 的目录前缀（含末尾 '/'；无 '/' 则用当前目录），拼固定 8.3 名
|
||
* config.TMP。目标 "/config.ini" → "/config.TMP"（与旧硬编码值一致）
|
||
*/
|
||
static int s_build_tmp_path(const char *p_path, char *p_out, size_t cap) {
|
||
const char *p_slash;
|
||
size_t dirlen;
|
||
|
||
if (p_path == NULL || p_out == NULL) {
|
||
return -1;
|
||
}
|
||
p_slash = strrchr(p_path, '/');
|
||
dirlen = (p_slash != NULL) ? ((size_t)(p_slash - p_path) + 1u) : 0u;
|
||
if (dirlen + sizeof(CFG_STORE_TMP_NAME) > cap) {
|
||
return -1;
|
||
}
|
||
if (dirlen != 0u) {
|
||
(void)memcpy(p_out, p_path, dirlen);
|
||
}
|
||
(void)memcpy(p_out + dirlen, CFG_STORE_TMP_NAME, sizeof(CFG_STORE_TMP_NAME));
|
||
return 0;
|
||
}
|
||
|
||
/*
|
||
* 函数功能：原子写文件（先写与目标同目录的 config.TMP，成功后 unlink 既有目标 + f_rename 替换）
|
||
* 入口参数：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) {
|
||
FIL f;
|
||
FRESULT fr;
|
||
UINT bw = 0u;
|
||
char tmp_path[CFG_STORE_TMP_PATH_MAX];
|
||
|
||
if (p_buf == NULL) {
|
||
return -1;
|
||
}
|
||
/* P3-2：临时文件由 p_path 推导（同目录 + 固定 8.3 名），不再硬编码卷根 */
|
||
if (s_build_tmp_path(p_path, tmp_path, sizeof(tmp_path)) != 0) {
|
||
return -1;
|
||
}
|
||
if (vol_lock_wait(0u) == 0u) {
|
||
return -1; /* 卷被占用：本轮跳过（保存请求由 2s 轮询重试） */
|
||
}
|
||
fr = f_open(&f, tmp_path, FA_WRITE | FA_CREATE_ALWAYS);
|
||
if (fr != FR_OK) {
|
||
vol_lock_release();
|
||
return -1;
|
||
}
|
||
fr = f_write(&f, (const void *)p_buf, (UINT)len, &bw);
|
||
(void)f_close(&f);
|
||
if (fr != FR_OK || bw != (UINT)len) {
|
||
(void)f_unlink(tmp_path);
|
||
vol_lock_release();
|
||
return -1;
|
||
}
|
||
/* 本 FatFs 移植的 f_rename 对已存在目标返回 FR_EXIST、不覆盖（ff.c
|
||
* "new name already in use" 检查，上游同语义）——"目标存在的覆盖写"必须先
|
||
* unlink 目标再 rename。2026-09-22 台架实证（E-01 验证暴露）：缺本步时
|
||
* 一切非首启写（UI 保存/模板重建）静默失败，模拟器后端（POSIX rename
|
||
* 覆盖语义）照不出。unlink→rename 非原子窗口掉电 = 配置文件暂失，
|
||
* 开机 load 按"首启"重建工厂模板——与函数失败语义一致，丢失边界 =
|
||
* 本次进行中的保存内容（目标原值本就是待覆盖的旧代数据） */
|
||
(void)f_unlink(p_path); /* 目标不存在返回 FR_NO_FILE，无害 */
|
||
fr = f_rename(tmp_path, p_path);
|
||
if (fr != FR_OK) {
|
||
(void)f_unlink(tmp_path);
|
||
vol_lock_release();
|
||
return -1;
|
||
}
|
||
vol_lock_release();
|
||
return 0;
|
||
}
|
||
|
||
/*
|
||
* 函数功能：文件状态（size + mtime 变更令牌）
|
||
* 入口参数：p_path - 文件路径 const char *
|
||
* p_st - 输出（不可为 NULL） cfg_file_stat_t *
|
||
* 返回值：0 - 成功；-1 - 文件缺失/读失败 int
|
||
* 限定条件：无
|
||
* 函数说明：FAT 时间分钟级粒度——同分钟内同长度重写不可检出（可接受，
|
||
* 见《配置文件设计说明》§6.2 mtime 令牌说明）
|
||
*/
|
||
int cfg_store_stat(const char *p_path, cfg_file_stat_t *p_st) {
|
||
FILINFO fno;
|
||
FRESULT fr;
|
||
|
||
if (p_st == NULL) {
|
||
return -1;
|
||
}
|
||
if (vol_lock_wait(0u) == 0u) {
|
||
return -1; /* 卷被占用：调用方按"文件缺失/读失败"语义处理
|
||
（poll = 保留 RAM 配置，安全） */
|
||
}
|
||
fr = f_stat(p_path, &fno);
|
||
if (fr != FR_OK) {
|
||
vol_lock_release();
|
||
return -1;
|
||
}
|
||
p_st->size = (uint32_t)fno.fsize;
|
||
p_st->mtime = (uint32_t)(((uint32_t)fno.fdate << 16) | (uint32_t)fno.ftime);
|
||
vol_lock_release();
|
||
return 0;
|
||
}
|
||
|
||
/*
|
||
* 函数功能：删除文件
|
||
* 入口参数：p_path - 文件路径 const char *
|
||
* 返回值：0 - 成功；-1 - 文件缺失/删除失败 int
|
||
* 限定条件：无
|
||
*/
|
||
int cfg_store_remove(const char *p_path) {
|
||
if (vol_lock_wait(0u) == 0u) {
|
||
return -1;
|
||
}
|
||
if (f_unlink(p_path) != FR_OK) {
|
||
vol_lock_release();
|
||
return -1;
|
||
}
|
||
vol_lock_release();
|
||
return 0;
|
||
}
|
||
|
||
/*
|
||
* 函数功能：取配置文件路径
|
||
* 入口参数：无
|
||
* 返回值："/config.ini"（卷根，8.3 合规：CONFIG + INI） const char *
|
||
* 限定条件：无
|
||
*/
|
||
const char *cfg_store_config_path(void) {
|
||
return s_path;
|
||
}
|
||
|
||
/*
|
||
* 函数功能：取配置文件临时文件路径
|
||
* 入口参数：无
|
||
* 返回值："/config.TMP"（卷根，8.3 合规：CONFIG + TMP） const char *
|
||
* 限定条件：无
|
||
*/
|
||
const char *cfg_store_tmp_path(void) {
|
||
return s_path_tmp;
|
||
}
|
||
|
||
/*
|
||
* 函数功能：取旧版配置遗留文件路径
|
||
* 入口参数：无
|
||
* 返回值："/cfg/netcfg.bin"（旧 NCFG 二进制格式） const char *
|
||
* 限定条件：无
|
||
*/
|
||
const char *cfg_store_legacy_path(void) {
|
||
return s_path_legacy;
|
||
}
|
||
|
||
/*
|
||
* 函数功能：分配共享核心临时缓冲（FreeRTOS 堆）
|
||
* 入口参数：size - 字节数 size_t
|
||
* 返回值：缓冲指针（内容未清零）；失败返回 NULL void *
|
||
* 限定条件：任务上下文调用（heap_4 内部临界区自护）；释放必须用 cfg_store_free
|
||
* 函数说明：MCU 端 MicroLIB C 堆仅 512B（startup Heap_Size=0x200），共享核心的 KB 级
|
||
* 缓冲若走 C 库 malloc 必然返回 NULL，故统一由本接口取 FreeRTOS 堆（P0-1）
|
||
*/
|
||
void *cfg_store_alloc(size_t size) {
|
||
return pvPortMalloc(size);
|
||
}
|
||
|
||
/*
|
||
* 函数功能：释放 cfg_store_alloc 分配的临时缓冲
|
||
* 入口参数：p_buf - 缓冲指针（NULL 安全） void *
|
||
* 返回值：无
|
||
* 限定条件：p_buf 必须来自 cfg_store_alloc（禁止释放栈地址或 C 库指针）
|
||
*/
|
||
void cfg_store_free(void *p_buf) {
|
||
if (p_buf != NULL) {
|
||
vPortFree(p_buf);
|
||
}
|
||
}
|
||
|
||
/*
|
||
* 函数功能：FreeRTOS 堆当前空闲字节数（分配失败诊断）
|
||
* 入口参数：无
|
||
* 返回值：空闲字节数（未计入碎片影响） uint32_t
|
||
* 限定条件：无
|
||
*/
|
||
uint32_t cfg_store_heap_free(void) {
|
||
return (uint32_t)xPortGetFreeHeapSize();
|
||
}
|