Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
ac61333
chore: add site-wide appearance customization and reading progress
xiaoshuaijie Oct 6, 2026
918677b
feat: add community page and improve site navigation
xiaoshuaijie Oct 6, 2026
c0b680c
fix: smooth theme switching and improve appearance controls
xiaoshuaijie Oct 6, 2026
981828e
fix: update English translations and correct docs reading progress
xiaoshuaijie Oct 6, 2026
7a3ba51
fix: address build output, accessibility, and clipboard issues
xiaoshuaijie Oct 6, 2026
713a1ae
Trim the appearance panel and align the new pages with XRobot Style
Jiu-xiao Oct 6, 2026
86b679a
Clean up the clipboard fallback and follow the animation switch acros…
Jiu-xiao Oct 6, 2026
a462415
Merge pull request #24 from xrobot-org/perf/frontend-optimization
Jiu-xiao Oct 6, 2026
0d37565
HPM: pins and clocks come from the project; HPMI2C and HPMPWM call no…
Jiu-xiao Oct 6, 2026
0ee2405
Merge pull request #25 from xrobot-org/docs/hpm-no-board-helpers
Jiu-xiao Oct 6, 2026
4244dc1
Document the MSPM0 and HPM code generation, the pin layout and the re…
Jiu-xiao Oct 7, 2026
73cf01d
Polish the MSPM0, HPM and pin layout pages after the read-through
Jiu-xiao Oct 7, 2026
b7f6b2a
Cover the dma_mgr dependency and the remaining MSPM0 and HPM generati…
Jiu-xiao Oct 7, 2026
18076e8
Correct the MSPM0, HPM and pin layout pages against the generator and…
Jiu-xiao Oct 7, 2026
42a787e
HPM: the GPIO clock joins the clock group before init_bsp_pins()
Jiu-xiao Oct 10, 2026
6be586a
Module CI: context refs follow the event, document the build-type input
Jiu-xiao Oct 10, 2026
874a0d7
Lock and setup: same-or-dev chain semantics, the release gate and --l…
Jiu-xiao Oct 10, 2026
c7cd5e3
Instance config: bare names for pointer parameters, native YAML sync …
Jiu-xiao Oct 10, 2026
011cf8d
LibXR: the build option, RamFS commands, the power managers, ObjectPo…
Jiu-xiao Oct 10, 2026
652ebe1
Code generation: the generated power manager object and the HPM pin data
Jiu-xiao Oct 10, 2026
599342b
Versions: the website follows the x.0.1 release
Jiu-xiao Oct 10, 2026
d52ddb2
Self-review: link the RamFS page and describe the pool and mailbox be…
Jiu-xiao Oct 10, 2026
426c38a
Power: the HPM Shutdown() wakes up on RESETN
Jiu-xiao Oct 10, 2026
94ac591
docs: add the SlotPool page and adjust the MPMC queue selection advice
Jiu-xiao Oct 10, 2026
590f28e
SlotPool page: who calls AddMessage, and the example's full branch
Jiu-xiao Oct 10, 2026
bd7d8ac
SlotPool page: dequeue order follows the publish sequence
Jiu-xiao Oct 10, 2026
7c0d19e
Merge pull request #26 from xrobot-org/docs/release-x.0.1-20261010
Jiu-xiao Oct 11, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/about.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ XRobot 前身为 [qdu-rm-mcu](https://gitee.com/qsheeeeen/qdu-rm-mcu.git),由
以下名单按人工维护,不包含 bot 账号。

- <img src="https://github.com/Jiu-xiao.png?size=48" width="24" height="24" style={{borderRadius: '50%', verticalAlign: 'middle'}} alt="@Jiu-xiao avatar" /> [@Jiu-xiao](https://github.com/Jiu-xiao) - 框架设计者,`STM32 / CH32 / Linux` 驱动开发
- <img src="https://github.com/molqzone.png?size=48" width="24" height="24" style={{borderRadius: '50%', verticalAlign: 'middle'}} alt="@molqzone avatar" /> [@molqzone](https://github.com/molqzone) - `MSPM0`、`DAPLink`
- <img src="https://github.com/molqzone.png?size=48" width="24" height="24" style={{borderRadius: '50%', verticalAlign: 'middle'}} alt="@molqzone avatar" /> [@molqzone](https://github.com/molqzone) - `DAPLink`
- <img src="https://github.com/xiaoshuaijie.png?size=48" width="24" height="24" style={{borderRadius: '50%', verticalAlign: 'middle'}} alt="@xiaoshuaijie avatar" /> [@xiaoshuaijie](https://github.com/xiaoshuaijie) - 网站 UI、`MSPM0`
- <img src="https://github.com/CaFeZn.png?size=48" width="24" height="24" style={{borderRadius: '50%', verticalAlign: 'middle'}} alt="@CaFeZn avatar" /> [@CaFeZn](https://github.com/CaFeZn) - `HPM` 系列
- <img src="https://github.com/llLeo306.png?size=48" width="24" height="24" style={{borderRadius: '50%', verticalAlign: 'middle'}} alt="@llLeo306 avatar" /> [@llLeo306](https://github.com/llLeo306) - 控制与实时系统

Expand Down
2 changes: 1 addition & 1 deletion docs/basic_coding/cmake.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ CMake 内部会把配置名称转换为小写。交叉编译时须设置 `LIBXR_
| `LIBXR_SHARED_BUILD` | 构建共享库 |
| `LIBXR_OBJECT_BUILD` | 构建对象库 |

未指定库类型时默认构建静态库。Debug 构建定义 `LIBXR_DEBUG_BUILD`;`LIBXR_DEV_ASSERT_BUILD` 独立控制 `DEV_ASSERT`。
未指定库类型时默认构建静态库。`LIBXR_DEBUG_BUILD` 默认跟随构建类型:未显式设置时,每次配置按当前构建类型重新计算(Debug 开启、其余关闭),作为普通变量不写入缓存,同一构建目录中切换构建类型后立即生效;用 `-DLIBXR_DEBUG_BUILD=ON/OFF` 显式设置后该值进入缓存,此后始终按用户的值。`LIBXR_DEV_ASSERT_BUILD` 独立控制 `DEV_ASSERT`。

## 日志与格式化

Expand Down
2 changes: 1 addition & 1 deletion docs/basic_coding/core/core-assert.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ LibXR::Assert::RegisterFatalErrorCallback(cb);

| 宏 | 生效条件 | 关闭时 | 用途 |
| --- | --- | --- | --- |
| `ASSERT(expr)` / `ASSERT_FROM_CALLBACK(expr, in_isr)` | 定义 `LIBXR_DEBUG_BUILD`(`CMAKE_BUILD_TYPE=Debug` 时自动定义) | 表达式仍求值,不检查 | 调用前提与配置检查 |
| `ASSERT(expr)` / `ASSERT_FROM_CALLBACK(expr, in_isr)` | 定义 `LIBXR_DEBUG_BUILD`;未显式设置时按构建类型决定(Debug 开启),`-DLIBXR_DEBUG_BUILD=ON/OFF` 可在任何构建类型下覆盖 | 表达式仍求值,不检查 | 调用前提与配置检查 |
| `REQUIRE(expr)` / `REQUIRE_FROM_CALLBACK(expr, in_isr)` | 始终生效 | — | 不可恢复的运行错误 |
| `DEV_ASSERT(expr)` / `DEV_ASSERT_FROM_CALLBACK(expr, in_isr)` | CMake 选项 `LIBXR_DEV_ASSERT_BUILD=ON` | 表达式不求值 | LibXR 内部开发检查 |

Expand Down
16 changes: 15 additions & 1 deletion docs/basic_coding/driver/power.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,12 @@ public:

// 跳转到启动加载器(默认退化为 Reset)
virtual void JumpToBootloader() { Reset(); }

// 在 RamFS 根目录注册 power 命令
void RegisterCommand(RamFS& ramfs);

// 读一次引脚,电平等于 level 时进入启动加载器
void CheckBootloaderPin(GPIO& pin, bool level);
};
```

Expand All @@ -32,10 +38,18 @@ public:
- `Reset()` 可用于软复位控制器、重新启动系统等;
- `Shutdown()` 用于关机、掉电、进入睡眠等低功耗控制;
- `JumpToBootloader()` 默认会退化为 `Reset()`,平台实现可按需改为真正的 Bootloader 跳转;
- `RegisterCommand(ramfs)` 在 RamFS 根目录注册 `power` 命令(见[内存文件系统](../middleware/ramfs.md)):终端中 `power reset`、`power shutdown`、`power bootloader` 分别调用上述三个方法,不带参数或参数不认识时打印用法并返回 -1。命令文件在第一次注册时分配,之后不释放,同一个对象只注册一次;
- `CheckBootloaderPin(pin, level)` 读一次引脚,电平等于 `level` 时调用 `JumpToBootloader()`,否则直接返回;在初始化早期调用一次,按住该引脚对应的按键再复位即可进入启动加载器,运行中该引脚仍归程序使用。引脚的输入方向和上下拉由工程配置决定,本函数不修改;悬空的引脚可能误触发;
- 可用于平台的电源按钮、远程命令、低电量策略等情境;
- 由具体平台实现其底层行为,接口保持一致,便于移植与抽象封装。

## 平台实现

MSPM0 的 `MSPM0PowerManager` 中,`Reset()` 触发 boot 配置流程,复位绝大部分核内逻辑并给 SRAM 重新上电,效果等同整机重新从 Flash 启动;`Shutdown()` 进入 SHUTDOWN 模式,由 NRST、SWD 活动或配置了唤醒功能的 IO 唤醒,退出 SHUTDOWN 触发 BOR,唤醒后等同一次复位重启;`JumpToBootloader()` 复位进入 ROM BSL,复位前按 SDK 示例清零 SRAM 的数据与 ECC 码,规避 `BSL_ERR_01`。MSPM0 的 ROM BSL 走串口,因此 `power bootloader` 之后可以用串口烧录固件。

HPM 的 `HPMPowerManager` 中,`Reset()` 使能 PPOR 软件复位源后触发复位;`Shutdown()` 在带 PDGO 的 SoC 上设置关断计数后等待断电,由 RESETN 引脚唤醒,没有 PDGO 的 SoC 退化为关中断后执行 WFI;`JumpToBootloader()` 关中断后调用 ROM API 进入 ROM ISP,外设由 ROM 自动探测,调用正常不返回,返回时复位整机。经 USB 的 ROM ISP 在 HPM5301 和 HPM5361 上未能枚举。

## 说明

- `PowerManager` 只有 `Reset()`、`Shutdown()` 和默认调用 `Reset()` 的 `JumpToBootloader()` 三个接口。
- `PowerManager` 提供 `Reset()`、`Shutdown()`、`JumpToBootloader()` 三个平台接口,以及 `RegisterCommand()`、`CheckBootloaderPin()` 两个由基类实现的通用接口。
- 状态查询、事件回调、低功耗级别等由具体平台实现或上层代码提供。
20 changes: 11 additions & 9 deletions docs/basic_coding/middleware/ramfs.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,10 +35,13 @@ sidebar_position: 6
通过 `CreateFile()` 创建:

- `CreateFile(name, data)`:`data` 为 `const` 对象时创建只读文件,否则创建可读写文件;
- `CreateFile(name, exec, arg)` 或 `CreateCommand(name, exec, arg)`:创建可执行文件,`Run(argc, argv)` 调用 `exec(arg, argc, argv)`。
- `CreateFile(name, exec, arg)` 或 `CreateCommand(name, exec, arg)`:创建可执行文件,`Run(argc, argv)` 调用 `exec(arg, argc, argv)`;
- `CreateCommand(name, exec)`:创建不需要执行上下文的可执行文件,`exec` 直接接收 `argc` 和 `argv`。

`IsReadOnly()`、`IsReadWrite()`、`IsExecutable()` 返回文件种类。

`Add()` 只接受左值:RamFS 只保存节点地址,节点须在整个运行期内有效,传入 `CreateCommand()` 返回的临时对象会留下悬空指针。

### Dir

目录类支持添加 / 查找:
Expand All @@ -58,18 +61,16 @@ sidebar_position: 6
```cpp
RamFS fs;

int counter = 0;
static int counter = 0;

// 创建可执行文件(每次调用将计数器 +1)
auto exec_file = RamFS::CreateFile<int*>(
"runme",
[](int* arg, int argc, char** argv) {
// 创建不需要执行上下文的可执行文件(每次调用将计数器 +1)
auto exec_file = RamFS::CreateCommand("runme",
[](int argc, char** argv) {
UNUSED(argc);
UNUSED(argv);
(*arg)++;
counter++;
return 0;
},
&counter
}
);

// 创建读写文件
Expand Down Expand Up @@ -108,6 +109,7 @@ for (int i = 1; i <= 5; ++i) {
| `FindDir(name)` | 查找目录 |
| `FindCustom(name)` | 查找自定义节点 |
| `CreateCommand(name, exec, arg)` | 创建可执行文件,与 `CreateFile(name, exec, arg)` 相同 |
| `CreateCommand(name, exec)` | 创建不需要执行上下文的可执行文件 |
| `bin_` | 构造时创建并挂在根目录下的 `bin` 目录 |

### File 接口
Expand Down
2 changes: 1 addition & 1 deletion docs/basic_coding/middleware/terminal.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ Terminal(RamFS &ramfs,
- 命令输入被缓存在 `input_line_` 中,按回车自动解析并执行;
- 内建命令只有 `cd` 和 `ls`;`ls` 每行输出类型字母和名称:`d` 目录、`x` 可执行文件、`f` 普通文件、`?` 自定义节点;
- 其他输入把第一个参数当作 RamFS 文件路径:不含 `/` 时只在当前目录查找,以 `/` 开头时从根目录解析;找到可执行文件则运行,找不到时输出 `Command not found.`,不是可执行文件时输出 `Not an executable file.`;
- 命令通常用 `CreateCommand()` 创建后加入 `ramfs.bin_`,在根目录下以 `/bin/<name>` 调用,或先 `cd bin`;
- 命令通常用 `CreateCommand(name, exec)` 创建后加入 `ramfs.bin_`,在根目录下以 `/bin/<name>` 调用,或先 `cd bin`;
- 支持 ANSI 上下左右键移动与历史记录查阅;
- Tab 键补全第一个参数的路径。

Expand Down
2 changes: 2 additions & 0 deletions docs/basic_coding/structure/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,12 @@ sidebar_position: 2
- [Queue(普通 FIFO 队列)](./queue.md)
- [SPSCQueue(单生产者单消费者无锁队列)](./spsc_queue.md)
- [MPMCQueue(多生产者多消费者有界队列)](./mpmc_queue.md)
- [SlotPool(消息槽池)](./slot_pool.md)
- [Stack(栈)](./stack.md)
- [List(链表)](./list.md)
- [LockFreeList(无锁链表)](./lockfree_list.md)
- [ObjectPool(RAII 对象池)](./object_pool.md)
- [LatestSnapshot(最新值邮箱)](./latest_snapshot.md)
- [RBTree(红黑树)](./rbt.md)
- [DoubleBuffer(双缓冲区)](./double_buffer.md)

Expand Down
77 changes: 77 additions & 0 deletions docs/basic_coding/structure/latest_snapshot.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
---
id: latest_snapshot
title: 最新值邮箱
sidebar_position: 10
---

# LatestSnapshot(最新值邮箱)

`LibXR::LatestSnapshot<T>` 是单生产者、单消费者的邮箱,只保留最新一份完整值。

它适用于只关心最新数据的场合。以接收中断与控制线程为例:中断每收到一帧反馈就发布一次,控制线程按自己的节奏读取,读到的始终是最近一次发布的值;控制线程来不及读取时,中间的发布被后来的覆盖,不排队、不积压。

## 核心特性

- 内部三个槽:生产者独占后槽,消费者独占前槽,中间槽由一个原子状态交给对方,承载最新一次完成的发布;
- 连续的 `Store()` 可以覆盖消费者尚未取走的中间值;消费者正在拷贝的值在它独占的前槽里,不受影响;
- 三个槽随对象构造,`LatestSnapshot` 自身不分配内存;
- 对象不可拷贝、不可移动。

## 常用接口

```cpp
template <typename T>
class LatestSnapshot
{
public:
explicit LatestSnapshot(const T& initial);

void Store(const T& value);

bool LoadLatest(T& output);
};
```

- `LatestSnapshot(initial)`:用同一个初始值构造三个槽;第一次 `Store()` 之前,`LoadLatest()` 输出这个初始值;
- `Store(value)`:先把值拷入生产者独占的后槽,再把该槽作为最新的中间槽交给消费者;
- `LoadLatest(output)`:有新的发布时先取得它,没有时 `output` 得到消费者上一次取得的值;本次取得了新的发布时返回 `true`,否则返回 `false`。

`T` 须可拷贝构造、可拷贝赋值。

## 并发约束

- `Store()` 只能由唯一的生产者调用,`LoadLatest()` 只能由唯一的消费者串行调用,同一时刻只有一次调用;
- 生产者和消费者的调用可以在不同核、线程或中断中重叠,两者的交接用一个 32 位原子状态完成;
- 值在发布时整体拷贝,因此每次读到的都是一份完整的值。

## 使用示例

```cpp
struct Feedback
{
uint32_t seq = 0;
float position = 0.0f;
};

LibXR::LatestSnapshot<Feedback> feedback(Feedback{});

// 接收中断中发布最新的反馈帧
void OnFeedbackFrame(const Feedback& frame)
{
feedback.Store(frame);
}

// 控制线程中读取;本次取到新的发布时 LoadLatest() 返回 true
void ControlStep()
{
Feedback frame{};
if (feedback.LoadLatest(frame))
{
// frame 是本次取得的最新反馈
}
}
```

## 选择建议

生产者与消费者各只有一个、且每次发布都必须被处理时用 `SPSCQueue`;只关心最新值、中间值可以丢弃时用 `LatestSnapshot`。任一侧不止一个时使用 `MPMCQueue`。
7 changes: 4 additions & 3 deletions docs/basic_coding/structure/mpmc_queue.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,10 @@ queue.Pop(value);
- 中断与线程、多个线程共同访问的公共队列;
- 驱动内部需要有界并发队列的地方。

例如 CAN 驱动的发送队列使用 `MPMCQueue<ClassicPack>`。
例如数据在任务和线程之间传递、调用方能等待或稍后重试的公共队列。单核上若某个操作在占槽与发布之间被抢占,其他上下文会看到瞬时的 FULL/EMPTY;中断会读写、拿到 FULL 只能丢数据的场合(例如中断与任务共享的发送队列)改用 [SlotPool](./slot_pool.md)。

## 和 `SPSCQueue` 的取舍
## 和 `SPSCQueue`、`SlotPool` 的取舍

- 生产者和消费者各只有一个:使用 `SPSCQueue`;
- 有多个生产者或多个消费者:使用 `MPMCQueue`。
- 有多个生产者或多个消费者:使用 `MPMCQueue`;
- 中断会读写、拿到 FULL 只能丢数据、希望 FULL/EMPTY 是准的:使用 [SlotPool](./slot_pool.md),一个被打断的操作只占自己的槽;`MPMCQueue` 的单次入队出队是 O(1),`SlotPool` 是 O(N),大容量、多核高争用、调用方能等待或重试的场合仍然适合 `MPMCQueue`。
Loading
Loading