Update system.

Author: Jiu-xiao

docs/basic_coding/system/README.md

@@ -0,0 +1,19 @@
+---
+id: system-coding
+title: 操作系统
+sidebar_position: 4
+---
+
+# 操作系统
+
+本模块提供 LibXR 对线程管理、同步原语、定时器等底层操作系统资源的统一抽象，确保在不同 RTOS、Linux 乃至裸机环境下均可无缝移植。
+
+## 快速导航
+
+- [Thread（线程）](./thread.md)
+- [Mutex（互斥锁）](./mutex.md)
+- [Semaphore（信号量）](./semaphore.md)
+- [Async（异步任务）](./async.md)
+- [Timer（定时器）](./timer.md)
+
+更多使用方法、平台适配指引与设计思想，请参阅各页面的详细说明。

docs/basic_coding/system/async.md

@@ -0,0 +1,89 @@
+---
+id: async
+title: 异步任务
+sidebar_position: 6
+---
+
+# ASync（异步任务）
+
+`LibXR::ASync` 通过 **专用工作线程 + 计数信号量** 为耗时操作提供简单、低开销的异步执行能力。用户可在任务或中断回调中分配 `Job` 回调，框架在后台线程中顺序执行并更新状态，无需自行管理线程生命周期或复杂的队列。
+
+> **典型应用**：SPI 采样结束中断后触发 FFT 计算；主循环内提交 OTA 校验；GPIO ISR 内上报事件至云端等。
+
+## 设计要点
+
+| 目标             | 说明                                                                                                 |
+| ---------------- | ---------------------------------------------------------------------------------------------------- |
+| **线程独占执行** | 每个 `ASync` 实例内部创建 1 个工作线程，通过 `Semaphore` 唤醒执行 `Job`，避免任务间竞态。            |
+| **ISR 安全提交** | `AssignJobFromCallback()` 可在中断/回调环境调用，采用 `Semaphore::PostFromCallback()` 安全唤醒线程。 |
+| **状态可查询**   | `GetStatus()` 返回 `READY/BUSY/DONE`，任务完成后自动复位，可用于轮询或超时检测。                     |
+| **依赖可裁剪**   | 仅依赖 `Thread` 与 `Semaphore` 封装；裸机模式下可退化为同步执行。        |
+| **极简接口**     | 不引入模板队列或动态分配，接口面向回调 `Callback<ASync*>`，易于绑定成员函数或自由函数。              |
+
+## 核心接口
+
+```cpp
+class ASync {
+public:
+  enum class Status : uint8_t { READY, BUSY, DONE };
+
+  ASync(size_t stack_depth, Thread::Priority priority);
+
+  using Job = LibXR::Callback<ASync*>;
+  ErrorCode AssignJob(Job job);                       // 任务上下文提交
+  void       AssignJobFromCallback(Job job, bool isr);// ISR/回调上下文提交
+  Status     GetStatus();                             // 查询状态并自动复位
+};
+```
+
+### 错误码
+
+* `ErrorCode::OK`      提交成功
+* `ErrorCode::BUSY`    已有任务在执行
+
+## 使用示例
+
+```cpp
+#include <libxr/async.hpp>
+
+LibXR::ASync async_worker(2048, LibXR::Thread::Priority::NORMAL);
+
+void HeavyCalc(bool, int *, LibXR::ASync*)
+{
+  DoFFT();   // 耗时 5‑10 ms
+}
+
+int arg = 0;
+auto async_job = LibXR::ASync::Job::Create(HeavyCalc, &arg);
+
+void SensorISR()
+{
+  // 采样完成后在中断中提交计算任务
+  async_worker.AssignJobFromCallback(HeavyCalc, true);
+}
+
+void Loop()
+{
+  // ...
+
+  if (async_worker.GetStatus()==LibXR::ASync::Status::DONE) {
+    PublishResult();
+  }
+
+  // ...
+}
+```
+
+## 平台适配
+
+`ASync` 本身不依赖特定 OS，所有平台差异已由 `Thread` 与 `Semaphore` 层吸收：
+
+| 功能     | 依赖模块                        |
+| -------- | ------------------------------- |
+| 线程创建 | `Thread::Create()`              |
+| 任务唤醒 | `Semaphore::Post/Wait`          |
+| ISR 兼容 | `Semaphore::PostFromCallback()` |
+
+裸机模式下可在 `async.cpp` 中改为 **同步直调**：若系统无线程支持，`AssignJob()` 直接调用 `job.Run()`，`ASync` 退化为函数调用包装。
+
+设计理念中Callback不允许阻塞/延时，但是此处复用了Callback的接口与数据结构，为防止混淆重命名为`Job`。

docs/basic_coding/system/mutex.md

@@ -0,0 +1,53 @@
+---
+id: mutex
+title: 互斥锁
+sidebar_position: 4
+---
+
+# Mutex（互斥锁）
+
+`LibXR::Mutex` 提供轻量级、跨平台的 **线程互斥** 机制，用于保护多任务环境中的临界区。当前支持 **POSIX pthread** 与 **FreeRTOS/ThreadX** 实现，裸机环境可退化为空实现（自旋等待或禁用中断临界区）。
+
+> **⚠️ 注意**：互斥锁 **只能** 在任务（线程）上下文调用，**不支持** 在中断服务程序（ISR）中加/解锁。
+
+## 设计要点
+
+| 目标 | 说明 |
+| ---- | ---- |
+| **跨平台** | 隐藏 `pthread_mutex`, `xSemaphoreHandle`, `TX_MUTEX` 等差异。|
+| **RAII 友好** | 内置 `LockGuard`，避免忘记 Unlock。|
+| **优先级继承** | 在支持的 RTOS 上启用互斥量优先级继承，减小优先级反转风险。|
+| **轻量低开销** | 调用路径贴近底层系统调用。|
+
+## 核心接口
+
+```cpp
+class Mutex {
+public:
+  Mutex();
+  ~Mutex();
+
+  ErrorCode Lock();     // 阻塞加锁
+  ErrorCode TryLock();  // 非阻塞尝试
+  void Unlock();        // 解锁
+
+  class LockGuard {
+  public:
+    explicit LockGuard(Mutex& m);
+    ~LockGuard();
+  };
+};
+```
+
+## 使用示例
+
+```cpp
+LibXR::Mutex m;
+int shared = 0;
+
+void Worker()
+{
+  LibXR::Mutex::LockGuard lock(m);  // 构造时加锁
+  shared++;                         // 安全访问
+}                                    // 析构时自动解锁
+```

docs/basic_coding/system/semaphore.md

@@ -0,0 +1,41 @@
+---
+id: semaphore
+title: 信号量
+sidebar_position: 5
+---
+
+# Semaphore（信号量）
+
+`LibXR::Semaphore` 提供**计数型信号量**以协调多任务/ISR 对共享资源的访问，支持线程上下文的阻塞等待 (`Wait`) 和中断安全的释放 (`PostFromCallback`)。当前实现覆盖 **POSIX sem\_t**、**FreeRTOS Counting Semaphore**、**ThreadX TX\_SEMAPHORE** 以及 **Bare‑metal** 自旋等版本。
+
+## 设计要点
+
+| 目标         | 说明                                                                    |
+| ---------- | --------------------------------------------------------------------- |
+| **跨平台**    | 隐藏 `sem_t` / `SemaphoreHandle_t` / `TX_SEMAPHORE` 等差异。 |
+| **ISR 友好** | 提供 `PostFromCallback(bool in_isr)`，在中断或 DMA 回调内安全释放并触发任务切换。           |
+| **超时等待**   | `Wait(timeout_ms)` 支持毫秒级超时。                      |
+| **轻量裁剪**   | 仅依赖 C++17 与可选 RTOS 头文件。                      |
+| **可观测性**   | `Value()` 返回当前计数，方便调试与性能分析。                                           |
+
+## 核心接口
+
+```cpp
+class Semaphore {
+public:
+  explicit Semaphore(uint32_t init = 0);
+  ~Semaphore();
+
+  void     Post();                    // 线程上下文释放
+  void     PostFromCallback(bool irq);// 中断/回调上下文释放
+  ErrorCode Wait(uint32_t timeout=UINT32_MAX); // 阻塞等待
+  size_t   Value();                   // 当前计数
+};
+```
+
+### 错误码
+
+* `ErrorCode::OK`       操作成功
+* `ErrorCode::TIMEOUT` 等待超时
+
+> **⚠️ 注意**：`Wait()` **不能** 在 ISR 中调用。

docs/basic_coding/system/thread.md

@@ -0,0 +1,77 @@
+---
+id: thread
+title: 线程
+sidebar_position: 3
+---
+
+# Thread（线程）
+
+`LibXR::Thread` 封装了 **线程的创建、调度与时间控制**，在不同平台呈现统一的面向对象接口。目前已提供 **POSIX / FreeRTOS / ThreadX / Bare‑metal** 等多种适配实现；用户无需关心具体 OS 调用，即可在多种环境下保持一致的线程逻辑。
+
+## 设计要点
+
+| 目标         | 说明                                                                                  |
+| ---------- | ----------------------------------------------------------------------------------- |
+| **跨平台**    | 统一 API 隐藏 `pthread`, `xTask`, `TX_THREAD` 等差异。 |
+| **轻量可裁剪**  | 仅依赖 C++17 与可选 RTOS 头文件；可在无 OS 场景开启。                            |
+| **优先级枚举**  | 采用 `enum class Priority { IDLE…REALTIME }`，由每个移植层映射到本地优先级区间，避免直接暴露 OS 常量。           |
+| **时间基准统一** | 所有 `Sleep` / `SleepUntil` 以 **毫秒** 为单位，`GetTime()` 返回系统启动后的毫秒计数，方便跨平台超时逻辑。          |
+
+## 公开接口速览
+
+| 方法                                                                                                               | 作用                                                 |
+| ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `template <typename Arg> void Create(Arg arg, void (*func)(Arg), const char* name, size_t stack, Priority prio)` | 创建并启动线程，支持任意函数签名；栈深、优先级参数由各平台解释。                   |
+| `static Thread Current()`                                                                                        | 获取当前线程对象包装。                                        |
+| `static uint32_t GetTime()`                                                                                      | 返回自启动以来的毫秒计数（32 位环绕）。                              |
+| `static void Sleep(uint32_t ms)`                                                                                 | 阻塞当前线程指定毫秒。                                        |
+| `static void SleepUntil(TimestampMS& last, uint32_t period)`                                                     | 周期性延时，常用于固定周期循环。`last` 在函数内自动更新。                   |
+| `static void Yield()`                                                                                            | 主动让出 CPU，调用底层 `sched_yield()` / `taskYIELD()` 等实现。 |
+| `operator libxr_thread_handle()`                                                                                 | 隐式转换为底层线程句柄，供与平台 API 交互。                           |
+
+> **提示**：若系统不支持线程优先级或实时调度，可在移植层内部降级处理，不影响上层逻辑。
+
+## 典型用法
+
+```cpp
+#include <thread.hpp>
+
+void Blink(int* arg) {
+    auto last = LibXR::Thread::GetTime();
+    while (true) {
+        ToggleLED();            // 用户自定义函数
+        LibXR::Thread::SleepUntil(last, 500); // 500 ms 间隔
+    }
+}
+
+int main() {
+    int arg = 0;
+    LibXR::Thread t;
+    t.Create(&arg, Blink, "blink", 2048, LibXR::Thread::Priority::MEDIUM);
+    // 主线程继续执行其它任务 …
+    for (;;) {
+        LibXR::Thread::Yield();
+    }
+}
+```
+
+## 平台适配概览
+
+| 平台                       | 头/源文件                       | 关键映射                                                          |
+| ------------------------ | --------------------------- | ------------------------------------------------------------- |
+| **Linux / POSIX**        | `thread.hpp` + `thread.cpp` | `pthread_create`, `clock_nanosleep`, `sched_yield`            |
+| **FreeRTOS**             | `thread.hpp` + `thread.cpp` | `xTaskCreate`, `vTaskDelay`, `xTaskGetTickCount`              |
+| **ThreadX (Azure RTOS)** | `thread.hpp` + `thread.cpp` | `tx_thread_create`, `tx_thread_sleep`, `tx_thread_relinquish` |
+| **Bare‑metal**           | `thread.hpp` + `thread.cpp` | 轮询 `Timebase` + `Timer::RefreshTimerInIdle` 实现软延时             |
+
+移植新平台时，仅需：
+
+1. 在 `platform/<os>/` 下实现对应的 `thread.hpp / thread.cpp`；
+2. 在 `libxr_system.hpp` 中 typedef `libxr_thread_handle`；
+3. 更新构建系统以选择正确源文件。
+
+## 参考实现细节
+
+* POSIX 版本优先尝试 `SCHED_FIFO` 并根据可用优先级范围映射 `Priority`；否则回退默认策略并给出日志警告。
+* FreeRTOS/ThreadX 版本通过 `configMAX_PRIORITIES` 或 `TX_MAX_PRIORITIES` 动态计算优先级步长，确保与内核配置一致。
+* Bare-metal 版本创建线程时会直接开始运行线程函数，无法返回主线程。

docs/basic_coding/system/timer.md

@@ -0,0 +1,78 @@
+---
+id: timer
+title: 定时器
+sidebar_position: 7
+---
+
+# Timer（定时器）
+
+`LibXR::Timer` 实现了**跨平台的周期性任务调度**，支持高精度多任务定时执行。它提供统一的定时任务创建、启动、停止、删除及周期调整等接口，底层利用 `Thread::SleepUntil` 实现精确调度，适配多线程和裸机场景。可用于定时回调、周期控制、异步定时任务等各种需求。
+
+## 设计要点
+
+| 目标          | 说明                                        |
+| ----------- | ----------------------------------------- |
+| **跨平台统一**   | 定时调度机制与 OS 解耦，兼容多线程与裸机环境。                 |
+| **多任务支持**   | 支持并发多个周期性任务调度，任务独立注册与管理。                  |
+| **高精度**     | 任务调度精度达 1ms，基于 `Thread::SleepUntil` 精确控制。 |
+| **灵活接口**    | 支持任务周期动态调整、启动/停止/删除/添加等全生命周期操作。           |
+| **线程安全可裁剪** | 内部自动管理任务线程，裸机模式下自动刷新，无需用户主动调用。            |
+
+## 公开接口速览
+
+| 方法                                                                                                 | 作用                                          |
+| -------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| `template <typename Arg> static TimerHandle CreateTask(void (*fun)(Arg), Arg arg, uint32_t cycle)` | 创建周期性任务（周期 ms），返回任务句柄。                      |
+| `static void Start(TimerHandle handle)`                                                            | 启动指定任务。                                     |
+| `static void Stop(TimerHandle handle)`                                                             | 停止指定任务。                                     |
+| `static void SetCycle(TimerHandle handle, uint32_t cycle)`                                         | 修改任务周期。                                     |
+| `static void Remove(TimerHandle handle)`                                                           | 删除指定任务。                                     |
+| `static void Add(TimerHandle handle)`                                                              | 将任务添加到调度列表（首次添加会自动启动管理线程）。                  |
+| `static void Refresh()`                                                                            | 主动刷新所有任务（轮询场景下调用，通常由定时线程自动执行）。              |
+| `static void RefreshTimerInIdle()`                                                                 | 在裸机下**由 Thread 延时/Mutex/信号量自动调用**，用户无需手动调用。 |
+
+> **提示**：所有定时任务周期单位均为**毫秒**，所有任务由 Timer 管理线程或主循环自动调度，无需手动管理任务遍历与时间计算。裸机场景下，Thread 延时、Mutex 和信号量等待时会自动刷新定时器，无需用户干预。
+
+## 典型用法
+
+```cpp
+#include <timer.hpp>
+
+void PrintHello(int* value) {
+    printf("Hello, value = %d\n", *value);
+}
+
+int main() {
+    int arg = 123;
+    // 创建定时任务，每 1000ms 调用一次 PrintHello
+    auto handle = LibXR::Timer::CreateTask(PrintHello, &arg, 1000);
+
+    LibXR::Timer::Add(handle);    // 加入调度并自动启动定时线程
+    LibXR::Timer::Start(handle);  // 启动任务
+
+    while (1) {
+        // 主循环，裸机下无需主动刷新定时器
+        // 多线程下可执行其它任务
+        LibXR::Thread::Sleep(UINT32_MAX);
+    }
+}
+```
+
+## 平台适配概览
+
+| 场景       | 关键实现                      | 调度机制说明                             |
+| -------- | ------------------------- | ---------------------------------- |
+| 多线程/RTOS | Thread::SleepUntil + 管理线程 | 自动启动管理线程，1ms 精度循环检查并调度任务。          |
+| 裸机/单线程   | RefreshTimerInIdle 自动调用   | Thread 延时/Mutex/信号量等待时自动刷新，无需手动调用。 |
+
+移植到新平台时，仅需保证 Thread 及 Timebase 支持，无需修改 Timer 主体逻辑。
+
+## 参考实现细节
+
+* 每个定时任务都封装为 ControlBlock，通过 List 链表统一管理；
+* CreateTask 支持带参数回调，内部类型安全，无需手动绑定上下文；
+* Add 第一次调用会自动分配任务列表与管理线程（多线程环境）；
+* Refresh 遍历所有已启用任务，按周期自动计数与触发，无需用户管理遍历与计时；
+* 裸机下，Thread 延时/Mutex/信号量等待自动刷新定时器，确保任务及时调度；
+* 支持任务周期动态调整、运行中启停与删除，接口灵活安全；
+* 断言机制保证非法操作（如多次添加、错误删除）即时报错。

i18n/en/docusaurus-plugin-content-docs/current/basic_coding/system/README.md

@@ -0,0 +1,19 @@
+---
+id: system-coding
+title: Operating System
+sidebar_position: 4
+---
+
+# Operating System
+
+This module provides LibXR's unified abstraction for low-level OS resources such as thread management, synchronization primitives, and timers, ensuring seamless portability across various RTOSes, Linux, and even bare-metal environments.
+
+## Quick Navigation
+
+- [Thread](./thread.md)
+- [Mutex](./mutex.md)
+- [Semaphore](./semaphore.md)
+- [Async](./async.md)
+- [Timer](./timer.md)
+
+For more usage guidelines, platform adaptation instructions, and design principles, please refer to the individual pages.