Add driver.

Author: Jiu-xiao

docs/basic_coding/driver/README.md

@@ -0,0 +1,46 @@
+---
+id: device-coding
+title: 外设驱动
+sidebar_position: 5
+---
+
+# 外设驱动（Device Drivers）
+
+本模块汇总 LibXR 对常见硬件外设的抽象接口，提供统一的面向对象编程方式，支持异步操作、配置封装、平台适配等特性。
+
+LibXR 所有设备接口均遵循以下设计原则：
+
+- **平台无关**：抽象类接口统一命名、统一行为，不依赖底层硬件寄存器或驱动结构；
+- **支持异步操作**：基于 `ReadPort` / `WritePort` 的通用操作模型，适配中断、DMA 等硬件机制；
+- **类型安全**：接口参数和配置结构体使用强类型封装，提升可靠性与代码可读性；
+- **最小依赖**：核心模块仅依赖 C++17 特性和 LibXR 基础组件，适用于裸机和各种 RTOS 平台；
+- **灵活扩展**：每种外设可根据平台能力裁剪实现，支持复用系统资源（如共享总线）；
+
+---
+
+## 快速导航
+
+- [GPIO（通用输入输出）](./gpio.md)
+- [UART（串口通信）](./uart.md)
+- [I2C（I2C 总线）](./i2c.md)
+- [SPI（SPI 接口）](./spi.md)
+- [CAN / FDCAN（控制器局域网）](./can.md)
+- [ADC（模数转换）](./adc.md)
+- [PWM（脉宽调制）](./pwm.md)
+- [Flash（闪存接口）](./flash.md)
+- [Power（电源管理）](./power.md)
+- [Timebase（时间基准）](./timebase.md)
+
+---
+
+## 使用示例
+
+每个外设抽象类通常包含以下组成：
+
+- `Configuration` 配置结构体
+- `SetConfig()` 设置接口
+- `Read()` / `Write()` 数据传输接口
+- `Enable()` / `Disable()` 控制接口（若适用）
+- `Callback` 事件响应注册（如中断）
+
+用户无需关心底层是STM32UART、ESP32UART还是LinuxUART，只需拿到基类指针并调用接口即可。

docs/basic_coding/driver/adc.md

@@ -0,0 +1,32 @@
+---
+id: adc
+title: 模数转换
+sidebar_position: 6
+---
+
+# ADC（模数转换）
+
+`LibXR::ADC` 提供平台无关的模拟数字转换（ADC）接口，用于读取模拟输入电压值，适用于电压检测、传感器读取等应用场景。
+
+## 接口定义
+
+```cpp
+class ADC {
+public:
+  ADC() = default;
+
+  // 读取 ADC 电压值，单位为伏特（float 类型）
+  virtual float Read() = 0;
+};
+```
+
+- `Read()` 是纯虚函数，子类需实现具体的采样逻辑；
+- 返回值通常为 0 ~ 3.3V 或芯片支持的其他范围；
+- 接口简单明了，适合平台移植与模拟信号读取抽象。
+
+## 特性总结
+
+- 提供统一的模拟电压读取接口；
+- 避免平台差异，便于上层逻辑复用；
+- 适用于温度、电压、光照等传感器输入；
+- 所有平台需实现 `Read()` 方法完成采样。

docs/basic_coding/driver/can.md

@@ -0,0 +1,98 @@
+---
+id: can
+title: 控制器局域网
+sidebar_position: 5
+---
+
+# CAN / FDCAN（控制器局域网）
+
+`LibXR::CAN` 与 `LibXR::FDCAN` 提供跨平台的控制器局域网通信接口，支持经典 CAN 消息与 FD CAN 消息收发，具备回调注册与过滤功能，适用于车辆通信、传感器网络等场景。
+
+## CAN 接口说明
+
+### 消息类型
+
+```cpp
+enum class Type : uint8_t {
+  STANDARD,         // 标准帧
+  EXTENDED,         // 扩展帧
+  REMOTE_STANDARD,  // 标准远程帧
+  REMOTE_EXTENDED,  // 扩展远程帧
+};
+```
+
+### 消息结构
+
+```cpp
+struct ClassicPack {
+  uint32_t id;       // 消息 ID
+  Type type;         // 消息类型
+  uint8_t data[8];   // 数据，最多 8 字节
+};
+```
+
+### 注册回调
+
+```cpp
+using Callback = LibXR::Callback<const ClassicPack &>;
+void Register(Callback cb, Type type,
+              FilterMode mode = FilterMode::ID_RANGE,
+              uint32_t start_id_mask = 0,
+              uint32_t end_id_match = UINT32_MAX);
+```
+
+- 支持掩码或区间两种过滤模式
+- 可按消息类型分别注册回调
+- 回调类型为 `Callback<const ClassicPack&>`
+
+### 添加消息
+
+```cpp
+virtual ErrorCode AddMessage(const ClassicPack &pack) = 0;
+```
+
+- 派生类需实现该接口完成消息注入
+
+---
+
+## FDCAN 接口扩展
+
+### FD 消息结构
+
+```cpp
+struct FDPack {
+  uint32_t id;        // 消息 ID
+  Type type;          // 消息类型
+  uint8_t len;        // 数据长度
+  uint8_t data[64];   // 数据，最多 64 字节
+};
+```
+
+### 注册回调
+
+```cpp
+using CallbackFD = LibXR::Callback<const FDPack &>;
+void Register(CallbackFD cb, Type type,
+              FilterMode mode = FilterMode::ID_RANGE,
+              uint32_t start_id_mask = 0,
+              uint32_t end_id_mask = UINT32_MAX);
+```
+
+- 支持按 ID 区间或掩码过滤
+- 每种类型可独立注册多个回调
+
+### 添加 FD 消息
+
+```cpp
+virtual ErrorCode AddMessage(const FDPack &pack) = 0;
+```
+
+---
+
+## 特性总结
+
+- 支持标准 CAN 与 FDCAN 协议；
+- 消息过滤灵活，支持掩码与范围；
+- 可在 ISR 安全调用回调；
+- 支持多订阅者、无锁列表；
+- 抽象接口适用于多平台驱动扩展。

docs/basic_coding/driver/flash.md

@@ -0,0 +1,34 @@
+---
+id: flash
+title: 闪存接口
+sidebar_position: 8
+---
+
+# Flash（闪存接口）
+
+`LibXR::Flash` 提供跨平台的抽象闪存访问接口，用于块擦除与写入操作，适配 NOR/NAND Flash、EEPROM、NVS 等非易失性存储设备。
+
+## 接口定义
+
+```cpp
+class Flash {
+public:
+  Flash(size_t min_erase_size, size_t min_write_size, RawData flash_area);
+
+  // 擦除指定区域（起始偏移与长度）
+  virtual ErrorCode Erase(size_t offset, size_t size) = 0;
+
+  // 写入数据到指定偏移地址
+  virtual ErrorCode Write(size_t offset, ConstRawData data) = 0;
+
+  size_t min_erase_size_;   // 最小可擦除块大小（字节）
+  size_t min_write_size_;   // 最小可写入块大小（字节）
+  RawData flash_area_;      // 映射的闪存内存区域
+};
+```
+
+## 使用说明
+
+- 所有写入必须对齐 `min_write_size_`，擦除对齐 `min_erase_size_`；
+- `flash_area_` 指向实际用于存储的内存区域或 Flash 映射地址；
+- 上层可基于该接口实现参数存储、文件系统、日志管理等功能。

docs/basic_coding/driver/gpio.md

@@ -0,0 +1,81 @@
+---
+id: gpio
+title: GPIO
+sidebar_position: 1
+---
+
+# GPIO（通用输入输出）
+
+`LibXR::GPIO` 提供跨平台的通用输入输出（General Purpose Input/Output）抽象接口，支持多种输入输出模式及中断回调机制。用户可继承此接口实现具体平台的 GPIO 控制逻辑。
+
+## 接口概览
+
+### 配置枚举
+
+```cpp
+enum class Direction : uint8_t {
+  INPUT,                 // 输入模式
+  OUTPUT_PUSH_PULL,      // 推挽输出
+  OUTPUT_OPEN_DRAIN,     // 开漏输出
+  FALL_INTERRUPT,        // 下降沿中断
+  RISING_INTERRUPT,      // 上升沿中断
+  FALL_RISING_INTERRUPT  // 双沿中断
+};
+
+enum class Pull : uint8_t {
+  NONE,  // 无上下拉
+  UP,    // 上拉
+  DOWN   // 下拉
+};
+```
+
+### 配置结构体
+
+```cpp
+struct Configuration {
+  Direction direction;  // 引脚方向
+  Pull pull;            // 上下拉设置
+};
+```
+
+### 回调类型
+
+```cpp
+using Callback = LibXR::Callback<>;
+```
+
+### 构造与配置
+
+```cpp
+GPIO();  // 默认构造函数
+virtual ErrorCode SetConfig(Configuration config) = 0;
+```
+
+### 引脚控制
+
+```cpp
+virtual bool Read() = 0;              // 读取引脚电平
+virtual ErrorCode Write(bool value) = 0; // 写入引脚电平
+```
+
+### 中断控制
+
+```cpp
+virtual ErrorCode EnableInterrupt() = 0;   // 使能中断
+virtual ErrorCode DisableInterrupt() = 0;  // 禁用中断
+```
+
+### 注册事件回调
+
+```cpp
+using Callback = LibXR::Callback<>;
+ErrorCode RegisterCallback(Callback callback); // 注册中断处理函数
+```
+
+## 特性总结
+
+- 支持输入/输出/中断等多种模式配置；
+- 提供类型安全的配置结构体；
+- 事件处理使用统一回调接口，可在 ISR 或任务中触发；
+- 平台实现需完整覆盖虚函数定义；
+- 可与其他 LibXR 模块配合使用，如 Topic、Timer 等。

docs/basic_coding/driver/i2c.md

@@ -0,0 +1,52 @@
+---
+id: i2c
+title: I2C
+sidebar_position: 3
+---
+
+# I2C（串行总线）
+
+`LibXR::I2C` 提供平台无关的 I2C 总线通信接口，支持读写设备与寄存器、通信速率配置，适用于外设控制、传感器访问等场景。
+
+## 接口概览
+
+### 枚举类型
+
+```cpp
+enum class MemAddrLength : uint8_t {
+  BYTE_8,
+  BYTE_16
+};
+```
+
+### 配置结构
+
+```cpp
+struct Configuration {
+  uint32_t clock_speed;  // 通信时钟速率（单位 Hz）
+};
+```
+
+### 主要方法
+
+```cpp
+virtual ErrorCode Read(uint16_t slave_addr, RawData read_data, ReadOperation& op) = 0;
+virtual ErrorCode Write(uint16_t slave_addr, ConstRawData write_data, WriteOperation& op) = 0;
+virtual ErrorCode SetConfig(Configuration config) = 0;
+
+virtual ErrorCode MemRead(uint16_t slave_addr, uint16_t mem_addr,
+                          RawData read_data, ReadOperation& op,
+                          MemAddrLength mem_addr_size = MemAddrLength::BYTE_8) = 0;
+
+virtual ErrorCode MemWrite(uint16_t slave_addr, uint16_t mem_addr,
+                           ConstRawData write_data, WriteOperation& op,
+                           MemAddrLength mem_addr_size = MemAddrLength::BYTE_8) = 0;
+```
+
+## 特性总结
+
+- 支持 I2C 设备读写与寄存器读写；
+- 支持配置通信时钟频率；
+- 寄存器访问支持 8/16 位地址；
+- 接口统一，兼容异步/同步调用模型；
+- 便于派生平台相关实现，支持跨平台适配。

docs/basic_coding/driver/power.md

@@ -0,0 +1,32 @@
+---
+id: power
+title: 电源管理
+sidebar_position: 9
+---
+
+# Power（电源管理）
+
+`LibXR::PowerManager` 提供统一的电源管理接口，适用于实现系统复位、关机或进入低功耗模式等功能，供平台或电源控制驱动实现。
+
+## 接口定义
+
+```cpp
+class PowerManager {
+public:
+  PowerManager() = default;
+  virtual ~PowerManager() = default;
+
+  // 系统复位操作（由子类实现具体逻辑）
+  virtual void Reset() = 0;
+
+  // 系统关机操作（由子类实现具体逻辑）
+  virtual void Shutdown() = 0;
+};
+```
+
+## 使用说明
+
+- `Reset()` 可用于软复位控制器、重新启动系统等；
+- `Shutdown()` 用于关机、掉电、进入睡眠等低功耗控制；
+- 可用于平台的电源按钮、远程命令、低电量策略等情境；
+- 由具体平台实现其底层行为，接口保持一致，便于移植与抽象封装。