STM32F4-Base/App/cfg/cfg_file_store_mcu.c

/*
 * 模块名称：cfg_file_store (MCU 后端)
 * 模块功能：cfg_file 存储后端——NAND 上 FatFS 文件 /config.ini（卷根，8.3 合规）；
 *          原子写 = 临时文件 config.TMP（与目标同目录）+ f_rename；mtime 变更令牌 =
 *          (fdate << 16) | fmtime
 * 适用平台：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.5  2026-10-24  王建锋  仅注释更正：cfg_store_read 的"限定条件"引用了
 *                              FRESULT 里不存在的 FR_NO_SYSTEM，改成实际会返回的
 *                              FR_NOT_READY / FR_NO_FILESYSTEM 并写明"非 FR_OK 一律
 *                              转 -1，不要枚举错误码集合"（无行为改动）
 *     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";

/* 函数定义区 */

/*
 * 函数功能：读文件（最多 cap 字节）
 * 入口参数：p_path  - 文件路径  const char *
 *           p_buf   - 接收缓冲（不可为 NULL）  uint8_t *
 *           cap     - 缓冲容量  size_t
 *           p_nread - 实际读字节数输出（不可为 NULL）  size_t *
 * 返回值：0 - 成功；-1 - 文件缺失/读失败  int
 * 限定条件：卷已挂载。未挂载时本函数一律转 -1，但**别照着不存在的错误码去写
 *           判据**：Lib/FatFs/ff.h 的 FRESULT 共 20 个码（FR_OK..FR_INVALID_PARAMETER），
 *           没有 FR_NO_SYSTEM（旧注释此处笔误，2026-10-24 更正）。本移植里卷未挂载
 *           实际返回 FR_NOT_READY(3)（物理驱动器不可用）或 FF_VOLUMES 内无已挂载卷时
 *           由 mount_volume 直接给错；卷上无有效 FAT 则返回 FR_NO_FILESYSTEM(13)。
 *           本函数（以及 write_atomic / stat / remove）对**任何**非 FR_OK 一律转 -1，
 *           所以这些码的差异不影响对外语义——也正因如此，谁都不该去枚举错误码集合，
 *           除了自愈触发集那种"必须区分能不能靠删文件修好"的场合（见 sys_log_mcu.c
 *           的 s_is_selfheal_code）。
 * 函数说明：FIL 为**函数级 static**而非局部——本 FatFs 移植 FF_FS_TINY=0，
 *          `FIL` 内含 `buf[FF_MAX_SS]`=512 B（Lib/FatFs/ff.h），一个局部对象就吃掉
 *          528 B 栈，是配置/syslog 调用链栈深的主要来源（2026-10-10 栈预算整改）。
 *          安全性：整个 FIL 生命周期都在 `vol_lock_wait()/release()` 区间内，
 *          跨任务访问被卷锁串行化，且本函数不递归、不嵌套自身
 */
int cfg_store_read(const char *p_path, uint8_t *p_buf, size_t cap, size_t *p_nread) {
    static FIL f;                 /* static：省 528 B 栈；卷锁内串行使用 */
    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
 * 限定条件：卷已挂载；中途失败（含掉电）不损坏目标文件
 * 函数说明：`FIL` 用函数级 static 而非局部（FF_FS_TINY=0 → 单个 FIL = 528 B 栈）；
 *          与 cfg_store_read 各持自己的 static 对象，互不共享，且全程在卷锁区间内
 */
int cfg_store_write_atomic(const char *p_path, const uint8_t *p_buf, size_t len) {
    static FIL f;                 /* static：省 528 B 栈；卷锁内串行使用 */
    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 的路径 getter（cfg_store_legacy_path）已于
 * 2026-10-10 随旧档迁移 net_cfg_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();
}