RT-Thread · O-O-BOOK · May 6, 2026
diff --git a/components/Kconfig b/components/Kconfig
@@ -32,6 +32,7 @@ endif
 if !RT_USING_NANO
 rsource "dfs/Kconfig"
 rsource "fal/Kconfig"
+rsource "custom_fee/Kconfig"
 rsource "drivers/Kconfig"
 rsource "libc/Kconfig"
 rsource "net/Kconfig"

diff --git a/components/custom_fee/Kconfig b/components/custom_fee/Kconfig
@@ -0,0 +1,11 @@
+config COMPONENT_USING_CUSTOM_FEE
+    bool "using component custom fee"
+    default n
+
+if COMPONENT_USING_CUSTOM_FEE
+
+config CUSTOM_FEE_MOCK_FLASH_SIZE
+    hex "RAM mock flash size"
+    default 0xA0000
+
+endif
diff --git a/components/custom_fee/README.md b/components/custom_fee/README.md
@@ -0,0 +1,111 @@
+# custom_fee
+
+`custom_fee` is a fixed-block Flash EEPROM Emulation (FEE) component for embedded
+systems. It targets deterministic block storage rather than a general-purpose KV
+database, with append-only writes, checkpoint-assisted boot recovery, and
+background garbage collection.
+
+## Implemented scope
+
+The current source tree already contains the main control flow and data-model
+building blocks for the component:
+
+- Public API entry points in [fee_api.h](./fee_api.h)
+  and [fee_api.c](./fee_api.c)
+- Request submission and foreground/background arbitration in
+  [fee_sched.c](./fee_sched.c)
+- Core read, write, invalidate, rollback, and record validation logic in
+  [fee_core.c](./fee_core.c)
+- RAM cache maintenance and checkpoint import/export in
+  [fee_cache.c](./fee_cache.c) and
+  [fee_ckpt.c](./fee_ckpt.c)
+- Boot recovery, checkpoint restore, tail scan, and interrupted-GC handling in
+  [fee_recovery.c](./fee_recovery.c)
+- Incremental garbage collection state handling in
+  [fee_gc.c](./fee_gc.c)
+- On-flash header, tail, and record helpers in
+  [fee_onflash.h](./fee_onflash.h) and
+  [fee_onflash.c](./fee_onflash.c)
+- Static block and lane configuration in
+  [fee_cfg.h](./fee_cfg.h) and
+  [fee_cfg.c](./fee_cfg.c)
+
+## Functional characteristics
+
+At the component level, the current implementation is designed around these
+behaviors:
+
+- Block-oriented access by `block_id`
+- Synchronous reads plus queued writes, invalidates, and rollbacks
+- Current-copy and previous-copy tracking for rollback and tolerant recovery
+- RAM cache lookup after initialization instead of full media scans on every read
+- Checkpoint-based startup acceleration with staged initialization states
+- Lane-based isolation for fast, normal, and bulk traffic
+- Background GC and checkpoint work driven by `fee_mainfunction()`
+- Record-level commit markers and CRC validation for power-loss recovery
+
+## Public API
+
+The user-facing API currently exposed by
+[fee_api.h](./fee_api.h) is:
+
+```c
+fee_ret_t fee_init(void);
+fee_ret_t fee_read(uint16_t block_id, uint16_t offset, uint8_t *dst, uint16_t len);
+fee_ret_t fee_write(uint16_t block_id, const uint8_t *src, uint16_t len);
+fee_ret_t fee_invalidate(uint16_t block_id);
+fee_ret_t fee_get_status(uint16_t block_id, fee_block_status_t *status);
+fee_ret_t fee_rollback(uint16_t block_id);
+void fee_mainfunction(void);
+
+fee_status_t fee_get_memif_status(void);
+fee_job_result_t fee_get_job_result(void);
+fee_init_state_t fee_get_init_state(void);
+```
+
+## Directory layout
+
+- [doc/README.md](./doc/README.md): documentation index
+- [doc/en/README.md](./doc/en/README.md): English documents
+- [doc/zh/README.md](./doc/zh/README.md): Chinese documents
+- Source files in the repository root: API, scheduler, GC, recovery, cache,
+  checkpoint, on-flash format, and configuration modules
+- [Kconfig](./Kconfig) and
+  [SConscript](./SConscript): integration hooks
+
+## Documentation sets
+
+Two separated documentation sets are now provided:
+
+- English: [doc/en/README.md](./doc/en/README.md)
+- Chinese: [doc/zh/README.md](./doc/zh/README.md)
+
+Recommended entry points:
+
+- Architecture and redesign baseline:
+  [doc/en/fee_redesign.md](./doc/en/fee_redesign.md)
+- Public API and usage:
+  [doc/en/fee_API.md](./doc/en/fee_API.md)
+- Diagnostic test interpretation:
+  [doc/en/fee_diag_test.md](./doc/en/fee_diag_test.md)
+
+## Current repository status
+
+This repository snapshot is still an integration-oriented implementation set,
+not a production-complete drop-in release.
+
+- The core module logic and design documents are present.
+- 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.
+
+## Quick integration notes
+
+1. Configure the component in [Kconfig](./Kconfig).
+2. Define the block table and flash capabilities required by the target.
+3. Call `fee_init()` during boot.
+4. Drive `fee_mainfunction()` periodically.
+5. Treat `fee_write()`, `fee_invalidate()`, and `fee_rollback()` as queued jobs
+   and observe completion through status/job-result APIs.
+
diff --git a/components/custom_fee/README.zh-CN.md b/components/custom_fee/README.zh-CN.md
@@ -0,0 +1,81 @@
+# custom_fee
+
+`custom_fee` 是一个面向嵌入式场景的固定逻辑块 Flash EEPROM Emulation
+（FEE）组件。它针对的是可预测的块存储，而不是通用 KV 数据库，核心目标是
+提供追加写、基于 checkpoint 的快速恢复，以及后台 GC 整理能力。
+
+## 当前已实现范围
+
+当前代码树已经包含该组件的主要控制流程和数据模型骨架：
+
+- [fee_api.h](./fee_api.h) / [fee_api.c](./fee_api.c)：对外 API 入口
+- [fee_sched.c](./fee_sched.c)：请求分级和前后台调度
+- [fee_core.c](./fee_core.c)：读、写、失效、回滚和记录校验
+- [fee_cache.c](./fee_cache.c) / [fee_ckpt.c](./fee_ckpt.c)：RAM cache 与 checkpoint
+- [fee_recovery.c](./fee_recovery.c)：上电恢复、tail scan、GC 中断恢复
+- [fee_gc.c](./fee_gc.c)：增量 GC 状态推进
+- [fee_onflash.h](./fee_onflash.h) / [fee_onflash.c](./fee_onflash.c)：落盘格式辅助逻辑
+- [fee_cfg.h](./fee_cfg.h) / [fee_cfg.c](./fee_cfg.c)：静态 block 和 lane 配置
+
+## 组件功能特征
+
+当前实现围绕以下能力展开：
+
+- 基于 `block_id` 的块访问模型
+- 同步读，异步排队的写入、失效和回滚
+- 当前副本与上一副本并存，支持回滚和容错恢复
+- 初始化完成后优先走 RAM cache，而不是每次读都全盘扫描
+- 通过 checkpoint 缩短启动恢复时间
+- `FAST` / `NORMAL` / `BULK` lane 隔离
+- 通过 `fee_mainfunction()` 推进后台 GC 和 checkpoint
+- 结合提交标记和 CRC 做掉电一致性判定
+
+## 对外 API
+
+当前对业务层暴露的接口定义在 [fee_api.h](./fee_api.h)：
+
+```c
+fee_ret_t fee_init(void);
+fee_ret_t fee_read(uint16_t block_id, uint16_t offset, uint8_t *dst, uint16_t len);
+fee_ret_t fee_write(uint16_t block_id, const uint8_t *src, uint16_t len);
+fee_ret_t fee_invalidate(uint16_t block_id);
+fee_ret_t fee_get_status(uint16_t block_id, fee_block_status_t *status);
+fee_ret_t fee_rollback(uint16_t block_id);
+void fee_mainfunction(void);
+
+fee_status_t fee_get_memif_status(void);
+fee_job_result_t fee_get_job_result(void);
+fee_init_state_t fee_get_init_state(void);
+```
+
+## 文档入口
+
+- [doc/README.md](./doc/README.md)：文档总索引
+- [doc/zh/README.md](./doc/zh/README.md)：中文版文档
+- [doc/en/README.md](./doc/en/README.md)：英文版文档
+
+建议从以下文档开始阅读：
+
+- 架构与总体设计：
+  [doc/zh/fee_redesign.md](./doc/zh/fee_redesign.md)
+- 对外接口与接入方式：
+  [doc/zh/fee_API.md](./doc/zh/fee_API.md)
+- 诊断测试与结果解读：
+  [doc/zh/fee_diag_test.md](./doc/zh/fee_diag_test.md)
+
+## 当前仓库状态
+
+当前仓库更接近一个可集成的实现集合，还不是可直接量产落地的完整版本。
+
+- 核心 FEE 逻辑和设计文档已经具备。
+- 文档中约定了 `fee_port` 适配层和测试后端的集成方式。
+- 相关适配层与测试源文件目前不在这个快照里，实际接板仍需要项目侧补齐。
+
+## 快速接入建议
+
+1. 在 [Kconfig](./Kconfig) 中打开组件。
+2. 根据目标平台配置 block 表和底层 flash 能力参数。
+3. 系统启动时调用 `fee_init()`。
+4. 周期性调用 `fee_mainfunction()`。
+5. 将 `fee_write()`、`fee_invalidate()`、`fee_rollback()` 视为异步请求，
+   并通过状态接口查询最终结果。
diff --git a/components/custom_fee/SConscript b/components/custom_fee/SConscript
@@ -0,0 +1,29 @@
+from building import *
+
+objs = []
+cwd = GetCurrentDir()
+
+if not GetDepend("COMPONENT_USING_CUSTOM_FEE"):
+    Return('objs')
+
+src = [
+    'fee_cfg.c',
+    'fee_api.c',
+    'fee_port.c',
+    'fee_sched.c',
+    'fee_core.c',
+    'fee_gc.c',
+    'fee_recovery.c',
+    'fee_cache.c',
+    'fee_ckpt.c',
+    'fee_lane_fast.c',
+    'fee_lane_log.c',
+    'fee_lane_bulk.c',
+    'fee_onflash.c',
+    'fee_test.c',
+]
+
+CPPPATH = [cwd]
+group = DefineGroup('custom_fee', src, depend = ['COMPONENT_USING_CUSTOM_FEE'], CPPPATH = CPPPATH)
+
+Return('group')
diff --git a/components/custom_fee/doc/en/README.md b/components/custom_fee/doc/en/README.md
@@ -0,0 +1,27 @@
+# custom_fee English Documentation
+
+This directory contains the English documentation set for `custom_fee`.
+
+## Recommended reading order
+
+1. [fee_redesign.md](./fee_redesign.md)
+2. [fee_API.md](./fee_API.md)
+3. [fee_onflash_format.md](./fee_onflash_format.md)
+4. [fee_boot_recovery.md](./fee_boot_recovery.md)
+5. [fee_scheduler_gc.md](./fee_scheduler_gc.md)
+6. [fee_cache_checkpoint.md](./fee_cache_checkpoint.md)
+7. [fee_cfg_rules.md](./fee_cfg_rules.md)
+8. [fee_port_adapter.md](./fee_port_adapter.md)
+9. [fee_diag_test.md](./fee_diag_test.md)
+
+## Document overview
+
+- `fee_redesign.md`: system goals, architecture, storage model, and rollout plan
+- `fee_API.md`: public API semantics, integration pattern, and usage pitfalls
+- `fee_onflash_format.md`: sector, record, and checkpoint persistence format
+- `fee_boot_recovery.md`: boot recovery states, checkpoint restore, and tail scan
+- `fee_scheduler_gc.md`: request scheduling, `BUSY_INTERNAL`, and GC rules
+- `fee_cache_checkpoint.md`: RAM cache structure, checkpoint policy, and bounds
+- `fee_cfg_rules.md`: block configuration, lane mapping, and sizing rules
+- `fee_port_adapter.md`: flash-port abstraction and backend expectations
+- `fee_diag_test.md`: diagnostic test flow, dump interpretation, and performance view