Skip to content

Commit 5ad4d7d

Browse files
O-O-BOOKO-O-BOOK
committed
[feat]fee first version
1 parent 1254af4 commit 5ad4d7d

55 files changed

Lines changed: 15697 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎components/Kconfig‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ endif
3232
if !RT_USING_NANO
3333
rsource "dfs/Kconfig"
3434
rsource "fal/Kconfig"
35+
rsource "custom_fee/Kconfig"
3536
rsource "drivers/Kconfig"
3637
rsource "libc/Kconfig"
3738
rsource "net/Kconfig"

‎components/custom_fee/Kconfig‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
config COMPONENT_USING_CUSTOM_FEE
2+
bool "using component custom fee"
3+
default n
4+
5+
if COMPONENT_USING_CUSTOM_FEE
6+
7+
config CUSTOM_FEE_MOCK_FLASH_SIZE
8+
hex "RAM mock flash size"
9+
default 0xA0000
10+
11+
endif

‎components/custom_fee/README.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# custom_fee
2+
3+
`custom_fee` is a fixed-block Flash EEPROM Emulation (FEE) component for embedded
4+
systems. It targets deterministic block storage rather than a general-purpose KV
5+
database, with append-only writes, checkpoint-assisted boot recovery, and
6+
background garbage collection.
7+
8+
## Implemented scope
9+
10+
The current source tree already contains the main control flow and data-model
11+
building blocks for the component:
12+
13+
- Public API entry points in [fee_api.h](./fee_api.h)
14+
and [fee_api.c](./fee_api.c)
15+
- Request submission and foreground/background arbitration in
16+
[fee_sched.c](./fee_sched.c)
17+
- Core read, write, invalidate, rollback, and record validation logic in
18+
[fee_core.c](./fee_core.c)
19+
- RAM cache maintenance and checkpoint import/export in
20+
[fee_cache.c](./fee_cache.c) and
21+
[fee_ckpt.c](./fee_ckpt.c)
22+
- Boot recovery, checkpoint restore, tail scan, and interrupted-GC handling in
23+
[fee_recovery.c](./fee_recovery.c)
24+
- Incremental garbage collection state handling in
25+
[fee_gc.c](./fee_gc.c)
26+
- On-flash header, tail, and record helpers in
27+
[fee_onflash.h](./fee_onflash.h) and
28+
[fee_onflash.c](./fee_onflash.c)
29+
- Static block and lane configuration in
30+
[fee_cfg.h](./fee_cfg.h) and
31+
[fee_cfg.c](./fee_cfg.c)
32+
33+
## Functional characteristics
34+
35+
At the component level, the current implementation is designed around these
36+
behaviors:
37+
38+
- Block-oriented access by `block_id`
39+
- Synchronous reads plus queued writes, invalidates, and rollbacks
40+
- Current-copy and previous-copy tracking for rollback and tolerant recovery
41+
- RAM cache lookup after initialization instead of full media scans on every read
42+
- Checkpoint-based startup acceleration with staged initialization states
43+
- Lane-based isolation for fast, normal, and bulk traffic
44+
- Background GC and checkpoint work driven by `fee_mainfunction()`
45+
- Record-level commit markers and CRC validation for power-loss recovery
46+
47+
## Public API
48+
49+
The user-facing API currently exposed by
50+
[fee_api.h](./fee_api.h) is:
51+
52+
```c
53+
fee_ret_t fee_init(void);
54+
fee_ret_t fee_read(uint16_t block_id, uint16_t offset, uint8_t *dst, uint16_t len);
55+
fee_ret_t fee_write(uint16_t block_id, const uint8_t *src, uint16_t len);
56+
fee_ret_t fee_invalidate(uint16_t block_id);
57+
fee_ret_t fee_get_status(uint16_t block_id, fee_block_status_t *status);
58+
fee_ret_t fee_rollback(uint16_t block_id);
59+
void fee_mainfunction(void);
60+
61+
fee_status_t fee_get_memif_status(void);
62+
fee_job_result_t fee_get_job_result(void);
63+
fee_init_state_t fee_get_init_state(void);
64+
```
65+
66+
## Directory layout
67+
68+
- [doc/README.md](./doc/README.md): documentation index
69+
- [doc/en/README.md](./doc/en/README.md): English documents
70+
- [doc/zh/README.md](./doc/zh/README.md): Chinese documents
71+
- Source files in the repository root: API, scheduler, GC, recovery, cache,
72+
checkpoint, on-flash format, and configuration modules
73+
- [Kconfig](./Kconfig) and
74+
[SConscript](./SConscript): integration hooks
75+
76+
## Documentation sets
77+
78+
Two separated documentation sets are now provided:
79+
80+
- English: [doc/en/README.md](./doc/en/README.md)
81+
- Chinese: [doc/zh/README.md](./doc/zh/README.md)
82+
83+
Recommended entry points:
84+
85+
- Architecture and redesign baseline:
86+
[doc/en/fee_redesign.md](./doc/en/fee_redesign.md)
87+
- Public API and usage:
88+
[doc/en/fee_API.md](./doc/en/fee_API.md)
89+
- Diagnostic test interpretation:
90+
[doc/en/fee_diag_test.md](./doc/en/fee_diag_test.md)
91+
92+
## Current repository status
93+
94+
This repository snapshot is still an integration-oriented implementation set,
95+
not a production-complete drop-in release.
96+
97+
- The core module logic and design documents are present.
98+
- The documentation references a `fee_port` adapter layer and test backends as
99+
part of the intended integration model.
100+
- The corresponding adapter and test source files are not included in this
101+
snapshot, so bring-up still requires project-side integration work.
102+
103+
## Quick integration notes
104+
105+
1. Configure the component in [Kconfig](./Kconfig).
106+
2. Define the block table and flash capabilities required by the target.
107+
3. Call `fee_init()` during boot.
108+
4. Drive `fee_mainfunction()` periodically.
109+
5. Treat `fee_write()`, `fee_invalidate()`, and `fee_rollback()` as queued jobs
110+
and observe completion through status/job-result APIs.
111+

‎components/custom_fee/README.zh-CN.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# custom_fee
2+
3+
`custom_fee` 是一个面向嵌入式场景的固定逻辑块 Flash EEPROM Emulation
4+
（FEE）组件。它针对的是可预测的块存储，而不是通用 KV 数据库，核心目标是
5+
提供追加写、基于 checkpoint 的快速恢复，以及后台 GC 整理能力。
6+
7+
## 当前已实现范围
8+
9+
当前代码树已经包含该组件的主要控制流程和数据模型骨架：
10+
11+
- [fee_api.h](./fee_api.h) / [fee_api.c](./fee_api.c)：对外 API 入口
12+
- [fee_sched.c](./fee_sched.c)：请求分级和前后台调度
13+
- [fee_core.c](./fee_core.c)：读、写、失效、回滚和记录校验
14+
- [fee_cache.c](./fee_cache.c) / [fee_ckpt.c](./fee_ckpt.c)：RAM cache 与 checkpoint
15+
- [fee_recovery.c](./fee_recovery.c)：上电恢复、tail scan、GC 中断恢复
16+
- [fee_gc.c](./fee_gc.c)：增量 GC 状态推进
17+
- [fee_onflash.h](./fee_onflash.h) / [fee_onflash.c](./fee_onflash.c)：落盘格式辅助逻辑
18+
- [fee_cfg.h](./fee_cfg.h) / [fee_cfg.c](./fee_cfg.c)：静态 block 和 lane 配置
19+
20+
## 组件功能特征
21+
22+
当前实现围绕以下能力展开：
23+
24+
- 基于 `block_id` 的块访问模型
25+
- 同步读，异步排队的写入、失效和回滚
26+
- 当前副本与上一副本并存，支持回滚和容错恢复
27+
- 初始化完成后优先走 RAM cache，而不是每次读都全盘扫描
28+
- 通过 checkpoint 缩短启动恢复时间
29+
- `FAST` / `NORMAL` / `BULK` lane 隔离
30+
- 通过 `fee_mainfunction()` 推进后台 GC 和 checkpoint
31+
- 结合提交标记和 CRC 做掉电一致性判定
32+
33+
## 对外 API
34+
35+
当前对业务层暴露的接口定义在 [fee_api.h](./fee_api.h)：
36+
37+
```c
38+
fee_ret_t fee_init(void);
39+
fee_ret_t fee_read(uint16_t block_id, uint16_t offset, uint8_t *dst, uint16_t len);
40+
fee_ret_t fee_write(uint16_t block_id, const uint8_t *src, uint16_t len);
41+
fee_ret_t fee_invalidate(uint16_t block_id);
42+
fee_ret_t fee_get_status(uint16_t block_id, fee_block_status_t *status);
43+
fee_ret_t fee_rollback(uint16_t block_id);
44+
void fee_mainfunction(void);
45+
46+
fee_status_t fee_get_memif_status(void);
47+
fee_job_result_t fee_get_job_result(void);
48+
fee_init_state_t fee_get_init_state(void);
49+
```
50+
51+
## 文档入口
52+
53+
- [doc/README.md](./doc/README.md)：文档总索引
54+
- [doc/zh/README.md](./doc/zh/README.md)：中文版文档
55+
- [doc/en/README.md](./doc/en/README.md)：英文版文档
56+
57+
建议从以下文档开始阅读：
58+
59+
- 架构与总体设计：
60+
[doc/zh/fee_redesign.md](./doc/zh/fee_redesign.md)
61+
- 对外接口与接入方式：
62+
[doc/zh/fee_API.md](./doc/zh/fee_API.md)
63+
- 诊断测试与结果解读：
64+
[doc/zh/fee_diag_test.md](./doc/zh/fee_diag_test.md)
65+
66+
## 当前仓库状态
67+
68+
当前仓库更接近一个可集成的实现集合，还不是可直接量产落地的完整版本。
69+
70+
- 核心 FEE 逻辑和设计文档已经具备。
71+
- 文档中约定了 `fee_port` 适配层和测试后端的集成方式。
72+
- 相关适配层与测试源文件目前不在这个快照里，实际接板仍需要项目侧补齐。
73+
74+
## 快速接入建议
75+
76+
1. 在 [Kconfig](./Kconfig) 中打开组件。
77+
2. 根据目标平台配置 block 表和底层 flash 能力参数。
78+
3. 系统启动时调用 `fee_init()`。
79+
4. 周期性调用 `fee_mainfunction()`。
80+
5. 将 `fee_write()`、`fee_invalidate()`、`fee_rollback()` 视为异步请求，
81+
并通过状态接口查询最终结果。

‎components/custom_fee/SConscript‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
from building import *
2+
3+
objs = []
4+
cwd = GetCurrentDir()
5+
6+
if not GetDepend("COMPONENT_USING_CUSTOM_FEE"):
7+
Return('objs')
8+
9+
src = [
10+
'fee_cfg.c',
11+
'fee_api.c',
12+
'fee_port.c',
13+
'fee_sched.c',
14+
'fee_core.c',
15+
'fee_gc.c',
16+
'fee_recovery.c',
17+
'fee_cache.c',
18+
'fee_ckpt.c',
19+
'fee_lane_fast.c',
20+
'fee_lane_log.c',
21+
'fee_lane_bulk.c',
22+
'fee_onflash.c',
23+
'fee_test.c',
24+
]
25+
26+
CPPPATH = [cwd]
27+
group = DefineGroup('custom_fee', src, depend = ['COMPONENT_USING_CUSTOM_FEE'], CPPPATH = CPPPATH)
28+
29+
Return('group')

‎components/custom_fee/doc/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# custom_fee Documentation
2+
3+
This directory contains the separated bilingual documentation sets for
4+
`custom_fee`.
5+
6+
- English documents: [en/README.md](./en/README.md)
7+
- 中文文档: [zh/README.md](./zh/README.md)
8+
9+
The legacy `doc/*.md` files are kept in place during the transition. New readers
10+
should start from the language-specific indexes above.

‎components/custom_fee/doc/en/README.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# custom_fee English Documentation
2+
3+
This directory contains the English documentation set for `custom_fee`.
4+
5+
## Recommended reading order
6+
7+
1. [fee_redesign.md](./fee_redesign.md)
8+
2. [fee_API.md](./fee_API.md)
9+
3. [fee_onflash_format.md](./fee_onflash_format.md)
10+
4. [fee_boot_recovery.md](./fee_boot_recovery.md)
11+
5. [fee_scheduler_gc.md](./fee_scheduler_gc.md)
12+
6. [fee_cache_checkpoint.md](./fee_cache_checkpoint.md)
13+
7. [fee_cfg_rules.md](./fee_cfg_rules.md)
14+
8. [fee_port_adapter.md](./fee_port_adapter.md)
15+
9. [fee_diag_test.md](./fee_diag_test.md)
16+
17+
## Document overview
18+
19+
- `fee_redesign.md`: system goals, architecture, storage model, and rollout plan
20+
- `fee_API.md`: public API semantics, integration pattern, and usage pitfalls
21+
- `fee_onflash_format.md`: sector, record, and checkpoint persistence format
22+
- `fee_boot_recovery.md`: boot recovery states, checkpoint restore, and tail scan
23+
- `fee_scheduler_gc.md`: request scheduling, `BUSY_INTERNAL`, and GC rules
24+
- `fee_cache_checkpoint.md`: RAM cache structure, checkpoint policy, and bounds
25+
- `fee_cfg_rules.md`: block configuration, lane mapping, and sizing rules
26+
- `fee_port_adapter.md`: flash-port abstraction and backend expectations
27+
- `fee_diag_test.md`: diagnostic test flow, dump interpretation, and performance view

0 commit comments

Comments
 (0)