docs: reconcile xrobot site with libxr master

Author: Jiu-xiao

docs/adv_coding/middleware/linux_shared_topic_design.md

@@ -10,7 +10,7 @@ sidebar_position: 2
 
 ## 1. 为什么不是直接改 `Topic`
 
-`LinuxSharedTopic<T>` 解决的是 Linux / Webots 主机进程间通信、大 payload 共享、零拷贝读取以及多订阅者队列策略；原始 `Topic` 更像是进程内发布订阅，语义偏 MCU 和轻量系统，用缓存、回调、同步/异步订阅者去组织数据流。这两条路径的约束根本不同，所以共享内存语义没有继续塞回 `Topic` 本体，而是单独做成 `LibXR::LinuxSharedTopic<T>`。这样 `Topic` 仍然保持轻量，Linux 主机 IPC 也可以沿着共享内存模型单独演化。
+`LinuxSharedTopic<T>` 解决的是 Linux / Webots 主机进程间通信、大 payload 共享、零拷贝读取以及多订阅者队列策略；原始 `Topic` 更像是进程内发布订阅，语义偏 MCU 和轻量系统，用精确类型分发、回调、同步/异步订阅者去组织数据流。这两条路径的约束根本不同，所以共享内存语义没有继续塞回 `Topic` 本体，而是单独做成 `LibXR::LinuxSharedTopic<T>`。这样 `Topic` 仍然保持轻量，Linux 主机 IPC 也可以沿着共享内存模型单独演化。
 
 ## 2. 数据面和控制面分离
 

docs/adv_coding/middleware/topic_design.md

@@ -10,23 +10,29 @@ sidebar_position: 1
 
 ## `Topic` 解决什么问题
 
-`Topic` 的目标不是做一个“什么都能承载”的消息总线，而是在尽量轻的前提下，把同一进程内最常见的几种数据交接方式统一起来：发布者写入，订阅者按自己的方式接收，必要时缓存最近一份数据，必要时再做多发布者保护。它没有引入 Linux 共享内存、进程间同步或复杂的持久队列语义，就是因为这些需求已经超出了这条轻量路径的边界。
+`Topic` 的目标不是做一个“什么都能承载”的消息总线，而是在尽量轻的前提下，把同一进程内最常见的几种数据交接方式统一起来：发布者写入，订阅者按自己的方式接收，必要时再做多发布者保护。它没有引入 Linux 共享内存、进程间同步或复杂的持久队列语义，就是因为这些需求已经超出了这条轻量路径的边界。
 
 ## `Block` 的角色
 
-从源码上看，`Topic` 的中心结构是 `Block`。里面放着主题当前的数据、最大长度、订阅者链表，以及控制并发访问的状态。默认情况下它优化的是单发布者路径：如果没有显式启用 `multi_publisher`，内部只用一个原子 `busy` 状态来做轻量串行化；一旦启用多发布者，才退回到 `Mutex`。这条边界很关键，因为它说明 `Topic` 首先服务的是常见的单发布者场景，而不是默认把所有发布都拖进重同步原语。
+从源码上看，`Topic` 的中心结构是 `Block`。里面放着 payload 类型契约、名称 CRC32 键、订阅者链表，以及控制并发访问的状态。默认情况下它优化的是单发布者路径：如果没有显式启用 `multi_publisher`，内部只用一个原子 `busy` 状态来做轻量串行化；一旦启用多发布者，才退回到 `Mutex`。这条边界很关键，因为它说明 `Topic` 首先服务的是常见的单发布者场景，而不是默认把所有发布都拖进重同步原语。
 
-## 缓存为什么是可选的
+## 为什么不再内置 latest cache
 
-缓存也是同样的思路。`Topic` 并不会强制持有一份独立副本，而是允许按需启用 cache。不开 cache 时，发布路径只是把当前数据视图挂到 `Block` 上；开了 cache，才在内部保留一份稳定副本。换句话说，如果上层需要“最近一份稳定数据”的语义，就显式打开缓存；如果只想做一次轻量交接，就没有必要默认承担额外拷贝成本。
+当前主线里，`Topic` 已经明确退回到“发布即分发”的角色，不再在 `Block` 里保存最近一次 payload 副本。这么做的结果是边界更清楚：
+
+- `Topic` 负责一次发布如何扇出到不同订阅者；
+- latest-value 语义如果确实需要，由上层模块自己显式维护；
+- packet 打包也直接针对调用者手里的 payload 做，不再绕 topic 内部缓存转一圈。
+
+这条调整减少了 `Topic` 同时承担“分发总线”和“缓存容器”两种职责时的语义混杂。
 
 ## 订阅者为什么分类型
 
 订阅者类型之所以分成同步、异步、队列和回调四类，也不是为了把接口做花，而是因为它们代表了四种完全不同的消费语义。`SyncSubscriber` 关心的是“有新数据时唤醒我”；`ASyncSubscriber` 更接近“我之后再来取最新结果”；`QueuedSubscriber` 关心的是“请把每次发布都排进队列”；回调订阅则是“发布时立即触发我”。如果把这些语义都压成一个统一订阅者接口，最后势必要么退化成最保守子集，要么把大量分支逻辑塞进运行期。
 
 ## 它为什么不是严格消息队列
 
-从并发角度看，`Topic` 更像一套“发布时把数据分发到不同消费形态”的框架，而不是严格意义上的消息队列。同步路径里有 `Semaphore`，异步路径里有状态块，队列路径里有 `LockFreeQueue`，回调路径则挂在 `LockFreeList` 上。正因为如此，它特别适合进程内模块交接、日志分发、状态广播这类问题；但如果你需要的是进程间共享大 payload、明确的 queue-full 策略或者零拷贝共享槽位，就应该转去 `LinuxSharedTopic<T>`，而不是继续往 `Topic` 里堆系统级语义。
+从并发角度看，`Topic` 更像一套“发布时把数据分发到不同消费形态”的框架，而不是严格意义上的消息队列。同步路径里有 `Semaphore`，异步路径里有状态块，队列路径里有 `SPSCQueue`，回调路径则挂在 `LockFreeList` 上。正因为如此，它特别适合进程内模块交接、日志分发、状态广播这类问题；但如果你需要的是进程间共享大 payload、明确的 queue-full 策略或者零拷贝共享槽位，就应该转去 `LinuxSharedTopic<T>`，而不是继续往 `Topic` 里堆系统级语义。
 
 ## `WaitTopic` 和 domain
 

docs/basic_coding/README.md

@@ -6,4 +6,13 @@ sidebar_position: 6
 
 # 基础编程（libxr）
 
-本章简要介绍 LibXR 的CMake配置与基础API的使用方法，包括常用工具，外设，操作系统API以及各种控制算法。
+本章简要介绍 LibXR 的 CMake 配置与基础 API 的使用方法，包括核心组件、数据结构、中间件、操作系统抽象、外设驱动以及数学与工具模块。
+
+## 目录
+
+- [核心组件](/docs/basic_coding/core)
+- [数据结构](/docs/basic_coding/structure)
+- [中间件](/docs/basic_coding/middleware)
+- [操作系统](/docs/basic_coding/system)
+- [外设驱动](/docs/basic_coding/driver)
+- [数学与工具](/docs/basic_coding/utils)

docs/basic_coding/core/README.md

@@ -14,9 +14,13 @@ sidebar_position: 1
 - [`libxr_assert`](./core-assert.md)：断言机制与致命错误回调
 - [`libxr_cb`](./core-cb.md)：类型安全的回调机制
 - [`libxr_type`](./core-type.md)：原始数据封装与类型识别
+- [`libxr_mem`](./core-mem.md)：内存复制、清零与比较辅助
 - [`libxr_string`](./core-string.md)：固定长度安全字符串
 - [`libxr_color`](./core-color.md)：终端输出格式与 ANSI 控制
+- [`print`](./core-print.md)：编译期格式化输出与 sink / bounded-buffer 包装
 - [`libxr_time`](./core-time.md)：微秒/毫秒级时间戳与时间差
 - [`libxr_rw`](./core-rw.md)：通用读写接口与操作封装
+- [`Operation`](./core-op.md)：异步完成反馈模型
+- [`Pipe`](./core-pipe.md)：基于共享字节队列的单向管道
 
 各模块将在后续页面中展开详细介绍。

docs/basic_coding/core/core-assert.md

@@ -6,44 +6,34 @@ sidebar_position: 2
 
 # 断言与错误处理
 
-本模块用于运行时错误检查、致命错误处理及调试期间的尺寸校验。其核心是 `LibXR::Assert` 类及 `ASSERT` / `ASSERT_FROM_CALLBACK` 宏，常配合 `libxr_def` 使用。
+本模块用于运行时错误检查与致命错误回调管理。当前公开接口核心是 `LibXR::Assert` 命名空间中的 fatal callback 管理函数，以及 `ASSERT` / `ASSERT_FROM_CALLBACK` 这些宏。
 
 ## 致命错误处理接口
 
 ```cpp
 extern "C" void libxr_fatal_error(const char *file, uint32_t line, bool in_isr);
 ```
 
-该函数用于终止程序执行，可在正常或回调上下文中调用。发生断言失败时将自动调用，并可通过 `Assert` 类注册回调处理。
+该函数用于终止程序执行，可在正常或回调上下文中调用。发生断言失败时将自动调用，并可通过 `LibXR::Assert` 命名空间中的回调注册接口处理。
 
-## `LibXR::Assert` 类
+## `LibXR::Assert` 命名空间
 
-用于注册致命错误回调，并在调试模式下进行尺寸检查。
+当前公开的核心接口包括：
 
-### 注册回调
-
-```cpp
-LibXR::Assert::RegisterFatalErrorCB(cb);
-```
-
-支持传入任意 `Callback<const char*, uint32_t>` 类型的函数或对象，用于处理致命错误事件。
+- `using FatalCallback = LibXR::Callback<const char*, uint32_t>`
+- `RegisterFatalErrorCallback(cb)`
+- `FatalErrorCallback()`
+- `RunFatalErrorCallback(in_isr, file, line)`
 
-### 尺寸限制检查
-
-在调试模式（定义 `LIBXR_DEBUG_BUILD`）下启用：
+### 注册回调
 
 ```cpp
-template <SizeLimitMode mode>
-static void SizeLimitCheck(size_t limit, size_t size);
+LibXR::Assert::RegisterFatalErrorCallback(cb);
 ```
 
-支持三种模式：
+支持传入 `LibXR::Assert::FatalCallback`，也就是 `LibXR::Callback<const char*, uint32_t>` 类型的回调对象，用于处理致命错误事件。
 
-- `EQUAL`: 大小必须等于限制值
-- `MORE`: 大小必须大于等于限制值
-- `LESS`: 大小必须小于等于限制值
-
-发布模式下此函数为空操作。
+说明：当前尺寸关系判断本身在 `libxr_def.hpp` 中以 `constexpr bool SizeLimitCheck(...)` 的形式公开，而不是在这里再单独定义一个调试专用静态类接口。
 
 ## 宏定义：断言检查
 
@@ -55,14 +45,21 @@ static void SizeLimitCheck(size_t limit, size_t size);
 ## 用例示例
 
 ```cpp
-auto err_cb = LibXR::Assert::Callback::Create(
+using Arg = int;
+Arg arg = 0;
+
+auto err_cb = LibXR::Assert::FatalCallback::Create(
     [](bool in_isr, Arg arg, const char *file, uint32_t line)
     {
+    (void)in_isr;
+    (void)arg;
+    (void)file;
+    (void)line;
     // do something
     },
     arg);
 
-LibXR::Assert::RegisterFatalErrorCB(err_cb);
+LibXR::Assert::RegisterFatalErrorCallback(err_cb);
 
 ASSERT(buffer != nullptr);
 ASSERT_FROM_CALLBACK(buffer != nullptr, in_isr);

docs/basic_coding/core/core-cb.md

@@ -6,7 +6,7 @@ sidebar_position: 3
 
 # 通用回调
 
-本模块提供轻量级、可嵌入中断的通用回调系统，包括 `Callback` 和 `CallbackBlock` 两个模板类，广泛用于异步通知、事件处理、错误回调等场景。
+本模块提供轻量级、可嵌入中断的通用回调系统，核心公开接口是 `Callback`；其底层实现由 `CallbackBlock` 与可选的 `GuardedCallbackBlock` 组成，广泛用于异步通知、事件处理、错误回调等场景。
 
 ## CallbackBlock
 
@@ -15,18 +15,24 @@ template <typename ArgType, typename... Args>
 class CallbackBlock;
 ```
 
-用于封装一个具体的回调函数及其第一个绑定参数，并提供重入保护（reentrancy guard），可在 ISR 或任务上下文触发：
+用于封装一个具体的回调函数及其第一个绑定参数，并提供擦除后的统一调用入口，可在 ISR 或任务上下文触发：
 
 - `FunctionType`: 回调函数签名为 `void(bool in_isr, ArgType arg, Args... args)`。
 - 具体执行入口由内部 `InvokeThunk(...)` / `Invoke(...)` 完成。
 
-构造时即完成函数与绑定参数的绑定。支持移动构造与移动赋值，禁用拷贝。
+构造时即完成函数与绑定参数的绑定。当前实现显式禁用拷贝；文档不应把它视为一个普通可复制/可移动的小值对象。
 
-### 重入保护语义
+### `GuardedCallbackBlock` 的重入保护语义
 
-重入保护用于抑制回调链形成环时的栈递归增长（例如 A → B → C → A，使同一回调在其执行期间被间接再次触发）。
+当前主线中的重入保护并不是 `CallbackBlock` 默认自带，而是由 `GuardedCallbackBlock` 单独实现；对应的用户入口是：
 
-当同一 `CallbackBlock` 处于执行状态时再次触发：
+```cpp
+LibXR::Callback<Args...>::CreateGuarded(fun, bound_arg);
+```
+
+它用于抑制回调链形成环时的栈递归增长（例如 A → B → C → A，使同一回调在其执行期间被间接再次触发）。
+
+当同一 guarded callback 处于执行状态时再次触发：
 
 - 不会形成新的嵌套调用栈帧（不递归调用）；
 - 仅保留一次“待执行请求”（保存一份参数快照；后续重入会覆盖旧的待执行参数）；
@@ -41,7 +47,7 @@ template <typename... Args>
 class Callback;
 ```
 
-对 `CallbackBlock` 的进一步封装，提供统一接口、类型擦除和创建工厂方法。
+对底层 callback block 的进一步封装，提供统一接口、类型擦除和创建工厂方法。
 
 ### 创建回调
 
@@ -54,6 +60,14 @@ LibXR::Callback<Args...> cb = LibXR::Callback<Args...>::Create(fun, bound_arg);
 
 > 注意：当前 `Create` 的实现会 `new CallbackBlock<BoundArgType, Args...>`，因此**包含动态内存分配**；同时 `Callback` 本身不管理释放。
 
+如需 guarded 版本：
+
+```cpp
+LibXR::Callback<Args...> cb = LibXR::Callback<Args...>::CreateGuarded(fun, bound_arg);
+```
+
+该路径当前会分配 `GuardedCallbackBlock<...>`。
+
 ### 执行回调
 
 ```cpp
@@ -64,7 +78,7 @@ cb.Run(in_isr, arg1, arg2, ...);
 
 ### 其他接口与语义
 
-- `Empty()`: 判断回调是否为空（内部 `cb_block_ == nullptr`）
+- `Empty()`: 判断回调是否为空（当前实现为 `cb_block_ == &empty_cb_block_`）
 - 支持默认构造、拷贝构造、移动构造与赋值
   - 拷贝为浅拷贝：多个 `Callback` 实例会共享同一回调块指针与调用入口。
 
@@ -87,7 +101,7 @@ ISR=0 context=42 msg=Hello
 
 ## 设计特点
 
-- **重入保护**：回调重入时不递归，缓存一次待执行请求并在当前调用点补跑（trampoline 扁平化）
+- **可选重入保护**：只有 `CreateGuarded(...)` 路径才会启用 trampoline 扁平化的重入保护；普通 `Create(...)` 只创建基础 `CallbackBlock`
 - **支持 ISR 上下文**：接口显式携带 `in_isr`，可在中断中安全调用
 - **类型安全封装**：利用模板与类型推导实现参数绑定与调用
 - **轻量可嵌入**：结构简单，适用于 IO、定时器、事件发布等模块的回调传递

docs/basic_coding/core/core-color.md

@@ -6,75 +6,112 @@ sidebar_position: 6
 
 # 终端颜色与格式
 
-本模块定义了终端打印时常用的格式控制枚举和 ANSI 转义序列，支持文本加粗、颜色设置、背景色等，适用于串口调试终端、日志系统、彩色输出等场景。
+本模块对应 `libxr_color.hpp`，提供当前主线里用于终端文本样式、控制序列、前景色、背景色和常用预设的枚举与 ANSI 转义字符串。它主要服务于终端输出、Logger、串口调试终端等文本界面路径。
 
-## 文本格式 Format
+## 文本样式 `TextStyle`
 
 ```cpp
-enum class Format : uint8_t {
-  NONE = 0, RESET, BOLD, DARK, UNDERLINE, BLINK, REVERSE, CONCEALED, CLEAR_LINE, COUNT
+enum class TextStyle : uint8_t {
+  NONE = 0,
+  BOLD,
+  DIM,
+  UNDERLINE,
+  BLINK,
+  REVERSE,
+  CONCEALED,
+  COUNT
 };
 ```
 
-- `NONE`: 无格式
-- `RESET`: 重置所有格式
-- `BOLD`: 加粗
-- `DARK`: 暗色字体
-- `UNDERLINE`: 下划线
-- `BLINK`: 闪烁
-- `REVERSE`: 前景/背景反转
-- `CONCEALED`: 隐藏
-- `CLEAR_LINE`: 清除整行
+- `BOLD`：加粗
+- `DIM`：弱化/暗色
+- `UNDERLINE`：下划线
+- `BLINK`：闪烁
+- `REVERSE`：前景/背景反转
+- `CONCEALED`：隐藏文本
 
-对应 ANSI 转义字符串：`LIBXR_FORMAT_STR[]`
+对应 ANSI 转义字符串：`LIBXR_TEXT_STYLE_STR[]`
 
-## 字体颜色 Font
+## 终端控制 `TerminalControl`
 
 ```cpp
-enum class Font : uint8_t {
-  NONE = 0, BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, COUNT
+enum class TerminalControl : uint8_t {
+  NONE = 0,
+  RESET,
+  ERASE_LINE,
+  COUNT
 };
 ```
 
-对应 ANSI 字符串：`LIBXR_FONT_STR[]`
+- `RESET`：重置当前样式
+- `ERASE_LINE`：清除当前行
 
-## 背景颜色 Background
+对应 ANSI 转义字符串：`LIBXR_TERMINAL_CONTROL_STR[]`
+
+## 前景色 `Foreground`
 
 ```cpp
-enum class Background : uint8_t {
-  NONE = 0, BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, COUNT
+enum class Foreground : uint8_t {
+  NONE = 0,
+  BLACK,
+  RED,
+  GREEN,
+  YELLOW,
+  BLUE,
+  MAGENTA,
+  CYAN,
+  WHITE,
+  COUNT
 };
 ```
 
-对应 ANSI 字符串：`LIBXR_BACKGROUND_STR[]`
+对应 ANSI 转义字符串：`LIBXR_FOREGROUND_STR[]`
 
-## 粗体样式 Bold
+## 背景色 `Background`
 
 ```cpp
-enum class Bold : uint8_t {
-  NONE = 0, YELLOW, RED, ON_RED, COUNT
+enum class Background : uint8_t {
+  NONE = 0,
+  BLACK,
+  RED,
+  GREEN,
+  YELLOW,
+  BLUE,
+  MAGENTA,
+  CYAN,
+  WHITE,
+  COUNT
 };
 ```
 
-简化常用彩色粗体样式输出，例如：
+对应 ANSI 转义字符串：`LIBXR_BACKGROUND_STR[]`
 
-- `YELLOW`: 黄色加粗
-- `RED`: 红色加粗
-- `ON_RED`: 红底白字加粗
+## 常用预设 `Preset`
 
-对应 ANSI 字符串：`LIBXR_BOLD_STR[]`
+```cpp
+enum class Preset : uint8_t {
+  NONE = 0,
+  YELLOW_BOLD,
+  RED_BOLD,
+  BOLD_ON_RED,
+  COUNT
+};
+```
+
+- `YELLOW_BOLD`：黄色粗体
+- `RED_BOLD`：红色粗体
+- `BOLD_ON_RED`：红底粗体
+
+对应 ANSI 转义字符串：`LIBXR_PRESET_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];
+std::cout
+    << LIBXR_TEXT_STYLE_STR[static_cast<uint8_t>(LibXR::TextStyle::BOLD)]
+    << LIBXR_FOREGROUND_STR[static_cast<uint8_t>(LibXR::Foreground::GREEN)]
+    << "This is bold green text!"
+    << LIBXR_TERMINAL_CONTROL_STR[static_cast<uint8_t>(LibXR::TerminalControl::RESET)];
 ```
 
-效果为绿色加粗文本。
-
----
-
-本模块可配合终端类、调试输出类、日志系统使用，用于构建清晰、可读性强的彩色输出。
+Logger 当前也直接使用这一组常量：按日志级别从 `LIBXR_FOREGROUND_STR[]` 取前景色，再在结尾追加 `TerminalControl::RESET`。