Update basic_coding/core

Author: Jiu-xiao

docs/basic_coding/README.md

@@ -6,4 +6,4 @@ sidebar_position: 7
 
 # 基础编程（libxr）
 
-本页面简要介绍 LibXR 的CMake配置与基础API的使用方法，包括常用工具，外设，操作系统API以及各种控制算法。
+本章简要介绍 LibXR 的CMake配置与基础API的使用方法，包括常用工具，外设，操作系统API以及各种控制算法。

docs/basic_coding/core/README.md

@@ -0,0 +1,22 @@
+---
+id: core-coding
+title: 核心组件
+sidebar_position: 3
+---
+
+# 核心组件
+
+本章节介绍 LibXR 框架的核心模块，提供跨平台通用的数据类型、错误处理、操作封装、时间工具和终端格式支持等功能，为整个系统提供基础支撑。
+
+## 模块概览
+
+- [`libxr_def`](./core-def)：常用宏定义、错误码与基础常量
+- [`libxr_assert`](./core-assert)：断言机制与致命错误回调
+- [`libxr_cb`](./core-cb)：类型安全的回调机制
+- [`libxr_type`](./core-type)：原始数据封装与类型识别
+- [`libxr_string`](./core-string)：固定长度安全字符串
+- [`libxr_color`](./core-color)：终端输出格式与 ANSI 控制
+- [`libxr_time`](./core-time)：微秒/毫秒级时间戳与时间差
+- [`libxr_rw`](./core-rw)：通用读写接口与操作封装
+
+各模块将在后续页面中展开详细介绍。

docs/basic_coding/core/core-assert.md

@@ -0,0 +1,69 @@
+---
+id: core-assert
+title: 断言与错误处理
+sidebar_position: 2
+---
+
+# 断言与错误处理
+
+本模块用于运行时错误检查、致命错误处理及调试期间的尺寸校验。其核心是 `LibXR::Assert` 类及 `ASSERT` / `ASSERT_ISR` 宏，常配合 `libxr_def` 使用。
+
+## 致命错误处理接口
+
+```cpp
+void libxr_fatal_error(const char *file, uint32_t line, bool in_isr);
+```
+
+该函数用于终止程序执行，可在正常或中断上下文中调用。发生断言失败时将自动调用，并可通过 `Assert` 类注册回调处理。
+
+## `LibXR::Assert` 类
+
+用于注册致命错误回调，并在调试模式下进行尺寸检查。
+
+### 注册回调
+
+```cpp
+LibXR::Assert::RegisterFatalErrorCB(cb);
+```
+
+支持传入任意 `Callback<const char*, uint32_t>` 类型的函数或对象，用于处理致命错误事件。
+
+### 尺寸限制检查
+
+在调试模式（定义 `LIBXR_DEBUG_BUILD`）下启用：
+
+```cpp
+template <SizeLimitMode mode>
+static void SizeLimitCheck(size_t limit, size_t size);
+```
+
+支持三种模式：
+
+- `EQUAL`: 大小必须等于限制值
+- `MORE`: 大小必须大于等于限制值
+- `LESS`: 大小必须小于等于限制值
+
+发布模式下此函数为空操作。
+
+## 宏定义：断言检查
+
+- `ASSERT(expr)`: 普通上下文断言，失败时调用 `libxr_fatal_error(...)`
+- `ASSERT_ISR(expr)`: 中断上下文断言
+
+这些宏由 `LIBXR_DEBUG_BUILD` 控制是否启用，建议用于调试、开发阶段的防御性编程。
+
+## 用例示例
+
+```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));
+
+ASSERT(buffer != nullptr);
+ASSERT_ISR(interrupt_flag == true);
+```
+
+---
+
+本模块为 LibXR 所有调试和安全机制的核心基础，建议在系统开发初期即集成并启用断言与校验逻辑。

docs/basic_coding/core/core-cb.md

@@ -0,0 +1,82 @@
+---
+id: core-callback
+title: 通用回调
+sidebar_position: 3
+---
+
+# 通用回调
+
+本模块提供轻量级、可嵌入中断的通用回调系统，包括 `Callback` 和 `CallbackBlock` 两个模板类，广泛用于异步通知、事件处理、错误回调等场景。
+
+## CallbackBlock
+
+```cpp
+template <typename ArgType, typename... Args>
+class CallbackBlock;
+```
+
+用于封装一个具体的回调函数及其第一个绑定参数，支持中断上下文安全调用：
+
+- `FunctionType`: 回调函数签名为 `void(bool in_isr, ArgType arg, Args... args)`。
+- `Call(bool in_isr, Args&&...)`: 执行回调，传递额外参数。
+
+构造时即完成函数与绑定参数的绑定。支持移动构造与移动赋值，禁用拷贝。
+
+## Callback
+
+```cpp
+template <typename... Args>
+class Callback;
+```
+
+对 `CallbackBlock` 的进一步封装，提供统一接口、类型擦除和创建工厂方法：
+
+### 创建回调
+
+```cpp
+LibXR::Callback<Args...> cb = LibXR::Callback<Args...>::Create(fun, bound_arg);
+```
+
+- `fun`: 回调函数，格式为 `void(bool, BoundArgType, Args...)`
+- `bound_arg`: 回调函数的第一个绑定参数
+
+### 执行回调
+
+```cpp
+cb.Run(in_isr, arg1, arg2, ...);
+```
+
+可传递任意数量的附加参数，`in_isr` 指示是否在中断上下文中调用。
+
+### 其他接口
+
+- `Empty()`: 判断回调是否为空
+- 支持默认构造、拷贝构造、移动构造与赋值
+
+## 使用示例
+
+```cpp
+void OnEvent(bool in_isr, int context, const char* msg) {
+  printf("ISR=%d context=%d msg=%s\n", in_isr, context, msg);
+}
+
+auto cb = LibXR::Callback<const char*>::Create(OnEvent, 42);
+cb.Run(false, "Hello");
+```
+
+输出：
+
+```bash
+ISR=0 context=42 msg=Hello
+```
+
+## 设计特点
+
+- **无动态内存管理需求**：除非用户自定义 CallbackBlock 派生类
+- **支持 ISR 上下文**：可在中断中安全调用
+- **类型安全封装**：利用模板与类型推导实现参数绑定
+- **适用于嵌入式场景**：非常轻量，占用资源小
+
+---
+
+该模块是 LibXR 异步机制与回调接口的基础组件，适用于 IO、定时器、事件发布等模块的回调传递。

docs/basic_coding/core/core-color.md

@@ -0,0 +1,80 @@
+---
+id: core-color
+title: 终端颜色与格式
+sidebar_position: 6
+---
+
+# 终端颜色与格式
+
+本模块定义了终端打印时常用的格式控制枚举和 ANSI 转义序列，支持文本加粗、颜色设置、背景色等，适用于串口调试终端、日志系统、彩色输出等场景。
+
+## 文本格式 Format
+
+```cpp
+enum class Format : uint8_t {
+  NONE = 0, RESET, BOLD, DARK, UNDERLINE, BLINK, REVERSE, CONCEALED, CLEAR_LINE, COUNT
+};
+```
+
+- `NONE`: 无格式
+- `RESET`: 重置所有格式
+- `BOLD`: 加粗
+- `DARK`: 暗色字体
+- `UNDERLINE`: 下划线
+- `BLINK`: 闪烁
+- `REVERSE`: 前景/背景反转
+- `CONCEALED`: 隐藏
+- `CLEAR_LINE`: 清除整行
+
+对应 ANSI 转义字符串：`LIBXR_FORMAT_STR[]`
+
+## 字体颜色 Font
+
+```cpp
+enum class Font : uint8_t {
+  NONE = 0, BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, COUNT
+};
+```
+
+对应 ANSI 字符串：`LIBXR_FONT_STR[]`
+
+## 背景颜色 Background
+
+```cpp
+enum class Background : uint8_t {
+  NONE = 0, BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, COUNT
+};
+```
+
+对应 ANSI 字符串：`LIBXR_BACKGROUND_STR[]`
+
+## 粗体样式 Bold
+
+```cpp
+enum class Bold : uint8_t {
+  NONE = 0, YELLOW, RED, ON_RED, COUNT
+};
+```
+
+简化常用彩色粗体样式输出，例如：
+
+- `YELLOW`: 黄色加粗
+- `RED`: 红色加粗
+- `ON_RED`: 红底白字加粗
+
+对应 ANSI 字符串：`LIBXR_BOLD_STR[]`
+
+## 使用示例
+
+```cpp
+std::cout << LIBXR_FORMAT_STR[(int)Format::BOLD]
+          << LIBXR_FONT_STR[(int)Font::GREEN]
+          << "This is bold green text!"
+          << LIBXR_FORMAT_STR[(int)Format::RESET];
+```
+
+效果为绿色加粗文本。
+
+---
+
+本模块可配合终端类、调试输出类、日志系统使用，用于构建清晰、可读性强的彩色输出。

docs/basic_coding/core/core-def.md

@@ -0,0 +1,91 @@
+---
+id: core-def
+title: 公共定义
+sidebar_position: 1
+---
+
+# 公共定义
+
+本模块提供 LibXR 中最基础的宏、常量、错误码及通用模板函数，广泛用于其他模块的实现。它避免平台差异、简化编码，并为调试与运行时检查提供基础设施。
+
+## 数学与物理常量
+
+- `M_PI`, `M_2PI`: 圆周率及其两倍，常用于角度计算。
+- `M_1G`: 标准重力加速度常量，值为 `9.80665 m/s²`。
+
+## 常用宏定义
+
+- `DEF2STR(x)`: 将宏值转为字符串。
+- `UNUSED(x)`: 用于消除未使用变量的编译器警告。
+- `OFFSET_OF(type, member)`: 获取结构体成员的偏移量。
+- `MEMBER_SIZE_OF(type, member)`: 获取结构体成员的字节大小。
+- `CONTAINER_OF(ptr, type, member)`: 从成员指针获取结构体指针，常用于回溯对象。
+
+## 缓存行定义
+
+- `LIBXR_CACHE_LINE_SIZE`: 根据平台指针位数定义的缓存行大小，64 位平台为 64 字节，32 位平台为 32 字节。
+
+## 错误码定义（`ErrorCode`）
+
+枚举类型 `ErrorCode` 定义了统一的错误码系统，用于表示各类操作结果：
+
+| 名称         | 值   | 含义               |
+|--------------|------|--------------------|
+| `OK`         | 0    | 操作成功           |
+| `FAILED`     | -1   | 操作失败           |
+| `INIT_ERR`   | -2   | 初始化错误         |
+| `ARG_ERR`    | -3   | 参数错误           |
+| `STATE_ERR`  | -4   | 状态错误           |
+| `SIZE_ERR`   | -5   | 尺寸错误           |
+| `CHECK_ERR`  | -6   | 校验失败           |
+| `NOT_SUPPORT`| -7   | 功能不支持         |
+| `NOT_FOUND`  | -8   | 未找到对象         |
+| `NO_REPONSE` | -9   | 无响应             |
+| `NO_MEM`     | -10  | 内存不足           |
+| `NO_BUFF`    | -11  | 缓冲区不足         |
+| `TIMEOUT`    | -12  | 操作超时           |
+| `EMPTY`      | -13  | 数据为空           |
+| `FULL`       | -14  | 数据已满           |
+| `BUSY`       | -15  | 资源忙碌中         |
+| `PTR_NULL`   | -16  | 空指针错误         |
+| `OUT_OF_RANGE`| -17 | 超出有效范围       |
+
+## 尺寸限制模式（`SizeLimitMode`）
+
+用于运行时检查尺寸是否符合要求：
+
+- `EQUAL`: 必须等于参考值  
+- `LESS`: 小于或等于参考值  
+- `MORE`: 大于或等于参考值  
+- `NONE`: 不限制尺寸
+
+## 断言宏
+
+提供统一的运行时断言机制：
+
+- `ASSERT(x)`: 在调试模式下检查表达式是否为真，否则触发致命错误
+- `ASSERT_ISR(x)`: 用于中断上下文的断言检查
+
+在 `LIBXR_DEBUG_BUILD` 编译宏启用时生效，触发时会调用：
+
+```cpp
+void libxr_fatal_error(const char *file, uint32_t line, bool in_isr);
+```
+
+可通过注册回调处理断言失败行为（详见 `libxr_assert.hpp`）。
+
+## 通用模板函数
+
+```cpp
+template <typename T1, typename T2>
+constexpr auto LibXR::max(T1 a, T2 b) -> common_type<T1, T2>::type;
+
+template <typename T1, typename T2>
+constexpr auto LibXR::min(T1 a, T2 b) -> common_type<T1, T2>::type;
+```
+
+用于计算任意类型的最大/最小值，支持整数、浮点等常见数值类型。
+
+---
+
+该文件为 LibXR 的所有模块提供基础能力，强烈建议在开发过程中充分利用本模块的工具和约定。