Update middleware.

Author: Jiu-xiao

docs/basic_coding/core/core-assert.md

@@ -55,10 +55,14 @@ static void SizeLimitCheck(size_t limit, size_t size);
 ## 用例示例
 
 ```cpp
-LibXR::Assert::RegisterFatalErrorCB(
-    LibXR::Callback<const char*, uint32_t>::Create([](bool in_isr, const char* file, uint32_t line) {
-        printf("Fatal error at %s:%u (ISR=%d)\n", file, line, in_isr);
-    }, nullptr));
+auto err_cb = LibXR::Assert::Callback::Create(
+    [](bool in_isr, Arg arg, const char *file, uint32_t line)
+    {
+    // do something
+    },
+    arg);
+
+LibXR::Assert::RegisterFatalErrorCB(err_cb);
 
 ASSERT(buffer != nullptr);
 ASSERT_ISR(interrupt_flag == true);

docs/basic_coding/middleware/README.md

@@ -0,0 +1,28 @@
+---
+id: middleware-coding
+title: 中间件
+sidebar_position: 3
+---
+
+# 中间件
+
+本模块汇总了 LibXR 中用于系统服务、通信管理、终端交互等场景的中间件组件，设计强调线程安全、资源约束适配与平台无关性，涵盖如下内容：
+
+## 模块特性
+
+- **统一封装**：提供事件、日志、主题发布、虚拟终端等核心中间件功能。
+- **多种调用模型**：支持同步、异步、队列、回调等操作方式，适配不同场景。
+- **高性能实现**：内部大量使用无锁链表/队列等数据结构，保障并发性能。
+- **适配嵌入式限制**：支持 Flash 最小写入单元限制、内存受限设备上的键值存储等。
+
+## 快速导航
+
+- [Application 框架](./app-framework.md)
+- [Logger 日志系统](./logger.md)
+- [Event 事件系统](./event.md)
+- [Topic 发布订阅机制](./message.md)
+- [Database 键值数据库](./database.md)
+- [RamFS 内存文件系统](./ramfs.md)
+- [Terminal 命令终端](./terminal.md)
+
+更多接口说明与设计思想，请参考各页面的详细说明。

docs/basic_coding/middleware/app-framework.md

@@ -0,0 +1,73 @@
+---
+id: app-framework
+title: Application 框架
+sidebar_position: 1
+---
+
+# Application 框架
+
+`Application` 框架是 LibXR 中的核心中间件之一，负责管理设备注册与应用模块调度，是 XRobot 系统集成与运行控制的基础。
+
+## 模块组成
+
+- **HardwareContainer**：硬件容器类，支持设备对象的注册、查找、别名管理。
+- **Application**：应用模块抽象基类，需实现 `OnMonitor()` 方法。
+- **ApplicationManager**：模块调度器，用于统一管理多个 Application 实例并执行周期性任务。
+
+---
+
+## HardwareContainer：硬件设备注册与查找
+
+```cpp
+template <typename T>
+struct Entry {
+  T& object;
+  std::initializer_list<const char*> aliases;
+};
+
+HardwareContainer container({
+  Entry<UART>{uart1, {"uart1", "console"}},
+  Entry<Motor>{gpio1, {"gpio1", "LED"}}
+});
+```
+
+支持：
+
+- 多别名注册：同一个对象可注册多个别名。
+- 类型安全查找：支持模板化查找 `Find<T>("alias")`。
+- 查找失败断言：`FindOrExit<T>({...})` 可在未找到时报错退出。
+
+---
+
+## Application / ApplicationManager：统一应用模块管理
+
+```cpp
+class MyApp : public Application {
+ public:
+  void OnMonitor() override {
+    // 用户定义的周期任务逻辑
+  }
+};
+
+MyApp app;
+manager.Register(app);
+manager.MonitorAll();  // 周期调用所有模块的 OnMonitor()
+```
+
+支持：
+
+- 注册任意数量的模块；
+- 使用 `LockFreeList` 无锁结构存储模块；
+- 可用于实现定时任务调度、模块状态轮询等。
+
+---
+
+## 与 XRobot 的集成意义
+
+XRobot 系统的自动生成工具会为每个模块自动生成注册代码，统一调用 `HardwareContainer` 与 `ApplicationManager`，完成设备注册与主循环调度的构建。
+
+这使得所有模块可插拔化接入，支持快速扩展与平台无关运行。
+
+---
+
+更多示例与使用方式，请参考 `xrobot_main.cpp` 或模板生成代码。

docs/basic_coding/middleware/database.md

@@ -0,0 +1,127 @@
+---
+id: database
+title: 闪存数据库
+sidebar_position: 5
+---
+
+# Database 闪存数据库
+
+LibXR 提供了两种轻量级的嵌入式键值数据库实现：`DatabaseRawSequential` 和 `DatabaseRaw<N>`。  
+它们均继承自抽象接口类 `Database`，用于嵌入式 Flash 等顺序写入存储介质，具备主备冗余、断电保护、类型安全封装，适配不同的存储对齐约束。
+
+---
+
+## 主要功能
+
+- 支持主/备块数据冗余与校验，断电后可自动恢复；
+- 提供统一接口 `Database` 与模板封装 `Database::Key<T>`，支持类型安全读写；
+- 两种实现模式：
+  - `DatabaseRawSequential`：顺序写入，支持任意数据长度；
+  - `DatabaseRaw<N>`：页对齐写入，适用于 NOR Flash 等要求写入对齐的场景；
+- 所有数据操作通过 `Save()` 写入，`Restore()` 清空，支持完整恢复流程。
+
+---
+
+## 使用示例
+
+### 创建数据库对象
+
+```cpp
+LinuxBinaryFileFlash<2048> flash("/tmp/flash.bin", 512, 8);
+Database& db = *(new DatabaseRawSequential(flash));
+```
+
+或使用页对齐版本：
+
+```cpp
+LinuxBinaryFileFlash<2048> flash2("/tmp/flash2.bin", 512, 16);
+Database& db = *(new DatabaseRaw<16>(flash2));
+```
+
+### 定义类型安全的键
+
+```cpp
+int value = 42;
+Database::Key<int> key(db, "my_key", value);
+
+// 写入新值
+key = 123;
+
+// 读取回变量
+key.Load();
+printf("value = %d\n", static_cast<int>(key));
+```
+
+---
+
+## 类型安全封装：Key
+
+模板类 `Database::Key<T>` 提供类型安全的键值封装，构造时会尝试从数据库中加载键值，若不存在则添加新键。
+
+```cpp
+struct Config { uint32_t baudrate; uint8_t mode; };
+Database::Key<Config> cfg(db, "uart_cfg", {9600, 1});
+
+// 写入配置
+cfg = {115200, 0};
+
+// 加载配置
+cfg.Load();
+```
+
+- 支持所有 **可平铺内存的 POD 类型**（如结构体、数组、基本类型）；
+- 赋值操作 `key = value` 会自动更新数据库；
+- 可通过 `key.Load()` 显式从数据库刷新内容。
+
+---
+
+## 方法一览（基类接口）
+
+以下为抽象接口 `Database` 及其模板类 `Key<T>` 提供的完整方法：
+
+| 方法/操作                       | 功能描述                                                     |
+|----------------------------------|----------------------------------------------------------------|
+| `Database::Add(KeyBase&)`        | 添加键值（仅在数据库不存在该键时调用）                       |
+| `Database::Set(KeyBase&, RawData)` | 更新键值内容，要求名称和大小一致                            |
+| `Database::Get(KeyBase&)`        | 从数据库加载键值到内存                                        |
+| `Key<T>::Set(const T&)`          | 设置键值并写入数据库                                           |
+| `Key<T>::Load()`                 | 从数据库加载键值至变量                                         |
+| `Key<T>::operator=(const T&)`    | 设置键值（等效于 `Set()`）                                     |
+| `Key<T>::operator T()`           | 类型转换操作，返回当前变量值（不自动加载）                   |
+
+---
+
+## 工作机制概述
+
+尽管不同实现的底层机制有所区别，但统一遵循如下设计原则：
+
+- 使用主块和备块交替写入，确保写入过程可恢复；
+- 所有键值存储以原始名值对序列化，并带有校验位；
+- `Init()` 内部自动判断有效块并尝试恢复数据；
+- `Restore()` 可主动清空主备数据并初始化空数据库；
+- 每个派生类自动处理页对齐、可用空间等底层逻辑，用户无需关心。
+
+---
+
+## 注意事项
+
+- 请优先使用 `Database::Key<T>` 类型封装进行读写；
+- 写入仅在调用 `key = val` 或 `key.Set(val)` 时发生；
+- 对所有键值数据类型要求为 POD 且可拷贝存储；
+- 若存储已满或写入失败，`Set()` 会返回对应错误码；
+- 若需手动释放数据库对象，注意释放派生类指针。
+
+---
+
+## 应用场景
+
+- 嵌入式设备参数存储；
+- 状态断点续存；
+- 多模块配置持久化；
+- 无动态内存环境下的安全键值存储；
+
+---
+
+## 示例测试
+
+详见 [`test_database.cpp`]，展示了键值读写、结构体支持、掉电恢复等场景的完整用例。

docs/basic_coding/middleware/event.md

@@ -0,0 +1,97 @@
+---
+id: event
+title: 事件系统
+sidebar_position: 3
+---
+
+# Event 事件系统
+
+`Event` 类是 LibXR 中用于事件驱动机制的核心中间件，支持事件注册、事件触发、中断安全调用与事件绑定，是构建嵌入式任务协作的重要工具。
+
+## 模块功能
+
+- 基于 **事件 ID** 注册多个回调；
+- 支持 **线程/中断上下文触发**；
+- 可通过 `GetList()` 实现 **中断上下文安全事件触发**；
+- 支持 **事件桥接绑定**，用于跨模块事件流转；
+- 内部采用 **红黑树 + 无锁链表** 实现高效、并发安全存储。
+
+---
+
+## 快速使用
+
+### 注册事件回调
+
+```cpp
+int counter = 0;
+LibXR::Event evt;
+auto cb = LibXR::Event::Callback::Create(
+    [](bool, int *cnt, uint32_t event) {
+        (*cnt)++;
+        ASSERT(event == 0x10);
+    },
+    &counter);
+
+evt.Register(0x10, cb);
+```
+
+### 触发事件
+
+```cpp
+evt.Active(0x10);  // 普通线程上下文触发
+```
+
+### 中断上下文触发（需提前获取回调链表）
+
+```cpp
+// 在非回调中获取事件链表
+auto list = evt.GetList(0x1234);
+// 在回调中触发
+evt.ActiveFromCallback(list, 0x1234);
+```
+
+### 事件绑定
+
+```cpp
+evt_dst.Bind(evt_src, 0xA, 0xB);  // 当 evt_src 的事件 0xA 触发时，会激活 evt_dst 的事件 0xB
+```
+
+---
+
+## 类定义结构
+
+- `Event::Register(event, cb)`：注册回调；
+- `Event::Active(event)`：非中断触发；
+- `Event::ActiveFromCallback(list, event)`：中断上下文安全触发；
+- `Event::GetList(event)`：获取并缓存事件链表；
+- `Event::Bind(src, id_src, id_dst)`：实现事件桥接；
+- 内部使用 `RBTree<uint32_t>` 管理事件映射，事件对应回调使用 `LockFreeList` 存储。
+
+---
+
+## 示例：测试事件绑定与触发
+
+```cpp
+int arg = 0;
+auto cb = Event::Callback::Create([](bool, int* a, uint32_t e) {
+  *a += 1;
+}, &arg);
+
+Event e1, e2;
+e1.Register(0x1234, cb);
+e1.Active(0x1234);  // arg += 1
+e2.Bind(e1, 0x4321, 0x1234);
+e2.Active(0x4321);  // arg += 1
+```
+
+---
+
+## 应用场景
+
+- 按键/传感器中断触发事件；
+- 多任务协作中的状态通知；
+- 与 Topic/Message 联动构建事件-消息系统。
+
+---
+
+更多信息请查阅 `event.hpp` 源码。