docs: 继续调整措辞，删除 lockfree_queue 页面 (#14)

Jiu-xiao · web-flow · commit 1651b9cc46a6 · 2026-07-01T21:08:18.000+01:00
* docs: 继续调整措辞，删除 lockfree_queue 页面

- 去除「这条线」「当前接口边界」「语义边界」「这页不做什么」等写法
- 四处「当前接口边界」标题统一改为「说明」
- 删除已废弃的 lockfree_queue.md（中英文）
- perf-topic.md 删除多余的读者引导段落

* docs: 修复删除 lockfree_queue 后的死链
diff --git a/docs/adv_coding/driver/uart_driver.md b/docs/adv_coding/driver/uart_driver.md
@@ -26,7 +26,7 @@ UART 驱动对上统一暴露 `SetConfig(...)`、`Write(...)` 和 `Read(...)`。
 
 `ESP32UART` 仍然沿用同一套端口抽象，但内部会按芯片能力选择后端。有 GDMA 时走 DMA 路径，没有则退回 FIFO + UART 中断。无论底层是哪条后端，发送侧都保留 active/pending 双槽，接收侧都以“先把字节推入端口队列，再处理挂起读请求”为准。
 
-`ESP32CDCJtag` 也值得单独提一下。它对上同样继承 `LibXR::UART`，但底层不是传统 UART 外设，而是 `USB Serial/JTAG` 控制器。它保留了 UART 抽象，却不属于 XRUSB 的通用 `DeviceCore`。从驱动设计角度看，这条线依然遵循相同原则：发送侧准备下一块，接收侧把字节推进 `ReadPort`，只不过底层搬运方式从 UART DMA/FIFO 变成了 USB Serial/JTAG FIFO。
+`ESP32CDCJtag` 也值得单独提一下。它对上同样继承 `LibXR::UART`，但底层不是传统 UART 外设，而是 `USB Serial/JTAG` 控制器。它保留了 UART 抽象，却不属于 XRUSB 的通用 `DeviceCore`。从驱动设计角度看，它依然遵循相同原则：发送侧准备下一块，接收侧把字节推进 `ReadPort`，只不过底层搬运方式从 UART DMA/FIFO 变成了 USB Serial/JTAG FIFO。
 
 ## Linux 路径
 
diff --git a/docs/basic_coding/driver/power.md b/docs/basic_coding/driver/power.md
@@ -35,7 +35,7 @@ public:
 - 可用于平台的电源按钮、远程命令、低电量策略等情境；
 - 由具体平台实现其底层行为，接口保持一致，便于移植与抽象封装。
 
-## 当前接口边界
+## 说明
 
 - `PowerManager` 当前是一个非常窄的抽象面：只有 `Reset()`、`Shutdown()` 和默认退化为 `Reset()` 的 `JumpToBootloader()`。
 - 它不携带状态查询、事件回调、低功耗级别枚举等更丰富的统一策略接口；如果某个平台有这些能力，仍属于具体实现或更上层策略模块，而不是当前基类公共契约。
diff --git a/docs/basic_coding/driver/pwm.md b/docs/basic_coding/driver/pwm.md
@@ -38,7 +38,7 @@ public:
 - 提供启用与禁用接口，适合状态控制与节能管理；
 - 平台需实现具体信号输出逻辑，上层调用保持一致性。
 
-## 当前接口边界
+## 说明
 
 - `SetDutyCycle(float value)` 当前只以注释形式约定“0.0 ~ 1.0”这一常见占空比表达；若某个平台实现需要做钳制、量化或错误返回，具体行为仍由该后端决定。
 - `Configuration` 当前只包含 `frequency` 字段；占空比并不通过 `SetConfig()` 设置，而是单独走 `SetDutyCycle()`。
diff --git a/docs/basic_coding/driver/spi.md b/docs/basic_coding/driver/spi.md
@@ -118,9 +118,9 @@ struct ReadWriteInfo {
 - 提供全双工传输接口，并暴露 `GetRxBuffer()` / `GetTxBuffer()`、`SwitchBuffer()`、`SetActiveLength()` 等双缓冲辅助接口；
 - 通用操作模型（`OperationRW = WriteOperation`），支持同步、回调、轮询等模式；
 
-## 语义边界
+## 说明
 
-- `ReadAndWrite(...)`、`Transfer(...)`、`MemRead(...)`、`MemWrite(...)` 都是平台实现需要提供的抽象行为；本页不假定所有平台都共享相同的寄存器协议或 DMA 组织方式。
+- `ReadAndWrite(...)`、`Transfer(...)`、`MemRead(...)`、`MemWrite(...)` 都是平台实现需要提供的抽象行为；各平台的寄存器协议和 DMA 组织方式不一定相同。
 - 当前 `GetRxBuffer()` / `GetTxBuffer()` 在双缓冲关闭时返回构造时传入的 `rx_buffer_ / tx_buffer_`；双缓冲开启时返回当前 active 半区。
 - `SwitchBuffer()` 只在 `double_buffer == true` 时切换内部 `DoubleBuffer` 状态；否则不做任何操作。
 - `SetActiveLength()` / `GetActiveLength()` 当前只作用在发送侧 `double_buffer_tx_` 的辅助长度字段上，不表示一条独立的统一“传输长度元信息协议”。
diff --git a/docs/basic_coding/driver/uart.md b/docs/basic_coding/driver/uart.md
@@ -60,7 +60,7 @@ ErrorCode Read(RawData data, OperationType&& op, bool in_isr = false);
 - `OperationType` 需要是 `WriteOperation` / `ReadOperation`（或其派生/等价类型）。
 - `in_isr` 指示是否在中断上下文中调用（会透传到端口的 `operator()`）。
 
-## 当前接口边界
+## 说明
 
 - `UART::Parity` 当前只有 `NO_PARITY / EVEN / ODD` 三种取值；源码里仍保留 `Mark / Space` 的 TODO 注释，因此文档不应把这些模式写成已存在的通用接口能力。
 - `stop_bits` 当前只是一个原始 `uint8_t` 配置字段；基类接口本身没有再定义 `0.5 / 1.5` 这类统一枚举或跨平台保证。
diff --git a/docs/basic_coding/structure/README.md b/docs/basic_coding/structure/README.md
@@ -20,7 +20,6 @@ sidebar_position: 2
 - [Queue（普通 FIFO 队列）](./queue.md)
 - [SPSCQueue（单生产者单消费者无锁队列）](./spsc_queue.md)
 - [MPMCQueue（多生产者多消费者有界队列）](./mpmc_queue.md)
-- [LockFreeQueue（历史兼容说明）](./lockfree_queue.md)
 - [Stack（栈）](./stack.md)
 - [List（链表）](./list.md)
 - [LockFreeList（无锁链表）](./lockfree_list.md)
diff --git a/docs/basic_coding/structure/lockfree_pool.md b/docs/basic_coding/structure/lockfree_pool.md
@@ -52,7 +52,7 @@ sidebar_position: 8
 > - `ErrorCode::FULL`：无可写槽
 > - `ErrorCode::EMPTY`：无可读槽
 
-## 当前接口边界
+## 说明
 
 - 当前 `Put(const Data&, uint32_t& start_index)` / `Get(Data&, uint32_t& start_index)` 都只从给定起始槽位向后线性扫描；若想重新从头找，需要调用方自己把 `start_index` 重新置回 `0`。
 - `RecycleSlot(index)` 当前只在槽状态为 `READY` 时成功；如果槽位已经被 `Get*()` 取走并进入 `RECYCLE`，再次调用 `RecycleSlot()` 不会成功。
diff --git a/docs/basic_coding/structure/lockfree_queue.md b/docs/basic_coding/structure/lockfree_queue.md
diff --git a/docs/concept.md b/docs/concept.md
@@ -6,7 +6,7 @@ sidebar_position: 2
 
 # 设计思想
 
-这一页不讲 API 清单，而是说明 `LibXR` 在几个核心问题上的设计取向：数据流怎样组织、回调和中断该承担什么职责、I/O 完成行为怎样表达、平台边界怎样划分。很多接口看起来有些克制，由此而来。
+本页说明 `LibXR` 在几个核心问题上的设计取向：数据流怎样组织、回调和中断该承担什么职责、I/O 完成行为怎样表达、平台边界怎样划分。很多接口看起来有些克制，由此而来。
 
 ## `无锁数据结构与 ISR 驱动的数据流`
 
diff --git a/docs/env_setup/ch32.md b/docs/env_setup/ch32.md
@@ -8,7 +8,7 @@ sidebar_position: 2
 
 当前默认使用 WCH 提供的 GCC15 工具链，编译器前缀为 `riscv32-wch-elf-`。
 
-模板工程也已经按这条线配置。如果只是想快速编译，也可以直接使用 `docker-image-ch32-riscv`，当前镜像里已经是 `WCH GCC15 v240`。
+模板工程已按此配置。如果只是想快速编译，也可以直接使用 `docker-image-ch32-riscv`，当前镜像里已经是 `WCH GCC15 v240`。
 
 ## CMake 配置
 
diff --git a/docs/env_setup/esp32.md b/docs/env_setup/esp32.md
@@ -6,7 +6,7 @@ sidebar_position: 3
 
 # ESP32 环境配置
 
-ESP32 这条线直接使用官方 `ESP-IDF` 工作流。
+ESP32 使用官方 `ESP-IDF` 工作流。
 
 官方入口：
 
@@ -41,7 +41,3 @@ include(path_to_libxr/cmake/esp32.cmake)
 ## 当前环境信息
 
 当前 `docker-image-esp32` 里预装的是 `ESP-IDF v5.4.1`。如果你本地使用的是更新的 `5.x` 稳定版本，整体接入方式仍然成立，但实际组件拆分和目录结构仍然以你当前安装的官方 IDF 为准。
-
-## 说明
-
-ESP32 这条线按官方 `ESP-IDF + CMake + idf.py` 方式接，不再单独维护一套旁路环境说明。
diff --git a/docs/env_setup/hpm.md b/docs/env_setup/hpm.md
@@ -6,7 +6,7 @@ sidebar_position: 5
 
 # HPM 环境配置
 
-这一页只说明 **当前 LibXR 主线在 HPM 平台上的接入边界**，不展开先楫 SDK 的完整 GUI 建工程流程。
+本页说明 LibXR 在 HPM 平台上的接入方式，不包括如何用先楫 SDK 的 GUI 工具建立工程。
 
 如果你要快速起步，优先参考模板工程：
 
@@ -25,7 +25,7 @@ sidebar_position: 5
 
 ## 基本集成思路
 
-HPM 这条线仍然是普通 LibXR 外部工程接入方式：
+HPM 的接入方式与其他平台相同，是普通 LibXR 外部工程接入：
 
 ```cmake
 set(LIBXR_SYSTEM None)
@@ -50,40 +50,27 @@ LibXR 不代替 HPM SDK 的项目骨架，它是在 HPM 工程已经成立之后
 2. 再检查工程里是否已经能正常 `add_subdirectory(libxr)`。
 3. 最后再按需要接入具体外设类，例如 `HPMGPIO`、`HPMI2C`、`HPMPWM`、`HPMTimebase`。
 
-## 关于 `I2C` 的当前边界
+## 当前 I2C 支持情况
 
-HPM `I2C` 这一条现在已经不是简单 blocking-only 包装。按当前主线头文件，`HPMI2C` 还覆盖了：
+`HPMI2C` 已不是简单的 blocking-only 包装，当前主线还覆盖了：
 
 - 7-bit / 10-bit 主机寻址模式；
 - sequence frame；
 - transfer flags；
 - 可选 DMA helper 背景路径；
 - 等待策略与恢复路径。
 
-但这类能力是否在你的具体工程上可直接用，仍取决于：
+上述能力是否在你的工程里可直接用，取决于：
 
 - HPM SDK 头文件是否完整；
 - 是否存在对应 DMA / interrupt helper；
 - 目标板级时钟、引脚和总线恢复路径是否已验证。
 
-所以这页只把它定义成“主线代码已存在的能力边界”，不把它直接写成“所有 HPM 项目默认可用并已充分验证”。
-
-## 关于 `PWM` 的当前边界
+## 当前 PWM 支持情况
 
 `HPMPWM` 当前主线支持两类路径：
 
 - 如果目标 SoC 提供标准 PWM 外设，则走 `hpm_pwm_drv`；
 - 如果不满足该条件，代码里还有 `GPTMR` fallback 路径。
 
-这意味着文档里不能简单写成“只有某一种固定 PWM 方案”。具体走哪条线，要看你的芯片和 SDK 宏条件。
-
-## 这页不做什么
-
-这页不打算替代这些内容：
-
-- HPM SDK 本身的安装和环境变量教程；
-- 图形化建工程步骤；
-- 板级时钟/引脚向导截图；
-- 先楫 IDE 或 GUI 工具的完整操作手册。
-
-如果这些步骤已经和 LibXR 接入强相关，并且后面在模板仓库里形成了稳定做法，再单独补到模板或项目文档里更合适。
+具体走哪条，取决于芯片和 SDK 宏条件。
diff --git a/docs/perf/perf-topic.md b/docs/perf/perf-topic.md
@@ -6,7 +6,7 @@ sidebar_position: 3
 
 # 消息系统性能测试
 
-这一页的作用是给出消息系统性能基准的入口，而不是脱离测试条件直接下结论。
+本页汇总消息系统性能基准的参考资料。
 
 当前可公开参考的基准仓库在这里：
 
@@ -17,11 +17,3 @@ sidebar_position: 3
 - 测试是在什么系统和调度条件下跑的；
 - 测的是进程内 `Topic`、Linux 共享内存路径，还是别的链路；
 - payload 大小、订阅方式、发布频率和统计口径分别是什么。
-
-如果你只想知道当前主线有哪些相关能力，先回到：
-
-- [Topic](../basic_coding/middleware/message/topic.md)
-- [共享内存 Topic（Linux）](../basic_coding/middleware/message/linux-shared-topic.md)
-- [Memory FastCopy / FastSet / FastCmp](../basic_coding/core/core-mem.md)
-
-如果你要写新的性能结论，建议直接附上对应代码、输入规模和统计方法，不要只引用一句“亚微秒”或“快于 `std::memcpy`”这样的脱上下文描述。
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/README.md b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/README.md
@@ -20,7 +20,6 @@ This module summarizes the general-purpose data structures used in LibXR for tas
 - [Queue (ordinary FIFO)](./queue.md)
 - [SPSCQueue](./spsc_queue.md)
 - [MPMCQueue](./mpmc_queue.md)
-- [LockFreeQueue (historical compatibility note)](./lockfree_queue.md)
 - [Stack](./stack.md)
 - [List](./list.md)
 - [LockFreeList](./lockfree_list.md)
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/lockfree_queue.md b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/lockfree_queue.md
