[feat][component] custom_fee v0.1#11378
Conversation
|
|
|
👋 感谢您对 RT-Thread 的贡献!Thank you for your contribution to RT-Thread! 为确保代码符合 RT-Thread 的编码规范,请在你的仓库中执行以下步骤运行代码格式化工作流(如果格式化CI运行失败)。 🛠 操作步骤 | Steps
完成后,提交将自动更新至 如有问题欢迎联系我们,再次感谢您的贡献!💐 |
📌 Code Review Assignment🏷️ Tag: componentsReviewers: Maihuanyi Changed Files (Click to expand)
📊 Current Review Status (Last Updated: 2026-05-08 17:36 CST)
📝 Review Instructions
|
f6be5d0 to
5ad4d7d
Compare
There was a problem hiding this comment.
Pull request overview
This PR introduces a new RT-Thread component components/custom_fee, a fixed-block Flash EEPROM Emulation (FEE) implementation aimed at deterministic, append-only persistence with checkpoint-assisted boot recovery and background GC.
本 PR 引入新的独立组件 components/custom_fee,用于固定逻辑块的 Flash EEPROM Emulation(FEE),强调追加写、基于 checkpoint 的启动恢复,以及后台 GC。
Changes:
- Add
custom_feecomponent integration (Kconfig + SCons) and the core FEE modules (API/scheduler/core/GC/recovery/cache/checkpoint/on-flash helpers).
增加组件集成入口(Kconfig + SCons)并落地核心模块(API/调度/核心逻辑/GC/恢复/cache/checkpoint/落盘格式辅助)。 - Provide a weak, RAM-backed mock flash backend and diagnostic/testing utilities under
fee_test.c.
提供 weak 的 RAM mock flash 后端,以及诊断/测试工具(fee_test.c)。 - Add extensive English/Chinese documentation under
components/custom_fee/doc/{en,zh}.
增加中英文文档集(components/custom_fee/doc/{en,zh})。
Reviewed changes
Copilot reviewed 45 out of 45 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| components/Kconfig | Adds custom_fee into the components Kconfig menu. |
| components/custom_fee/SConscript | Builds the custom_fee sources when enabled. |
| components/custom_fee/Kconfig | Adds COMPONENT_USING_CUSTOM_FEE and mock flash size config. |
| components/custom_fee/README.md | English component overview and entry points. |
| components/custom_fee/README.zh-CN.md | Chinese component overview and entry points. |
| components/custom_fee/fee_api.h | Public API types and function declarations. |
| components/custom_fee/fee_api.c | Public API implementation and mainfunction orchestration. |
| components/custom_fee/fee_internal.h | Internal types, globals, and module function declarations. |
| components/custom_fee/fee_cfg.h | Static configuration types and compile-time limits. |
| components/custom_fee/fee_cfg.c | Default block table and configuration validation helpers. |
| components/custom_fee/fee_onflash.h | On-flash constants and persistent structure definitions. |
| components/custom_fee/fee_onflash.c | Encode/validate helpers and checksum/CRC routines. |
| components/custom_fee/fee_port.h | Port-layer capability and debug stats definitions. |
| components/custom_fee/fee_port.c | Port wrapper + weak RAM mock flash backend implementation. |
| components/custom_fee/fee_flash_drv.h | Flash-driver backend interface (strong override expected). |
| components/custom_fee/fee_cache.c | RAM cache + checkpoint import/export helpers. |
| components/custom_fee/fee_ckpt.c | Checkpoint image restore/flush logic (meta area). |
| components/custom_fee/fee_sched.c | Request queues and dispatch policy implementation. |
| components/custom_fee/fee_gc.c | Lane GC state machine and background GC stepping. |
| components/custom_fee/fee_core.c | Core read/write/invalidate/rollback and checkpoint request logic. |
| components/custom_fee/fee_recovery.c | Boot recovery, checkpoint selection, and tail scan logic. |
| components/custom_fee/fee_lane_fast.c | FAST lane init stub. |
| components/custom_fee/fee_lane_log.c | LOG/NORMAL lane init stub. |
| components/custom_fee/fee_lane_bulk.c | BULK lane init stub. |
| components/custom_fee/fee_test.c | Shell tests/diagnostics and flash layout dumping utilities. |
| components/custom_fee/doc/en/README.md | English doc index. |
| components/custom_fee/doc/en/fee_redesign.md | English architecture/design overview. |
| components/custom_fee/doc/en/fee_API.md | English public API usage guide. |
| components/custom_fee/doc/en/fee_onflash_format.md | English on-flash format specification. |
| components/custom_fee/doc/en/fee_boot_recovery.md | English boot recovery specification. |
| components/custom_fee/doc/en/fee_scheduler_gc.md | English scheduling + GC policy. |
| components/custom_fee/doc/en/fee_cache_checkpoint.md | English cache + checkpoint policy. |
| components/custom_fee/doc/en/fee_cfg_rules.md | English configuration rules and validation guidance. |
| components/custom_fee/doc/en/fee_port_adapter.md | English port adapter contract. |
| components/custom_fee/doc/en/fee_diag_test.md | English diagnostic test guide. |
| components/custom_fee/doc/zh/README.md | 中文文档索引。 |
| components/custom_fee/doc/zh/fee_redesign.md | 中文架构/设计总览。 |
| components/custom_fee/doc/zh/fee_API.md | 中文对外 API 指南。 |
| components/custom_fee/doc/zh/fee_onflash_format.md | 中文落盘格式说明。 |
| components/custom_fee/doc/zh/fee_boot_recovery.md | 中文启动恢复说明。 |
| components/custom_fee/doc/zh/fee_scheduler_gc.md | 中文调度与 GC 策略。 |
| components/custom_fee/doc/zh/fee_cache_checkpoint.md | 中文 cache 与 checkpoint 说明。 |
| components/custom_fee/doc/zh/fee_cfg_rules.md | 中文配置规则与校验建议。 |
| components/custom_fee/doc/zh/fee_port_adapter.md | 中文 port 适配边界说明。 |
| components/custom_fee/doc/zh/fee_diag_test.md | 中文诊断测试与解读指南。 |
| if !RT_USING_NANO | ||
| rsource "dfs/Kconfig" | ||
| rsource "fal/Kconfig" | ||
| rsource "custom_fee/Kconfig" |
| static fee_ret_t fee_port_check_range(uint32_t addr, uint32_t len) | ||
| { | ||
| if ((addr + len) > (uint32_t)sizeof(g_fee_mock_flash)) | ||
| { | ||
| return FEE_E_PARAM; | ||
| } |
| align = (cfg->record_align == 0U) ? FEE_CFG_ALIGN_UNIT : cfg->record_align; | ||
| payload_len = fee_onflash_align_up((uint32_t)data_len, FEE_CFG_ALIGN_UNIT); | ||
| span = (uint32_t)sizeof(fee_record_header_t) + payload_len + (uint32_t)sizeof(fee_commit_tail_t); | ||
|
|
||
| return fee_onflash_align_up(span, align); |
| { | ||
| return ret; | ||
| } | ||
|
|
| fee_ret_t fee_port_get_status(void); | ||
| fee_ret_t fee_port_get_job_result(void); |
| static uint32_t fee_onflash_crc32_update(uint32_t crc, const uint8_t *data, uint32_t len) | ||
| { | ||
| uint32_t i; | ||
|
|
||
| if (data == RT_NULL) | ||
| { | ||
| return crc; | ||
| } | ||
|
|
||
| for (i = 0U; i < len; ++i) | ||
| { | ||
| crc = (crc << 5) - crc + data[i]; | ||
| } |
|
|
||
| ## Directory layout | ||
|
|
||
| - [doc/README.md](./doc/README.md): documentation index |
| - [doc/README.md](./doc/README.md):文档总索引 | ||
| - [doc/zh/README.md](./doc/zh/README.md):中文版文档 | ||
| - [doc/en/README.md](./doc/en/README.md):英文版文档 |
| - The documentation references a `fee_port` adapter layer and test backends as | ||
| part of the intended integration model. | ||
| - The corresponding adapter and test source files are not included in this | ||
| snapshot, so bring-up still requires project-side integration work. |
|
|
||
| - 核心 FEE 逻辑和设计文档已经具备。 | ||
| - 文档中约定了 `fee_port` 适配层和测试后端的集成方式。 | ||
| - 相关适配层与测试源文件目前不在这个快照里,实际接板仍需要项目侧补齐。 |
拉取/合并请求描述:(PR description)
[
为什么提交这份PR (why to submit this PR)
本 PR 引入并完善了一个新的独立组件
custom_fee。它面向嵌入式场景下“少量 block 化数据需要可靠持久化到 flash”的需求,用来承接配置参数、标定数据、状态快照等非易失数据,而不是让业务层直接处理裸 flash record、掉电恢复、GC 和版本回滚。从设计目标上看,这个组件并不是要替代通用 KV 数据库,而是要解决固定逻辑块持久化场景下,通用方案常见的两个痛点:
FlashDB KVDB一类通用 KV 机制,降低 GC 被动触发、整 sector 扫描、逐条物理记录搬运带来的长尾问题这个组件主要解决以下问题:
如果目标问题是“FlashDB 在固定 block 存储场景下 GC 偏慢、上电读 block 偏慢”,那么这套
custom_fee的设计方向就是针对这两个问题给出专用解法,而不是继续在通用 KV 模型上做局部修补。custom_fee当前的核心机制如下:cur/prev地址和状态,读路径先查 cache,再按地址读 payload,避免反复全盘扫描rollback,也在当前副本异常时保留降级读取机会CKPT_READY阶段提前可读,剩余 tail 再后台补扫到FULL_READYFAST / NORMAL / BULKlane,把高频小数据和低频大数据隔离,减少相互干扰read走同步路径,write/invalidate/rollback走调度队列并由fee_mainfunction()推进,兼顾读延迟确定性和后台擦写调度fee_flash_driver_*接口,上层逻辑不关心底层接的是 RAM mock、QEMU 还是实际 flash/FLS 驱动因此,这个 PR 不只是“加几个测试”或“适配一个 BSP”,而是把
custom_fee作为一个可独立接入、可独立验证、可继续迁移到真实硬件的 FEE 组件完整落地出来。你的解决方案是什么 (what is your solution)
components/custom_fee文档整理到components/custom_fee/doc/,补充README、对外 API、on-flash 格式、checkpoint/cache、启动恢复、调度/GC、配置规则、端口适配和诊断测试说明fee_flash_driver_*驱动抽象;fee_port.c仅保留薄封装,默认提供 weak 的 RAM mock backend,板级工程可通过 strong definition 覆盖为真实 flash/FLS 驱动bsp/qemu-vexpress-a9打开custom_fee组件,使用 RAM mock flash 完成 bring-up 和回归验证fee_test.c,补充custom_fee_test/custom_fee_diag_test场景,覆盖 block 写入、读回、rollback、invalidate、重新初始化恢复read/write/erase/poll的真实访问次数与字节数统计fee_api.h使用 FEE;后续迁移到真实硬件时,仅需按统一接口实现fee_flash_driver_*请提供验证的bsp和config (provide the config and bsp)
bsp/qemu-vexpress-a9CONFIG_COMPONENT_USING_CUSTOM_FEE=yCONFIG_CUSTOM_FEE_MOCK_FLASH_SIZE=0xA0000scons -j8编译通过custom_fee_testcustom_fee_diag_testN/A(本次为本地 QEMU 验证,未提供个人 fork action 链接)]
当前拉取/合并请求的状态 Intent for your PR
必须选择一项 Choose one (Mandatory):
代码质量 Code Quality:
我在这个拉取/合并请求中已经考虑了 As part of this pull request, I've considered the following:
#if 0代码,不包含已经被注释了的代码 All redundant code is removed and cleaned up