From 4244dc16d1705c674468465e61ffbde72284a06b Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Wed, 7 Oct 2026 23:56:31 +0100 Subject: [PATCH 01/16] Document the MSPM0 and HPM code generation, the pin layout and the refreshed platform environment pages --- docs/code_gen/README.md | 7 +- docs/code_gen/hpm/README.md | 260 ++++++++++++++ docs/code_gen/mspm0/README.md | 324 ++++++++++++++++++ docs/code_gen/pins.md | 124 +++++++ docs/code_gen/xrobot_inter.md | 2 +- docs/env_setup/README.md | 6 +- docs/env_setup/hpm.md | 134 +++----- docs/env_setup/mspm0.md | 177 +++------- .../current/code_gen/README.md | 7 +- .../current/code_gen/hpm/README.md | 260 ++++++++++++++ .../current/code_gen/mspm0/README.md | 324 ++++++++++++++++++ .../current/code_gen/pins.md | 124 +++++++ .../current/code_gen/xrobot_inter.md | 2 +- .../current/env_setup/README.md | 6 +- .../current/env_setup/hpm.md | 138 +++----- .../current/env_setup/mspm0.md | 183 +++------- 16 files changed, 1640 insertions(+), 438 deletions(-) create mode 100644 docs/code_gen/hpm/README.md create mode 100644 docs/code_gen/mspm0/README.md create mode 100644 docs/code_gen/pins.md create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/code_gen/pins.md diff --git a/docs/code_gen/README.md b/docs/code_gen/README.md index 4c33c68..ad829be 100644 --- a/docs/code_gen/README.md +++ b/docs/code_gen/README.md @@ -6,11 +6,14 @@ sidebar_position: 5 # 代码生成(CodeGenerator) -CodeGenerator(pip 包 `libxr`,安装见[环境配置](../env_setup/README.md))根据 SDK 或工程描述文件生成 LibXR 的初始化代码,例如由 STM32CubeMX 的 `.ioc` 文件生成 C++ 外设对象和 `libxr_config.yaml`。本章说明代码生成器读取的工程输入、`libxr_config.yaml` 中各外设的设置和约束,以及生成的代码如何接入工程;运行期 API 见[基础编程(LibXR)](../basic_coding/README.md)。 +CodeGenerator(pip 包 `libxr`,安装见[环境配置](../env_setup/README.md))根据 SDK 或工程描述文件生成 LibXR 的初始化代码:由 STM32CubeMX 的 `.ioc` 文件、TI SysConfig 的 `.syscfg` 文件或 HPM Pinmux Tool 的工程生成 C++ 外设对象和 `libxr_config.yaml`。本章说明代码生成器读取的工程输入、`libxr_config.yaml` 中各外设的设置和约束,以及生成的代码如何接入工程;运行期 API 见[基础编程(LibXR)](../basic_coding/README.md)。 ## 章节 - [STM32 代码生成](./stm32/README.md) +- [MSPM0 代码生成](./mspm0/README.md) +- [HPM 代码生成](./hpm/README.md) +- [引脚布局(libxr pins)](./pins.md) - [与 XRobot 集成](./xrobot_inter.md) -STM32 部分包括 GPIO、UART、SPI、I2C、ADC、DAC、CAN、PWM、Flash、Cache、Watchdog、Timebase 和软件定时器的生成说明。 +STM32 部分包括 GPIO、UART、SPI、I2C、ADC、DAC、CAN、PWM、Flash、Cache、Watchdog、Timebase 和软件定时器的生成说明;MSPM0 和 HPM 部分说明各自的接入流程、生成的对象和 `libxr_config.yaml` 设置。 diff --git a/docs/code_gen/hpm/README.md b/docs/code_gen/hpm/README.md new file mode 100644 index 0000000..c3550e8 --- /dev/null +++ b/docs/code_gen/hpm/README.md @@ -0,0 +1,260 @@ +--- +id: code-gen-hpm +title: HPM 代码生成 +sidebar_position: 3 +--- + +# HPM 代码生成 + +代码生成器的 `libxr hpm setup` 命令把 HPM Pinmux Tool 工程接入 LibXR:解析工程,生成 C++ 初始化代码。引脚复用和时钟由 Pinmux Tool 的输出配置(工程根目录 `main.c` 调用生成的 pinmux 函数),`main.c` 由 BSP 维护,生成的代码是 `User/` 下的 `app_main`,构造参数全部使用 HPM SDK 的宏。 + +--- + +## 工程识别 + +工程是根目录有 `app.yaml`、`boards//` 下恰有一个 `.hpmpc` 文件的目录。选中的信号来自 `.hpmpc` 的 `selectPins`,以及 `main.c` 中 `main` 在预处理条件之外调用的 pinmux 函数;`.hpmpc` 中有而 `main` 没有调用的函数不参与。函数里的每个信号按 `hpm_iomux.h` 的宏名对照 SoC 封装的布局核对,封装没有的 pad 或 pad 不能承载的信号给出警告。 + +`main` 只在预处理条件里调用的 pinmux 函数同样不读(生成的对象不能依赖编译选项),每个这样的函数给出一条警告;调用全部在预处理条件里时读不到引脚。`main` 一次 pinmux 函数都没有调用时退回读 `init_bsp_pins`,工程没有这个函数时读不到引脚。 + +--- + +## 快速使用 + +在工程根目录下执行: + +```bash +libxr hpm setup -d . +``` + +该命令依次完成以下步骤: + +1. 工程目录还没有 `.gitignore` 时创建一个,忽略 `build`、`.history`、`.cache`、`CMakeFiles` 和 `.config.yaml`;已有的 `.gitignore` 保持不变; +2. 解析工程,写出 `.config.yaml`; +3. 在 `User/` 下生成 `app_main.cpp`、`app_main.h` 和 `libxr_config.yaml`。 + +`--xrobot` 和 `--no-xrobot` 都不写时,沿用输出文件现在的选择,新文件不使用 XRobot;使用 XRobot 时生成 `XR_REGISTER` 注册和 `XROBOT_MAIN();`,命令结束前提示运行 `xrobot gen` 更新 `User/xrobot_main.hpp`。已有的 `app_main.cpp` 不是 `libxr gen` 生成时,setup 给出警告并列出将被替换的行,User Code 区域之外的内容全部重新生成。 + +--- + +## 示例输出 + +以下是 bsp-hpm5301evklite 上的一次运行,工程已是最新: + +```text +[信息] .\User\app_main.cpp 使用了 XRobot,继续按 --xrobot 生成(--no-xrobot 可关闭)。 +[信息] 配置已导出到:.\.config.yaml +[信息] 系统:裸机 +[信息] 已生成 User:未变化 app_main.cpp、app_main.h、libxr_config.yaml +[信息] 下一步:运行 `xrobot gen` 更新 User/xrobot_main.hpp;libxr 的 setup 不更新它 + +===== [配置摘要] ===== + +SoC:HPM5301(QFN48) + +GPIO(2 个引脚): + pa10: PA10 + pa3: PA03 + +已启用的外设: + I2C:1 个实例 + I2C3 + PWM:1 个实例 + GPTMR0 + Other:7 个实例 + UART0 + UART3 + SPI1 + ADC0 + ACMP + USBPHY + USB0 +``` + +生成器只写内容有变化的文件;上例中工程已是最新,三个文件都没有改写。配置摘要中的 Other 是 LibXR 还没有驱动的配置,见[生成的对象与命名](#生成的对象与命名)。 + +--- + +## 输出结构 + +执行完成后,工程新增或修改这些文件: + +```txt +. +├── .config.yaml # 解析生成的配置文件 +├── app.yaml # HPM SDK 工程描述(BSP 提供) +├── main.c # BSP 提供:init_bsp_pins() 等之后调用 app_main() +├── boards// +│ └── tool_config.hpmpc # Pinmux Tool 工程(BSP 提供) +├── User/ +│ ├── app_main.cpp # 入口源文件 +│ ├── app_main.h # 入口源文件的头文件 +│ └── libxr_config.yaml # LibXR 配置文件 +└── libxr/ # Git 子模块:LibXR 本体 +``` + +--- + +## app_main.cpp + +`app_main.cpp` 包含 LibXR 初始化函数 `app_main()`。`/* User Code Begin N */` 与 `/* User Code End N */` 之间的代码在重新生成时保留,其余部分每次重新生成。生成的外设对象都是 `static` 对象,`app_main()` 返回后仍然有效;长期使用的局部对象声明为 `static`。外设对象可以以基类指针传给线程或模块使用,做法见[与XRobot集成](../xrobot_inter.md)。 + +下面是 bsp-hpm5301evklite 生成的 `app_main.cpp` 节选,省略处写作 `// ...`: + +```cpp +// Generated by `libxr gen`; do not edit by hand. +// Generated from boards/hpm5301evklite/tool_config.hpmpc (HPM5301); the Pinmux Tool +// configures the pins via init_bsp_pins() in main.c and main.c stays BSP-owned. Put +// application code between the "User Code Begin" and "User Code End" markers. +#include "app_main.h" + +#include "libxr.hpp" +#include "hpm_gpio.hpp" +#include "hpm_i2c.hpp" +#include "hpm_pwm.hpp" +#include "hpm_soc.h" +#include "hpm_timebase.hpp" +#include "xrobot_main.hpp" + +using namespace LibXR; + +/* User Code Begin 1 */ +// KEY interrupt counter, incremented in the GPIO interrupt callback. +static std::atomic key_irq_count{0}; +/* User Code End 1 */ + +extern "C" void app_main(void) +{ + /* User Code Begin 2 */ + /* User Code End 2 */ + + // Timebase and platform + static HPMTimebase timebase; + PlatformInit(); + + // GPIO: init_bsp_pins() configured pa10 (PA10) as an output pin, pa3 (PA03) as an input + // pin with a pull-down. The interrupt edge comes from the pinmux and every object + // carries its port IRQ; RegisterCallback and EnableInterrupt belong to the consumer (a + // Module or the User Code). + static HPMGPIO pa10(HPM_GPIO0, GPIO_DI_GPIOA, 10, IRQn_GPIO0_A); + static HPMGPIO pa3(HPM_GPIO0, GPIO_DI_GPIOA, 3, IRQn_GPIO0_A); + + // I2C: blocking transfers; the DMA-backed background path runs on dma_mgr. + static HPMI2C i2c3(HPM_I2C3, clock_i2c3, {100000U}); + + // PWM on a GPTMR comparator: the SoC has no PWM peripheral, so HPMPWM takes its GPTMR + // fallback path; the duty comparator is fixed at 0 and SetConfig is called when + // libxr_config sets a frequency. + static HPMPWM pwm_gptmr0_ch1(reinterpret_cast(HPM_GPTMR0), + clock_gptmr0, 1, 0, HPMPWM::Polarity::NORMAL); + + // Hardware registration + XR_REGISTER(pa10, LibXR::GPIO); + XR_REGISTER(pa3, LibXR::GPIO); + + XR_REGISTER(pwm_gptmr0_ch1, LibXR::PWM); + + XR_REGISTER(i2c3, LibXR::I2C); + + /* User Code Begin 3 */ + /* User Code End 3 */ + XROBOT_MAIN(); +} +``` + +引脚和时钟在 `main.c` 调用的 pinmux 函数中配置完毕,构造参数引用 SDK 的宏(`HPM_GPIO0`、`GPIO_DI_GPIOA`、`IRQn_GPIO0_A`、`HPM_I2C3`、`clock_i2c3`)。GPIO 对象带所属端口的 IRQ,端口的中断服务程序由 LibXR 驱动提供,边沿来自 pinmux,回调的登记(`RegisterCallback` 和 `EnableInterrupt`)由使用方完成。I2C 使用 dma_mgr 的后台路径时需要工程启用 `CONFIG_DMA_MGR`。 + +--- + +## 生成的对象与命名 + +生成的对象来自 LibXR 有驱动的配置:GPIO 引脚各生成一个对象,I2C 生成一个对象;GPTMR 上的 PWM 见下文。其余配置(UART、SPI、MCAN、ADC、ACMP、USB 等)列入配置摘要的 Other,只作展示。 + +对象的命名: + +| 配置 | 对象名 | 例子 | +| --- | --- | --- | +| GPIO | 引脚名(端口字母小写加线号),`GPIO:` 段可改名 | `pa10`、`pb11` | +| I2C | 外设实例名的小写 | `i2c3` | +| GPTMR 上的 PWM | `pwm_<实例小写>_ch<比较器号>` | `pwm_gptmr0_ch1` | + +GPTMR 的每个比较器(COMP_n)生成一个 PWM 对象,走 `HPMPWM` 的 GPTMR 路径;对象只在 SoC 没有 PWM 外设时生成,判定依据是芯片的引脚数据里有没有 PWM 外设的信号:HPM5301 没有,HPM5361 有 20 个,后者的 GPTMR 列入 Other 只作展示。占空比较器固定,极性固定为 `NORMAL`;对象和注册无条件生成,包在预处理条件里会使 XRobot 的生成器拒绝该文件。 + +--- + +## libxr_config.yaml + +`User/libxr_config.yaml` 保存代码生成的设置。文件不存在时按默认值新建;之后每次生成补上缺少的设置,已有的值保持不变。`.hpmpc` 只记录引脚,速率和频率以这里的设置为准。 + +| 段 | 键与默认值 | 说明 | +| --- | --- | --- | +| `I2C` | `speed: 100000` | 总线速率,单位 Hz,段中每个实例一项,键为小写的实例名 | +| `PWM` | `frequency`(默认 null) | 每个对象一项;null 时不调用 `SetConfig`,设置了必须是正整数(Hz) | +| `GPIO` | 键为引脚名,值为新名字 | 引脚改名;值为 null 时保留默认名。段中列出工程读到的每个引脚 | + +HPM 的生成器目前创建的串口对象还没有进入 libxr,`terminal_source` 没有可指向的终端;设置了它会得到警告。 + +以下是 bsp-hpm5301evklite 首次生成的 `User/libxr_config.yaml`: + +```yaml +generator: 6.0.0 +I2C: + i2c3: + speed: 100000 +PWM: + pwm_gptmr0_ch1: + frequency: +GPIO: + pa10: + pa3: +``` + +把 `GPIO` 段中 `pa10` 的值改为 `LED` 后重新生成,对象即为 `static HPMGPIO LED(HPM_GPIO0, GPIO_DI_GPIOA, 10, IRQn_GPIO0_A);`,注册同步更新。 + +--- + +## 支持的 SoC 与封装 + +当前数据覆盖 HPM5301(QFN48)和 HPM5361(LQFP100、LQFP64、QFN48);HPM53M1 暂不支持。引脚数据来自 HPM SDK 的 `hpm_iomux.h` 和 HPM5300 数据手册的引脚表。 + +--- + +## 重新生成代码 + +修改 `.hpmpc`、`main.c` 或 `User/libxr_config.yaml` 后,在工程根目录重新运行 `libxr hpm setup -d .`,或只重新生成 `User/` 下的文件: + +```bash +libxr parse -d . +libxr gen -i .config.yaml -o User/app_main.cpp +``` + +`.config.yaml` 由 `libxr parse` 写出,新克隆的工程里没有这个文件,先运行 `libxr parse`。VS Code 扩展的 Generate LibXR Code 动作依次运行这两条命令,见 [VS Code 扩展](../../env_setup/README.md#vs-code-扩展)。 + +--- + +## 可选参数 + +`libxr hpm setup` 的参数如下,`libxr hpm setup --help` 同样列出这些参数。 + +| 参数 | 说明 | +| ---------- | --------------------------- | +| `-d`, `--directory` | 工程目录:根目录有 `app.yaml`,`boards/` 下有一个 `.hpmpc`(默认:当前目录) | +| `-o`, `--output` | 输出的 C++ 文件(默认:DIRECTORY 下的 `User/app_main.cpp`) | +| `--xrobot` / `--no-xrobot` | 生成或不生成 `XR_REGISTER` 注册与 `XROBOT_MAIN();`,见 [与XRobot集成](../xrobot_inter.md);都不写时沿用输出文件现在的选择,新文件不使用 XRobot | +| `--libxr-config` | libxr_config.yaml 的路径或 URL(默认:输出文件旁边的 `libxr_config.yaml`) | +| `--verbose` | 输出调试日志 | + +--- + +## 相关命令 + +| 命令 | 功能说明 | +| ------------------------ | --------------------------------- | +| `libxr parse` | 解析工程,写出 `.config.yaml` | +| `libxr gen` | 由 `.config.yaml` 生成入口源文件和 `app_main.h`,并更新 `libxr_config.yaml` | +| `libxr pins` | 打印 SoC 的封装与引脚布局,见[引脚布局](../pins.md) | + +各命令的全部参数及默认值由 `libxr <命令> --help` 列出。 + +## 参考 + +* [LibXR 命令行工具以及文档](https://pypi.org/project/libxr/) diff --git a/docs/code_gen/mspm0/README.md b/docs/code_gen/mspm0/README.md new file mode 100644 index 0000000..749b5e2 --- /dev/null +++ b/docs/code_gen/mspm0/README.md @@ -0,0 +1,324 @@ +--- +id: code-gen-mspm0 +title: MSPM0 代码生成 +sidebar_position: 2 +--- + +# MSPM0 代码生成 + +代码生成器的 `libxr mspm0 setup` 命令把 TI SysConfig 工程接入 LibXR:解析工程根目录的 `.syscfg` 文件,生成 C++ 初始化代码。SysConfig 负责时钟、引脚、DMA 通道和外设的配置(`main.c` 中的 `SYSCFG_DL_init()`),生成的代码声明 LibXR 对象并把对象注册到 XRobot,构造参数全部使用 SysConfig 生成的宏。 + +--- + +## 快速使用 + +在 SysConfig 工程根目录下执行: + +```bash +libxr mspm0 setup -d . +``` + +工程根目录放置一个 `.syscfg` 文件。该命令依次完成以下步骤: + +1. 工程目录还没有 `.gitignore` 时创建一个,忽略 `build`、`.history`、`.cache`、`CMakeFiles` 和 `.config.yaml`;已有的 `.gitignore` 保持不变; +2. 解析 `.syscfg`,写出 `.config.yaml`; +3. 在 `User/` 下生成 `app_main.cpp`、`app_main.h` 和 `libxr_config.yaml`。 + +`--xrobot` 和 `--no-xrobot` 都不写时,沿用输出文件现在的选择,新文件不使用 XRobot;使用 XRobot 时生成 `XR_REGISTER` 注册和 `XROBOT_MAIN();`,命令结束前提示运行 `xrobot gen` 更新 `User/xrobot_main.hpp`。已有的 `app_main.cpp` 不是 `libxr gen` 生成时,setup 给出警告并列出将被替换的行,User Code 区域之外的内容全部重新生成。 + +--- + +## SysConfig 输出的来源 + +解析读取两个来源:`.syscfg` 本身(外设实例、参数和引脚分配),以及 SysConfig 生成的 `ti_msp_dl_config.h/.c`(实际写出的宏名、`CPUCLK_FREQ`、ULPCLK 分频和各实例的时钟配置)。 + +设置了环境变量 `SYSCONFIG_TOOL` 和 `MSPM0_SDK_INSTALL_DIR` 时,解析对 `.syscfg` 运行一次 SysConfig,输出写入临时目录;这两个变量与 BSP 的 `cmake/MSPM0SysConfig.cmake` 使用的是同一组。没有设置这两个变量时,解析复用工程 `build*`、`cmake-build*` 或 `out` 目录下比 `.syscfg` 新的生成输出。复用只比较修改时间:`.syscfg` 被替换为修改时间更旧的文件时仍会复用旧输出,此时重新构建一次,或设置这两个变量后再运行。 + +BSP 的 CMake 在 configure 阶段对 `.syscfg` 运行 SysConfig,输出在构建目录的 `syscfg/` 下,`.syscfg` 改动后自动重新生成,见 [MSPM0 环境配置](../../env_setup/mspm0.md)。 + +--- + +## 示例输出 + +以下是 bsp-mspm0g3507-mini 上设置了两个环境变量后的一次运行,工程已是最新: + +```text +[信息] .\User\app_main.cpp 使用了 XRobot,继续按 --xrobot 生成(--no-xrobot 可关闭)。 +[信息] 正在处理 mspm0g3507_minidb48.syscfg…… +[信息] 正在对 mspm0g3507_minidb48.syscfg 运行 SysConfig +[信息] 配置已导出到:.\.config.yaml +[信息] 系统:裸机 +[信息] 已生成 User:未变化 app_main.cpp、app_main.h、libxr_config.yaml +[信息] 下一步:运行 `xrobot gen` 更新 User/xrobot_main.hpp;libxr 的 setup 不更新它 + +===== [配置摘要] ===== + +MCU:MSPM0 MSPM0G3507 + +GPIO(4 个引脚): + LED1:PB8,OUTPUT + LED2:PA16,OUTPUT + KEY1:PB24,INPUT,FALL 中断 + KEY2:PB20,INPUT,FALL 中断 + +已启用的外设: + UART:2 个实例 + UART_0 + UART_1 + I2C:2 个实例 + I2C_0 + I2C_1 + SPI:1 个实例 + SPI_1 + PWM:1 个实例 + PWM_TIMA1 + Other:5 个实例 + ADC12_0 + ADC12_1 + DAC0 + MCAN_0 + QEI_TIMG8 +``` + +生成器只写内容有变化的文件;上例中工程已是最新,三个文件都没有改写。配置摘要中的 Other 是 LibXR 还没有驱动的配置,见[生成的对象与命名](#生成的对象与命名)。 + +--- + +## 输出结构 + +执行完成后,工程新增或修改这些文件: + +```txt +. +├── .config.yaml # 解析生成的配置文件 +├── main.c # BSP 提供:SYSCFG_DL_init() 之后调用 app_main() +├── User/ +│ ├── app_main.cpp # 入口源文件 +│ ├── app_main.h # 入口源文件的头文件 +│ └── libxr_config.yaml # LibXR 配置文件 +└── libxr/ # Git 子模块:LibXR 本体 +``` + +--- + +## app_main.cpp + +`app_main.cpp` 包含 LibXR 初始化函数 `app_main()`。`/* User Code Begin N */` 与 `/* User Code End N */` 之间的代码在重新生成时保留,其余部分每次重新生成。生成的外设对象都是 `static` 对象,`app_main()` 返回后仍然有效;长期使用的局部对象声明为 `static`。外设对象可以以基类指针传给线程或模块使用,做法见[与XRobot集成](../xrobot_inter.md)。 + +下面是 bsp-mspm0g3507-mini 生成的 `app_main.cpp` 节选,省略处写作 `// ...`: + +```cpp +// Generated by `libxr gen`; do not edit by hand. +// Generated from mspm0g3507_minidb48.syscfg (MSPM0G3507); SysConfig configures the +// clocks, pins, DMA channels and peripherals (SYSCFG_DL_init() in main.c). Put +// application code between the "User Code Begin" and "User Code End" markers. +#include "app_main.h" + +#include "libxr.hpp" +#include "mspm0_gpio.hpp" +// ... + +using namespace LibXR; + +/* User Code Begin 1 */ +// KEY interrupt counters, incremented in the GPIO interrupt callbacks. +static std::atomic key1_irq_count{0}; +/* User Code End 1 */ + +// Input clocks: the BUSCLK of the power domain. PD0 from ULPCLK = CPUCLK_FREQ / 2 +// (DL_SYSCTL_setULPCLKDivider) and PD1 from MCLK (CPUCLK_FREQ). The I2C driver resets +// the clock configuration of its peripherals, so the BUSCLK of the domain is the right +// argument. +static constexpr uint32_t PD0_BUSCLK_FREQ = (CPUCLK_FREQ / 2); +static constexpr uint32_t PD1_BUSCLK_FREQ = CPUCLK_FREQ; + +// Ownership of the DMA channels that serve a UART transmitter; +// MSPM0_UART_MAIN_INIT checks these names against the ones SysConfig generated. +#define DMA_CH_UART0_TX_LIBXR_UART_IRQN UART_0_INST_INT_IRQN +#define DMA_CH_UART0_TX_LIBXR_UART_TX 1 + +// DMA buffers. A UART gets 2 x N bytes for its two transmit halves; the receive side +// runs on byte interrupts. The SPI DMA buffers are split in two halves as well; the +// I2C driver uses polling, its buffer is the staging area for DMA transfers. +alignas(size_t) static uint8_t uart0_tx_buf[2 * 128]; +// ... +alignas(4) static uint8_t i2c0_buf[32]; + +extern "C" void app_main(void) +{ + /* User Code Begin 2 */ + /* User Code End 2 */ + + // Timebase and platform + static MSPM0Timebase timebase; + PlatformInit(); + + // GPIO: SysConfig configured LED1 (PB8), LED2 (PA16) as output pins and KEY1 (PB24), + // KEY2 (PB20) as input pins. The interrupt edge comes from SysConfig; RegisterCallback + // and EnableInterrupt belong to the consumer (a Module or the User Code). + static MSPM0GPIO LED1(GPIO_LEDS_PIN_LED1_PORT, GPIO_LEDS_PIN_LED1_PIN, + GPIO_LEDS_PIN_LED1_IOMUX); + // ... + + // UART: TX with DMA; the receive side runs on byte interrupts. + static MSPM0UART uart0(MSPM0_UART_MAIN_INIT(UART_0, DMA_CH_UART0_TX, uart0_tx_buf, + sizeof(uart0_tx_buf), 5, 128)); + // ... + + // I2C: polling; the buffer stages DMA transfers. + static MSPM0I2C i2c0(MSPM0_I2C_INIT(I2C_0, PD0_BUSCLK_FREQ, i2c0_buf, sizeof(i2c0_buf), + 8), {I2C_0_BUS_SPEED_HZ}); + + // SPI: DMA for transfers longer than the threshold. + static MSPM0SPI spi1(MSPM0_SPI_INIT(SPI_1, PD1_BUSCLK_FREQ, DMA_CH_SPI1_RX, + DMA_CH_SPI1_TX, spi1_rx_buf, sizeof(spi1_rx_buf), spi1_tx_buf, + sizeof(spi1_tx_buf), 3)); + + // PWM: the channels of one timer share one period, which SysConfig configures. + static MSPM0PWM pwm_tima1_c0(MSPM0_PWM_CH(PWM_TIMA1, 0)); + static MSPM0PWM pwm_tima1_c1(MSPM0_PWM_CH(PWM_TIMA1, 1)); + + // Terminal on uart0 + STDIO::read_ = uart0.read_port_; + STDIO::write_ = uart0.write_port_; + static RamFS ramfs("XRobot"); + static Terminal<32, 32, 5, 5> terminal(ramfs); + /* User Code Begin 3 */ + KEY1.SetConfig({GPIO::Direction::FALL_INTERRUPT, GPIO::Pull::NONE}); + KEY1.RegisterCallback(GPIO::Callback::Create(OnKeyInterrupt, &key1_irq_count)); + KEY1.EnableInterrupt(); + /* User Code End 3 */ + XROBOT_MAIN(); +} +``` + +每个外设对象以 SysConfig 生成的宏构造,例如 GPIO 的 `GPIO_LEDS_PIN_LED1_PORT`、UART 的 `UART_0`。各对象的中断由 LibXR 驱动在构造时开启并设置优先级,SysConfig 中对同一中断的设置被驱动覆盖;引脚中断的边沿来自 SysConfig,回调的登记(`RegisterCallback` 和 `EnableInterrupt`)由使用方完成,模块或 User Code 中的做法见上例的 User Code 区域。 + +--- + +## 生成的对象与命名 + +生成的对象来自 LibXR 有驱动的配置:UART、控制器模式的 I2C 和 SPI、PWM;GPIO 引脚各生成一个对象。其余配置(ADC12、DAC12、MCAN、QEI、目标模式的 I2C、外设模式的 SPI 等)列入配置摘要的 Other,只作展示。 + +对象的命名: + +| 配置 | 对象名 | 例子 | +| --- | --- | --- | +| GPIO | SysConfig 中引脚的标签(`$name` 去掉 `PIN_` 前缀) | `LED1`、`KEY1` | +| UART、I2C、SPI | 外设实例名的小写 | `uart0`、`i2c1`、`spi1` | +| PWM | `pwm_<定时器>_c<通道号>` | `pwm_tima1_c0` | + +定时器的每个 CCP 通道生成一个 PWM 对象,同一 TIMER 的通道共用一个周期,周期由 SysConfig 配置。`libxr_config.yaml` 给同一定时器的通道设置了不同的频率时,生成器给出警告,以最后一次 `SetConfig` 为准。 + +各配置的生成要求: + +- UART 需要发送 DMA 通道,接收默认按字节中断(`MSPM0_UART_MAIN_INIT`)。UART Extend 实例配置了接收 DMA 时按循环 DMA 接收(`MSPM0_UART_EXTEND_INIT`,接收环的字节数见 `rx_dma_buffer_size`),接收通道须为 FULL-DMA 通道;UART Main 实例的接收 DMA 通道用不上,生成器给出警告。缺少发送 DMA 的 UART 使生成报错。 +- SPI 需要一对 DMA 通道,否则生成报错。 +- I2C 以轮询工作,缓冲区是 DMA 传输的中转。 + +--- + +## 时钟 + +生成的代码为用到的电源域定义 BUSCLK 常量:PD1 的 BUSCLK 是 `CPUCLK_FREQ`,PD0 的是 `CPUCLK_FREQ` 除以 ULPCLK 分频(生成代码里的 `DL_SYSCTL_setULPCLKDivider`,默认 1)。I2C 驱动自行重设所辖外设的时钟配置(BUSCLK、分频 1),构造实参取所在电源域的 BUSCLK;SPI 驱动沿用 SysConfig 写下的时钟配置,构造实参取 SysConfig 选择的时钟源(BUSCLK、MFCLK 的 4 MHz 或 LFCLK 的 32.768 kHz)除以分频,其他时钟源使生成报错。SysConfig 为 I2C 和 SPI 输出的宏不含时钟频率,工程缺少电源域或 `CPUCLK_FREQ` 时生成报错。UART 直接引用 SysConfig 的 `INST_FREQUENCY` 宏,PWM 的源时钟由驱动按 `INST_CLK_FREQ` 反推。 + +--- + +## libxr_config.yaml + +`User/libxr_config.yaml` 保存代码生成的设置。文件不存在时按默认值新建;之后每次生成补上缺少的设置,已有的值保持不变。外设的设置段只在工程有对应外设时写入,段中每个实例一项,键为小写的实例名,PWM 的键为对象名。值为 null(YAML 中只写了键)时取默认值;缓冲区和队列必须是正整数。 + +下表列出各设置段,默认值与 STM32 不同的单独说明: + +| 段 | 键与默认值 | 说明 | +| --- | --- | --- | +| `UART` | `tx_buffer_size: 128`、`rx_buffer_size: 128`、`tx_queue_size: 5` | UART Extend 实例另有 `rx_dma_buffer_size: 128`(偶数) | +| `I2C` | `buffer_size: 32`、`dma_enable_min_size: 8` | | +| `SPI` | `tx_buffer_size: 32`、`rx_buffer_size: 32`、`dma_enable_min_size: 3` | | +| `PWM` | `frequency`(默认 null) | null 时不调用 `SetConfig`,见[生成的对象与命名](#生成的对象与命名) | +| `Terminal` | `read_buff_size: 32`、`max_line_size: 32`、`max_arg_number: 5`、`max_history_number: 5` | 终端的模板参数,见[串口与终端](../stm32/uart.md) | + +`terminal_source` 遵循 STM32 的约定:空值或 `none` 不生成终端;文件里还没有这个键时(第一次生成)选第一个 UART。`tx_buffer_size` 的取值还须满足驱动的断言:发送缓冲为 2 × N 字节,2 × N 是 `2 * alignof(size_t)` 的倍数(Cortex-M0+ 上即 N 为 4 的倍数),且 N 不超过单次 DMA 传输的 0xFFFF 字节。设置键不区分大小写,文件中已有的写法保持不变。 + +以下是 bsp-mspm0g3507-mini 首次生成的 `User/libxr_config.yaml`: + +```yaml +generator: 6.0.0 +terminal_source: uart0 +SPI: + spi1: + tx_buffer_size: 32 + rx_buffer_size: 32 + dma_enable_min_size: 3 +I2C: + i2c0: + buffer_size: 32 + dma_enable_min_size: 8 + i2c1: + buffer_size: 32 + dma_enable_min_size: 8 +Terminal: + read_buff_size: 32 + max_line_size: 32 + max_arg_number: 5 + max_history_number: 5 +UART: + uart0: + tx_buffer_size: 128 + rx_buffer_size: 128 + tx_queue_size: 5 + uart1: + tx_buffer_size: 128 + rx_buffer_size: 128 + tx_queue_size: 5 +PWM: + pwm_tima1_c0: + frequency: + pwm_tima1_c1: + frequency: +``` + +I2C 的总线速率和 UART 的波特率来自 SysConfig 工程(如 `I2C_0_BUS_SPEED_HZ`),`libxr_config.yaml` 中没有对应的设置。 + +--- + +## 重新生成代码 + +修改 `.syscfg` 或 `User/libxr_config.yaml` 后,在工程根目录重新运行 `libxr mspm0 setup -d .`,或只重新生成 `User/` 下的文件: + +```bash +libxr parse -d . +libxr gen -i .config.yaml -o User/app_main.cpp +``` + +`.config.yaml` 由 `libxr parse` 写出,新克隆的工程里没有这个文件,先运行 `libxr parse`。VS Code 扩展的 Generate LibXR Code 动作依次运行这两条命令,见 [VS Code 扩展](../../env_setup/README.md#vs-code-扩展)。 + +--- + +## 可选参数 + +`libxr mspm0 setup` 的参数如下,`libxr mspm0 setup --help` 同样列出这些参数。 + +| 参数 | 说明 | +| ---------- | --------------------------- | +| `-d`, `--directory` | 工程目录:根目录下有一个 `.syscfg` 文件(默认:当前目录) | +| `-o`, `--output` | 输出的 C++ 文件(默认:DIRECTORY 下的 `User/app_main.cpp`) | +| `--xrobot` / `--no-xrobot` | 生成或不生成 `XR_REGISTER` 注册与 `XROBOT_MAIN();`,见 [与XRobot集成](../xrobot_inter.md);都不写时沿用输出文件现在的选择,新文件不使用 XRobot | +| `--libxr-config` | libxr_config.yaml 的路径或 URL(默认:输出文件旁边的 `libxr_config.yaml`) | +| `--verbose` | 输出调试日志 | + +--- + +## 相关命令 + +| 命令 | 功能说明 | +| ------------------------ | --------------------------------- | +| `libxr parse` | 解析 `.syscfg`,写出 `.config.yaml` | +| `libxr gen` | 由 `.config.yaml` 生成入口源文件和 `app_main.h`,并更新 `libxr_config.yaml` | +| `libxr pins` | 打印型号的封装与引脚布局,见[引脚布局](../pins.md) | + +各命令的全部参数及默认值由 `libxr <命令> --help` 列出。 + +## 参考 + +* [LibXR 命令行工具以及文档](https://pypi.org/project/libxr/) diff --git a/docs/code_gen/pins.md b/docs/code_gen/pins.md new file mode 100644 index 0000000..f5e63a0 --- /dev/null +++ b/docs/code_gen/pins.md @@ -0,0 +1,124 @@ +--- +id: code-gen-pins +title: 引脚布局(libxr pins) +sidebar_position: 4 +--- + +# 引脚布局(libxr pins) + +`libxr pins` 打印一个型号的封装与引脚布局:每个引脚的位置、名称和可选的信号。数据来自各厂商的引脚数据:STM32 为 ST 的 STM32_open_pin_data,MSPM0 为 TI SysConfig 的器件数据,HPM 为 HPM SDK 的 `hpm_iomux.h` 和 HPM5300 数据手册的引脚表。 + +--- + +## 用法 + +```bash +libxr pins STM32H723VGT6 +libxr pins MSPM0G3507 --package LQFP-64 --format json +libxr pins MSPM0G3507SPMR +libxr pins HPM5301 +libxr pins -d path/to/project +``` + +型号作为位置参数给出。MSPM0 的封装优先取型号后缀中的封装代码(`MSPM0G3507SPMR` 的 `PM`),判断不了时用 `--package` 给出(`LQFP-64`、`PM` 等写法都可以);HPM 的型号即 SoC 名,封装有多个时用 `--package` 给出。 + +`-d` 给出工程目录时,打印的布局叠加工程已选的信号及其 `libxr_config.yaml` 设置。STM32 工程读 `.ioc` 文件,MSPM0 工程读根目录的 `.syscfg`(封装取自 SysConfig 工程),HPM 工程读 `boards/` 下的 `.hpmpc` 和 `main.c` 调用的 pinmux 函数(封装随解析结果给出)。设置从 `--libxr-config` 指定的文件读取,默认为工程中的 `User/libxr_config.yaml`。 + +--- + +## 输出 + +```bash +$ libxr pins MSPM0G3507 --package LQFP-64 +``` + +```yaml +model: MSPM0G3507 +platform: mspm0 +part: MSPM0G3507 +package: LQFP-64(PM) +pin_count: 64 +source: + vendor: Texas Instruments + dataset: SysConfig dist/deviceData + version: 1.28.1+4785 + license: TI limited license (TI devices only) +peripherals: + ADC0: + kind: ADC + signals: + '0': + - PA27 + '1': + - PA26 +# ... +``` + +`source` 记录数据的来源和版本;`peripherals` 按外设列出每个信号的可用引脚。 + +--- + +## 工程叠加 + +```bash +$ libxr pins -d . +``` + +叠加工程后,输出多了两层内容。`pins` 一节逐引脚列出工程选中的信号,GPIO 引脚带有厂商工程中的标签: + +```yaml + pins: + PB8: + signal: PB8 + peripheral: GPIOB + kind: GPIO + function: P8 + matched: true + label: LED1 +# ... +``` + +`peripherals` 一节按实例列出占用的引脚、厂商工程中该实例的参数,以及 `libxr_config.yaml` 中对应的设置项: + +```yaml + TIMA1: + kind: TIMA + pins: + CCP0: PA28 + CCP1: PA31 + sysconfig: + module: PWM + name: PWM_TIMA1 + params: {} + config: + - section: PWM + key: pwm_tima1_c0 + present: true + params: + frequency: null + - section: PWM + key: pwm_tima1_c1 + present: true + params: + frequency: null +# ... +``` + +`matched` 为 `false` 时,信号与该引脚可复用的信号不符,按原样列出。`config` 是该实例在 `libxr_config.yaml` 中的设置项列表:`present` 表示这一项是否已在文件中,`params` 是已写的设置;一个 PWM 实例的每个通道各占一项。HPM 工程的 GPIO 改名是 `GPIO` 段下的整段映射,`section: GPIO` 的项没有 `key`,`params` 为引脚名到新名字的映射。 + +--- + +## 参数 + +| 参数 | 说明 | +| ---------- | --------------------------- | +| `model` | 型号(默认:`-d` 给出的工程的型号) | +| `-d`, `--directory` | 工程目录:叠加它已选的信号和设置 | +| `-c`, `--libxr-config` | 读取设置的 libxr_config.yaml(默认:工程中的 `User/libxr_config.yaml`) | +| `-p`, `--package` | 封装,型号名不包含封装时给出(MSPM0:`LQFP-64`、`PM` 等);MSPM0 工程随 `-d` 从 SysConfig 工程取 | +| `-f`, `--format` | 输出格式:`yaml`(默认)或 `json` | +| `--verbose` | 输出调试日志 | + +## 参考 + +* [LibXR 命令行工具以及文档](https://pypi.org/project/libxr/) diff --git a/docs/code_gen/xrobot_inter.md b/docs/code_gen/xrobot_inter.md index 9335e4f..2693c54 100644 --- a/docs/code_gen/xrobot_inter.md +++ b/docs/code_gen/xrobot_inter.md @@ -1,7 +1,7 @@ --- id: code-gen-xrobot-inter title: 与XRobot集成 -sidebar_position: 2 +sidebar_position: 5 --- # 与XRobot集成 diff --git a/docs/env_setup/README.md b/docs/env_setup/README.md index b238a11..ac99525 100644 --- a/docs/env_setup/README.md +++ b/docs/env_setup/README.md @@ -75,9 +75,11 @@ BSP 使用的 xrobot 版本记录在 `Modules/modules.yaml` 的 `xrobot:` 字段 ### VS Code 扩展 -VS Code 扩展 [`XRobot.xrobot`](https://marketplace.visualstudio.com/items?itemName=XRobot.xrobot) 在活动栏中提供 XRobot 和 LibXR 两个视图。打开包含 `Modules/modules.yaml` 的 BSP 时,XRobot 视图显示其中的模块、配置和实例,修改通过 `xrobot` 命令完成;打开根目录有 `.ioc` 文件的 STM32CubeMX 工程时,LibXR 视图显示 `User/libxr_config.yaml` 和内部 Flash 布局,并运行 `libxr` 命令。 +VS Code 扩展 [`XRobot.xrobot`](https://marketplace.visualstudio.com/items?itemName=XRobot.xrobot) 在活动栏中提供 XRobot 和 LibXR 两个视图。打开包含 `Modules/modules.yaml` 的 BSP 时,XRobot 视图显示其中的模块、配置和实例,修改通过 `xrobot` 命令完成。 -扩展 2.0.0 要求 VS Code 1.108 及以上版本。XRobot 视图需要 xrobot 1.0.0 和 `git`,LibXR 视图需要 libxr 6.0.0,两者按上一节安装。扩展在 `PATH`、pip 的用户脚本目录和设置项 `xrobot.cli.extraPath` 中查找这些命令;命令装在虚拟环境中时,把虚拟环境中 `bin` 目录(Windows 上为 `Scripts` 目录)的完整路径写入 `xrobot.cli.extraPath`。 +LibXR 视图按工程根目录识别平台:根目录有 `.ioc` 的是 STM32CubeMX 工程,`app.yaml` 加 `boards/*/*.hpmpc` 的是 HPM 工程,SysConfig 的 `.syscfg` 是 MSPM0 工程。视图显示平台和 `User/libxr_config.yaml` 中的各项设置,设置可以直接修改,修改后重新生成代码;"Generate LibXR Code" 运行 `libxr parse` 和 `libxr gen`,还没有 `libxr_config.yaml` 时则是对应平台的 `libxr stm32 setup`、`libxr mspm0 setup` 或 `libxr hpm setup`。MSPM0 工程的 "Open in SysConfig" 用独立版 SysConfig 打开 `.syscfg`,HPM 工程的 "Open in HPM Pinmux Tool" 用 HPMicro 的 HPM Pinmux Tool 扩展打开 `.hpmpc`。两个视图都能打开芯片的封装图(引脚布局,`libxr pins`,需要带有该命令的 libxr):已选引脚按外设类别着色,MSPM0 的封装取自 SysConfig 工程,面板只读。 + +扩展 2.0.0 要求 VS Code 1.108 及以上版本。XRobot 视图需要 xrobot 1.0.0 和 `git`,LibXR 视图需要 libxr 6.0.0,两者按上一节安装。扩展在 `PATH`、pip 的用户脚本目录和设置项 `xrobot.cli.extraPath` 中查找这些命令;命令装在虚拟环境中时,把虚拟环境中 `bin` 目录(Windows 上为 `Scripts` 目录)的完整路径写入 `xrobot.cli.extraPath`。MSPM0 的 "Open in SysConfig" 另需设置 `xrobot.libxr.sysconfigTool` 和 `xrobot.libxr.mspm0SdkDir`,留空时使用同名环境变量 `SYSCONFIG_TOOL` 与 `MSPM0_SDK_INSTALL_DIR`。 ## 平台 diff --git a/docs/env_setup/hpm.md b/docs/env_setup/hpm.md index 7ecdc8b..cd732a6 100644 --- a/docs/env_setup/hpm.md +++ b/docs/env_setup/hpm.md @@ -6,116 +6,90 @@ sidebar_position: 5 # HPM 环境配置 -本页说明 LibXR 在 HPM 平台上的接入方式。 - -可以从模板工程开始: - -- [HPM5301_LibXR_Template](https://github.com/xrobot-org/HPM5301_LibXR_Template) +HPM 工程是标准的 HPM SDK CMake 工程,用 RISC-V GCC 工具链(编译器前缀 `riscv32-unknown-elf-`)构建。BSP [bsp-hpm5301evklite](https://github.com/xrobot-org/bsp-hpm5301evklite) 和 [bsp-rmcs-slave-lite](https://github.com/xrobot-org/bsp-rmcs-slave-lite) 是可以完整构建的工程,本页以它们为例;[代码生成](../code_gen/hpm/README.md)说明 `libxr hpm setup` 如何在这样的工程里生成 LibXR 代码。 ## 工具链 -HPM 工程使用 RISC-V GCC 工具链,编译器前缀为 `riscv32-unknown-elf-`。HPM SDK 从环境变量 `GNURISCV_TOOLCHAIN_PATH` 读取工具链的安装目录(`bin` 的上一级目录),编译器为其中的 `bin/riscv32-unknown-elf-gcc`;没有设置这个变量时,CMake 配置报错 `GNURISCV_TOOLCHAIN_PATH is not set yet`。 +HPM SDK 从环境变量 `GNURISCV_TOOLCHAIN_PATH` 读取工具链的安装目录(`bin` 的上一级目录),编译器为其中的 `bin/riscv32-unknown-elf-gcc`;没有设置这个变量时,CMake 配置报错 `GNURISCV_TOOLCHAIN_PATH is not set yet`。SDK 本体由 `HPM_SDK_BASE` 指向。 工具链的来源: - Windows:HPMicro 的开发环境包 [sdk_env](https://github.com/hpmicro/sdk_env),工具链放在其中的 `toolchains/` 目录,由 `start_cmd.cmd` 打开的命令行设置 `GNURISCV_TOOLCHAIN_PATH` 等环境变量; - Linux x64:[hpm-linux-gcc-release v0.1.0](https://github.com/Jiu-xiao/hpm-linux-gcc-release/releases/tag/v0.1.0) 发布的 `riscv32-unknown-elf` 工具链; -- Docker:`ghcr.io/xrobot-org/docker-image-hpm:main` 在 `/opt/hpm-riscv32-unknown-elf` 中装有上述 Linux 工具链(GCC 15.2.0),路径记录在环境变量 `XR_HPM_TOOLCHAIN_ROOT` 中,见 [Docker 环境配置](docker.md)。 +- Docker:`ghcr.io/xrobot-org/docker-image-hpm:main` 在 `/opt/hpm-riscv32-unknown-elf` 中装有上述 Linux 工具链(GCC 15.2.0),路径同时记录在 `GNURISCV_TOOLCHAIN_PATH` 和 `XR_HPM_TOOLCHAIN_ROOT` 中,见 [Docker 环境配置](docker.md)。 + +## 工程结构 + +以 bsp-hpm5301evklite 为例: + +```text +. +|-- CMakeLists.txt +|-- CMakePresets.json +|-- app.yaml +|-- main.c +|-- boards/ +| `-- hpm5301evklite/ +| |-- tool_config.hpmpc +| |-- pinmux.c +| `-- ... +|-- cmake/ +| `-- LibXR.CMake +|-- User/ +| `-- app_main.cpp +`-- libxr/ +``` -镜像没有设置 `GNURISCV_TOOLCHAIN_PATH`,在镜像中构建前先由 `XR_HPM_TOOLCHAIN_ROOT` 设置它,模板工程的 CI 也是这样做的: +* `CMakeLists.txt` 用 `find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})` 引入 HPM SDK,`BOARD_SEARCH_PATH` 指向 `boards/`,并设置 `CONFIG_DMA_MGR 1`(LibXR 的 HPM 驱动依赖 SDK 的 dma_mgr 组件) +* `app.yaml` 声明对 `board_gpt_pin` 的依赖;`boards//` 下有唯一的 `.hpmpc` 文件(BSP 命名为 `tool_config.hpmpc`)——两者共同构成 HPM 工程的特征,`libxr hpm setup` 和 VS Code 扩展据此识别工程 +* `boards//pinmux.c` 由 HPM Pinmux Tool 从 `tool_config.hpmpc` 生成,提供 `init_bsp_pins()` +* `main.c` 在工程根目录:先 `init_bsp_pins()`,再 SDK 板级的 `board_init()`,然后调用各外设的时钟函数(`init_uart3_clock()` 一类),最后进入 `app_main()` +* `User/` 存放代码生成的 `app_main.cpp`;`libxr hpm setup` 会在其中生成 `libxr_config.yaml` +* `libxr/` 是 LibXR 子模块 + +## 构建 + +`CMakePresets.json` 提供 `debug-flash-xip`、`debug-ram` 和 `release-flash-xip` 三个 preset(Ninja 生成器,`HPM_BUILD_TYPE` 对应 `flash_xip` 或 `ram`): ```bash -export GNURISCV_TOOLCHAIN_PATH="$XR_HPM_TOOLCHAIN_ROOT" cmake --preset release-flash-xip cmake --build --preset release-flash-xip ``` -## 当前主线里已经有什么 - -按 `libxr master` 当前 `driver/hpm` 目录,已经存在这些驱动实现: +产物在 `build/output/` 下,如 `demo.elf`、`demo.bin`。 -- `hpm_gpio.*` -- `hpm_i2c.*` -- `hpm_pwm.*` -- `hpm_timebase.*` +## CMake 集成 -它们通过 `driver/hpm/CMakeLists.txt` 统一加入构建。 - -## 基本集成思路 - -以下节选自 [HPM5301_LibXR_Template](https://github.com/xrobot-org/HPM5301_LibXR_Template) 的 `cmake/LibXR.CMake`: +`cmake/LibXR.CMake` 用三个变量选择平台,然后把 LibXR 作为子工程加入: ```cmake -# LibXR platform/driver selection set(LIBXR_SYSTEM None) set(LIBXR_DRIVER hpm) set(LIBXR_NO_EIGEN True) - -# ... - -# Import LibXR as a subproject -add_subdirectory("${LIBXR_DIR}" "${CMAKE_CURRENT_BINARY_DIR}/libxr") - -# Make LibXR compile with the same HPM SDK compile options/includes. -if(DEFINED HPM_SDK_LIB_ITF AND TARGET ${HPM_SDK_LIB_ITF}) - target_link_libraries(xr PUBLIC ${HPM_SDK_LIB_ITF}) -endif() - -# Let app sources directly include LibXR headers. -if(TARGET app) - target_link_libraries(app PUBLIC xr) -endif() - -# Ensure LibXR object files are linked into the final ELF target. -if(DEFINED APP_ELF_NAME AND TARGET ${APP_ELF_NAME}) - target_link_libraries(${APP_ELF_NAME} xr) -endif() ``` -`xr` 链接 `${HPM_SDK_LIB_ITF}`,LibXR 因此与应用使用相同的 HPM SDK 编译选项和头文件路径。 - -这里的前提是: - -- 工程已经能用 HPM SDK 正常编译; -- 工程已经把 HPM SDK 的头文件、启动文件、链接脚本和板级初始化接好; -- LibXR 只是在这个基础上接入 `driver/hpm` 与通用 runtime/middleware。 +`xr` 链接 `${HPM_SDK_LIB_ITF}`,LibXR 因此使用与 SDK 相同的编译选项和头文件路径;应用目标 `app` 和最终的 ELF 目标链接 `xr`。工具链的探测由 `find_package(hpm-sdk)` 完成。 -## 当前文档建议的实际入口 +## LibXR 的 HPM 驱动 -HPM 工程按以下顺序接入: +`driver/hpm` 提供四个驱动,由该目录的 `CMakeLists.txt` 统一加入构建: -1. 先用 HPM SDK 或模板工程把最小工程跑通。 -2. 再检查工程里是否已经能正常 `add_subdirectory(libxr)`。 -3. 最后再按需要接入具体外设类,例如 `HPMGPIO`、`HPMI2C`、`HPMPWM`、`HPMTimebase`。 - -外设的引脚复用和时钟由工程在创建 LibXR 对象之前配置,例如调用 HPM Pinmux Tool 生成的引脚函数和时钟函数;LibXR 的 HPM 驱动只调用 SDK 驱动,不调用 `board.c` 中的板级函数: - -```cpp -static LibXR::HPMI2C i2c3(HPM_I2C3, clock_i2c3, {100000}); -static LibXR::HPMPWM pwm(HPM_PWM0, clock_mot0, 0, 0, LibXR::HPMPWM::Polarity::NORMAL); -``` +- `hpm_gpio.*`:GPIO +- `hpm_i2c.*`:I2C 主机 +- `hpm_pwm.*`:PWM +- `hpm_timebase.*`:基于 MCHTMR 的时间基准 -## 当前 I2C 支持情况 +驱动只调用 SDK 的驱动函数;外设的引脚复用、时钟和初始化顺序由工程负责(`init_bsp_pins()`、`board_init()` 和 `init_*_clock()`),LibXR 对象在 `app_main()` 中创建。I2C 的 DMA 后台路径依赖 dma_mgr,BSP 用 `CONFIG_DMA_MGR 1` 启用它。 -`HPMI2C` 已不是简单的 blocking-only 包装,当前主线还覆盖了: +`HPMI2C` 在 SDK 的 `hpm_i2c_drv` 之上实现 LibXR 的 I2C 主机抽象:阻塞式字节流传输和寄存器/存储器地址式传输;默认 7 位主机寻址,`SetAddressMode()` 可切换到 SDK 支持的 10 位主机寻址;提供 dma_mgr 时,POLLING、CALLBACK 等等待策略可以走 DMA 后台路径;超时、总线忙、无响应等典型主机故障出现时,驱动按最近一次成功配置重建控制器。 -- 7-bit / 10-bit 主机寻址模式; -- sequence frame; -- transfer flags; -- 可选 DMA helper 背景路径; -- 等待策略与恢复路径。 +`HPMPWM` 的构造参数在两条代码路径下相同(外设地址、时钟、输出通道索引、比较器索引、极性):SoC 提供标准 PWM 外设时走 SDK 的 `hpm_pwm_drv`,其余 SoC 走 GPTMR 路径。`SetDutyCycle()` 接受 0.0 到 1.0 的占空比,`SetConfig()` 配置频率。 -上述能力在具体工程中能否使用,取决于: +## Docker 构建 -- HPM SDK 头文件是否完整; -- 工程是否启用了 SDK 的 `dma_mgr` 组件(`CONFIG_DMA_MGR`),未启用时编译报错; -- 引脚和时钟是否已在创建对象前配置。总线恢复使用 I2C 控制器自身产生的复位信号(9 个 SCL 脉冲)。 +镜像 `ghcr.io/xrobot-org/docker-image-hpm:main` 内置 RISC-V 工具链(GCC 15.2.0)、CMake、Ninja 和 HPM SDK v1.13.0,并设置好了 `GNURISCV_TOOLCHAIN_PATH` 与 `HPM_SDK_BASE`: -## 当前 PWM 支持情况 - -`HPMPWM` 当前主线支持两类路径: - -- 如果目标 SoC 提供标准 PWM 外设,则走 `hpm_pwm_drv`; -- 如果不满足该条件,代码里还有 `GPTMR` fallback 路径。 - -具体走哪条,取决于芯片和 SDK 宏条件。 +```bash +docker run --rm -v "$PWD:/work" -w /work ghcr.io/xrobot-org/docker-image-hpm:main \ + bash -c 'cmake --preset release-flash-xip && cmake --build --preset release-flash-xip' +``` diff --git a/docs/env_setup/mspm0.md b/docs/env_setup/mspm0.md index d3999f5..6241258 100644 --- a/docs/env_setup/mspm0.md +++ b/docs/env_setup/mspm0.md @@ -6,177 +6,92 @@ sidebar_position: 3.5 # MSPM0 环境配置 -当前默认使用 GNU Arm Embedded Toolchain,编译器前缀为 `arm-none-eabi-`。目前没有验证在 TI Arm Clang 工具链下的兼容性。 +MSPM0 工程基于 TI MSPM0 SDK 和 SysConfig,用 CMake、Ninja 和 GNU Arm Embedded Toolchain(编译器前缀 `arm-none-eabi-`)构建。BSP [bsp-mspm0g3507-mini](https://github.com/xrobot-org/bsp-mspm0g3507-mini) 和 [bsp-mspm0g3519-mini](https://github.com/xrobot-org/bsp-mspm0g3519-mini) 是可以完整构建的工程,本页以它们为例;[代码生成](../code_gen/mspm0/README.md)说明 `libxr mspm0 setup` 如何在这样的工程里生成 LibXR 代码。 -如果只是想快速开始,推荐直接使用 XRobot 的 MSPM0 Docker 镜像:`ghcr.io/xrobot-org/docker-image-mspm0:main`。 +快速开始推荐 Docker 镜像 `ghcr.io/xrobot-org/docker-image-mspm0:main`,见下文 [Docker 构建](#docker-构建)。 -## CMake 配置 +## 基础环境 -在 LibXR 外部工程中,MSPM0 通常按下面的方式接入: +本机构建安装: -```cmake -set(LIBXR_SYSTEM None) -set(LIBXR_DRIVER mspm0) -set(LIBXR_NO_EIGEN True) -set(MSPM0_SDK_DIR "${CMAKE_CURRENT_SOURCE_DIR}/mspm0-sdk") +* CMake(3.20 或更新版本)和 Ninja +* `arm-none-eabi-gcc`([GNU Arm Embedded Toolchain](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads)) +* [TI MSPM0 SDK](https://www.ti.com/tool/MSPM0-SDK) +* [SysConfig](https://www.ti.com/tool/SYSCONFIG) 独立安装包,其中的 `sysconfig_cli` 是命令行入口 -include("${CMAKE_SOURCE_DIR}/cmake/LibXR.CMake") -``` - -其中: +CMake 工程通过两个变量找到 SDK 与 SysConfig,变量名与 SDK 的 `imports.mak` 一致,环境变量或 CMake 缓存(`-D`)都可以: -* `LIBXR_SYSTEM None` 表示当前按裸机方式集成 -* `LIBXR_DRIVER mspm0` 表示启用 LibXR 的 MSPM0 驱动目录 -* `MSPM0_SDK_DIR` 指向 TI MSPM0 SDK 根目录 -* `cmake/LibXR.CMake` 负责把 LibXR 和 MSPM0 SDK 接到工程里 +* `MSPM0_SDK_INSTALL_DIR`:MSPM0 SDK 根目录 +* `SYSCONFIG_TOOL`:SysConfig 命令行的完整路径,Windows 是 `sysconfig_cli.bat`,Linux 是 `sysconfig_cli.sh` -一个清晰的职责分工通常是: +Windows PowerShell 的示例: -* 根 `CMakeLists.txt` 负责最终应用目标、用户源文件、链接选项和后处理 -* `cmake/LibXR.CMake` 负责 LibXR 平台选择、SDK 路径检查、SysConfig 输出检查,以及给 `xr` 目标补齐 MSPM0 相关依赖 +```powershell +$env:MSPM0_SDK_INSTALL_DIR = "C:\ti\mspm0_sdk_2_11_00_07" +$env:SYSCONFIG_TOOL = "C:\ti\sysconfig_1.28.1\sysconfig_cli.bat" +``` -## 目录结构 +## 工程结构 -模板工程 [MSPM0G3507 LibXR Template](https://github.com/xrobot-org/MSPM0G3507_LibXR_Template) 的目录结构如下: +BSP 的目录结构如下: ```text . |-- CMakeLists.txt |-- CMakePresets.json +|-- main.c +|-- mspm0g3507_minidb48.syscfg |-- cmake/ | |-- LibXR.CMake +| |-- MSPM0SysConfig.cmake | `-- arm-none-eabi-gcc.cmake -|-- Core/ |-- User/ -|-- libxr/ -|-- mspm0-sdk/ -|-- scripts/ -| `-- fetch-mspm0-sdk.sh -`-- sysconfig/ +| |-- app_main.cpp +| `-- libxr_config.yaml +|-- Modules/ +`-- libxr/ ``` -其中: - +* `main.c` 在工程根目录,先调用 SysConfig 生成的 `SYSCFG_DL_init()` 完成时钟、引脚和外设的初始化,然后进入 `app_main()` +* `.syscfg` 是 SysConfig 工程,在工程根目录;芯片、时钟、引脚和外设都由它描述,更换芯片只更换这份文件 +* `cmake/MSPM0SysConfig.cmake` 在 CMake 配置阶段调用 SysConfig 命令行,把 `ti_msp_dl_config.c/.h`、`device.opt`、链接脚本等输出生成到构建目录;CMake 跟踪 `.syscfg` 的修改,下一次构建自动重新生成 +* `User/` 存放代码生成的 `app_main.cpp` 和 `libxr_config.yaml` * `libxr/` 是 LibXR 子模块 -* `mspm0-sdk/` 是 TI MSPM0 SDK 子模块 -* `User/` 是应用源文件(`main.c`、`app_main.cpp`) -* `Core/` 是 syscalls 桩函数和栈保留链接脚本 -* `sysconfig/` 保存 SysConfig 工程及其生成的文件 -* `scripts/fetch-mspm0-sdk.sh` 只获取构建需要的 SDK 文件 - -SDK 不在仓库内时,把 `MSPM0_SDK_DIR` 指向 SDK 所在目录。 -## SysConfig 输出要求 +## CMake 集成 -MSPM0 工程通常依赖 SysConfig 输出的配置文件。CMake 一般只负责“查找并使用”,不负责调用 SysConfig 自动生成。 +`cmake/LibXR.CMake` 用三个变量把 LibXR 接入工程: -推荐把 SysConfig 输出统一放到: - -```text -sysconfig/ +```cmake +set(LIBXR_SYSTEM None) +set(LIBXR_DRIVER mspm0) +set(LIBXR_NO_EIGEN True) ``` -CMake 侧通常需要能找到这些文件: - -* `ti_msp*_config.c` -* `ti_msp*_config.h` -* `device.opt` -* 一份 `.lds` 链接脚本,常见文件名为 `device_linker.lds` - -如果项目采用自动发现方式,那么根工程里不需要手工写死 `ti_msp_dl_config.c` 这类具体文件名,只需要保证生成文件位于 `sysconfig/` 目录即可。 - -修改 `.syscfg` 文件后,先重新生成这些输出,再执行 CMake 构建。 - -## 芯片型号相关项 - -虽然本文是通用说明,但 MSPM0 项目里仍有几项内容必须随芯片型号或开发板变化: - -* 启动文件路径 -* `driverlib.a` 所在目录 -* SysConfig 目标板或目标芯片 -* 编译宏,例如 `__MSPM0xxxx__` - -MSPM0 工程里,很多编译问题本质上都是“芯片型号相关文件没有同步替换”。 - -## MSPM0 驱动 - -`driver/mspm0/CMakeLists.txt` 把以下驱动加入构建: +`LIBXR_SYSTEM None` 表示裸机系统,`LIBXR_DRIVER mspm0` 启用 LibXR 的 `driver/mspm0` 驱动目录。newlib 的系统调用由 `libxr/driver/mspm0/mspm0_syscalls.c` 提供,工程里另写 `_write`、`_read` 一类的桩函数会与它重复。 -- `mspm0_gpio.*` -- `mspm0_pwm.*` -- `mspm0_timebase.*` -- `mspm0_uart.*` -- `mspm0_spi.*` -- `mspm0_i2c.*` -- `mspm0_group1_shared.cpp` -- `mspm0_atomic_shim.c` +## 构建 -SPI / I2C 已在 LibXR 默认 MSPM0 构建列表中,上层工程不需要重复手工添加对应源文件。工程仍然需要提供匹配芯片的 SDK、SysConfig 输出和外设初始化配置。 +`CMakePresets.json` 提供 `debug` 和 `release` 两个 preset(Ninja 生成器,工具链文件 `cmake/arm-none-eabi-gcc.cmake`): -## 工具链要求 - -推荐使用: - -* `cmake` -* `ninja` -* `arm-none-eabi-gcc` -* `arm-none-eabi-g++` -* `arm-none-eabi-objcopy` - -本机直接构建的典型命令如下: - -```powershell -cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=arm-none-eabi-gcc -DCMAKE_CXX_COMPILER=arm-none-eabi-g++ -DCMAKE_ASM_COMPILER=arm-none-eabi-gcc -cmake --build build +```bash +cmake --preset debug +cmake --build --preset debug ``` +产物在 `build/debug/` 下:`mspm0_minidb48.elf`、`.hex` 和 `.bin`。 + ## Docker 构建 -镜像 `ghcr.io/xrobot-org/docker-image-mspm0:main` 提供 `arm-none-eabi-gcc`、CMake 和 Ninja。模板工程中的构建命令: +镜像 `ghcr.io/xrobot-org/docker-image-mspm0:main` 内置 `arm-none-eabi-gcc`、CMake、Ninja、MSPM0 SDK 和 SysConfig,并设置好了 `MSPM0_SDK_INSTALL_DIR` 与 `SYSCONFIG_TOOL`: ```bash -git submodule update --init libxr -sh scripts/fetch-mspm0-sdk.sh docker run --rm -v "$PWD:/work" -w /work ghcr.io/xrobot-org/docker-image-mspm0:main \ bash -c 'cmake --preset release && cmake --build --preset release' ``` -产物为 `build/release/ti_mspm0_libxr_dev.elf`、`.hex` 和 `.bin`。 - ## 常见问题 -### CMake 提示找不到 MSPM0 SDK - -先检查: - -```text -${MSPM0_SDK_DIR}/source -``` - -是否存在。如果不存在,说明 SDK 路径配置不对。 - -### CMake 提示找不到 SysConfig 文件 - -先检查 `sysconfig/` 下是否已经生成: - -* `ti_msp*_config.c` -* `ti_msp*_config.h` -* `device.opt` -* `.lds` - -如果缺文件,说明还没有完成 SysConfig 输出生成,或者输出目录与 CMake 约定不一致。 - -### 链接阶段出现 `_write/_read/_close` 一类 warning - -如果工程使用了: - -```text ---specs=nano.specs ---specs=nosys.specs -``` - -那么 `_write`、`_read`、`_close`、`_isatty`、`_fstat` 等未实现 warning 是常见现象。只要最终成功生成 ELF,通常不影响裸机程序运行。 - -## 示例工程 +### CMake 配置提示找不到 MSPM0 SDK 或 SysConfig -* [MSPM0G3507 LibXR Template](https://github.com/xrobot-org/MSPM0G3507_LibXR_Template) +CMake 配置阶段检查这两个变量:`MSPM0_SDK_INSTALL_DIR` 下应有 `.metadata/product.json`,`SYSCONFIG_TOOL` 应指向 `sysconfig_cli` 脚本本体。检查失败时配置以错误结束,错误信息会带上当前的变量值;按提示用环境变量或 `-D` 修正后重新配置。 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/README.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/README.md index 2841ca5..ced7f01 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/README.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/README.md @@ -6,11 +6,14 @@ sidebar_position: 5 # Code Generation -CodeGenerator (the pip package `libxr`; see [Environment Setup](../env_setup/README.md) for installation) generates LibXR initialization code from SDK or project description files, for example C++ peripheral objects and `libxr_config.yaml` from an STM32CubeMX `.ioc` file. This chapter describes the project inputs the generator reads, the settings and constraints of each peripheral in `libxr_config.yaml`, and how the generated code is integrated into the project; the runtime API is described in [Basic Programming (LibXR)](../basic_coding/README.md). +CodeGenerator (the pip package `libxr`; see [Environment Setup](../env_setup/README.md) for installation) generates LibXR initialization code from SDK or project description files: C++ peripheral objects and `libxr_config.yaml` from an STM32CubeMX `.ioc` file, a TI SysConfig `.syscfg` file, or an HPM Pinmux Tool project. This chapter describes the project inputs the generator reads, the settings and constraints of each peripheral in `libxr_config.yaml`, and how the generated code is integrated into the project; the runtime API is described in [Basic Programming (LibXR)](../basic_coding/README.md). ## Sections - [STM32 Code Generation](./stm32/README.md) +- [MSPM0 Code Generation](./mspm0/README.md) +- [HPM Code Generation](./hpm/README.md) +- [Pin Layout (libxr pins)](./pins.md) - [Integrate with XRobot](./xrobot_inter.md) -The STM32 section describes the generation of GPIO, UART, SPI, I2C, ADC, DAC, CAN, PWM, Flash, Cache, Watchdog, Timebase and the software timer. +The STM32 section describes the generation of GPIO, UART, SPI, I2C, ADC, DAC, CAN, PWM, Flash, Cache, Watchdog, Timebase and the software timer; the MSPM0 and HPM sections describe each platform's workflow, the generated objects and the `libxr_config.yaml` settings. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md new file mode 100644 index 0000000..d49c2ad --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md @@ -0,0 +1,260 @@ +--- +id: code-gen-hpm +title: HPM Code Generation +sidebar_position: 3 +--- + +# HPM Code Generation + +The CodeGenerator's `libxr hpm setup` command brings an HPM Pinmux Tool project to LibXR: it parses the project and generates C++ initialization code. The pin muxing and clocks are configured by the Pinmux Tool output (the pinmux functions that the root `main.c` calls), `main.c` stays BSP-owned, and the generated code is the `app_main` under `User/`, with every construction argument an HPM SDK macro. + +--- + +## Project Recognition + +The project is a directory with an `app.yaml` at its root and exactly one `.hpmpc` file under `boards//`. The selected signals come from the `selectPins` of the `.hpmpc` and the pinmux functions that `main` in the root `main.c` calls outside preprocessor conditions; functions present in the `.hpmpc` but never called by `main` do not take part. Every signal is checked, as the macro name of `hpm_iomux.h`, against the layout of the SoC package, and a pad the package does not have, or a signal its pad cannot carry, is warned about. + +Pinmux functions that `main` calls only inside preprocessor conditions are not read either (the generated objects must not depend on build options), one warning per function; when every call sits inside a condition, no pin is read. When `main` calls no pinmux function at all, the parser falls back to `init_bsp_pins`, and when the project has no such function, no pin is read. + +--- + +## Quick Start + +Run in the project root: + +```bash +libxr hpm setup -d . +``` + +The command performs these steps: + +1. When the project directory has no `.gitignore` yet, create one that ignores `build`, `.history`, `.cache`, `CMakeFiles` and `.config.yaml`; an existing `.gitignore` stays unchanged; +2. parse the project into `.config.yaml`; +3. generate `app_main.cpp`, `app_main.h` and `libxr_config.yaml` under `User/`. + +When neither `--xrobot` nor `--no-xrobot` is given, the output file keeps its choice and a new file does not use XRobot; with XRobot the command generates the `XR_REGISTER` registrations and `XROBOT_MAIN();`, and before it ends it suggests running `xrobot gen` to bring `User/xrobot_main.hpp` up to date. When the existing `app_main.cpp` was not generated by `libxr gen`, setup prints a warning that lists the lines to be replaced; everything outside the User Code regions is regenerated. + +--- + +## Example Output + +The following run of bsp-hpm5301evklite had the project already up to date: + +```text +[INFO] .\User\app_main.cpp uses XRobot; generating with --xrobot (--no-xrobot turns it off). +[INFO] Configuration exported to: .\.config.yaml +[INFO] System: bare metal +[INFO] Generated User: unchanged app_main.cpp, app_main.h, libxr_config.yaml +[INFO] Next: run `xrobot gen` to bring User/xrobot_main.hpp up to date; libxr setup does not update it + +===== [Configuration Summary] ===== + +SoC: HPM5301 (QFN48) + +GPIO (2 pins): + pa10: PA10 + pa3: PA03 + +Active Peripherals: + I2C: 1 instance(s) + I2C3 + PWM: 1 instance(s) + GPTMR0 + Other: 7 instance(s) + UART0 + UART3 + SPI1 + ADC0 + ACMP + USBPHY + USB0 +``` + +The generator writes only the files whose content changes; in the example the project was already up to date and none of the three files was rewritten. Other in the summary lists the configurations LibXR has no driver for, see [Generated Objects and Naming](#generated-objects-and-naming). + +--- + +## Output Layout + +After the run, the project gains or has these files modified: + +```txt +. +├── .config.yaml # the configuration file written by parsing +├── app.yaml # the HPM SDK project description (BSP-provided) +├── main.c # BSP-provided: calls app_main() after init_bsp_pins() and friends +├── boards// +│ └── tool_config.hpmpc # the Pinmux Tool project (BSP-provided) +├── User/ +│ ├── app_main.cpp # the entry source file +│ ├── app_main.h # the header of the entry source file +│ └── libxr_config.yaml # the LibXR configuration file +└── libxr/ # Git submodule: LibXR itself +``` + +--- + +## app_main.cpp + +`app_main.cpp` contains the LibXR initialization function `app_main()`. Code between `/* User Code Begin N */` and `/* User Code End N */` survives regeneration; the rest is regenerated every time. The generated peripheral objects are `static` and stay valid after `app_main()` returns; long-lived local objects are declared `static`. A peripheral object can be passed to a thread or a module as a base-class pointer, see [Integrate with XRobot](../xrobot_inter.md). + +The following is an excerpt of the `app_main.cpp` generated on bsp-hpm5301evklite, with `// ...` marking omissions: + +```cpp +// Generated by `libxr gen`; do not edit by hand. +// Generated from boards/hpm5301evklite/tool_config.hpmpc (HPM5301); the Pinmux Tool +// configures the pins via init_bsp_pins() in main.c and main.c stays BSP-owned. Put +// application code between the "User Code Begin" and "User Code End" markers. +#include "app_main.h" + +#include "libxr.hpp" +#include "hpm_gpio.hpp" +#include "hpm_i2c.hpp" +#include "hpm_pwm.hpp" +#include "hpm_soc.h" +#include "hpm_timebase.hpp" +#include "xrobot_main.hpp" + +using namespace LibXR; + +/* User Code Begin 1 */ +// KEY interrupt counter, incremented in the GPIO interrupt callback. +static std::atomic key_irq_count{0}; +/* User Code End 1 */ + +extern "C" void app_main(void) +{ + /* User Code Begin 2 */ + /* User Code End 2 */ + + // Timebase and platform + static HPMTimebase timebase; + PlatformInit(); + + // GPIO: init_bsp_pins() configured pa10 (PA10) as an output pin, pa3 (PA03) as an input + // pin with a pull-down. The interrupt edge comes from the pinmux and every object + // carries its port IRQ; RegisterCallback and EnableInterrupt belong to the consumer (a + // Module or the User Code). + static HPMGPIO pa10(HPM_GPIO0, GPIO_DI_GPIOA, 10, IRQn_GPIO0_A); + static HPMGPIO pa3(HPM_GPIO0, GPIO_DI_GPIOA, 3, IRQn_GPIO0_A); + + // I2C: blocking transfers; the DMA-backed background path runs on dma_mgr. + static HPMI2C i2c3(HPM_I2C3, clock_i2c3, {100000U}); + + // PWM on a GPTMR comparator: the SoC has no PWM peripheral, so HPMPWM takes its GPTMR + // fallback path; the duty comparator is fixed at 0 and SetConfig is called when + // libxr_config sets a frequency. + static HPMPWM pwm_gptmr0_ch1(reinterpret_cast(HPM_GPTMR0), + clock_gptmr0, 1, 0, HPMPWM::Polarity::NORMAL); + + // Hardware registration + XR_REGISTER(pa10, LibXR::GPIO); + XR_REGISTER(pa3, LibXR::GPIO); + + XR_REGISTER(pwm_gptmr0_ch1, LibXR::PWM); + + XR_REGISTER(i2c3, LibXR::I2C); + + /* User Code Begin 3 */ + /* User Code End 3 */ + XROBOT_MAIN(); +} +``` + +The pins and clocks are configured by the pinmux functions `main.c` calls, and the construction arguments reference SDK macros (`HPM_GPIO0`, `GPIO_DI_GPIOA`, `IRQn_GPIO0_A`, `HPM_I2C3`, `clock_i2c3`). A GPIO object carries the IRQ of its port, the port's interrupt service routine comes from the LibXR driver, the edge comes from the pinmux, and registering the callback (`RegisterCallback` and `EnableInterrupt`) belongs to the consumer. The DMA-backed background path of an I2C needs `CONFIG_DMA_MGR` enabled in the project. + +--- + +## Generated Objects and Naming + +Objects are generated for the configurations LibXR has drivers for: one object per GPIO pin, one per I2C; PWM on a GPTMR is described below. The remaining configurations (UART, SPI, MCAN, ADC, ACMP, USB and so on) are listed under Other in the summary for display only. + +The objects are named: + +| Configuration | Object name | Example | +| --- | --- | --- | +| GPIO | the pin name (lower-case port letter plus line), renamed in the `GPIO:` section | `pa10`, `pb11` | +| I2C | the lower-case peripheral instance name | `i2c3` | +| PWM on a GPTMR | `pwm__ch` | `pwm_gptmr0_ch1` | + +Every comparator (COMP_n) of a GPTMR gets a PWM object through the GPTMR path of `HPMPWM`; objects are generated only when the SoC has no PWM peripheral, decided from whether the chip's pin data has any PWM signal: HPM5301 has none, HPM5361 has 20, and on the latter the GPTMRs are listed under Other for display only. The duty comparator is fixed and the polarity is `NORMAL`; the objects and their registrations are generated unconditionally, and wrapping them in a preprocessor condition makes XRobot's generator reject the file. + +--- + +## libxr_config.yaml + +`User/libxr_config.yaml` stores the settings of code generation. A missing file is created with the defaults; later runs fill in the missing settings and keep the values already present. The `.hpmpc` records pins only, and the speed and frequency come from these settings. + +| Section | Keys and defaults | Notes | +| --- | --- | --- | +| `I2C` | `speed: 100000` | the bus speed in Hz, one entry per instance keyed by the lower-case instance name | +| `PWM` | `frequency` (default null) | one entry per object; null calls no `SetConfig`, a given value must be a positive integer (Hz) | +| `GPIO` | the key is a pin name, the value is the new name | renames a pin; a null value keeps the default name. The section lists every pin the project read | + +The HPM generator creates no UART yet, so `terminal_source` has no terminal to point at; setting it prints a warning. + +The following is the `User/libxr_config.yaml` generated on bsp-hpm5301evklite the first time: + +```yaml +generator: 6.0.0 +I2C: + i2c3: + speed: 100000 +PWM: + pwm_gptmr0_ch1: + frequency: +GPIO: + pa10: + pa3: +``` + +After changing the value of `pa10` in the `GPIO` section to `LED` and regenerating, the object becomes `static HPMGPIO LED(HPM_GPIO0, GPIO_DI_GPIOA, 10, IRQn_GPIO0_A);` with the registration updated the same way. + +--- + +## Supported SoCs and Packages + +The data currently covers HPM5301 (QFN48) and HPM5361 (LQFP100, LQFP64, QFN48); HPM53M1 is not supported yet. The pin data comes from the `hpm_iomux.h` of the HPM SDK and the pin tables of the HPM5300 datasheet. + +--- + +## Regenerating Code + +After changing the `.hpmpc`, `main.c` or `User/libxr_config.yaml`, run `libxr hpm setup -d .` in the project root again, or regenerate only the files under `User/`: + +```bash +libxr parse -d . +libxr gen -i .config.yaml -o User/app_main.cpp +``` + +`.config.yaml` is written by `libxr parse`; a freshly cloned project does not have it, so run `libxr parse` first. The Generate LibXR Code action of the VS Code extension runs the two commands in sequence, see [VS Code Extension](../../env_setup/README.md#vs-code-extension). + +--- + +## Options + +The options of `libxr hpm setup` are listed below; `libxr hpm setup --help` lists the same. + +| Option | Description | +| ---------- | --------------------------- | +| `-d`, `--directory` | the project directory: an `app.yaml` at its root and one `.hpmpc` under `boards/` (default: the current directory) | +| `-o`, `--output` | the output C++ file (default: `User/app_main.cpp` in DIRECTORY) | +| `--xrobot` / `--no-xrobot` | generate or skip the `XR_REGISTER` registrations and `XROBOT_MAIN();`, see [Integrate with XRobot](../xrobot_inter.md); when neither is given the output file keeps its choice, and a new file does not use XRobot | +| `--libxr-config` | path or URL of libxr_config.yaml (default: the `libxr_config.yaml` next to the output) | +| `--verbose` | enable debug logging | + +--- + +## Commands + +| Command | Description | +| ------------------------ | --------------------------------- | +| `libxr parse` | parse the project into `.config.yaml` | +| `libxr gen` | generate the entry source file and `app_main.h` from `.config.yaml`, and update `libxr_config.yaml` | +| `libxr pins` | print the package and pin layout of a SoC, see [Pin Layout](../pins.md) | + +The options and defaults of every command are listed by `libxr --help`. + +## Reference + +* [LibXR command-line tool and documentation](https://pypi.org/project/libxr/) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md new file mode 100644 index 0000000..6aa384a --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md @@ -0,0 +1,324 @@ +--- +id: code-gen-mspm0 +title: MSPM0 Code Generation +sidebar_position: 2 +--- + +# MSPM0 Code Generation + +The CodeGenerator's `libxr mspm0 setup` command brings a TI SysConfig project to LibXR: it parses the `.syscfg` file at the project root and generates C++ initialization code. SysConfig configures the clocks, pins, DMA channels and peripherals (`SYSCFG_DL_init()` in `main.c`); the generated code declares the LibXR objects and registers them with XRobot, and every construction argument is a macro SysConfig generated. + +--- + +## Quick Start + +Run in the SysConfig project root: + +```bash +libxr mspm0 setup -d . +``` + +The project root holds one `.syscfg` file. The command performs these steps: + +1. When the project directory has no `.gitignore` yet, create one that ignores `build`, `.history`, `.cache`, `CMakeFiles` and `.config.yaml`; an existing `.gitignore` stays unchanged; +2. parse the `.syscfg` into `.config.yaml`; +3. generate `app_main.cpp`, `app_main.h` and `libxr_config.yaml` under `User/`. + +When neither `--xrobot` nor `--no-xrobot` is given, the output file keeps its choice and a new file does not use XRobot; with XRobot the command generates the `XR_REGISTER` registrations and `XROBOT_MAIN();`, and before it ends it suggests running `xrobot gen` to bring `User/xrobot_main.hpp` up to date. When the existing `app_main.cpp` was not generated by `libxr gen`, setup prints a warning that lists the lines to be replaced; everything outside the User Code regions is regenerated. + +--- + +## Where the SysConfig Output Comes From + +Parsing reads two sources: the `.syscfg` itself (peripheral instances, parameters and pin assignments) and the `ti_msp_dl_config.h/.c` that SysConfig generates (the macro names actually emitted, `CPUCLK_FREQ`, the ULPCLK divider and the clock configuration of each instance). + +When the environment variables `SYSCONFIG_TOOL` and `MSPM0_SDK_INSTALL_DIR` are set, parsing runs SysConfig once on the `.syscfg` and writes the output to a temporary directory; these are the same variables the BSP's `cmake/MSPM0SysConfig.cmake` uses. Without them, parsing reuses a generated output newer than the `.syscfg` under `build*`, `cmake-build*` or `out` in the project. Reuse compares modification times only: a `.syscfg` replaced by one with an older modification time still reuses the old output, so build once more, or set the two variables and run again. + +The BSP's CMake runs SysConfig on the `.syscfg` at configure time and writes the output to the `syscfg/` directory of the build tree; a change to the `.syscfg` triggers regeneration, see [MSPM0 Environment Setup](../../env_setup/mspm0.md). + +--- + +## Example Output + +The following run of bsp-mspm0g3507-mini had the two environment variables set, and the project was already up to date: + +```text +[INFO] .\User\app_main.cpp uses XRobot; generating with --xrobot (--no-xrobot turns it off). +[INFO] Processing mspm0g3507_minidb48.syscfg... +[INFO] Running SysConfig on mspm0g3507_minidb48.syscfg +[INFO] Configuration exported to: .\.config.yaml +[INFO] System: bare metal +[INFO] Generated User: unchanged app_main.cpp, app_main.h, libxr_config.yaml +[INFO] Next: run `xrobot gen` to bring User/xrobot_main.hpp up to date; libxr setup does not update it + +===== [Configuration Summary] ===== + +MCU: MSPM0 MSPM0G3507 + +GPIO (4 pins): + LED1: PB8, OUTPUT + LED2: PA16, OUTPUT + KEY1: PB24, INPUT, FALL interrupt + KEY2: PB20, INPUT, FALL interrupt + +Active Peripherals: + UART: 2 instance(s) + UART_0 + UART_1 + I2C: 2 instance(s) + I2C_0 + I2C_1 + SPI: 1 instance(s) + SPI_1 + PWM: 1 instance(s) + PWM_TIMA1 + Other: 5 instance(s) + ADC12_0 + ADC12_1 + DAC0 + MCAN_0 + QEI_TIMG8 +``` + +The generator writes only the files whose content changes; in the example the project was already up to date and none of the three files was rewritten. Other in the summary lists the configurations LibXR has no driver for, see [Generated Objects and Naming](#generated-objects-and-naming). + +--- + +## Output Layout + +After the run, the project gains or has these files modified: + +```txt +. +├── .config.yaml # the configuration file written by parsing +├── main.c # BSP-provided: calls app_main() after SYSCFG_DL_init() +├── User/ +│ ├── app_main.cpp # the entry source file +│ ├── app_main.h # the header of the entry source file +│ └── libxr_config.yaml # the LibXR configuration file +└── libxr/ # Git submodule: LibXR itself +``` + +--- + +## app_main.cpp + +`app_main.cpp` contains the LibXR initialization function `app_main()`. Code between `/* User Code Begin N */` and `/* User Code End N */` survives regeneration; the rest is regenerated every time. The generated peripheral objects are `static` and stay valid after `app_main()` returns; long-lived local objects are declared `static`. A peripheral object can be passed to a thread or a module as a base-class pointer, see [Integrate with XRobot](../xrobot_inter.md). + +The following is an excerpt of the `app_main.cpp` generated on bsp-mspm0g3507-mini, with `// ...` marking omissions: + +```cpp +// Generated by `libxr gen`; do not edit by hand. +// Generated from mspm0g3507_minidb48.syscfg (MSPM0G3507); SysConfig configures the +// clocks, pins, DMA channels and peripherals (SYSCFG_DL_init() in main.c). Put +// application code between the "User Code Begin" and "User Code End" markers. +#include "app_main.h" + +#include "libxr.hpp" +#include "mspm0_gpio.hpp" +// ... + +using namespace LibXR; + +/* User Code Begin 1 */ +// KEY interrupt counters, incremented in the GPIO interrupt callbacks. +static std::atomic key1_irq_count{0}; +/* User Code End 1 */ + +// Input clocks: the BUSCLK of the power domain. PD0 from ULPCLK = CPUCLK_FREQ / 2 +// (DL_SYSCTL_setULPCLKDivider) and PD1 from MCLK (CPUCLK_FREQ). The I2C driver resets +// the clock configuration of its peripherals, so the BUSCLK of the domain is the right +// argument. +static constexpr uint32_t PD0_BUSCLK_FREQ = (CPUCLK_FREQ / 2); +static constexpr uint32_t PD1_BUSCLK_FREQ = CPUCLK_FREQ; + +// Ownership of the DMA channels that serve a UART transmitter; +// MSPM0_UART_MAIN_INIT checks these names against the ones SysConfig generated. +#define DMA_CH_UART0_TX_LIBXR_UART_IRQN UART_0_INST_INT_IRQN +#define DMA_CH_UART0_TX_LIBXR_UART_TX 1 + +// DMA buffers. A UART gets 2 x N bytes for its two transmit halves; the receive side +// runs on byte interrupts. The SPI DMA buffers are split in two halves as well; the +// I2C driver uses polling, its buffer is the staging area for DMA transfers. +alignas(size_t) static uint8_t uart0_tx_buf[2 * 128]; +// ... +alignas(4) static uint8_t i2c0_buf[32]; + +extern "C" void app_main(void) +{ + /* User Code Begin 2 */ + /* User Code End 2 */ + + // Timebase and platform + static MSPM0Timebase timebase; + PlatformInit(); + + // GPIO: SysConfig configured LED1 (PB8), LED2 (PA16) as output pins and KEY1 (PB24), + // KEY2 (PB20) as input pins. The interrupt edge comes from SysConfig; RegisterCallback + // and EnableInterrupt belong to the consumer (a Module or the User Code). + static MSPM0GPIO LED1(GPIO_LEDS_PIN_LED1_PORT, GPIO_LEDS_PIN_LED1_PIN, + GPIO_LEDS_PIN_LED1_IOMUX); + // ... + + // UART: TX with DMA; the receive side runs on byte interrupts. + static MSPM0UART uart0(MSPM0_UART_MAIN_INIT(UART_0, DMA_CH_UART0_TX, uart0_tx_buf, + sizeof(uart0_tx_buf), 5, 128)); + // ... + + // I2C: polling; the buffer stages DMA transfers. + static MSPM0I2C i2c0(MSPM0_I2C_INIT(I2C_0, PD0_BUSCLK_FREQ, i2c0_buf, sizeof(i2c0_buf), + 8), {I2C_0_BUS_SPEED_HZ}); + + // SPI: DMA for transfers longer than the threshold. + static MSPM0SPI spi1(MSPM0_SPI_INIT(SPI_1, PD1_BUSCLK_FREQ, DMA_CH_SPI1_RX, + DMA_CH_SPI1_TX, spi1_rx_buf, sizeof(spi1_rx_buf), spi1_tx_buf, + sizeof(spi1_tx_buf), 3)); + + // PWM: the channels of one timer share one period, which SysConfig configures. + static MSPM0PWM pwm_tima1_c0(MSPM0_PWM_CH(PWM_TIMA1, 0)); + static MSPM0PWM pwm_tima1_c1(MSPM0_PWM_CH(PWM_TIMA1, 1)); + + // Terminal on uart0 + STDIO::read_ = uart0.read_port_; + STDIO::write_ = uart0.write_port_; + static RamFS ramfs("XRobot"); + static Terminal<32, 32, 5, 5> terminal(ramfs); + /* User Code Begin 3 */ + KEY1.SetConfig({GPIO::Direction::FALL_INTERRUPT, GPIO::Pull::NONE}); + KEY1.RegisterCallback(GPIO::Callback::Create(OnKeyInterrupt, &key1_irq_count)); + KEY1.EnableInterrupt(); + /* User Code End 3 */ + XROBOT_MAIN(); +} +``` + +Every peripheral object is constructed from macros SysConfig generated, such as `GPIO_LEDS_PIN_LED1_PORT` for a GPIO or `UART_0` for a UART. The interrupts of these objects are enabled and prioritized by the LibXR drivers at construction, overriding the interrupt settings SysConfig made for the same IRQs; the edge of a pin interrupt comes from SysConfig, and registering the callback (`RegisterCallback` and `EnableInterrupt`) belongs to the consumer, shown in the User Code regions of the example. + +--- + +## Generated Objects and Naming + +Objects are generated for the configurations LibXR has drivers for: UART, I2C and SPI in controller mode, and PWM; every GPIO pin gets an object. The remaining configurations (ADC12, DAC12, MCAN, QEI, an I2C in target mode, an SPI in peripheral mode and so on) are listed under Other in the summary for display only. + +The objects are named: + +| Configuration | Object name | Example | +| --- | --- | --- | +| GPIO | the label of the pin in SysConfig (the `$name` without its `PIN_` prefix) | `LED1`, `KEY1` | +| UART, I2C, SPI | the lower-case peripheral instance name | `uart0`, `i2c1`, `spi1` | +| PWM | `pwm__c` | `pwm_tima1_c0` | + +Every CCP channel of a timer gets a PWM object; the channels of one timer share one period, which SysConfig configures. When `libxr_config.yaml` sets different frequencies for the channels of one timer, the generator prints a warning and the last `SetConfig` wins. + +The generation requirements of each configuration: + +- A UART needs a transmit DMA channel; the receive side runs on byte interrupts by default (`MSPM0_UART_MAIN_INIT`). A UART Extend instance with a receive DMA receives through a circular DMA (`MSPM0_UART_EXTEND_INIT`, the bytes of the receive ring in `rx_dma_buffer_size`), and its receive channel must be a FULL-DMA channel; the receive DMA channel of a UART Main instance is unused and warned about. A UART without transmit DMA makes generation fail. +- An SPI needs a pair of DMA channels, otherwise generation fails. +- An I2C works by polling; its buffer stages DMA transfers. + +--- + +## Clocks + +The generated code defines a BUSCLK constant for every power domain in use: the BUSCLK of PD1 is `CPUCLK_FREQ`, that of PD0 is `CPUCLK_FREQ` divided by the ULPCLK divider (the `DL_SYSCTL_setULPCLKDivider` of the generated code, 1 by default). The I2C driver resets the clock configuration of its peripherals itself (BUSCLK, divider 1), so its construction argument is the BUSCLK of the power domain; the SPI driver keeps the clock configuration SysConfig wrote, so its argument is the clock source SysConfig chose (BUSCLK, MFCLK at 4 MHz or LFCLK at 32.768 kHz) divided by its divider, and any other source makes generation fail. The macros SysConfig exports for an I2C or an SPI carry no clock frequency, and generation fails when the project has no power domain or `CPUCLK_FREQ`. A UART references the `INST_FREQUENCY` macro of SysConfig directly, and the source clock of a PWM is derived by the driver from `INST_CLK_FREQ`. + +--- + +## libxr_config.yaml + +`User/libxr_config.yaml` stores the settings of code generation. A missing file is created with the defaults; later runs fill in the missing settings and keep the values already present. A peripheral's settings section is written only when the project has that peripheral, one entry per instance keyed by the lower-case instance name, and a PWM entry by its object name. A null value (a key without a value in the YAML) takes the default; buffers and queues must be positive integers. + +The table lists the settings sections; defaults that differ from STM32 are noted: + +| Section | Keys and defaults | Notes | +| --- | --- | --- | +| `UART` | `tx_buffer_size: 128`, `rx_buffer_size: 128`, `tx_queue_size: 5` | A UART Extend instance also has `rx_dma_buffer_size: 128` (even) | +| `I2C` | `buffer_size: 32`, `dma_enable_min_size: 8` | | +| `SPI` | `tx_buffer_size: 32`, `rx_buffer_size: 32`, `dma_enable_min_size: 3` | | +| `PWM` | `frequency` (default null) | null calls no `SetConfig`, see [Generated Objects and Naming](#generated-objects-and-naming) | +| `Terminal` | `read_buff_size: 32`, `max_line_size: 32`, `max_arg_number: 5`, `max_history_number: 5` | template parameters of the terminal, see [Serial Ports and Terminal](../stm32/uart.md) | + +`terminal_source` follows the STM32 convention: an empty value or `none` generates no terminal; when the file has no such key yet (the first generation), the first UART is chosen. `tx_buffer_size` must also satisfy the driver's assertions: the transmit buffer is 2 × N bytes, 2 × N is a multiple of `2 * alignof(size_t)` (so N is a multiple of 4 on the Cortex-M0+), and N is at most the 0xFFFF bytes of one DMA transfer. Settings keys match without regard to case, and the spelling already in the file is kept. + +The following is the `User/libxr_config.yaml` generated on bsp-mspm0g3507-mini the first time: + +```yaml +generator: 6.0.0 +terminal_source: uart0 +SPI: + spi1: + tx_buffer_size: 32 + rx_buffer_size: 32 + dma_enable_min_size: 3 +I2C: + i2c0: + buffer_size: 32 + dma_enable_min_size: 8 + i2c1: + buffer_size: 32 + dma_enable_min_size: 8 +Terminal: + read_buff_size: 32 + max_line_size: 32 + max_arg_number: 5 + max_history_number: 5 +UART: + uart0: + tx_buffer_size: 128 + rx_buffer_size: 128 + tx_queue_size: 5 + uart1: + tx_buffer_size: 128 + rx_buffer_size: 128 + tx_queue_size: 5 +PWM: + pwm_tima1_c0: + frequency: + pwm_tima1_c1: + frequency: +``` + +The I2C bus speed and the UART baud rate come from the SysConfig project (such as `I2C_0_BUS_SPEED_HZ`); `libxr_config.yaml` has no setting for them. + +--- + +## Regenerating Code + +After changing the `.syscfg` or `User/libxr_config.yaml`, run `libxr mspm0 setup -d .` in the project root again, or regenerate only the files under `User/`: + +```bash +libxr parse -d . +libxr gen -i .config.yaml -o User/app_main.cpp +``` + +`.config.yaml` is written by `libxr parse`; a freshly cloned project does not have it, so run `libxr parse` first. The Generate LibXR Code action of the VS Code extension runs the two commands in sequence, see [VS Code Extension](../../env_setup/README.md#vs-code-extension). + +--- + +## Options + +The options of `libxr mspm0 setup` are listed below; `libxr mspm0 setup --help` lists the same. + +| Option | Description | +| ---------- | --------------------------- | +| `-d`, `--directory` | the project directory: one `.syscfg` file at its root (default: the current directory) | +| `-o`, `--output` | the output C++ file (default: `User/app_main.cpp` in DIRECTORY) | +| `--xrobot` / `--no-xrobot` | generate or skip the `XR_REGISTER` registrations and `XROBOT_MAIN();`, see [Integrate with XRobot](../xrobot_inter.md); when neither is given the output file keeps its choice, and a new file does not use XRobot | +| `--libxr-config` | path or URL of libxr_config.yaml (default: the `libxr_config.yaml` next to the output) | +| `--verbose` | enable debug logging | + +--- + +## Commands + +| Command | Description | +| ------------------------ | --------------------------------- | +| `libxr parse` | parse the `.syscfg` into `.config.yaml` | +| `libxr gen` | generate the entry source file and `app_main.h` from `.config.yaml`, and update `libxr_config.yaml` | +| `libxr pins` | print the package and pin layout of a model, see [Pin Layout](../pins.md) | + +The options and defaults of every command are listed by `libxr --help`. + +## Reference + +* [LibXR command-line tool and documentation](https://pypi.org/project/libxr/) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/pins.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/pins.md new file mode 100644 index 0000000..f35a4b1 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/pins.md @@ -0,0 +1,124 @@ +--- +id: code-gen-pins +title: Pin Layout (libxr pins) +sidebar_position: 4 +--- + +# Pin Layout (libxr pins) + +`libxr pins` prints the package and pin layout of a model: the position, name and selectable signals of every pin. The data comes from the vendors' pin data: ST's STM32_open_pin_data for STM32, the device data of TI SysConfig for MSPM0, and the `hpm_iomux.h` of the HPM SDK plus the pin tables of the HPM5300 datasheet for HPM. + +--- + +## Usage + +```bash +libxr pins STM32H723VGT6 +libxr pins MSPM0G3507 --package LQFP-64 --format json +libxr pins MSPM0G3507SPMR +libxr pins HPM5301 +libxr pins -d path/to/project +``` + +The model is a positional argument. The package of an MSPM0 comes from the package code in the model suffix first (`PM` of `MSPM0G3507SPMR`); when it cannot be told, give it with `--package` (`LQFP-64`, `PM` and the like all work). The model of an HPM is the SoC name; when the SoC has several packages, give it with `--package`. + +With `-d` naming a project directory, the printed layout overlays the signals the project has selected and their `libxr_config.yaml` settings. An STM32 project reads the `.ioc` file, an MSPM0 project reads the `.syscfg` at the root (the package comes from the SysConfig project), and an HPM project reads the `.hpmpc` under `boards/` and the pinmux functions `main.c` calls (the package comes with the parse result). The settings are read from the file `--libxr-config` names, by default `User/libxr_config.yaml` in the project. + +--- + +## Output + +```bash +$ libxr pins MSPM0G3507 --package LQFP-64 +``` + +```yaml +model: MSPM0G3507 +platform: mspm0 +part: MSPM0G3507 +package: LQFP-64(PM) +pin_count: 64 +source: + vendor: Texas Instruments + dataset: SysConfig dist/deviceData + version: 1.28.1+4785 + license: TI limited license (TI devices only) +peripherals: + ADC0: + kind: ADC + signals: + '0': + - PA27 + '1': + - PA26 +# ... +``` + +`source` records where the data comes from and its version; `peripherals` lists the pins every signal can sit on, per peripheral. + +--- + +## Project Overlay + +```bash +$ libxr pins -d . +``` + +With the project overlaid, the output gains two parts. The `pins` section lists the selected signals pin by pin, and a GPIO pin carries its label from the vendor project: + +```yaml + pins: + PB8: + signal: PB8 + peripheral: GPIOB + kind: GPIO + function: P8 + matched: true + label: LED1 +# ... +``` + +The `peripherals` section lists, per instance, the pins it occupies, its parameters in the vendor project, and the matching settings in `libxr_config.yaml`: + +```yaml + TIMA1: + kind: TIMA + pins: + CCP0: PA28 + CCP1: PA31 + sysconfig: + module: PWM + name: PWM_TIMA1 + params: {} + config: + - section: PWM + key: pwm_tima1_c0 + present: true + params: + frequency: null + - section: PWM + key: pwm_tima1_c1 + present: true + params: + frequency: null +# ... +``` + +A `matched` of `false` means the signal does not agree with what the pin can multiplex; it is given as it is. `config` is the list of the instance's settings entries in `libxr_config.yaml`: `present` tells whether the entry is already in the file, and `params` are the settings written; one PWM instance has one entry per channel. The GPIO renames of an HPM project are a whole section mapping: the `section: GPIO` entry has no `key`, and its `params` map pin names to new names. + +--- + +## Options + +| Option | Description | +| ---------- | --------------------------- | +| `model` | the model (default: the one of the project given with `-d`) | +| `-d`, `--directory` | the project directory: overlay the signals it has selected and their settings | +| `-c`, `--libxr-config` | the libxr_config.yaml to read the settings from (default: `User/libxr_config.yaml` in the project) | +| `-p`, `--package` | the package, for a model that does not name it (MSPM0: `LQFP-64`, `PM`, ...); with `-d` an MSPM0 takes it from the SysConfig project | +| `-f`, `--format` | the output format: `yaml` (default) or `json` | +| `--verbose` | enable debug logging | + +## Reference + +* [LibXR command-line tool and documentation](https://pypi.org/project/libxr/) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/xrobot_inter.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/xrobot_inter.md index 257ae61..7333c42 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/xrobot_inter.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/xrobot_inter.md @@ -1,7 +1,7 @@ --- id: code-gen-xrobot-inter title: Integrate with XRobot -sidebar_position: 2 +sidebar_position: 5 --- # Integrate with XRobot diff --git a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/README.md b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/README.md index 55961e7..9396ed8 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/README.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/README.md @@ -75,9 +75,11 @@ The xrobot version a BSP uses is recorded in the `xrobot:` field of `Modules/mod ### VS Code Extension -The VS Code extension [`XRobot.xrobot`](https://marketplace.visualstudio.com/items?itemName=XRobot.xrobot) adds two views to the activity bar, XRobot and LibXR. For a BSP with `Modules/modules.yaml`, the XRobot view shows its Modules, configurations and instances and makes changes through `xrobot` commands; for an STM32CubeMX project with an `.ioc` file at its root, the LibXR view shows `User/libxr_config.yaml` and the internal Flash layout and runs `libxr` commands. +The VS Code extension [`XRobot.xrobot`](https://marketplace.visualstudio.com/items?itemName=XRobot.xrobot) adds two views to the activity bar, XRobot and LibXR. When a BSP with `Modules/modules.yaml` is opened, the XRobot view shows its Modules, configurations and instances and makes changes through `xrobot` commands. -Extension 2.0.0 requires VS Code 1.108 or newer. The XRobot view needs xrobot 1.0.0 and `git`, the LibXR view needs libxr 6.0.0, both installed as in the previous section. The extension looks up these commands on `PATH`, in pip's per-user script directories and in the `xrobot.cli.extraPath` setting; when the commands are installed in a virtual environment, put the full path of its `bin` directory (`Scripts` on Windows) in `xrobot.cli.extraPath`. +The LibXR view recognizes the platform from the workspace root: a project with an `.ioc` at its root is an STM32CubeMX project, an `app.yaml` with `boards/*/*.hpmpc` is an HPM project, and a SysConfig `.syscfg` is an MSPM0 project. The view shows the platform and the settings of `User/libxr_config.yaml`; the settings can be edited there and the code is regenerated. "Generate LibXR Code" runs `libxr parse` and `libxr gen`, or the platform's `libxr stm32 setup`, `libxr mspm0 setup` or `libxr hpm setup` while there is no `libxr_config.yaml` yet. For an MSPM0 project, "Open in SysConfig" opens the `.syscfg` in the standalone SysConfig; for an HPM project, "Open in HPM Pinmux Tool" opens the `.hpmpc` with HPMicro's HPM Pinmux Tool extension. Both views can open the package drawing of the chip (the pin layout, `libxr pins`, which needs a libxr that has the command): the selected pins are coloured by peripheral category, the package of an MSPM0 comes from its SysConfig project, and the panel is read-only. + +Extension 2.0.0 requires VS Code 1.108 or newer. The XRobot view needs xrobot 1.0.0 and `git`, the LibXR view needs libxr 6.0.0, both installed as in the previous section. The extension looks up these commands on `PATH`, in pip's per-user script directories and in the `xrobot.cli.extraPath` setting; when the commands are installed in a virtual environment, put the full path of its `bin` directory (`Scripts` on Windows) in `xrobot.cli.extraPath`. "Open in SysConfig" for MSPM0 additionally uses the settings `xrobot.libxr.sysconfigTool` and `xrobot.libxr.mspm0SdkDir`; when they are empty, the environment variables `SYSCONFIG_TOOL` and `MSPM0_SDK_INSTALL_DIR` of the same names are used. ## Platforms diff --git a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md index 710f491..4ee3758 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md @@ -6,116 +6,90 @@ sidebar_position: 5 # HPM Environment Setup -This page describes how LibXR integrates on HPM. - -The template project is a starting point: - -- [HPM5301_LibXR_Template](https://github.com/xrobot-org/HPM5301_LibXR_Template) +An HPM project is a standard HPM SDK CMake project built with a RISC-V GCC toolchain (compiler prefix `riscv32-unknown-elf-`). The BSPs [bsp-hpm5301evklite](https://github.com/xrobot-org/bsp-hpm5301evklite) and [bsp-rmcs-slave-lite](https://github.com/xrobot-org/bsp-rmcs-slave-lite) are fully buildable projects and serve as the examples on this page; [Code Generation](../code_gen/hpm/README.md) describes how `libxr hpm setup` generates LibXR code in such a project. ## Toolchain -HPM projects use a RISC-V GCC toolchain with the compiler prefix `riscv32-unknown-elf-`. The HPM SDK reads the installation directory of the toolchain (the parent of `bin`) from the environment variable `GNURISCV_TOOLCHAIN_PATH`, and the compiler is `bin/riscv32-unknown-elf-gcc` inside it; without this variable, the CMake configuration fails with `GNURISCV_TOOLCHAIN_PATH is not set yet`. +The HPM SDK reads the toolchain installation directory (the parent of `bin`) from the environment variable `GNURISCV_TOOLCHAIN_PATH`, and the compiler is `bin/riscv32-unknown-elf-gcc` inside it; when the variable is missing, the CMake configuration fails with `GNURISCV_TOOLCHAIN_PATH is not set yet`. The SDK itself is pointed to by `HPM_SDK_BASE`. Sources of the toolchain: -- Windows: HPMicro's development environment package [sdk_env](https://github.com/hpmicro/sdk_env); the toolchain goes into its `toolchains/` directory, and the command prompt opened by `start_cmd.cmd` sets `GNURISCV_TOOLCHAIN_PATH` and the other environment variables; -- Linux x64: the `riscv32-unknown-elf` toolchain released by [hpm-linux-gcc-release v0.1.0](https://github.com/Jiu-xiao/hpm-linux-gcc-release/releases/tag/v0.1.0); -- Docker: `ghcr.io/xrobot-org/docker-image-hpm:main` has that Linux toolchain (GCC 15.2.0) in `/opt/hpm-riscv32-unknown-elf` and records the path in the environment variable `XR_HPM_TOOLCHAIN_ROOT`; see [Docker Environment Setup](docker.md). +- Windows: the HPMicro development environment package [sdk_env](https://github.com/hpmicro/sdk_env), whose `toolchains/` directory holds the toolchain; the command line opened by `start_cmd.cmd` sets `GNURISCV_TOOLCHAIN_PATH` and the other environment variables; +- Linux x64: the `riscv32-unknown-elf` toolchain published as [hpm-linux-gcc-release v0.1.0](https://github.com/Jiu-xiao/hpm-linux-gcc-release/releases/tag/v0.1.0); +- Docker: `ghcr.io/xrobot-org/docker-image-hpm:main` ships that Linux toolchain (GCC 15.2.0) in `/opt/hpm-riscv32-unknown-elf`, with the path recorded in both `GNURISCV_TOOLCHAIN_PATH` and `XR_HPM_TOOLCHAIN_ROOT`, see [Docker Environment Setup](docker.md). + +## Project Layout + +Taking bsp-hpm5301evklite as the example: + +```text +. +|-- CMakeLists.txt +|-- CMakePresets.json +|-- app.yaml +|-- main.c +|-- boards/ +| `-- hpm5301evklite/ +| |-- tool_config.hpmpc +| |-- pinmux.c +| `-- ... +|-- cmake/ +| `-- LibXR.CMake +|-- User/ +| `-- app_main.cpp +`-- libxr/ +``` + +* `CMakeLists.txt` brings in the HPM SDK with `find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})`, points `BOARD_SEARCH_PATH` at `boards/`, and sets `CONFIG_DMA_MGR 1` (the LibXR HPM drivers depend on the SDK dma_mgr component) +* `app.yaml` declares the dependency on `board_gpt_pin`; `boards//` contains the single `.hpmpc` file (the BSPs name it `tool_config.hpmpc`) — together these mark out an HPM project, which is how `libxr hpm setup` and the VS Code extension recognize one +* `boards//pinmux.c` is generated by the HPM Pinmux Tool from `tool_config.hpmpc` and provides `init_bsp_pins()` +* `main.c` sits in the project root: `init_bsp_pins()` first, then the SDK board's `board_init()`, then the clock functions of the peripherals (`init_uart3_clock()` and its siblings), and finally `app_main()` +* `User/` holds the generated `app_main.cpp`; `libxr hpm setup` generates `libxr_config.yaml` next to it +* `libxr/` is the LibXR submodule + +## Build -The image does not set `GNURISCV_TOOLCHAIN_PATH`. Before building in the image, set it from `XR_HPM_TOOLCHAIN_ROOT`, as the CI of the template project does: +`CMakePresets.json` provides the `debug-flash-xip`, `debug-ram` and `release-flash-xip` presets (Ninja generator, `HPM_BUILD_TYPE` of `flash_xip` or `ram`): ```bash -export GNURISCV_TOOLCHAIN_PATH="$XR_HPM_TOOLCHAIN_ROOT" cmake --preset release-flash-xip cmake --build --preset release-flash-xip ``` -## What Already Exists in Mainline - -According to the current `driver/hpm` directory in `libxr master`, the tree already contains these drivers: +The artifacts land in `build/output/`, for example `demo.elf` and `demo.bin`. -- `hpm_gpio.*` -- `hpm_i2c.*` -- `hpm_pwm.*` -- `hpm_timebase.*` +## CMake Integration -`driver/hpm/CMakeLists.txt` pulls them into the build directly. - -## Basic Integration Model - -The following is an excerpt from `cmake/LibXR.CMake` of [HPM5301_LibXR_Template](https://github.com/xrobot-org/HPM5301_LibXR_Template): +`cmake/LibXR.CMake` selects the platform with three variables and adds LibXR as a subproject: ```cmake -# LibXR platform/driver selection set(LIBXR_SYSTEM None) set(LIBXR_DRIVER hpm) set(LIBXR_NO_EIGEN True) - -# ... - -# Import LibXR as a subproject -add_subdirectory("${LIBXR_DIR}" "${CMAKE_CURRENT_BINARY_DIR}/libxr") - -# Make LibXR compile with the same HPM SDK compile options/includes. -if(DEFINED HPM_SDK_LIB_ITF AND TARGET ${HPM_SDK_LIB_ITF}) - target_link_libraries(xr PUBLIC ${HPM_SDK_LIB_ITF}) -endif() - -# Let app sources directly include LibXR headers. -if(TARGET app) - target_link_libraries(app PUBLIC xr) -endif() - -# Ensure LibXR object files are linked into the final ELF target. -if(DEFINED APP_ELF_NAME AND TARGET ${APP_ELF_NAME}) - target_link_libraries(${APP_ELF_NAME} xr) -endif() ``` -`xr` links `${HPM_SDK_LIB_ITF}`, so LibXR is compiled with the same HPM SDK options and include paths as the application. - -The preconditions are: - -- the project already builds with the HPM SDK -- the project already wires in HPM SDK headers, startup files, linker scripts, and board initialization -- LibXR is added on top of that baseline to provide `driver/hpm` plus the common runtime/middleware layers +`xr` links `${HPM_SDK_LIB_ITF}`, so LibXR compiles with the same options and include paths as the SDK; the application target `app` and the final ELF target link `xr`. Toolchain detection is handled by `find_package(hpm-sdk)`. -## Practical Entry Order +## The LibXR HPM Drivers -An HPM project integrates LibXR in this order: +`driver/hpm` provides four drivers, added to the build by the directory's `CMakeLists.txt`: -1. get the minimal HPM SDK or template project running first -2. verify that the project can already `add_subdirectory(libxr)` cleanly -3. then bring in concrete peripherals such as `HPMGPIO`, `HPMI2C`, `HPMPWM`, or `HPMTimebase` - -The project sets up the pin mux and the clocks of a peripheral before it creates the LibXR object, for example by calling the pin and clock functions generated by the HPM Pinmux Tool; the LibXR HPM drivers call the SDK drivers only, not the board functions in `board.c`: - -```cpp -static LibXR::HPMI2C i2c3(HPM_I2C3, clock_i2c3, {100000}); -static LibXR::HPMPWM pwm(HPM_PWM0, clock_mot0, 0, 0, LibXR::HPMPWM::Polarity::NORMAL); -``` +- `hpm_gpio.*`: GPIO +- `hpm_i2c.*`: I2C master +- `hpm_pwm.*`: PWM +- `hpm_timebase.*`: timebase on MCHTMR -## Current Boundary of `I2C` +The drivers call SDK driver functions only; pin muxing, clocks and the initialization order belong to the project (`init_bsp_pins()`, `board_init()` and the `init_*_clock()` functions), and the LibXR objects are created in `app_main()`. The DMA-backed I2C path depends on dma_mgr, which the BSPs enable with `CONFIG_DMA_MGR 1`. -The current HPM `I2C` line is no longer just a simple blocking wrapper. According to the current headers, `HPMI2C` already covers: +`HPMI2C` implements the LibXR I2C master abstraction on top of the SDK's `hpm_i2c_drv`: blocking byte-stream transfers and register/memory-address transfers; 7-bit master addressing by default with `SetAddressMode()` switching to the SDK's 10-bit master addressing; with dma_mgr present, wait strategies such as POLLING and CALLBACK can use the DMA-backed path; on typical master failures such as a timeout, a busy bus or no response, the driver rebuilds the controller with its most recent successful configuration. -- 7-bit / 10-bit master addressing modes -- sequence frames -- transfer flags -- optional DMA-helper background paths -- wait policies and recovery logic +`HPMPWM` takes the same constructor arguments on both code paths (peripheral address, clock, output channel index, comparator index, polarity): SoCs with a standard PWM peripheral go through the SDK's `hpm_pwm_drv`, the others through the GPTMR path. `SetDutyCycle()` accepts a duty cycle of 0.0 to 1.0, and `SetConfig()` sets the frequency. -Whether these capabilities can be used in a given project depends on: +## Docker Build -- whether the HPM SDK headers are complete -- whether the project enables the SDK `dma_mgr` component (`CONFIG_DMA_MGR`); the build stops with an error otherwise -- whether the pins and clocks are set up before the object is created. Bus recovery uses the reset signal of the I2C controller itself (9 SCL pulses). +The image `ghcr.io/xrobot-org/docker-image-hpm:main` ships the RISC-V toolchain (GCC 15.2.0), CMake, Ninja and the HPM SDK v1.13.0, with `GNURISCV_TOOLCHAIN_PATH` and `HPM_SDK_BASE` already set: -## Current Boundary of `PWM` - -`HPMPWM` currently supports two paths in mainline: - -- if the SoC provides a standard PWM peripheral, it uses `hpm_pwm_drv` -- otherwise the code still has a `GPTMR` fallback path - -The path depends on the chip and the SDK macro conditions. +```bash +docker run --rm -v "$PWD:/work" -w /work ghcr.io/xrobot-org/docker-image-hpm:main \ + bash -c 'cmake --preset release-flash-xip && cmake --build --preset release-flash-xip' +``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/mspm0.md b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/mspm0.md index d9425a7..eaffd91 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/mspm0.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/mspm0.md @@ -6,179 +6,92 @@ sidebar_position: 3.5 # MSPM0 Environment Setup -The current documented baseline uses the GNU Arm Embedded Toolchain with prefix `arm-none-eabi-`. Compatibility with TI Arm Clang has not been verified in this line. +An MSPM0 project builds on the TI MSPM0 SDK and SysConfig, with CMake, Ninja and the GNU Arm Embedded Toolchain (compiler prefix `arm-none-eabi-`). The BSPs [bsp-mspm0g3507-mini](https://github.com/xrobot-org/bsp-mspm0g3507-mini) and [bsp-mspm0g3519-mini](https://github.com/xrobot-org/bsp-mspm0g3519-mini) are fully buildable projects and serve as the examples on this page; [Code Generation](../code_gen/mspm0/README.md) describes how `libxr mspm0 setup` generates LibXR code in such a project. -If you only need a quick starting point, use the MSPM0 Docker image: +For a quick start the Docker image `ghcr.io/xrobot-org/docker-image-mspm0:main` is recommended, see [Docker Build](#docker-build) below. -- `ghcr.io/xrobot-org/docker-image-mspm0:main` +## Base Environment -## CMake Configuration +A local build installs: -For an external LibXR-based MSPM0 project, the usual shape is: +* CMake (3.20 or newer) and Ninja +* `arm-none-eabi-gcc` ([GNU Arm Embedded Toolchain](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads)) +* [TI MSPM0 SDK](https://www.ti.com/tool/MSPM0-SDK) +* The [SysConfig](https://www.ti.com/tool/SYSCONFIG) standalone installation, whose `sysconfig_cli` is the command-line entry point -```cmake -set(LIBXR_SYSTEM None) -set(LIBXR_DRIVER mspm0) -set(LIBXR_NO_EIGEN True) -set(MSPM0_SDK_DIR "${CMAKE_CURRENT_SOURCE_DIR}/mspm0-sdk") - -include("${CMAKE_SOURCE_DIR}/cmake/LibXR.CMake") -``` - -Meaning: +The CMake project finds the SDK and SysConfig through two variables, named after the SDK's `imports.mak`; environment variables and the CMake cache (`-D`) both work: -- `LIBXR_SYSTEM None`: bare-metal integration -- `LIBXR_DRIVER mspm0`: enable the LibXR MSPM0 driver directory -- `MSPM0_SDK_DIR`: points to the TI MSPM0 SDK root -- `cmake/LibXR.CMake`: wires LibXR and the MSPM0 SDK into the project +* `MSPM0_SDK_INSTALL_DIR`: the MSPM0 SDK root +* `SYSCONFIG_TOOL`: the full path of the SysConfig command line, `sysconfig_cli.bat` on Windows and `sysconfig_cli.sh` on Linux -Typical responsibility split: +A Windows PowerShell example: -- the root `CMakeLists.txt` owns the final application target, user sources, link options, and post-processing -- `cmake/LibXR.CMake` owns LibXR platform selection, SDK path checks, SysConfig output checks, and MSPM0-specific dependencies for the `xr` target +```powershell +$env:MSPM0_SDK_INSTALL_DIR = "C:\ti\mspm0_sdk_2_11_00_07" +$env:SYSCONFIG_TOOL = "C:\ti\sysconfig_1.28.1\sysconfig_cli.bat" +``` -## Directory Layout +## Project Layout -The template project [MSPM0G3507 LibXR Template](https://github.com/xrobot-org/MSPM0G3507_LibXR_Template) is laid out as follows: +The BSP directory structure: ```text . |-- CMakeLists.txt |-- CMakePresets.json +|-- main.c +|-- mspm0g3507_minidb48.syscfg |-- cmake/ | |-- LibXR.CMake +| |-- MSPM0SysConfig.cmake | `-- arm-none-eabi-gcc.cmake -|-- Core/ |-- User/ -|-- libxr/ -|-- mspm0-sdk/ -|-- scripts/ -| `-- fetch-mspm0-sdk.sh -`-- sysconfig/ +| |-- app_main.cpp +| `-- libxr_config.yaml +|-- Modules/ +`-- libxr/ ``` -Where: - -- `libxr/` is the LibXR submodule -- `mspm0-sdk/` is the TI MSPM0 SDK submodule -- `User/` holds the application sources (`main.c`, `app_main.cpp`) -- `Core/` holds the syscalls stubs and the stack-reservation linker script -- `sysconfig/` holds the SysConfig project and its generated files -- `scripts/fetch-mspm0-sdk.sh` fetches only the SDK files the build needs +* `main.c` sits in the project root, calls the SysConfig-generated `SYSCFG_DL_init()` for the clocks, pins and peripherals, and then enters `app_main()` +* The `.syscfg` file is the SysConfig project, in the project root; it describes the device, clocks, pins and peripherals, and changing the device means changing this one file +* `cmake/MSPM0SysConfig.cmake` runs the SysConfig command line at the CMake configure step and generates `ti_msp_dl_config.c/.h`, `device.opt`, the linker script and the rest into the build directory; CMake tracks changes to the `.syscfg` and regenerates on the next build +* `User/` holds the generated `app_main.cpp` and `libxr_config.yaml` +* `libxr/` is the LibXR submodule -When the SDK is outside the repository, point `MSPM0_SDK_DIR` at it. +## CMake Integration -## SysConfig Output Requirements +`cmake/LibXR.CMake` brings LibXR into the project with three variables: -MSPM0 projects typically depend on SysConfig-generated files. CMake is normally responsible only for finding and consuming them, not for invoking SysConfig automatically. - -Recommended location: - -```text -sysconfig/ +```cmake +set(LIBXR_SYSTEM None) +set(LIBXR_DRIVER mspm0) +set(LIBXR_NO_EIGEN True) ``` -CMake usually needs these files to exist: - -- `ti_msp*_config.c` -- `ti_msp*_config.h` -- `device.opt` -- one `.lds` linker script, commonly named `device_linker.lds` - -If the project uses automatic discovery, the root project does not need to hard-code names such as `ti_msp_dl_config.c`; it is enough to keep the generated files under `sysconfig/`. - -After the `.syscfg` file changes, regenerate these outputs before running CMake again. - -## Chip-Specific Items - -Even though this page is generic, several items must still track the actual chip or board: - -- startup-file path -- `driverlib.a` location -- SysConfig target board / target chip -- compiler macros such as `__MSPM0xxxx__` - -Many MSPM0 build issues are ultimately “chip-specific files were not switched consistently.” - -## MSPM0 Drivers +`LIBXR_SYSTEM None` is the bare-metal system and `LIBXR_DRIVER mspm0` enables the LibXR `driver/mspm0` driver directory. The newlib system calls come from `libxr/driver/mspm0/mspm0_syscalls.c`; stub functions such as `_write` or `_read` written elsewhere in the project would duplicate it. -`driver/mspm0/CMakeLists.txt` builds these drivers: +## Build -- `mspm0_gpio.*` -- `mspm0_pwm.*` -- `mspm0_timebase.*` -- `mspm0_uart.*` -- `mspm0_spi.*` -- `mspm0_i2c.*` -- `mspm0_group1_shared.cpp` -- `mspm0_atomic_shim.c` +`CMakePresets.json` provides the `debug` and `release` presets (Ninja generator, toolchain file `cmake/arm-none-eabi-gcc.cmake`): -SPI/I2C are already part of the LibXR MSPM0 build, so upper projects do not need to add those sources again. The project still supplies the matching SDK, SysConfig output, and peripheral initialization. - -## Toolchain Requirements - -Recommended tools: - -- `cmake` -- `ninja` -- `arm-none-eabi-gcc` -- `arm-none-eabi-g++` -- `arm-none-eabi-objcopy` - -A typical direct build command on the host looks like this: - -```powershell -cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=arm-none-eabi-gcc -DCMAKE_CXX_COMPILER=arm-none-eabi-g++ -DCMAKE_ASM_COMPILER=arm-none-eabi-gcc -cmake --build build +```bash +cmake --preset debug +cmake --build --preset debug ``` +The artifacts land in `build/debug/`: `mspm0_minidb48.elf`, `.hex` and `.bin`. + ## Docker Build -The image `ghcr.io/xrobot-org/docker-image-mspm0:main` provides `arm-none-eabi-gcc`, CMake and Ninja. In the template project: +The image `ghcr.io/xrobot-org/docker-image-mspm0:main` ships `arm-none-eabi-gcc`, CMake, Ninja, the MSPM0 SDK and SysConfig, with `MSPM0_SDK_INSTALL_DIR` and `SYSCONFIG_TOOL` already set: ```bash -git submodule update --init libxr -sh scripts/fetch-mspm0-sdk.sh docker run --rm -v "$PWD:/work" -w /work ghcr.io/xrobot-org/docker-image-mspm0:main \ bash -c 'cmake --preset release && cmake --build --preset release' ``` -The output is `build/release/ti_mspm0_libxr_dev.elf`, `.hex` and `.bin`. - -## Common Problems - -### CMake cannot find the MSPM0 SDK - -Check whether: - -```text -${MSPM0_SDK_DIR}/source -``` - -exists. If it does not, the SDK path is wrong. - -### CMake cannot find SysConfig-generated files - -Check whether `sysconfig/` already contains: - -- `ti_msp*_config.c` -- `ti_msp*_config.h` -- `device.opt` -- `.lds` - -If files are missing, SysConfig output has not been generated yet, or the output directory no longer matches the CMake expectation. - -### Link warnings such as `_write/_read/_close` - -If the project uses: - -```text ---specs=nano.specs ---specs=nosys.specs -``` - -then warnings about `_write`, `_read`, `_close`, `_isatty`, `_fstat`, and similar symbols are common. As long as the final ELF is produced successfully, bare-metal runtime behavior is usually unaffected. +## FAQ -## Example Project +### CMake configuration reports the MSPM0 SDK or SysConfig missing -- [MSPM0G3507 LibXR Template](https://github.com/xrobot-org/MSPM0G3507_LibXR_Template) +The configure step checks both variables: `MSPM0_SDK_INSTALL_DIR` should contain `.metadata/product.json`, and `SYSCONFIG_TOOL` should point at the `sysconfig_cli` script itself. A failed check ends the configuration with an error that includes the current variable value; fix the variable through the environment or `-D` as the message suggests and configure again. From 73cf01dc10033d835ffe76b11bf39e319e0fc366 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Thu, 8 Oct 2026 00:00:47 +0100 Subject: [PATCH 02/16] Polish the MSPM0, HPM and pin layout pages after the read-through --- docs/code_gen/hpm/README.md | 2 +- docs/code_gen/mspm0/README.md | 4 ++-- docs/code_gen/pins.md | 2 +- docs/env_setup/hpm.md | 2 +- .../current/code_gen/hpm/README.md | 2 +- .../docusaurus-plugin-content-docs/current/code_gen/pins.md | 2 +- .../docusaurus-plugin-content-docs/current/env_setup/hpm.md | 2 +- 7 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/code_gen/hpm/README.md b/docs/code_gen/hpm/README.md index c3550e8..bef763a 100644 --- a/docs/code_gen/hpm/README.md +++ b/docs/code_gen/hpm/README.md @@ -214,7 +214,7 @@ GPIO: ## 支持的 SoC 与封装 -当前数据覆盖 HPM5301(QFN48)和 HPM5361(LQFP100、LQFP64、QFN48);HPM53M1 暂不支持。引脚数据来自 HPM SDK 的 `hpm_iomux.h` 和 HPM5300 数据手册的引脚表。 +当前数据覆盖 HPM5301(QFN48)和 HPM5361(LQFP100、LQFP64、QFN48);HPM53M1 暂不支持。引脚数据来自 HPM SDK 的 `hpm_iomux.h`、`hpm_soc_ip.h` 和 HPM5300 数据手册的引脚表。 --- diff --git a/docs/code_gen/mspm0/README.md b/docs/code_gen/mspm0/README.md index 749b5e2..35dec3d 100644 --- a/docs/code_gen/mspm0/README.md +++ b/docs/code_gen/mspm0/README.md @@ -6,7 +6,7 @@ sidebar_position: 2 # MSPM0 代码生成 -代码生成器的 `libxr mspm0 setup` 命令把 TI SysConfig 工程接入 LibXR:解析工程根目录的 `.syscfg` 文件,生成 C++ 初始化代码。SysConfig 负责时钟、引脚、DMA 通道和外设的配置(`main.c` 中的 `SYSCFG_DL_init()`),生成的代码声明 LibXR 对象并把对象注册到 XRobot,构造参数全部使用 SysConfig 生成的宏。 +代码生成器的 `libxr mspm0 setup` 命令把 TI SysConfig 工程接入 LibXR:解析工程根目录的 `.syscfg` 文件,生成 C++ 初始化代码。SysConfig 负责时钟、引脚、DMA 通道和外设的配置(`main.c` 中的 `SYSCFG_DL_init()`),生成的代码声明 LibXR 对象,XRobot 工程在生成时用 `XR_REGISTER` 把对象注册进去,构造参数全部使用 SysConfig 生成的宏。 --- @@ -18,7 +18,7 @@ sidebar_position: 2 libxr mspm0 setup -d . ``` -工程根目录放置一个 `.syscfg` 文件。该命令依次完成以下步骤: +工程根目录有一份 `.syscfg` 文件。该命令依次完成以下步骤: 1. 工程目录还没有 `.gitignore` 时创建一个,忽略 `build`、`.history`、`.cache`、`CMakeFiles` 和 `.config.yaml`;已有的 `.gitignore` 保持不变; 2. 解析 `.syscfg`,写出 `.config.yaml`; diff --git a/docs/code_gen/pins.md b/docs/code_gen/pins.md index f5e63a0..c90b45b 100644 --- a/docs/code_gen/pins.md +++ b/docs/code_gen/pins.md @@ -6,7 +6,7 @@ sidebar_position: 4 # 引脚布局(libxr pins) -`libxr pins` 打印一个型号的封装与引脚布局:每个引脚的位置、名称和可选的信号。数据来自各厂商的引脚数据:STM32 为 ST 的 STM32_open_pin_data,MSPM0 为 TI SysConfig 的器件数据,HPM 为 HPM SDK 的 `hpm_iomux.h` 和 HPM5300 数据手册的引脚表。 +`libxr pins` 打印一个型号的封装与引脚布局:每个引脚的位置、名称和可选的信号。数据来自各厂商的引脚数据:STM32 为 ST 的 STM32_open_pin_data,MSPM0 为 TI SysConfig 的器件数据,HPM 为 HPM SDK 的 `hpm_iomux.h`、`hpm_soc_ip.h` 和 HPM5300 数据手册的引脚表。 --- diff --git a/docs/env_setup/hpm.md b/docs/env_setup/hpm.md index cd732a6..7c3a80c 100644 --- a/docs/env_setup/hpm.md +++ b/docs/env_setup/hpm.md @@ -40,7 +40,7 @@ HPM SDK 从环境变量 `GNURISCV_TOOLCHAIN_PATH` 读取工具链的安装目录 `-- libxr/ ``` -* `CMakeLists.txt` 用 `find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})` 引入 HPM SDK,`BOARD_SEARCH_PATH` 指向 `boards/`,并设置 `CONFIG_DMA_MGR 1`(LibXR 的 HPM 驱动依赖 SDK 的 dma_mgr 组件) +* `CMakeLists.txt` 用 `find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})` 引入 HPM SDK,`BOARD_SEARCH_PATH` 指向 `boards/`,并设置 `CONFIG_DMA_MGR 1`(I2C 驱动的 DMA 后台路径使用它) * `app.yaml` 声明对 `board_gpt_pin` 的依赖;`boards//` 下有唯一的 `.hpmpc` 文件(BSP 命名为 `tool_config.hpmpc`)——两者共同构成 HPM 工程的特征,`libxr hpm setup` 和 VS Code 扩展据此识别工程 * `boards//pinmux.c` 由 HPM Pinmux Tool 从 `tool_config.hpmpc` 生成,提供 `init_bsp_pins()` * `main.c` 在工程根目录:先 `init_bsp_pins()`,再 SDK 板级的 `board_init()`,然后调用各外设的时钟函数(`init_uart3_clock()` 一类),最后进入 `app_main()` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md index d49c2ad..fa48a75 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md @@ -214,7 +214,7 @@ After changing the value of `pa10` in the `GPIO` section to `LED` and regenerati ## Supported SoCs and Packages -The data currently covers HPM5301 (QFN48) and HPM5361 (LQFP100, LQFP64, QFN48); HPM53M1 is not supported yet. The pin data comes from the `hpm_iomux.h` of the HPM SDK and the pin tables of the HPM5300 datasheet. +The data currently covers HPM5301 (QFN48) and HPM5361 (LQFP100, LQFP64, QFN48); HPM53M1 is not supported yet. The pin data comes from the `hpm_iomux.h` and `hpm_soc_ip.h` of the HPM SDK and the pin tables of the HPM5300 datasheet. --- diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/pins.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/pins.md index f35a4b1..0b0b210 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/pins.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/pins.md @@ -6,7 +6,7 @@ sidebar_position: 4 # Pin Layout (libxr pins) -`libxr pins` prints the package and pin layout of a model: the position, name and selectable signals of every pin. The data comes from the vendors' pin data: ST's STM32_open_pin_data for STM32, the device data of TI SysConfig for MSPM0, and the `hpm_iomux.h` of the HPM SDK plus the pin tables of the HPM5300 datasheet for HPM. +`libxr pins` prints the package and pin layout of a model: the position, name and selectable signals of every pin. The data comes from the vendors' pin data: ST's STM32_open_pin_data for STM32, the device data of TI SysConfig for MSPM0, and the `hpm_iomux.h` and `hpm_soc_ip.h` of the HPM SDK plus the pin tables of the HPM5300 datasheet for HPM. --- diff --git a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md index 4ee3758..0cffbcf 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md @@ -40,7 +40,7 @@ Taking bsp-hpm5301evklite as the example: `-- libxr/ ``` -* `CMakeLists.txt` brings in the HPM SDK with `find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})`, points `BOARD_SEARCH_PATH` at `boards/`, and sets `CONFIG_DMA_MGR 1` (the LibXR HPM drivers depend on the SDK dma_mgr component) +* `CMakeLists.txt` brings in the HPM SDK with `find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})`, points `BOARD_SEARCH_PATH` at `boards/`, and sets `CONFIG_DMA_MGR 1` (the DMA-backed I2C path uses it) * `app.yaml` declares the dependency on `board_gpt_pin`; `boards//` contains the single `.hpmpc` file (the BSPs name it `tool_config.hpmpc`) — together these mark out an HPM project, which is how `libxr hpm setup` and the VS Code extension recognize one * `boards//pinmux.c` is generated by the HPM Pinmux Tool from `tool_config.hpmpc` and provides `init_bsp_pins()` * `main.c` sits in the project root: `init_bsp_pins()` first, then the SDK board's `board_init()`, then the clock functions of the peripherals (`init_uart3_clock()` and its siblings), and finally `app_main()` From b7f6b2a8711fef0ecee624ce2d71ec8636524be9 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Thu, 8 Oct 2026 00:24:05 +0100 Subject: [PATCH 03/16] Cover the dma_mgr dependency and the remaining MSPM0 and HPM generation constraints --- docs/code_gen/hpm/README.md | 6 ++++-- docs/code_gen/mspm0/README.md | 4 +++- docs/env_setup/hpm.md | 6 +++--- .../current/code_gen/hpm/README.md | 6 ++++-- .../current/code_gen/mspm0/README.md | 4 +++- .../docusaurus-plugin-content-docs/current/env_setup/hpm.md | 6 +++--- 6 files changed, 20 insertions(+), 12 deletions(-) diff --git a/docs/code_gen/hpm/README.md b/docs/code_gen/hpm/README.md index bef763a..0a29332 100644 --- a/docs/code_gen/hpm/README.md +++ b/docs/code_gen/hpm/README.md @@ -14,6 +14,8 @@ sidebar_position: 3 工程是根目录有 `app.yaml`、`boards//` 下恰有一个 `.hpmpc` 文件的目录。选中的信号来自 `.hpmpc` 的 `selectPins`,以及 `main.c` 中 `main` 在预处理条件之外调用的 pinmux 函数;`.hpmpc` 中有而 `main` 没有调用的函数不参与。函数里的每个信号按 `hpm_iomux.h` 的宏名对照 SoC 封装的布局核对,封装没有的 pad 或 pad 不能承载的信号给出警告。 +gpiom 设置把引脚分给 GPIO0 以外的控制器(`gpioController` 不为 1,未写时是 GPIO0)时,不为它生成对象,每个这样的引脚给出一条警告。 + `main` 只在预处理条件里调用的 pinmux 函数同样不读(生成的对象不能依赖编译选项),每个这样的函数给出一条警告;调用全部在预处理条件里时读不到引脚。`main` 一次 pinmux 函数都没有调用时退回读 `init_bsp_pins`,工程没有这个函数时读不到引脚。 --- @@ -161,7 +163,7 @@ extern "C" void app_main(void) } ``` -引脚和时钟在 `main.c` 调用的 pinmux 函数中配置完毕,构造参数引用 SDK 的宏(`HPM_GPIO0`、`GPIO_DI_GPIOA`、`IRQn_GPIO0_A`、`HPM_I2C3`、`clock_i2c3`)。GPIO 对象带所属端口的 IRQ,端口的中断服务程序由 LibXR 驱动提供,边沿来自 pinmux,回调的登记(`RegisterCallback` 和 `EnableInterrupt`)由使用方完成。I2C 使用 dma_mgr 的后台路径时需要工程启用 `CONFIG_DMA_MGR`。 +引脚和时钟在 `main.c` 调用的 pinmux 函数中配置完毕,构造参数引用 SDK 的宏(`HPM_GPIO0`、`GPIO_DI_GPIOA`、`IRQn_GPIO0_A`、`HPM_I2C3`、`clock_i2c3`)。GPIO 对象带所属端口的 IRQ,端口的中断服务程序由 LibXR 驱动提供,边沿来自 pinmux,回调的登记(`RegisterCallback` 和 `EnableInterrupt`)由使用方完成。LibXR 的 HPM 驱动依赖 SDK 的 `dma_mgr` 组件,工程需要启用 `CONFIG_DMA_MGR`(BSP 已启用)。 --- @@ -187,7 +189,7 @@ GPTMR 的每个比较器(COMP_n)生成一个 PWM 对象,走 `HPMPWM` 的 G | 段 | 键与默认值 | 说明 | | --- | --- | --- | -| `I2C` | `speed: 100000` | 总线速率,单位 Hz,段中每个实例一项,键为小写的实例名 | +| `I2C` | `speed: 100000` | 总线速率,单位 Hz,段中每个实例一项,键为小写的实例名;取值须为 100000、400000 或 1000000(HPM 的 I2C 驱动支持的档位),其他值使生成报错 | | `PWM` | `frequency`(默认 null) | 每个对象一项;null 时不调用 `SetConfig`,设置了必须是正整数(Hz) | | `GPIO` | 键为引脚名,值为新名字 | 引脚改名;值为 null 时保留默认名。段中列出工程读到的每个引脚 | diff --git a/docs/code_gen/mspm0/README.md b/docs/code_gen/mspm0/README.md index 35dec3d..6ce4836 100644 --- a/docs/code_gen/mspm0/README.md +++ b/docs/code_gen/mspm0/README.md @@ -208,12 +208,14 @@ extern "C" void app_main(void) | UART、I2C、SPI | 外设实例名的小写 | `uart0`、`i2c1`、`spi1` | | PWM | `pwm_<定时器>_c<通道号>` | `pwm_tima1_c0` | +GPIO 引脚的 `$name` 去掉 `PIN_` 前缀后不是合法标识符时(SysConfig 默认的 `PIN_0` 去掉后是 `0`),对象改用小写的组名加引脚名(如 `gpio_btn_pin_0`),并给出警告提示在 SysConfig 中给引脚命名。 + 定时器的每个 CCP 通道生成一个 PWM 对象,同一 TIMER 的通道共用一个周期,周期由 SysConfig 配置。`libxr_config.yaml` 给同一定时器的通道设置了不同的频率时,生成器给出警告,以最后一次 `SetConfig` 为准。 各配置的生成要求: - UART 需要发送 DMA 通道,接收默认按字节中断(`MSPM0_UART_MAIN_INIT`)。UART Extend 实例配置了接收 DMA 时按循环 DMA 接收(`MSPM0_UART_EXTEND_INIT`,接收环的字节数见 `rx_dma_buffer_size`),接收通道须为 FULL-DMA 通道;UART Main 实例的接收 DMA 通道用不上,生成器给出警告。缺少发送 DMA 的 UART 使生成报错。 -- SPI 需要一对 DMA 通道,否则生成报错。 +- SPI 需要一对 DMA 通道,否则生成报错;接收通道须由 RX 触发(SysConfig 的 SPI > DMA Configuration 中,DMA Event 触发选 `DL_SPI_DMA_INTERRUPT_RX`),RX timeout 触发使生成报错。 - I2C 以轮询工作,缓冲区是 DMA 传输的中转。 --- diff --git a/docs/env_setup/hpm.md b/docs/env_setup/hpm.md index 7c3a80c..d3baffe 100644 --- a/docs/env_setup/hpm.md +++ b/docs/env_setup/hpm.md @@ -40,7 +40,7 @@ HPM SDK 从环境变量 `GNURISCV_TOOLCHAIN_PATH` 读取工具链的安装目录 `-- libxr/ ``` -* `CMakeLists.txt` 用 `find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})` 引入 HPM SDK,`BOARD_SEARCH_PATH` 指向 `boards/`,并设置 `CONFIG_DMA_MGR 1`(I2C 驱动的 DMA 后台路径使用它) +* `CMakeLists.txt` 用 `find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})` 引入 HPM SDK,`BOARD_SEARCH_PATH` 指向 `boards/`,并设置 `CONFIG_DMA_MGR 1`(LibXR 的 HPM 驱动依赖 SDK 的 dma_mgr 组件) * `app.yaml` 声明对 `board_gpt_pin` 的依赖;`boards//` 下有唯一的 `.hpmpc` 文件(BSP 命名为 `tool_config.hpmpc`)——两者共同构成 HPM 工程的特征,`libxr hpm setup` 和 VS Code 扩展据此识别工程 * `boards//pinmux.c` 由 HPM Pinmux Tool 从 `tool_config.hpmpc` 生成,提供 `init_bsp_pins()` * `main.c` 在工程根目录:先 `init_bsp_pins()`,再 SDK 板级的 `board_init()`,然后调用各外设的时钟函数(`init_uart3_clock()` 一类),最后进入 `app_main()` @@ -79,9 +79,9 @@ set(LIBXR_NO_EIGEN True) - `hpm_pwm.*`:PWM - `hpm_timebase.*`:基于 MCHTMR 的时间基准 -驱动只调用 SDK 的驱动函数;外设的引脚复用、时钟和初始化顺序由工程负责(`init_bsp_pins()`、`board_init()` 和 `init_*_clock()`),LibXR 对象在 `app_main()` 中创建。I2C 的 DMA 后台路径依赖 dma_mgr,BSP 用 `CONFIG_DMA_MGR 1` 启用它。 +驱动只调用 SDK 的驱动函数;外设的引脚复用、时钟和初始化顺序由工程负责(`init_bsp_pins()`、`board_init()` 和 `init_*_clock()`),LibXR 对象在 `app_main()` 中创建。驱动依赖 SDK 的 `dma_mgr` 组件,BSP 用 `CONFIG_DMA_MGR 1` 启用它。 -`HPMI2C` 在 SDK 的 `hpm_i2c_drv` 之上实现 LibXR 的 I2C 主机抽象:阻塞式字节流传输和寄存器/存储器地址式传输;默认 7 位主机寻址,`SetAddressMode()` 可切换到 SDK 支持的 10 位主机寻址;提供 dma_mgr 时,POLLING、CALLBACK 等等待策略可以走 DMA 后台路径;超时、总线忙、无响应等典型主机故障出现时,驱动按最近一次成功配置重建控制器。 +`HPMI2C` 在 SDK 的 `hpm_i2c_drv` 之上实现 LibXR 的 I2C 主机抽象:阻塞式字节流传输和寄存器/存储器地址式传输;默认 7 位主机寻址,`SetAddressMode()` 可切换到 SDK 支持的 10 位主机寻址;POLLING、CALLBACK 等等待策略可以走 dma_mgr 的 DMA 后台路径;超时、总线忙、无响应等典型主机故障出现时,驱动按最近一次成功配置重建控制器。 `HPMPWM` 的构造参数在两条代码路径下相同(外设地址、时钟、输出通道索引、比较器索引、极性):SoC 提供标准 PWM 外设时走 SDK 的 `hpm_pwm_drv`,其余 SoC 走 GPTMR 路径。`SetDutyCycle()` 接受 0.0 到 1.0 的占空比,`SetConfig()` 配置频率。 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md index fa48a75..c79977f 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md @@ -14,6 +14,8 @@ The CodeGenerator's `libxr hpm setup` command brings an HPM Pinmux Tool project The project is a directory with an `app.yaml` at its root and exactly one `.hpmpc` file under `boards//`. The selected signals come from the `selectPins` of the `.hpmpc` and the pinmux functions that `main` in the root `main.c` calls outside preprocessor conditions; functions present in the `.hpmpc` but never called by `main` do not take part. Every signal is checked, as the macro name of `hpm_iomux.h`, against the layout of the SoC package, and a pad the package does not have, or a signal its pad cannot carry, is warned about. +When the gpiom settings assign a pin to a controller other than GPIO0 (`gpioController` other than 1; unset means GPIO0), no object is generated for it, one warning per pin. + Pinmux functions that `main` calls only inside preprocessor conditions are not read either (the generated objects must not depend on build options), one warning per function; when every call sits inside a condition, no pin is read. When `main` calls no pinmux function at all, the parser falls back to `init_bsp_pins`, and when the project has no such function, no pin is read. --- @@ -161,7 +163,7 @@ extern "C" void app_main(void) } ``` -The pins and clocks are configured by the pinmux functions `main.c` calls, and the construction arguments reference SDK macros (`HPM_GPIO0`, `GPIO_DI_GPIOA`, `IRQn_GPIO0_A`, `HPM_I2C3`, `clock_i2c3`). A GPIO object carries the IRQ of its port, the port's interrupt service routine comes from the LibXR driver, the edge comes from the pinmux, and registering the callback (`RegisterCallback` and `EnableInterrupt`) belongs to the consumer. The DMA-backed background path of an I2C needs `CONFIG_DMA_MGR` enabled in the project. +The pins and clocks are configured by the pinmux functions `main.c` calls, and the construction arguments reference SDK macros (`HPM_GPIO0`, `GPIO_DI_GPIOA`, `IRQn_GPIO0_A`, `HPM_I2C3`, `clock_i2c3`). A GPIO object carries the IRQ of its port, the port's interrupt service routine comes from the LibXR driver, the edge comes from the pinmux, and registering the callback (`RegisterCallback` and `EnableInterrupt`) belongs to the consumer. The HPM drivers of LibXR depend on the `dma_mgr` component of the SDK, and the project needs `CONFIG_DMA_MGR` enabled (the BSPs enable it). --- @@ -187,7 +189,7 @@ Every comparator (COMP_n) of a GPTMR gets a PWM object through the GPTMR path of | Section | Keys and defaults | Notes | | --- | --- | --- | -| `I2C` | `speed: 100000` | the bus speed in Hz, one entry per instance keyed by the lower-case instance name | +| `I2C` | `speed: 100000` | the bus speed in Hz, one entry per instance keyed by the lower-case instance name; the value must be 100000, 400000 or 1000000 (the steps the HPM I2C driver supports), anything else stops generation with an error | | `PWM` | `frequency` (default null) | one entry per object; null calls no `SetConfig`, a given value must be a positive integer (Hz) | | `GPIO` | the key is a pin name, the value is the new name | renames a pin; a null value keeps the default name. The section lists every pin the project read | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md index 6aa384a..65b43a2 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md @@ -208,12 +208,14 @@ The objects are named: | UART, I2C, SPI | the lower-case peripheral instance name | `uart0`, `i2c1`, `spi1` | | PWM | `pwm__c` | `pwm_tima1_c0` | +When the `$name` of a GPIO pin without its `PIN_` prefix is not a valid identifier (the SysConfig default `PIN_0` leaves `0`), the object takes the lower-case group plus pin name instead (such as `gpio_btn_pin_0`), and a warning asks for naming the pin in SysConfig. + Every CCP channel of a timer gets a PWM object; the channels of one timer share one period, which SysConfig configures. When `libxr_config.yaml` sets different frequencies for the channels of one timer, the generator prints a warning and the last `SetConfig` wins. The generation requirements of each configuration: - A UART needs a transmit DMA channel; the receive side runs on byte interrupts by default (`MSPM0_UART_MAIN_INIT`). A UART Extend instance with a receive DMA receives through a circular DMA (`MSPM0_UART_EXTEND_INIT`, the bytes of the receive ring in `rx_dma_buffer_size`), and its receive channel must be a FULL-DMA channel; the receive DMA channel of a UART Main instance is unused and warned about. A UART without transmit DMA makes generation fail. -- An SPI needs a pair of DMA channels, otherwise generation fails. +- An SPI needs a pair of DMA channels, otherwise generation fails; the receive channel must be triggered by RX (in SysConfig's SPI > DMA Configuration, pick `DL_SPI_DMA_INTERRUPT_RX` as the DMA Event trigger), an RX timeout trigger makes generation fail. - An I2C works by polling; its buffer stages DMA transfers. --- diff --git a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md index 0cffbcf..41a86a4 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md @@ -40,7 +40,7 @@ Taking bsp-hpm5301evklite as the example: `-- libxr/ ``` -* `CMakeLists.txt` brings in the HPM SDK with `find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})`, points `BOARD_SEARCH_PATH` at `boards/`, and sets `CONFIG_DMA_MGR 1` (the DMA-backed I2C path uses it) +* `CMakeLists.txt` brings in the HPM SDK with `find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})`, points `BOARD_SEARCH_PATH` at `boards/`, and sets `CONFIG_DMA_MGR 1` (the HPM drivers of LibXR depend on the SDK's dma_mgr component) * `app.yaml` declares the dependency on `board_gpt_pin`; `boards//` contains the single `.hpmpc` file (the BSPs name it `tool_config.hpmpc`) — together these mark out an HPM project, which is how `libxr hpm setup` and the VS Code extension recognize one * `boards//pinmux.c` is generated by the HPM Pinmux Tool from `tool_config.hpmpc` and provides `init_bsp_pins()` * `main.c` sits in the project root: `init_bsp_pins()` first, then the SDK board's `board_init()`, then the clock functions of the peripherals (`init_uart3_clock()` and its siblings), and finally `app_main()` @@ -79,9 +79,9 @@ set(LIBXR_NO_EIGEN True) - `hpm_pwm.*`: PWM - `hpm_timebase.*`: timebase on MCHTMR -The drivers call SDK driver functions only; pin muxing, clocks and the initialization order belong to the project (`init_bsp_pins()`, `board_init()` and the `init_*_clock()` functions), and the LibXR objects are created in `app_main()`. The DMA-backed I2C path depends on dma_mgr, which the BSPs enable with `CONFIG_DMA_MGR 1`. +The drivers call SDK driver functions only; pin muxing, clocks and the initialization order belong to the project (`init_bsp_pins()`, `board_init()` and the `init_*_clock()` functions), and the LibXR objects are created in `app_main()`. The drivers depend on the SDK's `dma_mgr` component, which the BSPs enable with `CONFIG_DMA_MGR 1`. -`HPMI2C` implements the LibXR I2C master abstraction on top of the SDK's `hpm_i2c_drv`: blocking byte-stream transfers and register/memory-address transfers; 7-bit master addressing by default with `SetAddressMode()` switching to the SDK's 10-bit master addressing; with dma_mgr present, wait strategies such as POLLING and CALLBACK can use the DMA-backed path; on typical master failures such as a timeout, a busy bus or no response, the driver rebuilds the controller with its most recent successful configuration. +`HPMI2C` implements the LibXR I2C master abstraction on top of the SDK's `hpm_i2c_drv`: blocking byte-stream transfers and register/memory-address transfers; 7-bit master addressing by default with `SetAddressMode()` switching to the SDK's 10-bit master addressing; wait strategies such as POLLING and CALLBACK can use the DMA-backed path on dma_mgr; on typical master failures such as a timeout, a busy bus or no response, the driver rebuilds the controller with its most recent successful configuration. `HPMPWM` takes the same constructor arguments on both code paths (peripheral address, clock, output channel index, comparator index, polarity): SoCs with a standard PWM peripheral go through the SDK's `hpm_pwm_drv`, the others through the GPTMR path. `SetDutyCycle()` accepts a duty cycle of 0.0 to 1.0, and `SetConfig()` sets the frequency. From 18076e88aad6c24107da38c16b344cbfcb0c073f Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Thu, 8 Oct 2026 00:51:26 +0100 Subject: [PATCH 04/16] Correct the MSPM0, HPM and pin layout pages against the generator and the BSPs - The libxr pins overlay is the project section (assignments, peripherals), not a pins section; the command and its output share one block. - The example runs and app_main.cpp excerpts are the first generation on a BSP copy; the MSPM0 excerpt no longer references a callback it leaves out, and wiring a key interrupt in the User Code regions is shown separately. - HPM: I2C needs SCL and SDA, a capture-only GPTMR is display-only, GPIO names drop leading zeros, the settings rules (null defaults, integer literals, keys in any case, rename checks, stale null entries) and why there is no terminal. - MSPM0: object and settings keys come from the peripheral name (UART0), not the SysConfig instance name; the regeneration steps keep the XRobot choice and remind to run xrobot gen. - Environment pages: building a BSP needs xrobot setup first; mspm0_syscalls.c provides __dso_handle, _getpid and _kill as weak definitions, not the newlib system calls; driver/hpm also has hpm_dma. - VS Code extension: the pin layout opens from the LibXR view; MSPM0/HPM need extension 2.1.0 and libxr 6.1.0; the SysConfig settings also serve parsing. --- docs/code_gen/hpm/README.md | 33 +++---- docs/code_gen/mspm0/README.md | 91 +++++++++++++++---- docs/code_gen/pins.md | 38 ++++---- docs/env_setup/README.md | 4 +- docs/env_setup/hpm.md | 10 +- docs/env_setup/mspm0.md | 9 +- .../current/code_gen/hpm/README.md | 33 +++---- .../current/code_gen/mspm0/README.md | 89 ++++++++++++++---- .../current/code_gen/pins.md | 38 ++++---- .../current/env_setup/README.md | 4 +- .../current/env_setup/hpm.md | 10 +- .../current/env_setup/mspm0.md | 9 +- 12 files changed, 239 insertions(+), 129 deletions(-) diff --git a/docs/code_gen/hpm/README.md b/docs/code_gen/hpm/README.md index 0a29332..f96b380 100644 --- a/docs/code_gen/hpm/README.md +++ b/docs/code_gen/hpm/README.md @@ -6,7 +6,7 @@ sidebar_position: 3 # HPM 代码生成 -代码生成器的 `libxr hpm setup` 命令把 HPM Pinmux Tool 工程接入 LibXR:解析工程,生成 C++ 初始化代码。引脚复用和时钟由 Pinmux Tool 的输出配置(工程根目录 `main.c` 调用生成的 pinmux 函数),`main.c` 由 BSP 维护,生成的代码是 `User/` 下的 `app_main`,构造参数全部使用 HPM SDK 的宏。 +代码生成器的 `libxr hpm setup` 命令把 HPM Pinmux Tool 工程接入 LibXR:解析工程,生成 C++ 初始化代码。引脚复用和时钟由 Pinmux Tool 导出的代码配置,工程根目录的 `main.c` 调用其中的 pinmux 函数,`main.c` 由 BSP 维护;生成的代码是 `User/` 下的 `app_main`,以 HPM SDK 的宏构造 LibXR 对象。 --- @@ -40,13 +40,14 @@ libxr hpm setup -d . ## 示例输出 -以下是 bsp-hpm5301evklite 上的一次运行,工程已是最新: +以下是在 bsp-hpm5301evklite 的副本上删去 `User/` 下的三个生成文件后的首次运行: ```text -[信息] .\User\app_main.cpp 使用了 XRobot,继续按 --xrobot 生成(--no-xrobot 可关闭)。 +$ libxr hpm setup -d . --xrobot [信息] 配置已导出到:.\.config.yaml [信息] 系统:裸机 -[信息] 已生成 User:未变化 app_main.cpp、app_main.h、libxr_config.yaml +[信息] .\User\libxr_config.yaml 不存在,按默认设置新建 +[信息] 已生成 User:已写入 app_main.cpp、app_main.h、libxr_config.yaml [信息] 下一步:运行 `xrobot gen` 更新 User/xrobot_main.hpp;libxr 的 setup 不更新它 ===== [配置摘要] ===== @@ -72,7 +73,7 @@ GPIO(2 个引脚): USB0 ``` -生成器只写内容有变化的文件;上例中工程已是最新,三个文件都没有改写。配置摘要中的 Other 是 LibXR 还没有驱动的配置,见[生成的对象与命名](#生成的对象与命名)。 +之后再运行时,生成器只改写内容有变化的文件。配置摘要中的 Other 是 LibXR 还没有驱动的配置,见[生成的对象与命名](#生成的对象与命名)。 --- @@ -100,7 +101,7 @@ GPIO(2 个引脚): `app_main.cpp` 包含 LibXR 初始化函数 `app_main()`。`/* User Code Begin N */` 与 `/* User Code End N */` 之间的代码在重新生成时保留,其余部分每次重新生成。生成的外设对象都是 `static` 对象,`app_main()` 返回后仍然有效;长期使用的局部对象声明为 `static`。外设对象可以以基类指针传给线程或模块使用,做法见[与XRobot集成](../xrobot_inter.md)。 -下面是 bsp-hpm5301evklite 生成的 `app_main.cpp` 节选,省略处写作 `// ...`: +下面是上例首次生成的 `app_main.cpp`: ```cpp // Generated by `libxr gen`; do not edit by hand. @@ -120,8 +121,6 @@ GPIO(2 个引脚): using namespace LibXR; /* User Code Begin 1 */ -// KEY interrupt counter, incremented in the GPIO interrupt callback. -static std::atomic key_irq_count{0}; /* User Code End 1 */ extern "C" void app_main(void) @@ -163,23 +162,23 @@ extern "C" void app_main(void) } ``` -引脚和时钟在 `main.c` 调用的 pinmux 函数中配置完毕,构造参数引用 SDK 的宏(`HPM_GPIO0`、`GPIO_DI_GPIOA`、`IRQn_GPIO0_A`、`HPM_I2C3`、`clock_i2c3`)。GPIO 对象带所属端口的 IRQ,端口的中断服务程序由 LibXR 驱动提供,边沿来自 pinmux,回调的登记(`RegisterCallback` 和 `EnableInterrupt`)由使用方完成。LibXR 的 HPM 驱动依赖 SDK 的 `dma_mgr` 组件,工程需要启用 `CONFIG_DMA_MGR`(BSP 已启用)。 +引脚和时钟在 `main.c` 调用的 pinmux 函数中配置完毕,构造参数引用 SDK 的宏(`HPM_GPIO0`、`GPIO_DI_GPIOA`、`IRQn_GPIO0_A`、`HPM_I2C3`、`clock_i2c3`)。GPIO 对象带所属端口的 IRQ,端口的中断服务程序由 LibXR 驱动提供,边沿来自 pinmux,回调的登记(`RegisterCallback` 和 `EnableInterrupt`)由使用方完成。LibXR 的 HPM 驱动依赖 SDK 的 `dma_mgr` 组件,工程的 `CMakeLists.txt` 设置 `CONFIG_DMA_MGR`,两个 BSP 都已设置。 --- ## 生成的对象与命名 -生成的对象来自 LibXR 有驱动的配置:GPIO 引脚各生成一个对象,I2C 生成一个对象;GPTMR 上的 PWM 见下文。其余配置(UART、SPI、MCAN、ADC、ACMP、USB 等)列入配置摘要的 Other,只作展示。 +生成的对象来自 LibXR 有驱动的配置:每个 GPIO 引脚一个对象,每个同时选了 SCL 和 SDA 的 I2C 一个对象;GPTMR 上的 PWM 见下文。其余配置(UART、SPI、MCAN、ADC、ACMP、USB、缺 SCL 或 SDA 的 I2C、只有捕获输入的 GPTMR 等)列入配置摘要的 Other,只作展示。 对象的命名: | 配置 | 对象名 | 例子 | | --- | --- | --- | -| GPIO | 引脚名(端口字母小写加线号),`GPIO:` 段可改名 | `pa10`、`pb11` | -| I2C | 外设实例名的小写 | `i2c3` | +| GPIO | `p` 加小写的端口字母和去掉前导零的线号,`GPIO` 段可改名 | `pa10`、`pa3`(PA03) | +| I2C | 外设名的小写 | `i2c3` | | GPTMR 上的 PWM | `pwm_<实例小写>_ch<比较器号>` | `pwm_gptmr0_ch1` | -GPTMR 的每个比较器(COMP_n)生成一个 PWM 对象,走 `HPMPWM` 的 GPTMR 路径;对象只在 SoC 没有 PWM 外设时生成,判定依据是芯片的引脚数据里有没有 PWM 外设的信号:HPM5301 没有,HPM5361 有 20 个,后者的 GPTMR 列入 Other 只作展示。占空比较器固定,极性固定为 `NORMAL`;对象和注册无条件生成,包在预处理条件里会使 XRobot 的生成器拒绝该文件。 +GPTMR 的每个比较器(COMP_n)生成一个 PWM 对象,走 `HPMPWM` 的 GPTMR 路径;对象只在 SoC 没有 PWM 外设时生成,判定依据是芯片的引脚数据里有没有 PWM 外设的信号:HPM5301 没有,HPM5361 有,后者的 GPTMR 列入 Other 只作展示。占空比比较器固定为 0,极性为 `NORMAL`;对象和注册无条件生成,包在预处理条件里会使 XRobot 的生成器拒绝该文件。 --- @@ -193,7 +192,9 @@ GPTMR 的每个比较器(COMP_n)生成一个 PWM 对象,走 `HPMPWM` 的 G | `PWM` | `frequency`(默认 null) | 每个对象一项;null 时不调用 `SetConfig`,设置了必须是正整数(Hz) | | `GPIO` | 键为引脚名,值为新名字 | 引脚改名;值为 null 时保留默认名。段中列出工程读到的每个引脚 | -HPM 的生成器目前创建的串口对象还没有进入 libxr,`terminal_source` 没有可指向的终端;设置了它会得到警告。 +设置值为 null 时取默认值;数值也可以写成字符串形式的整数字面量(如 `'0x61A80'`)。设置键不区分大小写,文件中已有的写法保持不变。GPIO 的新名字必须是合法的 C++ 标识符,不能是 C++ 关键字或保留标识符,不能与 HPM SDK 的宏、生成代码中的名字或其他对象重名,不满足的名字一次全部列出后生成报错;引脚离开工程后,它值为 null 的改名项随之删除,写了名字的保留并给出警告。 + +HPM 的生成器不创建 UART 对象(LibXR 的 HPM UART 驱动还没有合入),所以不生成终端;文件中写了 `terminal_source` 时给出警告。 以下是 bsp-hpm5301evklite 首次生成的 `User/libxr_config.yaml`: @@ -222,14 +223,14 @@ GPIO: ## 重新生成代码 -修改 `.hpmpc`、`main.c` 或 `User/libxr_config.yaml` 后,在工程根目录重新运行 `libxr hpm setup -d .`,或只重新生成 `User/` 下的文件: +修改 `.hpmpc`、`main.c` 或 `User/libxr_config.yaml` 后,在工程根目录重新运行 `libxr hpm setup -d .`,或分两步运行: ```bash libxr parse -d . libxr gen -i .config.yaml -o User/app_main.cpp ``` -`.config.yaml` 由 `libxr parse` 写出,新克隆的工程里没有这个文件,先运行 `libxr parse`。VS Code 扩展的 Generate LibXR Code 动作依次运行这两条命令,见 [VS Code 扩展](../../env_setup/README.md#vs-code-扩展)。 +`.config.yaml` 由 `libxr parse` 写出,新克隆的工程里没有这个文件,先运行 `libxr parse`。不写 `--xrobot` 和 `--no-xrobot` 时,`libxr gen` 沿用输出文件现在的选择;生成后运行 `xrobot gen` 更新 `User/xrobot_main.hpp`。VS Code 扩展的 Generate LibXR Code 动作依次运行这两条命令,见 [VS Code 扩展](../../env_setup/README.md#vs-code-扩展)。 --- diff --git a/docs/code_gen/mspm0/README.md b/docs/code_gen/mspm0/README.md index 6ce4836..ecd9b69 100644 --- a/docs/code_gen/mspm0/README.md +++ b/docs/code_gen/mspm0/README.md @@ -6,7 +6,7 @@ sidebar_position: 2 # MSPM0 代码生成 -代码生成器的 `libxr mspm0 setup` 命令把 TI SysConfig 工程接入 LibXR:解析工程根目录的 `.syscfg` 文件,生成 C++ 初始化代码。SysConfig 负责时钟、引脚、DMA 通道和外设的配置(`main.c` 中的 `SYSCFG_DL_init()`),生成的代码声明 LibXR 对象,XRobot 工程在生成时用 `XR_REGISTER` 把对象注册进去,构造参数全部使用 SysConfig 生成的宏。 +代码生成器的 `libxr mspm0 setup` 命令把 TI SysConfig 工程接入 LibXR:解析工程根目录的 `.syscfg` 文件,生成 C++ 初始化代码。时钟、引脚、DMA 通道和外设由 SysConfig 配置,`main.c` 调用 `SYSCFG_DL_init()` 完成初始化;生成的代码以 SysConfig 生成的宏构造 LibXR 对象,XRobot 工程另外生成 `XR_REGISTER` 硬件注册。 --- @@ -40,15 +40,17 @@ BSP 的 CMake 在 configure 阶段对 `.syscfg` 运行 SysConfig,输出在构 ## 示例输出 -以下是 bsp-mspm0g3507-mini 上设置了两个环境变量后的一次运行,工程已是最新: +以下是在 bsp-mspm0g3507-mini 的副本上删去 `User/` 下的三个生成文件后的首次运行,设置了两个环境变量: ```text -[信息] .\User\app_main.cpp 使用了 XRobot,继续按 --xrobot 生成(--no-xrobot 可关闭)。 +$ libxr mspm0 setup -d . --xrobot [信息] 正在处理 mspm0g3507_minidb48.syscfg…… [信息] 正在对 mspm0g3507_minidb48.syscfg 运行 SysConfig [信息] 配置已导出到:.\.config.yaml [信息] 系统:裸机 -[信息] 已生成 User:未变化 app_main.cpp、app_main.h、libxr_config.yaml +[信息] .\User\libxr_config.yaml 不存在,按默认设置新建 +[信息] 未设置 terminal_source;使用 uart0 +[信息] 已生成 User:已写入 app_main.cpp、app_main.h、libxr_config.yaml [信息] 下一步:运行 `xrobot gen` 更新 User/xrobot_main.hpp;libxr 的 setup 不更新它 ===== [配置摘要] ===== @@ -80,7 +82,7 @@ GPIO(4 个引脚): QEI_TIMG8 ``` -生成器只写内容有变化的文件;上例中工程已是最新,三个文件都没有改写。配置摘要中的 Other 是 LibXR 还没有驱动的配置,见[生成的对象与命名](#生成的对象与命名)。 +之后再运行时,生成器只改写内容有变化的文件。配置摘要中的 Other 是 LibXR 还没有驱动的配置,见[生成的对象与命名](#生成的对象与命名)。 --- @@ -105,7 +107,7 @@ GPIO(4 个引脚): `app_main.cpp` 包含 LibXR 初始化函数 `app_main()`。`/* User Code Begin N */` 与 `/* User Code End N */` 之间的代码在重新生成时保留,其余部分每次重新生成。生成的外设对象都是 `static` 对象,`app_main()` 返回后仍然有效;长期使用的局部对象声明为 `static`。外设对象可以以基类指针传给线程或模块使用,做法见[与XRobot集成](../xrobot_inter.md)。 -下面是 bsp-mspm0g3507-mini 生成的 `app_main.cpp` 节选,省略处写作 `// ...`: +下面是上例首次生成的 `app_main.cpp` 节选,省略处写作 `// ...`: ```cpp // Generated by `libxr gen`; do not edit by hand. @@ -116,13 +118,17 @@ GPIO(4 个引脚): #include "libxr.hpp" #include "mspm0_gpio.hpp" -// ... +#include "mspm0_i2c.hpp" +#include "mspm0_pwm.hpp" +#include "mspm0_spi.hpp" +#include "mspm0_timebase.hpp" +#include "mspm0_uart.hpp" +#include "ti_msp_dl_config.h" +#include "xrobot_main.hpp" using namespace LibXR; /* User Code Begin 1 */ -// KEY interrupt counters, incremented in the GPIO interrupt callbacks. -static std::atomic key1_irq_count{0}; /* User Code End 1 */ // Input clocks: the BUSCLK of the power domain. PD0 from ULPCLK = CPUCLK_FREQ / 2 @@ -136,6 +142,7 @@ static constexpr uint32_t PD1_BUSCLK_FREQ = CPUCLK_FREQ; // MSPM0_UART_MAIN_INIT checks these names against the ones SysConfig generated. #define DMA_CH_UART0_TX_LIBXR_UART_IRQN UART_0_INST_INT_IRQN #define DMA_CH_UART0_TX_LIBXR_UART_TX 1 +// ... // DMA buffers. A UART gets 2 x N bytes for its two transmit halves; the receive side // runs on byte interrupts. The SPI DMA buffers are split in two halves as well; the @@ -143,6 +150,7 @@ static constexpr uint32_t PD1_BUSCLK_FREQ = CPUCLK_FREQ; alignas(size_t) static uint8_t uart0_tx_buf[2 * 128]; // ... alignas(4) static uint8_t i2c0_buf[32]; +// ... extern "C" void app_main(void) { @@ -159,6 +167,8 @@ extern "C" void app_main(void) static MSPM0GPIO LED1(GPIO_LEDS_PIN_LED1_PORT, GPIO_LEDS_PIN_LED1_PIN, GPIO_LEDS_PIN_LED1_IOMUX); // ... + static MSPM0GPIO KEY1(GPIO_KEYS_PORT, GPIO_KEYS_PIN_KEY1_PIN, GPIO_KEYS_PIN_KEY1_IOMUX); + static MSPM0GPIO KEY2(GPIO_KEYS_PORT, GPIO_KEYS_PIN_KEY2_PIN, GPIO_KEYS_PIN_KEY2_IOMUX); // UART: TX with DMA; the receive side runs on byte interrupts. static MSPM0UART uart0(MSPM0_UART_MAIN_INIT(UART_0, DMA_CH_UART0_TX, uart0_tx_buf, @@ -168,6 +178,7 @@ extern "C" void app_main(void) // I2C: polling; the buffer stages DMA transfers. static MSPM0I2C i2c0(MSPM0_I2C_INIT(I2C_0, PD0_BUSCLK_FREQ, i2c0_buf, sizeof(i2c0_buf), 8), {I2C_0_BUS_SPEED_HZ}); + // ... // SPI: DMA for transfers longer than the threshold. static MSPM0SPI spi1(MSPM0_SPI_INIT(SPI_1, PD1_BUSCLK_FREQ, DMA_CH_SPI1_RX, @@ -183,16 +194,58 @@ extern "C" void app_main(void) STDIO::write_ = uart0.write_port_; static RamFS ramfs("XRobot"); static Terminal<32, 32, 5, 5> terminal(ramfs); + static auto terminal_task = Timer::CreateTask(terminal.TaskFun, &terminal, 10); + Timer::Add(terminal_task); + Timer::Start(terminal_task); + + // Hardware registration + XR_REGISTER(LED1, LibXR::GPIO); + // ... + + XR_REGISTER(pwm_tima1_c0, LibXR::PWM); + // ... + + XR_REGISTER(spi1, LibXR::SPI); + + XR_REGISTER(uart0, LibXR::UART); + // ... + + XR_REGISTER(i2c0, LibXR::I2C); + // ... + + XR_REGISTER(ramfs, LibXR::RamFS); + + XR_REGISTER(terminal, LibXR::Terminal<32, 32, 5, 5>); + /* User Code Begin 3 */ - KEY1.SetConfig({GPIO::Direction::FALL_INTERRUPT, GPIO::Pull::NONE}); - KEY1.RegisterCallback(GPIO::Callback::Create(OnKeyInterrupt, &key1_irq_count)); - KEY1.EnableInterrupt(); /* User Code End 3 */ XROBOT_MAIN(); } ``` -每个外设对象以 SysConfig 生成的宏构造,例如 GPIO 的 `GPIO_LEDS_PIN_LED1_PORT`、UART 的 `UART_0`。各对象的中断由 LibXR 驱动在构造时开启并设置优先级,SysConfig 中对同一中断的设置被驱动覆盖;引脚中断的边沿来自 SysConfig,回调的登记(`RegisterCallback` 和 `EnableInterrupt`)由使用方完成,模块或 User Code 中的做法见上例的 User Code 区域。 +每个外设对象以 SysConfig 生成的宏构造,例如 GPIO 的 `GPIO_LEDS_PIN_LED1_PORT`、UART 的 `UART_0`。各对象用到的中断由 LibXR 驱动在构造时开启并设置优先级,SysConfig 中对同一中断的设置被驱动覆盖。引脚中断的边沿来自 SysConfig,回调的登记(`RegisterCallback` 和 `EnableInterrupt`)由使用方在模块或 User Code 区域中完成,例如为 KEY1 接上中断计数: + +```cpp +/* User Code Begin 1 */ +#include + +static std::atomic key1_irq_count{0}; + +static void OnKeyInterrupt(bool in_isr, std::atomic* count) +{ + (void)in_isr; + count->fetch_add(1, std::memory_order_relaxed); +} +/* User Code End 1 */ + +// ... + + /* User Code Begin 3 */ + KEY1.SetConfig({GPIO::Direction::FALL_INTERRUPT, GPIO::Pull::NONE}); + KEY1.RegisterCallback(GPIO::Callback::Create(OnKeyInterrupt, &key1_irq_count)); + KEY1.EnableInterrupt(); + /* User Code End 3 */ +``` --- @@ -205,12 +258,12 @@ extern "C" void app_main(void) | 配置 | 对象名 | 例子 | | --- | --- | --- | | GPIO | SysConfig 中引脚的标签(`$name` 去掉 `PIN_` 前缀) | `LED1`、`KEY1` | -| UART、I2C、SPI | 外设实例名的小写 | `uart0`、`i2c1`、`spi1` | +| UART、I2C、SPI | 实例所用外设名的小写(`UART_0` 使用 UART0) | `uart0`、`i2c1`、`spi1` | | PWM | `pwm_<定时器>_c<通道号>` | `pwm_tima1_c0` | GPIO 引脚的 `$name` 去掉 `PIN_` 前缀后不是合法标识符时(SysConfig 默认的 `PIN_0` 去掉后是 `0`),对象改用小写的组名加引脚名(如 `gpio_btn_pin_0`),并给出警告提示在 SysConfig 中给引脚命名。 -定时器的每个 CCP 通道生成一个 PWM 对象,同一 TIMER 的通道共用一个周期,周期由 SysConfig 配置。`libxr_config.yaml` 给同一定时器的通道设置了不同的频率时,生成器给出警告,以最后一次 `SetConfig` 为准。 +定时器的每个 CCP 通道生成一个 PWM 对象,同一定时器的通道共用一个周期,周期由 SysConfig 配置。`libxr_config.yaml` 给同一定时器的通道设置了不同的频率时,生成器给出警告,以最后一次 `SetConfig` 为准。 各配置的生成要求: @@ -228,9 +281,9 @@ GPIO 引脚的 `$name` 去掉 `PIN_` 前缀后不是合法标识符时(SysConf ## libxr_config.yaml -`User/libxr_config.yaml` 保存代码生成的设置。文件不存在时按默认值新建;之后每次生成补上缺少的设置,已有的值保持不变。外设的设置段只在工程有对应外设时写入,段中每个实例一项,键为小写的实例名,PWM 的键为对象名。值为 null(YAML 中只写了键)时取默认值;缓冲区和队列必须是正整数。 +`User/libxr_config.yaml` 保存代码生成的设置。文件不存在时按默认值新建;之后每次生成补上缺少的设置,已有的值保持不变。外设的设置段只在工程有对应外设时写入,段中每个对象一项,键为对象名(`uart0`、`pwm_tima1_c0`)。值为 null(YAML 中只写了键)时取默认值;缓冲区和队列必须是正整数。 -下表列出各设置段,默认值与 STM32 不同的单独说明: +各设置段: | 段 | 键与默认值 | 说明 | | --- | --- | --- | @@ -286,14 +339,14 @@ I2C 的总线速率和 UART 的波特率来自 SysConfig 工程(如 `I2C_0_BUS ## 重新生成代码 -修改 `.syscfg` 或 `User/libxr_config.yaml` 后,在工程根目录重新运行 `libxr mspm0 setup -d .`,或只重新生成 `User/` 下的文件: +修改 `.syscfg` 或 `User/libxr_config.yaml` 后,在工程根目录重新运行 `libxr mspm0 setup -d .`(SysConfig 输出的来源同上),或分两步运行: ```bash libxr parse -d . libxr gen -i .config.yaml -o User/app_main.cpp ``` -`.config.yaml` 由 `libxr parse` 写出,新克隆的工程里没有这个文件,先运行 `libxr parse`。VS Code 扩展的 Generate LibXR Code 动作依次运行这两条命令,见 [VS Code 扩展](../../env_setup/README.md#vs-code-扩展)。 +`.config.yaml` 由 `libxr parse` 写出,新克隆的工程里没有这个文件,先运行 `libxr parse`。不写 `--xrobot` 和 `--no-xrobot` 时,`libxr gen` 沿用输出文件现在的选择;生成后运行 `xrobot gen` 更新 `User/xrobot_main.hpp`。VS Code 扩展的 Generate LibXR Code 动作依次运行这两条命令,见 [VS Code 扩展](../../env_setup/README.md#vs-code-扩展)。 --- diff --git a/docs/code_gen/pins.md b/docs/code_gen/pins.md index c90b45b..a7a417e 100644 --- a/docs/code_gen/pins.md +++ b/docs/code_gen/pins.md @@ -22,17 +22,14 @@ libxr pins -d path/to/project 型号作为位置参数给出。MSPM0 的封装优先取型号后缀中的封装代码(`MSPM0G3507SPMR` 的 `PM`),判断不了时用 `--package` 给出(`LQFP-64`、`PM` 等写法都可以);HPM 的型号即 SoC 名,封装有多个时用 `--package` 给出。 -`-d` 给出工程目录时,打印的布局叠加工程已选的信号及其 `libxr_config.yaml` 设置。STM32 工程读 `.ioc` 文件,MSPM0 工程读根目录的 `.syscfg`(封装取自 SysConfig 工程),HPM 工程读 `boards/` 下的 `.hpmpc` 和 `main.c` 调用的 pinmux 函数(封装随解析结果给出)。设置从 `--libxr-config` 指定的文件读取,默认为工程中的 `User/libxr_config.yaml`。 +`-d` 给出工程目录时,打印的布局叠加工程已选的信号及其 `libxr_config.yaml` 设置。STM32 工程读 `.ioc` 文件,MSPM0 工程读根目录的 `.syscfg`(封装取自 SysConfig 工程),HPM 工程读 `boards/` 下的 `.hpmpc` 和 `main.c` 在预处理条件之外调用的 pinmux 函数(封装取自 `.hpmpc`)。设置从 `--libxr-config` 指定的文件读取,默认为工程中的 `User/libxr_config.yaml`。 --- ## 输出 -```bash -$ libxr pins MSPM0G3507 --package LQFP-64 -``` - ```yaml +$ libxr pins MSPM0G3507 --package LQFP-64 model: MSPM0G3507 platform: mspm0 part: MSPM0G3507 @@ -60,14 +57,18 @@ peripherals: ## 工程叠加 -```bash -$ libxr pins -d . -``` - -叠加工程后,输出多了两层内容。`pins` 一节逐引脚列出工程选中的信号,GPIO 引脚带有厂商工程中的标签: +给出 `-d` 时,输出多一个 `project` 段:`directory`、`source` 记录工程目录和读取的工程文件,`libxr_config`、`sysconfig_file` 是读取的设置文件和 SysConfig 工程(HPM 工程的 `sysconfig_file` 是 `.hpmpc`);`assignments` 逐引脚列出工程选中的信号,GPIO 引脚带有生成代码中的对象名 `label`;`peripherals` 按外设列出占用的引脚、MSPM0 工程中该外设在 SysConfig 中的参数(`sysconfig`),以及它在 `libxr_config.yaml` 中的设置项(`config`)。以下取自 bsp-mspm0g3507-mini: ```yaml - pins: +$ libxr pins -d . +# ... +project: + directory: . + source: mspm0g3507_minidb48.syscfg + libxr_config: User\libxr_config.yaml + sysconfig_file: mspm0g3507_minidb48.syscfg + assignments: + # ... PB8: signal: PB8 peripheral: GPIOB @@ -75,12 +76,9 @@ $ libxr pins -d . function: P8 matched: true label: LED1 -# ... -``` - -`peripherals` 一节按实例列出占用的引脚、厂商工程中该实例的参数,以及 `libxr_config.yaml` 中对应的设置项: - -```yaml + # ... + peripherals: + # ... TIMA1: kind: TIMA pins: @@ -101,10 +99,10 @@ $ libxr pins -d . present: true params: frequency: null -# ... + # ... ``` -`matched` 为 `false` 时,信号与该引脚可复用的信号不符,按原样列出。`config` 是该实例在 `libxr_config.yaml` 中的设置项列表:`present` 表示这一项是否已在文件中,`params` 是已写的设置;一个 PWM 实例的每个通道各占一项。HPM 工程的 GPIO 改名是 `GPIO` 段下的整段映射,`section: GPIO` 的项没有 `key`,`params` 为引脚名到新名字的映射。 +`matched` 为 `false` 时,信号与该引脚可复用的信号不符,按原样列出。`config` 是该实例在 `libxr_config.yaml` 中的设置项列表:`present` 表示这一项是否已在文件中,`params` 是已写的设置;一个 PWM 实例的每个通道各占一项。HPM 工程的 GPIO 改名是 `GPIO` 段下的整段映射:`section: GPIO` 的项 `key` 为 `null`,`params` 是引脚名到新名字的映射,值为 `null` 时保留默认名。 --- @@ -115,7 +113,7 @@ $ libxr pins -d . | `model` | 型号(默认:`-d` 给出的工程的型号) | | `-d`, `--directory` | 工程目录:叠加它已选的信号和设置 | | `-c`, `--libxr-config` | 读取设置的 libxr_config.yaml(默认:工程中的 `User/libxr_config.yaml`) | -| `-p`, `--package` | 封装,型号名不包含封装时给出(MSPM0:`LQFP-64`、`PM` 等);MSPM0 工程随 `-d` 从 SysConfig 工程取 | +| `-p`, `--package` | 封装,型号名不包含封装时给出(MSPM0:`LQFP-64`、`PM` 等;HPM:`QFN48` 等);用 `-d` 时取自 SysConfig 或 Pinmux Tool 工程 | | `-f`, `--format` | 输出格式:`yaml`(默认)或 `json` | | `--verbose` | 输出调试日志 | diff --git a/docs/env_setup/README.md b/docs/env_setup/README.md index ac99525..0581621 100644 --- a/docs/env_setup/README.md +++ b/docs/env_setup/README.md @@ -77,9 +77,9 @@ BSP 使用的 xrobot 版本记录在 `Modules/modules.yaml` 的 `xrobot:` 字段 VS Code 扩展 [`XRobot.xrobot`](https://marketplace.visualstudio.com/items?itemName=XRobot.xrobot) 在活动栏中提供 XRobot 和 LibXR 两个视图。打开包含 `Modules/modules.yaml` 的 BSP 时,XRobot 视图显示其中的模块、配置和实例,修改通过 `xrobot` 命令完成。 -LibXR 视图按工程根目录识别平台:根目录有 `.ioc` 的是 STM32CubeMX 工程,`app.yaml` 加 `boards/*/*.hpmpc` 的是 HPM 工程,SysConfig 的 `.syscfg` 是 MSPM0 工程。视图显示平台和 `User/libxr_config.yaml` 中的各项设置,设置可以直接修改,修改后重新生成代码;"Generate LibXR Code" 运行 `libxr parse` 和 `libxr gen`,还没有 `libxr_config.yaml` 时则是对应平台的 `libxr stm32 setup`、`libxr mspm0 setup` 或 `libxr hpm setup`。MSPM0 工程的 "Open in SysConfig" 用独立版 SysConfig 打开 `.syscfg`,HPM 工程的 "Open in HPM Pinmux Tool" 用 HPMicro 的 HPM Pinmux Tool 扩展打开 `.hpmpc`。两个视图都能打开芯片的封装图(引脚布局,`libxr pins`,需要带有该命令的 libxr):已选引脚按外设类别着色,MSPM0 的封装取自 SysConfig 工程,面板只读。 +LibXR 视图按工程根目录识别平台:根目录有 `.ioc` 的是 STM32CubeMX 工程,`app.yaml` 加 `boards/*/*.hpmpc` 的是 HPM 工程,SysConfig 的 `.syscfg` 是 MSPM0 工程。视图显示平台和 `User/libxr_config.yaml` 中的各项设置,设置可以直接修改,修改后重新生成代码;"Generate LibXR Code" 运行 `libxr parse` 和 `libxr gen`,还没有 `libxr_config.yaml` 时则是对应平台的 `libxr stm32 setup`、`libxr mspm0 setup` 或 `libxr hpm setup`。MSPM0 工程的 "Open in SysConfig" 用独立版 SysConfig 打开 `.syscfg`,HPM 工程的 "Open in HPM Pinmux Tool" 用 HPMicro 的 HPM Pinmux Tool 扩展打开 `.hpmpc`。LibXR 视图的 "Pin Layout" 打开芯片的封装图(引脚布局,`libxr pins`):已选引脚按外设类别着色,MSPM0 的封装取自 SysConfig 工程,面板只读。 -扩展 2.0.0 要求 VS Code 1.108 及以上版本。XRobot 视图需要 xrobot 1.0.0 和 `git`,LibXR 视图需要 libxr 6.0.0,两者按上一节安装。扩展在 `PATH`、pip 的用户脚本目录和设置项 `xrobot.cli.extraPath` 中查找这些命令;命令装在虚拟环境中时,把虚拟环境中 `bin` 目录(Windows 上为 `Scripts` 目录)的完整路径写入 `xrobot.cli.extraPath`。MSPM0 的 "Open in SysConfig" 另需设置 `xrobot.libxr.sysconfigTool` 和 `xrobot.libxr.mspm0SdkDir`,留空时使用同名环境变量 `SYSCONFIG_TOOL` 与 `MSPM0_SDK_INSTALL_DIR`。 +扩展要求 VS Code 1.108 及以上版本,MSPM0、HPM 工程和引脚布局需要扩展 2.1.0。XRobot 视图需要 xrobot 1.0.0 和 `git`;LibXR 视图需要 libxr,STM32 工程用 6.0.0 即可,MSPM0、HPM 工程和引脚布局需要 6.1.0;两者按上一节安装。扩展在 `PATH`、pip 的用户脚本目录和设置项 `xrobot.cli.extraPath` 中查找这些命令;命令装在虚拟环境中时,把虚拟环境中 `bin` 目录(Windows 上为 `Scripts` 目录)的完整路径写入 `xrobot.cli.extraPath`。MSPM0 工程的解析(运行 SysConfig)和 "Open in SysConfig" 使用设置项 `xrobot.libxr.sysconfigTool` 和 `xrobot.libxr.mspm0SdkDir`,留空时使用环境变量 `SYSCONFIG_TOOL` 与 `MSPM0_SDK_INSTALL_DIR`。 ## 平台 diff --git a/docs/env_setup/hpm.md b/docs/env_setup/hpm.md index d3baffe..a5492cf 100644 --- a/docs/env_setup/hpm.md +++ b/docs/env_setup/hpm.md @@ -41,7 +41,7 @@ HPM SDK 从环境变量 `GNURISCV_TOOLCHAIN_PATH` 读取工具链的安装目录 ``` * `CMakeLists.txt` 用 `find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})` 引入 HPM SDK,`BOARD_SEARCH_PATH` 指向 `boards/`,并设置 `CONFIG_DMA_MGR 1`(LibXR 的 HPM 驱动依赖 SDK 的 dma_mgr 组件) -* `app.yaml` 声明对 `board_gpt_pin` 的依赖;`boards//` 下有唯一的 `.hpmpc` 文件(BSP 命名为 `tool_config.hpmpc`)——两者共同构成 HPM 工程的特征,`libxr hpm setup` 和 VS Code 扩展据此识别工程 +* `app.yaml` 声明对 `board_gpt_pin` 的依赖;`boards//` 下有唯一的 `.hpmpc` 文件(BSP 命名为 `tool_config.hpmpc`);`libxr hpm setup` 和 VS Code 扩展按这两项识别 HPM 工程 * `boards//pinmux.c` 由 HPM Pinmux Tool 从 `tool_config.hpmpc` 生成,提供 `init_bsp_pins()` * `main.c` 在工程根目录:先 `init_bsp_pins()`,再 SDK 板级的 `board_init()`,然后调用各外设的时钟函数(`init_uart3_clock()` 一类),最后进入 `app_main()` * `User/` 存放代码生成的 `app_main.cpp`;`libxr hpm setup` 会在其中生成 `libxr_config.yaml` @@ -49,9 +49,10 @@ HPM SDK 从环境变量 `GNURISCV_TOOLCHAIN_PATH` 读取工具链的安装目录 ## 构建 -`CMakePresets.json` 提供 `debug-flash-xip`、`debug-ram` 和 `release-flash-xip` 三个 preset(Ninja 生成器,`HPM_BUILD_TYPE` 对应 `flash_xip` 或 `ram`): +`CMakePresets.json` 提供 `debug-flash-xip`、`debug-ram` 和 `release-flash-xip` 三个 preset(Ninja 生成器,`HPM_BUILD_TYPE` 对应 `flash_xip` 或 `ram`)。BSP 使用 XRobot 模块,配置前先运行一次 `xrobot setup`,它按 `xrobot.lock` 拉取模块并生成 `Modules/CMakeLists.txt`: ```bash +xrobot setup cmake --preset release-flash-xip cmake --build --preset release-flash-xip ``` @@ -72,12 +73,13 @@ set(LIBXR_NO_EIGEN True) ## LibXR 的 HPM 驱动 -`driver/hpm` 提供四个驱动,由该目录的 `CMakeLists.txt` 统一加入构建: +`driver/hpm` 中的驱动由该目录的 `CMakeLists.txt` 统一加入构建: - `hpm_gpio.*`:GPIO - `hpm_i2c.*`:I2C 主机 - `hpm_pwm.*`:PWM - `hpm_timebase.*`:基于 MCHTMR 的时间基准 +- `hpm_dma.*`:初始化 SDK 的 dma_mgr(只做一次),供 I2C 的 DMA 后台路径使用 驱动只调用 SDK 的驱动函数;外设的引脚复用、时钟和初始化顺序由工程负责(`init_bsp_pins()`、`board_init()` 和 `init_*_clock()`),LibXR 对象在 `app_main()` 中创建。驱动依赖 SDK 的 `dma_mgr` 组件,BSP 用 `CONFIG_DMA_MGR 1` 启用它。 @@ -91,5 +93,5 @@ set(LIBXR_NO_EIGEN True) ```bash docker run --rm -v "$PWD:/work" -w /work ghcr.io/xrobot-org/docker-image-hpm:main \ - bash -c 'cmake --preset release-flash-xip && cmake --build --preset release-flash-xip' + bash -c 'pip install xrobot==1.0.0 && xrobot setup && cmake --preset release-flash-xip && cmake --build --preset release-flash-xip' ``` diff --git a/docs/env_setup/mspm0.md b/docs/env_setup/mspm0.md index 6241258..0984583 100644 --- a/docs/env_setup/mspm0.md +++ b/docs/env_setup/mspm0.md @@ -53,7 +53,7 @@ BSP 的目录结构如下: ``` * `main.c` 在工程根目录,先调用 SysConfig 生成的 `SYSCFG_DL_init()` 完成时钟、引脚和外设的初始化,然后进入 `app_main()` -* `.syscfg` 是 SysConfig 工程,在工程根目录;芯片、时钟、引脚和外设都由它描述,更换芯片只更换这份文件 +* `.syscfg` 是 SysConfig 工程,在工程根目录;芯片、时钟、引脚和外设都由它描述 * `cmake/MSPM0SysConfig.cmake` 在 CMake 配置阶段调用 SysConfig 命令行,把 `ti_msp_dl_config.c/.h`、`device.opt`、链接脚本等输出生成到构建目录;CMake 跟踪 `.syscfg` 的修改,下一次构建自动重新生成 * `User/` 存放代码生成的 `app_main.cpp` 和 `libxr_config.yaml` * `libxr/` 是 LibXR 子模块 @@ -68,13 +68,14 @@ set(LIBXR_DRIVER mspm0) set(LIBXR_NO_EIGEN True) ``` -`LIBXR_SYSTEM None` 表示裸机系统,`LIBXR_DRIVER mspm0` 启用 LibXR 的 `driver/mspm0` 驱动目录。newlib 的系统调用由 `libxr/driver/mspm0/mspm0_syscalls.c` 提供,工程里另写 `_write`、`_read` 一类的桩函数会与它重复。 +`LIBXR_SYSTEM None` 表示裸机系统,`LIBXR_DRIVER mspm0` 启用 LibXR 的 `driver/mspm0` 驱动目录。链接选项与 SDK 例程的 gcc makefile 相同(`-nostartfiles`、`--specs=nano.specs`、`--specs=nosys.specs`),C++ 运行时因此缺少的 `__dso_handle`、`_getpid` 和 `_kill` 由 LibXR 的 `driver/mspm0/mspm0_syscalls.c` 以弱定义提供,工程需要时可以自行定义。 ## 构建 -`CMakePresets.json` 提供 `debug` 和 `release` 两个 preset(Ninja 生成器,工具链文件 `cmake/arm-none-eabi-gcc.cmake`): +`CMakePresets.json` 提供 `debug` 和 `release` 两个 preset(Ninja 生成器,工具链文件 `cmake/arm-none-eabi-gcc.cmake`)。BSP 使用 XRobot 模块,配置前先运行一次 `xrobot setup`,它按 `xrobot.lock` 拉取模块并生成 `Modules/CMakeLists.txt`(xrobot 的安装见[环境配置](./README.md)): ```bash +xrobot setup cmake --preset debug cmake --build --preset debug ``` @@ -87,7 +88,7 @@ cmake --build --preset debug ```bash docker run --rm -v "$PWD:/work" -w /work ghcr.io/xrobot-org/docker-image-mspm0:main \ - bash -c 'cmake --preset release && cmake --build --preset release' + bash -c 'pip install xrobot==1.0.0 && xrobot setup && cmake --preset release && cmake --build --preset release' ``` ## 常见问题 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md index c79977f..6839e69 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md @@ -6,7 +6,7 @@ sidebar_position: 3 # HPM Code Generation -The CodeGenerator's `libxr hpm setup` command brings an HPM Pinmux Tool project to LibXR: it parses the project and generates C++ initialization code. The pin muxing and clocks are configured by the Pinmux Tool output (the pinmux functions that the root `main.c` calls), `main.c` stays BSP-owned, and the generated code is the `app_main` under `User/`, with every construction argument an HPM SDK macro. +The CodeGenerator's `libxr hpm setup` command brings an HPM Pinmux Tool project to LibXR: it parses the project and generates C++ initialization code. The pin muxing and clocks are configured by the code the Pinmux Tool exports, whose pinmux functions the root `main.c` calls, and `main.c` stays BSP-owned; the generated code is the `app_main` under `User/`, which constructs the LibXR objects from HPM SDK macros. --- @@ -40,13 +40,14 @@ When neither `--xrobot` nor `--no-xrobot` is given, the output file keeps its ch ## Example Output -The following run of bsp-hpm5301evklite had the project already up to date: +The following is the first run on a copy of bsp-hpm5301evklite with the three generated files under `User/` removed: ```text -[INFO] .\User\app_main.cpp uses XRobot; generating with --xrobot (--no-xrobot turns it off). +$ libxr hpm setup -d . --xrobot [INFO] Configuration exported to: .\.config.yaml [INFO] System: bare metal -[INFO] Generated User: unchanged app_main.cpp, app_main.h, libxr_config.yaml +[INFO] .\User\libxr_config.yaml does not exist; creating it with the default settings +[INFO] Generated User: wrote app_main.cpp, app_main.h, libxr_config.yaml [INFO] Next: run `xrobot gen` to bring User/xrobot_main.hpp up to date; libxr setup does not update it ===== [Configuration Summary] ===== @@ -72,7 +73,7 @@ Active Peripherals: USB0 ``` -The generator writes only the files whose content changes; in the example the project was already up to date and none of the three files was rewritten. Other in the summary lists the configurations LibXR has no driver for, see [Generated Objects and Naming](#generated-objects-and-naming). +Later runs rewrite only the files whose content changes. Other in the summary lists the configurations LibXR has no driver for, see [Generated Objects and Naming](#generated-objects-and-naming). --- @@ -100,7 +101,7 @@ After the run, the project gains or has these files modified: `app_main.cpp` contains the LibXR initialization function `app_main()`. Code between `/* User Code Begin N */` and `/* User Code End N */` survives regeneration; the rest is regenerated every time. The generated peripheral objects are `static` and stay valid after `app_main()` returns; long-lived local objects are declared `static`. A peripheral object can be passed to a thread or a module as a base-class pointer, see [Integrate with XRobot](../xrobot_inter.md). -The following is an excerpt of the `app_main.cpp` generated on bsp-hpm5301evklite, with `// ...` marking omissions: +The following is the `app_main.cpp` of that first run: ```cpp // Generated by `libxr gen`; do not edit by hand. @@ -120,8 +121,6 @@ The following is an excerpt of the `app_main.cpp` generated on bsp-hpm5301evklit using namespace LibXR; /* User Code Begin 1 */ -// KEY interrupt counter, incremented in the GPIO interrupt callback. -static std::atomic key_irq_count{0}; /* User Code End 1 */ extern "C" void app_main(void) @@ -163,23 +162,23 @@ extern "C" void app_main(void) } ``` -The pins and clocks are configured by the pinmux functions `main.c` calls, and the construction arguments reference SDK macros (`HPM_GPIO0`, `GPIO_DI_GPIOA`, `IRQn_GPIO0_A`, `HPM_I2C3`, `clock_i2c3`). A GPIO object carries the IRQ of its port, the port's interrupt service routine comes from the LibXR driver, the edge comes from the pinmux, and registering the callback (`RegisterCallback` and `EnableInterrupt`) belongs to the consumer. The HPM drivers of LibXR depend on the `dma_mgr` component of the SDK, and the project needs `CONFIG_DMA_MGR` enabled (the BSPs enable it). +The pins and clocks are configured by the pinmux functions `main.c` calls, and the construction arguments reference SDK macros (`HPM_GPIO0`, `GPIO_DI_GPIOA`, `IRQn_GPIO0_A`, `HPM_I2C3`, `clock_i2c3`). A GPIO object carries the IRQ of its port, the port's interrupt service routine comes from the LibXR driver, the edge comes from the pinmux, and registering the callback (`RegisterCallback` and `EnableInterrupt`) belongs to the consumer. The HPM drivers of LibXR depend on the `dma_mgr` component of the SDK, and the project's `CMakeLists.txt` sets `CONFIG_DMA_MGR`, as both BSPs do. --- ## Generated Objects and Naming -Objects are generated for the configurations LibXR has drivers for: one object per GPIO pin, one per I2C; PWM on a GPTMR is described below. The remaining configurations (UART, SPI, MCAN, ADC, ACMP, USB and so on) are listed under Other in the summary for display only. +Objects are generated for the configurations LibXR has drivers for: one object per GPIO pin and one per I2C that selects both SCL and SDA; PWM on a GPTMR is described below. The remaining configurations (UART, SPI, MCAN, ADC, ACMP, USB, an I2C without SCL or SDA, a GPTMR with capture inputs only and so on) are listed under Other in the summary for display only. The objects are named: | Configuration | Object name | Example | | --- | --- | --- | -| GPIO | the pin name (lower-case port letter plus line), renamed in the `GPIO:` section | `pa10`, `pb11` | -| I2C | the lower-case peripheral instance name | `i2c3` | +| GPIO | `p`, the lower-case port letter and the line without leading zeros, renamed in the `GPIO` section | `pa10`, `pa3` (PA03) | +| I2C | the lower-case peripheral name | `i2c3` | | PWM on a GPTMR | `pwm__ch` | `pwm_gptmr0_ch1` | -Every comparator (COMP_n) of a GPTMR gets a PWM object through the GPTMR path of `HPMPWM`; objects are generated only when the SoC has no PWM peripheral, decided from whether the chip's pin data has any PWM signal: HPM5301 has none, HPM5361 has 20, and on the latter the GPTMRs are listed under Other for display only. The duty comparator is fixed and the polarity is `NORMAL`; the objects and their registrations are generated unconditionally, and wrapping them in a preprocessor condition makes XRobot's generator reject the file. +Every comparator (COMP_n) of a GPTMR gets a PWM object through the GPTMR path of `HPMPWM`; objects are generated only when the SoC has no PWM peripheral, decided from whether the chip's pin data has any PWM signal: HPM5301 has none, HPM5361 has some, and on the latter the GPTMRs are listed under Other for display only. The duty comparator is fixed at 0 and the polarity is `NORMAL`; the objects and their registrations are generated unconditionally, and wrapping them in a preprocessor condition makes XRobot's generator reject the file. --- @@ -193,7 +192,9 @@ Every comparator (COMP_n) of a GPTMR gets a PWM object through the GPTMR path of | `PWM` | `frequency` (default null) | one entry per object; null calls no `SetConfig`, a given value must be a positive integer (Hz) | | `GPIO` | the key is a pin name, the value is the new name | renames a pin; a null value keeps the default name. The section lists every pin the project read | -The HPM generator creates no UART yet, so `terminal_source` has no terminal to point at; setting it prints a warning. +A null value takes the default; a number may also be written as a string holding an integer literal (such as `'0x61A80'`). Settings keys match without regard to case, and the spelling already in the file is kept. A new GPIO name must be a valid C++ identifier that is no C++ keyword or reserved identifier and does not collide with an HPM SDK macro, a name of the generated code or another object; every name that breaks this is listed at once and generation fails. When a pin leaves the project, its rename entry is removed if its value is null, and kept with a warning if it holds a name. + +The HPM generator creates no UART (the HPM UART driver of LibXR has not been merged yet), so no terminal is generated; a `terminal_source` written in the file prints a warning. The following is the `User/libxr_config.yaml` generated on bsp-hpm5301evklite the first time: @@ -222,14 +223,14 @@ The data currently covers HPM5301 (QFN48) and HPM5361 (LQFP100, LQFP64, QFN48); ## Regenerating Code -After changing the `.hpmpc`, `main.c` or `User/libxr_config.yaml`, run `libxr hpm setup -d .` in the project root again, or regenerate only the files under `User/`: +After changing the `.hpmpc`, `main.c` or `User/libxr_config.yaml`, run `libxr hpm setup -d .` again at the project root, or run the two steps: ```bash libxr parse -d . libxr gen -i .config.yaml -o User/app_main.cpp ``` -`.config.yaml` is written by `libxr parse`; a freshly cloned project does not have it, so run `libxr parse` first. The Generate LibXR Code action of the VS Code extension runs the two commands in sequence, see [VS Code Extension](../../env_setup/README.md#vs-code-extension). +`.config.yaml` is written by `libxr parse`; a freshly cloned project does not have it, so run `libxr parse` first. Without `--xrobot` and `--no-xrobot`, `libxr gen` keeps the choice of the output file; afterwards `xrobot gen` brings `User/xrobot_main.hpp` up to date. The Generate LibXR Code action of the VS Code extension runs the two commands in sequence, see [VS Code Extension](../../env_setup/README.md#vs-code-extension). --- diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md index 65b43a2..78b6ea8 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md @@ -6,7 +6,7 @@ sidebar_position: 2 # MSPM0 Code Generation -The CodeGenerator's `libxr mspm0 setup` command brings a TI SysConfig project to LibXR: it parses the `.syscfg` file at the project root and generates C++ initialization code. SysConfig configures the clocks, pins, DMA channels and peripherals (`SYSCFG_DL_init()` in `main.c`); the generated code declares the LibXR objects and registers them with XRobot, and every construction argument is a macro SysConfig generated. +The CodeGenerator's `libxr mspm0 setup` command brings a TI SysConfig project to LibXR: it parses the `.syscfg` file at the project root and generates C++ initialization code. SysConfig configures the clocks, pins, DMA channels and peripherals, which `main.c` initializes with `SYSCFG_DL_init()`; the generated code constructs the LibXR objects from the macros SysConfig generated, and an XRobot project also gets the `XR_REGISTER` registrations. --- @@ -40,15 +40,17 @@ The BSP's CMake runs SysConfig on the `.syscfg` at configure time and writes the ## Example Output -The following run of bsp-mspm0g3507-mini had the two environment variables set, and the project was already up to date: +The following is the first run on a copy of bsp-mspm0g3507-mini with the three generated files under `User/` removed, with the two environment variables set: ```text -[INFO] .\User\app_main.cpp uses XRobot; generating with --xrobot (--no-xrobot turns it off). +$ libxr mspm0 setup -d . --xrobot [INFO] Processing mspm0g3507_minidb48.syscfg... [INFO] Running SysConfig on mspm0g3507_minidb48.syscfg [INFO] Configuration exported to: .\.config.yaml [INFO] System: bare metal -[INFO] Generated User: unchanged app_main.cpp, app_main.h, libxr_config.yaml +[INFO] .\User\libxr_config.yaml does not exist; creating it with the default settings +[INFO] terminal_source is not set; using uart0 +[INFO] Generated User: wrote app_main.cpp, app_main.h, libxr_config.yaml [INFO] Next: run `xrobot gen` to bring User/xrobot_main.hpp up to date; libxr setup does not update it ===== [Configuration Summary] ===== @@ -80,7 +82,7 @@ Active Peripherals: QEI_TIMG8 ``` -The generator writes only the files whose content changes; in the example the project was already up to date and none of the three files was rewritten. Other in the summary lists the configurations LibXR has no driver for, see [Generated Objects and Naming](#generated-objects-and-naming). +Later runs rewrite only the files whose content changes. Other in the summary lists the configurations LibXR has no driver for, see [Generated Objects and Naming](#generated-objects-and-naming). --- @@ -105,7 +107,7 @@ After the run, the project gains or has these files modified: `app_main.cpp` contains the LibXR initialization function `app_main()`. Code between `/* User Code Begin N */` and `/* User Code End N */` survives regeneration; the rest is regenerated every time. The generated peripheral objects are `static` and stay valid after `app_main()` returns; long-lived local objects are declared `static`. A peripheral object can be passed to a thread or a module as a base-class pointer, see [Integrate with XRobot](../xrobot_inter.md). -The following is an excerpt of the `app_main.cpp` generated on bsp-mspm0g3507-mini, with `// ...` marking omissions: +The following is an excerpt of the `app_main.cpp` of that first run, with `// ...` marking omissions: ```cpp // Generated by `libxr gen`; do not edit by hand. @@ -116,13 +118,17 @@ The following is an excerpt of the `app_main.cpp` generated on bsp-mspm0g3507-mi #include "libxr.hpp" #include "mspm0_gpio.hpp" -// ... +#include "mspm0_i2c.hpp" +#include "mspm0_pwm.hpp" +#include "mspm0_spi.hpp" +#include "mspm0_timebase.hpp" +#include "mspm0_uart.hpp" +#include "ti_msp_dl_config.h" +#include "xrobot_main.hpp" using namespace LibXR; /* User Code Begin 1 */ -// KEY interrupt counters, incremented in the GPIO interrupt callbacks. -static std::atomic key1_irq_count{0}; /* User Code End 1 */ // Input clocks: the BUSCLK of the power domain. PD0 from ULPCLK = CPUCLK_FREQ / 2 @@ -136,6 +142,7 @@ static constexpr uint32_t PD1_BUSCLK_FREQ = CPUCLK_FREQ; // MSPM0_UART_MAIN_INIT checks these names against the ones SysConfig generated. #define DMA_CH_UART0_TX_LIBXR_UART_IRQN UART_0_INST_INT_IRQN #define DMA_CH_UART0_TX_LIBXR_UART_TX 1 +// ... // DMA buffers. A UART gets 2 x N bytes for its two transmit halves; the receive side // runs on byte interrupts. The SPI DMA buffers are split in two halves as well; the @@ -143,6 +150,7 @@ static constexpr uint32_t PD1_BUSCLK_FREQ = CPUCLK_FREQ; alignas(size_t) static uint8_t uart0_tx_buf[2 * 128]; // ... alignas(4) static uint8_t i2c0_buf[32]; +// ... extern "C" void app_main(void) { @@ -159,6 +167,8 @@ extern "C" void app_main(void) static MSPM0GPIO LED1(GPIO_LEDS_PIN_LED1_PORT, GPIO_LEDS_PIN_LED1_PIN, GPIO_LEDS_PIN_LED1_IOMUX); // ... + static MSPM0GPIO KEY1(GPIO_KEYS_PORT, GPIO_KEYS_PIN_KEY1_PIN, GPIO_KEYS_PIN_KEY1_IOMUX); + static MSPM0GPIO KEY2(GPIO_KEYS_PORT, GPIO_KEYS_PIN_KEY2_PIN, GPIO_KEYS_PIN_KEY2_IOMUX); // UART: TX with DMA; the receive side runs on byte interrupts. static MSPM0UART uart0(MSPM0_UART_MAIN_INIT(UART_0, DMA_CH_UART0_TX, uart0_tx_buf, @@ -168,6 +178,7 @@ extern "C" void app_main(void) // I2C: polling; the buffer stages DMA transfers. static MSPM0I2C i2c0(MSPM0_I2C_INIT(I2C_0, PD0_BUSCLK_FREQ, i2c0_buf, sizeof(i2c0_buf), 8), {I2C_0_BUS_SPEED_HZ}); + // ... // SPI: DMA for transfers longer than the threshold. static MSPM0SPI spi1(MSPM0_SPI_INIT(SPI_1, PD1_BUSCLK_FREQ, DMA_CH_SPI1_RX, @@ -183,16 +194,58 @@ extern "C" void app_main(void) STDIO::write_ = uart0.write_port_; static RamFS ramfs("XRobot"); static Terminal<32, 32, 5, 5> terminal(ramfs); + static auto terminal_task = Timer::CreateTask(terminal.TaskFun, &terminal, 10); + Timer::Add(terminal_task); + Timer::Start(terminal_task); + + // Hardware registration + XR_REGISTER(LED1, LibXR::GPIO); + // ... + + XR_REGISTER(pwm_tima1_c0, LibXR::PWM); + // ... + + XR_REGISTER(spi1, LibXR::SPI); + + XR_REGISTER(uart0, LibXR::UART); + // ... + + XR_REGISTER(i2c0, LibXR::I2C); + // ... + + XR_REGISTER(ramfs, LibXR::RamFS); + + XR_REGISTER(terminal, LibXR::Terminal<32, 32, 5, 5>); + /* User Code Begin 3 */ - KEY1.SetConfig({GPIO::Direction::FALL_INTERRUPT, GPIO::Pull::NONE}); - KEY1.RegisterCallback(GPIO::Callback::Create(OnKeyInterrupt, &key1_irq_count)); - KEY1.EnableInterrupt(); /* User Code End 3 */ XROBOT_MAIN(); } ``` -Every peripheral object is constructed from macros SysConfig generated, such as `GPIO_LEDS_PIN_LED1_PORT` for a GPIO or `UART_0` for a UART. The interrupts of these objects are enabled and prioritized by the LibXR drivers at construction, overriding the interrupt settings SysConfig made for the same IRQs; the edge of a pin interrupt comes from SysConfig, and registering the callback (`RegisterCallback` and `EnableInterrupt`) belongs to the consumer, shown in the User Code regions of the example. +Every peripheral object is constructed from macros SysConfig generated, such as `GPIO_LEDS_PIN_LED1_PORT` for a GPIO or `UART_0` for a UART. The interrupts these objects use are enabled and prioritized by the LibXR drivers at construction, overriding the interrupt settings SysConfig made for the same IRQs. The edge of a pin interrupt comes from SysConfig, and the consumer registers the callback (`RegisterCallback` and `EnableInterrupt`) in a Module or a User Code region, for example to count the interrupts of KEY1: + +```cpp +/* User Code Begin 1 */ +#include + +static std::atomic key1_irq_count{0}; + +static void OnKeyInterrupt(bool in_isr, std::atomic* count) +{ + (void)in_isr; + count->fetch_add(1, std::memory_order_relaxed); +} +/* User Code End 1 */ + +// ... + + /* User Code Begin 3 */ + KEY1.SetConfig({GPIO::Direction::FALL_INTERRUPT, GPIO::Pull::NONE}); + KEY1.RegisterCallback(GPIO::Callback::Create(OnKeyInterrupt, &key1_irq_count)); + KEY1.EnableInterrupt(); + /* User Code End 3 */ +``` --- @@ -205,7 +258,7 @@ The objects are named: | Configuration | Object name | Example | | --- | --- | --- | | GPIO | the label of the pin in SysConfig (the `$name` without its `PIN_` prefix) | `LED1`, `KEY1` | -| UART, I2C, SPI | the lower-case peripheral instance name | `uart0`, `i2c1`, `spi1` | +| UART, I2C, SPI | the lower-case name of the peripheral the instance uses (`UART_0` uses UART0) | `uart0`, `i2c1`, `spi1` | | PWM | `pwm__c` | `pwm_tima1_c0` | When the `$name` of a GPIO pin without its `PIN_` prefix is not a valid identifier (the SysConfig default `PIN_0` leaves `0`), the object takes the lower-case group plus pin name instead (such as `gpio_btn_pin_0`), and a warning asks for naming the pin in SysConfig. @@ -228,9 +281,9 @@ The generated code defines a BUSCLK constant for every power domain in use: the ## libxr_config.yaml -`User/libxr_config.yaml` stores the settings of code generation. A missing file is created with the defaults; later runs fill in the missing settings and keep the values already present. A peripheral's settings section is written only when the project has that peripheral, one entry per instance keyed by the lower-case instance name, and a PWM entry by its object name. A null value (a key without a value in the YAML) takes the default; buffers and queues must be positive integers. +`User/libxr_config.yaml` stores the settings of code generation. A missing file is created with the defaults; later runs fill in the missing settings and keep the values already present. A peripheral's settings section is written only when the project has that peripheral, one entry per object keyed by the object name (`uart0`, `pwm_tima1_c0`). A null value (a key without a value in the YAML) takes the default; buffers and queues must be positive integers. -The table lists the settings sections; defaults that differ from STM32 are noted: +The settings sections: | Section | Keys and defaults | Notes | | --- | --- | --- | @@ -286,14 +339,14 @@ The I2C bus speed and the UART baud rate come from the SysConfig project (such a ## Regenerating Code -After changing the `.syscfg` or `User/libxr_config.yaml`, run `libxr mspm0 setup -d .` in the project root again, or regenerate only the files under `User/`: +After changing the `.syscfg` or `User/libxr_config.yaml`, run `libxr mspm0 setup -d .` again at the project root (the SysConfig output comes from the same sources as above), or run the two steps: ```bash libxr parse -d . libxr gen -i .config.yaml -o User/app_main.cpp ``` -`.config.yaml` is written by `libxr parse`; a freshly cloned project does not have it, so run `libxr parse` first. The Generate LibXR Code action of the VS Code extension runs the two commands in sequence, see [VS Code Extension](../../env_setup/README.md#vs-code-extension). +`.config.yaml` is written by `libxr parse`; a freshly cloned project does not have it, so run `libxr parse` first. Without `--xrobot` and `--no-xrobot`, `libxr gen` keeps the choice of the output file; afterwards `xrobot gen` brings `User/xrobot_main.hpp` up to date. The Generate LibXR Code action of the VS Code extension runs the two commands in sequence, see [VS Code Extension](../../env_setup/README.md#vs-code-extension). --- diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/pins.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/pins.md index 0b0b210..fd23d6e 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/pins.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/pins.md @@ -22,17 +22,14 @@ libxr pins -d path/to/project The model is a positional argument. The package of an MSPM0 comes from the package code in the model suffix first (`PM` of `MSPM0G3507SPMR`); when it cannot be told, give it with `--package` (`LQFP-64`, `PM` and the like all work). The model of an HPM is the SoC name; when the SoC has several packages, give it with `--package`. -With `-d` naming a project directory, the printed layout overlays the signals the project has selected and their `libxr_config.yaml` settings. An STM32 project reads the `.ioc` file, an MSPM0 project reads the `.syscfg` at the root (the package comes from the SysConfig project), and an HPM project reads the `.hpmpc` under `boards/` and the pinmux functions `main.c` calls (the package comes with the parse result). The settings are read from the file `--libxr-config` names, by default `User/libxr_config.yaml` in the project. +With `-d` naming a project directory, the printed layout overlays the signals the project has selected and their `libxr_config.yaml` settings. An STM32 project reads the `.ioc` file, an MSPM0 project reads the `.syscfg` at the root (the package comes from the SysConfig project), and an HPM project reads the `.hpmpc` under `boards/` and the pinmux functions `main.c` calls outside preprocessor conditions (the package comes from the `.hpmpc`). The settings are read from the file `--libxr-config` names, by default `User/libxr_config.yaml` in the project. --- ## Output -```bash -$ libxr pins MSPM0G3507 --package LQFP-64 -``` - ```yaml +$ libxr pins MSPM0G3507 --package LQFP-64 model: MSPM0G3507 platform: mspm0 part: MSPM0G3507 @@ -60,14 +57,18 @@ peripherals: ## Project Overlay -```bash -$ libxr pins -d . -``` - -With the project overlaid, the output gains two parts. The `pins` section lists the selected signals pin by pin, and a GPIO pin carries its label from the vendor project: +With `-d` the output gains a `project` section: `directory` and `source` record the project directory and the project file read, `libxr_config` and `sysconfig_file` the settings file and the SysConfig project read (the `sysconfig_file` of an HPM project is its `.hpmpc`); `assignments` lists the selected signals pin by pin, with the object name of a GPIO pin in the generated code as `label`; and `peripherals` lists per peripheral the pins it occupies, for an MSPM0 project its parameters in SysConfig (`sysconfig`), and its settings entries in `libxr_config.yaml` (`config`). The following is taken from bsp-mspm0g3507-mini: ```yaml - pins: +$ libxr pins -d . +# ... +project: + directory: . + source: mspm0g3507_minidb48.syscfg + libxr_config: User\libxr_config.yaml + sysconfig_file: mspm0g3507_minidb48.syscfg + assignments: + # ... PB8: signal: PB8 peripheral: GPIOB @@ -75,12 +76,9 @@ With the project overlaid, the output gains two parts. The `pins` section lists function: P8 matched: true label: LED1 -# ... -``` - -The `peripherals` section lists, per instance, the pins it occupies, its parameters in the vendor project, and the matching settings in `libxr_config.yaml`: - -```yaml + # ... + peripherals: + # ... TIMA1: kind: TIMA pins: @@ -101,10 +99,10 @@ The `peripherals` section lists, per instance, the pins it occupies, its paramet present: true params: frequency: null -# ... + # ... ``` -A `matched` of `false` means the signal does not agree with what the pin can multiplex; it is given as it is. `config` is the list of the instance's settings entries in `libxr_config.yaml`: `present` tells whether the entry is already in the file, and `params` are the settings written; one PWM instance has one entry per channel. The GPIO renames of an HPM project are a whole section mapping: the `section: GPIO` entry has no `key`, and its `params` map pin names to new names. +A `matched` of `false` means the signal does not agree with what the pin can multiplex; it is given as it is. `config` is the list of the instance's settings entries in `libxr_config.yaml`: `present` tells whether the entry is already in the file, and `params` are the settings written; one PWM instance has one entry per channel. The GPIO renames of an HPM project are a whole section mapping: the `section: GPIO` entry has the `key` `null`, and its `params` map pin names to new names, a `null` value keeping the default name. --- @@ -115,7 +113,7 @@ A `matched` of `false` means the signal does not agree with what the pin can mul | `model` | the model (default: the one of the project given with `-d`) | | `-d`, `--directory` | the project directory: overlay the signals it has selected and their settings | | `-c`, `--libxr-config` | the libxr_config.yaml to read the settings from (default: `User/libxr_config.yaml` in the project) | -| `-p`, `--package` | the package, for a model that does not name it (MSPM0: `LQFP-64`, `PM`, ...); with `-d` an MSPM0 takes it from the SysConfig project | +| `-p`, `--package` | the package, for a model that does not name it (MSPM0: `LQFP-64`, `PM`, ...; HPM: `QFN48`, ...); with `-d` it comes from the SysConfig or Pinmux Tool project | | `-f`, `--format` | the output format: `yaml` (default) or `json` | | `--verbose` | enable debug logging | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/README.md b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/README.md index 9396ed8..83ab1d3 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/README.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/README.md @@ -77,9 +77,9 @@ The xrobot version a BSP uses is recorded in the `xrobot:` field of `Modules/mod The VS Code extension [`XRobot.xrobot`](https://marketplace.visualstudio.com/items?itemName=XRobot.xrobot) adds two views to the activity bar, XRobot and LibXR. When a BSP with `Modules/modules.yaml` is opened, the XRobot view shows its Modules, configurations and instances and makes changes through `xrobot` commands. -The LibXR view recognizes the platform from the workspace root: a project with an `.ioc` at its root is an STM32CubeMX project, an `app.yaml` with `boards/*/*.hpmpc` is an HPM project, and a SysConfig `.syscfg` is an MSPM0 project. The view shows the platform and the settings of `User/libxr_config.yaml`; the settings can be edited there and the code is regenerated. "Generate LibXR Code" runs `libxr parse` and `libxr gen`, or the platform's `libxr stm32 setup`, `libxr mspm0 setup` or `libxr hpm setup` while there is no `libxr_config.yaml` yet. For an MSPM0 project, "Open in SysConfig" opens the `.syscfg` in the standalone SysConfig; for an HPM project, "Open in HPM Pinmux Tool" opens the `.hpmpc` with HPMicro's HPM Pinmux Tool extension. Both views can open the package drawing of the chip (the pin layout, `libxr pins`, which needs a libxr that has the command): the selected pins are coloured by peripheral category, the package of an MSPM0 comes from its SysConfig project, and the panel is read-only. +The LibXR view recognizes the platform from the workspace root: a project with an `.ioc` at its root is an STM32CubeMX project, an `app.yaml` with `boards/*/*.hpmpc` is an HPM project, and a SysConfig `.syscfg` is an MSPM0 project. The view shows the platform and the settings of `User/libxr_config.yaml`; the settings can be edited there and the code is regenerated. "Generate LibXR Code" runs `libxr parse` and `libxr gen`, or the platform's `libxr stm32 setup`, `libxr mspm0 setup` or `libxr hpm setup` while there is no `libxr_config.yaml` yet. For an MSPM0 project, "Open in SysConfig" opens the `.syscfg` in the standalone SysConfig; for an HPM project, "Open in HPM Pinmux Tool" opens the `.hpmpc` with HPMicro's HPM Pinmux Tool extension. "Pin Layout" in the LibXR view opens the package drawing of the chip (the pin layout, `libxr pins`): the selected pins are coloured by peripheral category, the package of an MSPM0 comes from its SysConfig project, and the panel is read-only. -Extension 2.0.0 requires VS Code 1.108 or newer. The XRobot view needs xrobot 1.0.0 and `git`, the LibXR view needs libxr 6.0.0, both installed as in the previous section. The extension looks up these commands on `PATH`, in pip's per-user script directories and in the `xrobot.cli.extraPath` setting; when the commands are installed in a virtual environment, put the full path of its `bin` directory (`Scripts` on Windows) in `xrobot.cli.extraPath`. "Open in SysConfig" for MSPM0 additionally uses the settings `xrobot.libxr.sysconfigTool` and `xrobot.libxr.mspm0SdkDir`; when they are empty, the environment variables `SYSCONFIG_TOOL` and `MSPM0_SDK_INSTALL_DIR` of the same names are used. +The extension requires VS Code 1.108 or newer; MSPM0 and HPM projects and the pin layout need extension 2.1.0. The XRobot view needs xrobot 1.0.0 and `git`; the LibXR view needs libxr, 6.0.0 for STM32 projects and 6.1.0 for MSPM0 and HPM projects and the pin layout; both are installed as in the previous section. The extension looks up these commands on `PATH`, in pip's per-user script directories and in the `xrobot.cli.extraPath` setting; when the commands are installed in a virtual environment, put the full path of its `bin` directory (`Scripts` on Windows) in `xrobot.cli.extraPath`. Parsing an MSPM0 project (which runs SysConfig) and "Open in SysConfig" use the settings `xrobot.libxr.sysconfigTool` and `xrobot.libxr.mspm0SdkDir`; when they are empty, the environment variables `SYSCONFIG_TOOL` and `MSPM0_SDK_INSTALL_DIR` are used. ## Platforms diff --git a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md index 41a86a4..13ed6a1 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md @@ -41,7 +41,7 @@ Taking bsp-hpm5301evklite as the example: ``` * `CMakeLists.txt` brings in the HPM SDK with `find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})`, points `BOARD_SEARCH_PATH` at `boards/`, and sets `CONFIG_DMA_MGR 1` (the HPM drivers of LibXR depend on the SDK's dma_mgr component) -* `app.yaml` declares the dependency on `board_gpt_pin`; `boards//` contains the single `.hpmpc` file (the BSPs name it `tool_config.hpmpc`) — together these mark out an HPM project, which is how `libxr hpm setup` and the VS Code extension recognize one +* `app.yaml` declares the dependency on `board_gpt_pin`; `boards//` contains the single `.hpmpc` file (the BSPs name it `tool_config.hpmpc`); `libxr hpm setup` and the VS Code extension recognize an HPM project by these two * `boards//pinmux.c` is generated by the HPM Pinmux Tool from `tool_config.hpmpc` and provides `init_bsp_pins()` * `main.c` sits in the project root: `init_bsp_pins()` first, then the SDK board's `board_init()`, then the clock functions of the peripherals (`init_uart3_clock()` and its siblings), and finally `app_main()` * `User/` holds the generated `app_main.cpp`; `libxr hpm setup` generates `libxr_config.yaml` next to it @@ -49,9 +49,10 @@ Taking bsp-hpm5301evklite as the example: ## Build -`CMakePresets.json` provides the `debug-flash-xip`, `debug-ram` and `release-flash-xip` presets (Ninja generator, `HPM_BUILD_TYPE` of `flash_xip` or `ram`): +`CMakePresets.json` provides the `debug-flash-xip`, `debug-ram` and `release-flash-xip` presets (Ninja generator, `HPM_BUILD_TYPE` of `flash_xip` or `ram`). The BSP uses XRobot Modules, so `xrobot setup` runs once before configuring; it fetches the Modules from `xrobot.lock` and generates `Modules/CMakeLists.txt`: ```bash +xrobot setup cmake --preset release-flash-xip cmake --build --preset release-flash-xip ``` @@ -72,12 +73,13 @@ set(LIBXR_NO_EIGEN True) ## The LibXR HPM Drivers -`driver/hpm` provides four drivers, added to the build by the directory's `CMakeLists.txt`: +The drivers in `driver/hpm` are added to the build by the directory's `CMakeLists.txt`: - `hpm_gpio.*`: GPIO - `hpm_i2c.*`: I2C master - `hpm_pwm.*`: PWM - `hpm_timebase.*`: timebase on MCHTMR +- `hpm_dma.*`: initializes the SDK's dma_mgr once, for the DMA background path of the I2C The drivers call SDK driver functions only; pin muxing, clocks and the initialization order belong to the project (`init_bsp_pins()`, `board_init()` and the `init_*_clock()` functions), and the LibXR objects are created in `app_main()`. The drivers depend on the SDK's `dma_mgr` component, which the BSPs enable with `CONFIG_DMA_MGR 1`. @@ -91,5 +93,5 @@ The image `ghcr.io/xrobot-org/docker-image-hpm:main` ships the RISC-V toolchain ```bash docker run --rm -v "$PWD:/work" -w /work ghcr.io/xrobot-org/docker-image-hpm:main \ - bash -c 'cmake --preset release-flash-xip && cmake --build --preset release-flash-xip' + bash -c 'pip install xrobot==1.0.0 && xrobot setup && cmake --preset release-flash-xip && cmake --build --preset release-flash-xip' ``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/mspm0.md b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/mspm0.md index eaffd91..81d0383 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/mspm0.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/mspm0.md @@ -53,7 +53,7 @@ The BSP directory structure: ``` * `main.c` sits in the project root, calls the SysConfig-generated `SYSCFG_DL_init()` for the clocks, pins and peripherals, and then enters `app_main()` -* The `.syscfg` file is the SysConfig project, in the project root; it describes the device, clocks, pins and peripherals, and changing the device means changing this one file +* The `.syscfg` file is the SysConfig project, in the project root; it describes the device, clocks, pins and peripherals * `cmake/MSPM0SysConfig.cmake` runs the SysConfig command line at the CMake configure step and generates `ti_msp_dl_config.c/.h`, `device.opt`, the linker script and the rest into the build directory; CMake tracks changes to the `.syscfg` and regenerates on the next build * `User/` holds the generated `app_main.cpp` and `libxr_config.yaml` * `libxr/` is the LibXR submodule @@ -68,13 +68,14 @@ set(LIBXR_DRIVER mspm0) set(LIBXR_NO_EIGEN True) ``` -`LIBXR_SYSTEM None` is the bare-metal system and `LIBXR_DRIVER mspm0` enables the LibXR `driver/mspm0` driver directory. The newlib system calls come from `libxr/driver/mspm0/mspm0_syscalls.c`; stub functions such as `_write` or `_read` written elsewhere in the project would duplicate it. +`LIBXR_SYSTEM None` is the bare-metal system and `LIBXR_DRIVER mspm0` enables the LibXR `driver/mspm0` driver directory. The link options are those of the SDK example gcc makefiles (`-nostartfiles`, `--specs=nano.specs`, `--specs=nosys.specs`), and `__dso_handle`, `_getpid` and `_kill`, which the C++ runtime then lacks, are provided as weak definitions by the LibXR `driver/mspm0/mspm0_syscalls.c`; a project can define its own. ## Build -`CMakePresets.json` provides the `debug` and `release` presets (Ninja generator, toolchain file `cmake/arm-none-eabi-gcc.cmake`): +`CMakePresets.json` provides the `debug` and `release` presets (Ninja generator, toolchain file `cmake/arm-none-eabi-gcc.cmake`). The BSP uses XRobot Modules, so `xrobot setup` runs once before configuring; it fetches the Modules from `xrobot.lock` and generates `Modules/CMakeLists.txt` (installing xrobot is described in [Environment Setup](./README.md)): ```bash +xrobot setup cmake --preset debug cmake --build --preset debug ``` @@ -87,7 +88,7 @@ The image `ghcr.io/xrobot-org/docker-image-mspm0:main` ships `arm-none-eabi-gcc` ```bash docker run --rm -v "$PWD:/work" -w /work ghcr.io/xrobot-org/docker-image-mspm0:main \ - bash -c 'cmake --preset release && cmake --build --preset release' + bash -c 'pip install xrobot==1.0.0 && xrobot setup && cmake --preset release && cmake --build --preset release' ``` ## FAQ From 42a787e537a37219d3f5ffb508baedfab45ffcbc Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 10 Oct 2026 03:31:45 +0100 Subject: [PATCH 05/16] HPM: the GPIO clock joins the clock group before init_bsp_pins() --- docs/env_setup/hpm.md | 2 +- i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/env_setup/hpm.md b/docs/env_setup/hpm.md index a5492cf..e566253 100644 --- a/docs/env_setup/hpm.md +++ b/docs/env_setup/hpm.md @@ -43,7 +43,7 @@ HPM SDK 从环境变量 `GNURISCV_TOOLCHAIN_PATH` 读取工具链的安装目录 * `CMakeLists.txt` 用 `find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})` 引入 HPM SDK,`BOARD_SEARCH_PATH` 指向 `boards/`,并设置 `CONFIG_DMA_MGR 1`(LibXR 的 HPM 驱动依赖 SDK 的 dma_mgr 组件) * `app.yaml` 声明对 `board_gpt_pin` 的依赖;`boards//` 下有唯一的 `.hpmpc` 文件(BSP 命名为 `tool_config.hpmpc`);`libxr hpm setup` 和 VS Code 扩展按这两项识别 HPM 工程 * `boards//pinmux.c` 由 HPM Pinmux Tool 从 `tool_config.hpmpc` 生成,提供 `init_bsp_pins()` -* `main.c` 在工程根目录:先 `init_bsp_pins()`,再 SDK 板级的 `board_init()`,然后调用各外设的时钟函数(`init_uart3_clock()` 一类),最后进入 `app_main()` +* `main.c` 在工程根目录:先调用板级时钟函数把 GPIO 时钟加入时钟组(bsp-hpm5301evklite 为 `init_board_clock()`,bsp-rmcs-slave-lite 为 `board_init_clock_group()`),再 `init_bsp_pins()`,然后 SDK 板级的 `board_init()` 和各外设的时钟函数(`init_uart3_clock()` 一类),最后进入 `app_main()`。GPIO 时钟加入时钟组之前,`init_bsp_pins()` 对 GPIO 方向和电平的设置不生效 * `User/` 存放代码生成的 `app_main.cpp`;`libxr hpm setup` 会在其中生成 `libxr_config.yaml` * `libxr/` 是 LibXR 子模块 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md index 13ed6a1..bc74d63 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md @@ -43,7 +43,7 @@ Taking bsp-hpm5301evklite as the example: * `CMakeLists.txt` brings in the HPM SDK with `find_package(hpm-sdk REQUIRED HINTS $ENV{HPM_SDK_BASE})`, points `BOARD_SEARCH_PATH` at `boards/`, and sets `CONFIG_DMA_MGR 1` (the HPM drivers of LibXR depend on the SDK's dma_mgr component) * `app.yaml` declares the dependency on `board_gpt_pin`; `boards//` contains the single `.hpmpc` file (the BSPs name it `tool_config.hpmpc`); `libxr hpm setup` and the VS Code extension recognize an HPM project by these two * `boards//pinmux.c` is generated by the HPM Pinmux Tool from `tool_config.hpmpc` and provides `init_bsp_pins()` -* `main.c` sits in the project root: `init_bsp_pins()` first, then the SDK board's `board_init()`, then the clock functions of the peripherals (`init_uart3_clock()` and its siblings), and finally `app_main()` +* `main.c` sits in the project root: a board clock function first adds the GPIO clock to the clock group (`init_board_clock()` in bsp-hpm5301evklite, `board_init_clock_group()` in bsp-rmcs-slave-lite), then `init_bsp_pins()`, then the SDK board's `board_init()` and the clock functions of the peripherals (`init_uart3_clock()` and its siblings), and finally `app_main()`. Until the GPIO clock is in the clock group, the GPIO directions and levels set by `init_bsp_pins()` have no effect * `User/` holds the generated `app_main.cpp`; `libxr hpm setup` generates `libxr_config.yaml` next to it * `libxr/` is the LibXR submodule From 6be586a51db7311d4f460532fb3dc4b34fed9a92 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 10 Oct 2026 05:29:00 +0100 Subject: [PATCH 06/16] Module CI: context refs follow the event, document the build-type input --- docs/proj_man/ci.md | 13 +++++++++---- .../current/proj_man/ci.md | 13 +++++++++---- 2 files changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/proj_man/ci.md b/docs/proj_man/ci.md index b691f2b..90bfd3a 100644 --- a/docs/proj_man/ci.md +++ b/docs/proj_man/ci.md @@ -12,7 +12,7 @@ sidebar_position: 6 ## 模块 CI -模块仓库调用共享工作流 `xrobot-org/XRobot/.github/workflows/module-ci.yml`。官方模块的 `.github/workflows/build.yml`(`dev` 与 `master` 相同),XRobot 和 LibXR 使用默认的 `master`: +模块仓库调用共享工作流 `xrobot-org/XRobot/.github/workflows/module-ci.yml`。官方模块的 `.github/workflows/build.yml`(`dev` 与 `master` 相同)不传 ref 输入,XRobot、LibXR 和依赖按事件的默认上下文构建: ```yaml name: Module CI @@ -31,11 +31,14 @@ jobs: `xrobot check-module` 像 `xrobot setup` 一样解析模块,会更新 `xrobot.lock` 和 `Modules/`;`-o FILE` 指定输出文件(默认 `module_check.cpp`),`--template-arg` 给出类模板的模板实参(每个写一次),`--offline` 只使用 `Modules/` 中已有的模块。 +`xrobot-ref`、`libxr-ref`、`dependency-ref` 默认为空,此时按事件决定上下文:PR 用目标分支;推送功能分支用同名分支,对方仓库没有同名分支时退回 `dev`;推送 `dev`/`master` 用 `dev`/`master`;tag 推送用 `master`;手动触发和定时用当前分支。PR 用目标分支而不是源分支:同名分支是还没有合并的代码,下游 PR 基于它通过不代表上游合并后可用;上游合并后手动重跑下游 PR,即可按合并后的代码重新构建。填入其中任何一个输入时覆盖按事件决定的值。 + | 输入 | 默认值 | 含义 | | --- | --- | --- | -| `xrobot-ref` | `master` | 使用的 XRobot 版本 | -| `libxr-ref` | `master` | 使用的 LibXR 版本 | -| `dependency-ref` | `refs/heads/master` | 依赖 `same-or-dev` 的上下文 | +| `xrobot-ref` | 空 | XRobot 的分支、tag 或提交;空时按事件决定(见上文) | +| `libxr-ref` | 空 | LibXR 的分支、tag 或提交;空时按事件决定(见上文) | +| `dependency-ref` | 空 | `same-or-dev` 依赖的上下文(`refs/heads/...` 或 `refs/tags/...`);空时为事件分支的 `refs/heads/` | +| `build-type` | `RelWithDebInfo` | CMake 构建类型,见下文 | | `template-args` | `'[]'` | 类模板的模板实参(JSON 列表) | | `sources` | 空 | 另外使用的 index URL,每行一个;与官方 index 列出同一个包时以官方为准 | | `image` | `ghcr.io/xrobot-org/docker-image-linux:main` | 构建容器 | @@ -44,6 +47,8 @@ jobs: | `ctest-regex` | 空 | 非空时构建测试并运行匹配的 CTest | | `ctest-timeout` | `15` | 每个 CTest 测试的超时(秒) | +`build-type` 的默认值 `RelWithDebInfo` 通常自带 `-DNDEBUG`,会关闭 `assert()`;工作流把该构建类型的编译选项设为 `-O2 -g`,让标准 `assert()` 和 `eigen_assert` 生效,并定义 `LIBXR_DEBUG_BUILD` 打开 LibXR 的调试构建(见 [LibXR 的构建配置](../basic_coding/cmake.md))。填其他值时原样使用。`cmake-options` 追加在最后,可以覆盖前面的参数。 + --- ## BSP CI diff --git a/i18n/en/docusaurus-plugin-content-docs/current/proj_man/ci.md b/i18n/en/docusaurus-plugin-content-docs/current/proj_man/ci.md index 14bb320..a160774 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/proj_man/ci.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/proj_man/ci.md @@ -12,7 +12,7 @@ The CI of Module repositories and STM32 BSPs calls shared workflows of the XRobo ## Module CI -Module repositories call the shared workflow `xrobot-org/XRobot/.github/workflows/module-ci.yml`. The `.github/workflows/build.yml` of official Modules (the same on `dev` and `master`), which use the default `master` of XRobot and LibXR: +Module repositories call the shared workflow `xrobot-org/XRobot/.github/workflows/module-ci.yml`. The `.github/workflows/build.yml` of official Modules (the same on `dev` and `master`) passes no ref inputs; XRobot, LibXR and the dependencies build against the default context of the event: ```yaml name: Module CI @@ -31,11 +31,14 @@ In a Linux container the workflow resolves the Module's dependencies, runs `xrob `xrobot check-module` resolves Modules as `xrobot setup` does and updates `xrobot.lock` and `Modules/`; `-o FILE` names the output file (default `module_check.cpp`), `--template-arg` gives one template argument of a class template (once per argument), and `--offline` uses only the Modules already in `Modules/`. +`xrobot-ref`, `libxr-ref` and `dependency-ref` default to empty, in which case the event chooses the context: a pull request builds against its target branch; a push to a feature branch uses the branch of the same name, falling back to `dev` when the other repository has no branch of that name; a push to `dev`/`master` uses `dev`/`master`; a tag push uses `master`; a manual run and a schedule use the current branch. A pull request uses its target branch rather than its source branch: a branch of the same name holds unmerged code, and a downstream PR passing against it does not mean the dependency works once the upstream is merged; after the upstream merges, re-running the downstream PR manually rebuilds against the merged code. Filling in any of the three inputs overrides the value the event would choose. + | Input | Default | Meaning | | --- | --- | --- | -| `xrobot-ref` | `master` | XRobot version used | -| `libxr-ref` | `master` | LibXR version used | -| `dependency-ref` | `refs/heads/master` | Context for `same-or-dev` dependencies | +| `xrobot-ref` | empty | XRobot branch, tag or commit; empty follows the event (see above) | +| `libxr-ref` | empty | LibXR branch, tag or commit; empty follows the event (see above) | +| `dependency-ref` | empty | Context for `same-or-dev` dependencies (`refs/heads/...` or `refs/tags/...`); empty is `refs/heads/` of the event branch | +| `build-type` | `RelWithDebInfo` | CMake build type, see below | | `template-args` | `'[]'` | Template arguments for a class template (JSON list) | | `sources` | empty | Further index URLs, one per line; the official indexes win when both list a package | | `image` | `ghcr.io/xrobot-org/docker-image-linux:main` | Build container | @@ -44,6 +47,8 @@ In a Linux container the workflow resolves the Module's dependencies, runs `xrob | `ctest-regex` | empty | When set, build tests and run the matching CTest tests | | `ctest-timeout` | `15` | Per-test CTest timeout in seconds | +With the default `RelWithDebInfo`, the workflow sets the compile options of this build type to `-O2 -g`: `RelWithDebInfo` normally implies `-DNDEBUG`, which turns `assert()` off, so the standard `assert()` and `eigen_assert` stay active, and `LIBXR_DEBUG_BUILD` is defined to turn on the LibXR debug build (see [the build configuration of LibXR](../basic_coding/cmake.md)). Any other value is used as it is. `cmake-options` are appended last and can override the options before them. + --- ## BSP CI From 874a0d7bc85d5abbc1591fdd61ce47222524f3ed Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 10 Oct 2026 05:39:09 +0100 Subject: [PATCH 07/16] Lock and setup: same-or-dev chain semantics, the release gate and --leave-local --- docs/proj_man/setup.md | 9 +++++++-- .../current/proj_man/setup.md | 9 +++++++-- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/proj_man/setup.md b/docs/proj_man/setup.md index 3a6abd7..3faf090 100644 --- a/docs/proj_man/setup.md +++ b/docs/proj_man/setup.md @@ -44,7 +44,9 @@ xrobot module remove owner/Repo | `same-or-dev` | 与 BSP 当前分支同名的模块分支,不存在时用 `dev`;BSP 在标签上时要求同名标签 | | `same` | 必须存在同名分支或标签 | -`same` / `same-or-dev` 以 BSP 仓库的当前分支为上下文。CI 等分离 HEAD 的检出用 `--context-ref refs/heads/<分支>`(或 `refs/tags/<标签>`)传入逻辑分支;请求中的 `context_ref` 为这一个模块及其依赖指定上下文,例如用 PR 的提交测试一个模块时保留其依赖的分支。 +`same` / `same-or-dev` 跟随 BSP 仓库的当前分支;CI 等分离 HEAD 的检出用 `--context-ref refs/heads/<分支>`(或 `refs/tags/<标签>`)传入逻辑分支。请求中的 `context_ref` 为这一个模块及其依赖指定上下文,例如用 PR 的提交测试一个模块时保留其依赖的分支。显式分支名的请求把它自己的分支作为下一层的上下文;`same`、`same-or-dev`、显式 tag 和提交号沿用最初的上下文,每一层各自查找同名分支、找不到退回 `dev`,中间层退回 `dev` 不改变下一层跟随的分支。同一模块沿两条依赖链解析到不同提交时,报错列出链上缺同名分支、退回 `dev` 的仓库。 + +BSP 不在 Git 仓库中时没有可跟随的分支:不加 `--update` 时沿用 lock 中的提交;`--update` 会报错,需要用 `--context-ref refs/heads/<分支>` 给出逻辑分支,或给请求写显式的 ref。 --- @@ -63,12 +65,15 @@ lock 由 `xrobot setup` 写出,首行为生成说明,不应手动编辑。 | `xrobot setup --offline` | 不访问网络,只使用本地已有的检出和提交;需要 `xrobot.lock`,且 `modules.yaml` 与 lock 一致 | | `xrobot setup --context-ref REF` | 指定 `same` / `same-or-dev` 的 BSP 上下文 | | `xrobot setup --release-ref REF` | 拒绝对目标分支未发布的提交(见下文) | +| `xrobot setup --leave-local MODULE...` | 把点名的模块移到 lock 解析出的提交(见下文) | | `xrobot setup --no-line-directives` | 重新生成头文件时不写 `#line` 指令 | `--update` 不能与 `--frozen`、`--offline` 同时使用;它还会对所有配置执行 `xrobot sync`,并打印改动。 模块被检出为锁定提交的分离 HEAD。模块已在锁定的提交上时,其中未提交的修改保持不变;需要把模块移到另一个提交时,若模块有未提交的修改,或 HEAD 是不在任何远程分支或标签上的本地提交,`xrobot setup` 停止并说明原因。在 BSP 中开发模块时,保持修改未提交;准备好后推送到模块的一个分支,再运行 `xrobot setup --update <模块>`。 +`xrobot setup --leave-local <模块...>` 把点名的模块移到 lock 解析出的提交:模块停在未推送的本地提交上时,先打印这些提交,再检出目标提交,本地提交留在原来的分支上,HEAD 游离时可用 `git reflog` 找回。点名模块有未提交的修改时仍然拒绝;加 `-f` 时先打印将丢弃的内容,再丢弃需要移动的点名模块的已跟踪修改和未跟踪文件(子模块里的同样处理),被忽略的文件保留。`-f` 只与 `--leave-local` 一起使用,只作用于点名的模块。 + 两个选中的模块定义了同名的全局类、依赖成环、同一模块被解析到不同提交时,setup 都会报错。 --- @@ -103,7 +108,7 @@ BSP 与官方模块使用同一套分支:`dev` 接收修改,`master` 是稳 | `refs/heads/master`、`refs/heads/main`、`refs/tags/...` | 模块的 `master`(或 `main`) | | 其他分支(如 `refs/heads/feature-x`) | 不检查 | -显式请求的标签视为已发布;没有该分支线的第三方模块只能用显式提交。未合并、或以 squash / rebase 方式合并的提交不在目标分支上,此时先合并模块,再运行 `xrobot setup --update <模块> --context-ref refs/heads/<目标分支>`。 +显式请求的标签视为已发布;没有该分支线的第三方模块只能用显式提交。模块 PR 以 merge commit 合并后,锁定的提交就在目标分支上,BSP 无需刷新 lock 即可通过;以 squash / rebase 方式合并或改写历史后,锁定的提交不再在目标分支上,按报错给出的命令刷新,例如 `xrobot setup --update <模块> --context-ref refs/heads/dev`。 同一规则也用于工具版本:`Modules/modules.yaml` 的 `xrobot:` 必须存在,`User/libxr_config.yaml` 中写了 `generator:` 时同样检查;写成提交号时必须在工具仓库的对应分支上,发布版本号直接通过。 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/proj_man/setup.md b/i18n/en/docusaurus-plugin-content-docs/current/proj_man/setup.md index 13d22fb..44f4c41 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/proj_man/setup.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/proj_man/setup.md @@ -44,7 +44,9 @@ Without `@ref`, `xrobot module add` writes `@same-or-dev`. | `same-or-dev` | The Module branch named like the BSP's current branch, otherwise `dev`; on a BSP tag, the identical tag | | `same` | The branch or tag with the same name must exist | -`same` / `same-or-dev` use the BSP repository's current branch as context. A detached checkout (such as CI) passes the logical ref with `--context-ref refs/heads/` (or `refs/tags/`). `context_ref` in a request sets the context for that Module and its dependencies, for example to test a Module at a PR commit while its dependencies follow the PR's branch. +`same` / `same-or-dev` follow the BSP repository's current branch; a detached checkout (such as CI) passes the logical ref with `--context-ref refs/heads/` (or `refs/tags/`). `context_ref` in a request sets the context for that Module and its dependencies, for example to test a Module at a PR commit while its dependencies follow the PR's branch. A request with an explicit branch name makes that branch the context of the next layer; `same`, `same-or-dev`, explicit tags and commits keep the original context: every layer looks for its own branch of that name and falls back to `dev`, and a middle layer's fallback does not change what the next layer follows. When one Module resolves to different commits along two dependency chains, the error names the repositories in the chains that lack the branch and fell back to `dev`. + +A BSP outside Git has no branch to follow: without `--update` the lock is kept as it is; `--update` fails and needs `--context-ref refs/heads/`, or an explicit ref in the request. --- @@ -63,12 +65,15 @@ The lock is written by `xrobot setup`, says so in its first line, and is not edi | `xrobot setup --offline` | Uses only local checkouts and commits, without network access; needs `xrobot.lock`, and `modules.yaml` must match it | | `xrobot setup --context-ref REF` | Sets the BSP context for `same` / `same-or-dev` | | `xrobot setup --release-ref REF` | Refuses commits that are not released for the target line (see below) | +| `xrobot setup --leave-local MODULE...` | Moves the named Modules to their resolved commits (see below) | | `xrobot setup --no-line-directives` | Leaves the `#line` directives out of the regenerated header | `--update` cannot be combined with `--frozen` or `--offline`. It also runs `xrobot sync` on every configuration and prints the changes. Modules are checked out at their locked commits (detached HEAD). A Module already at its locked commit keeps its uncommitted changes. When a Module has to move to another commit, `xrobot setup` stops with an explanation if the Module has uncommitted changes or its HEAD is a local commit that is on no remote branch or tag. While developing a Module inside a BSP, keep the changes uncommitted; when they are ready, push them to a branch of the Module and run `xrobot setup --update `. +`xrobot setup --leave-local ` moves the named Modules to the commits the lock resolves to: at an unpushed local commit, the commits are printed first, then the target commit is checked out, and the local commits stay on the original branch or are recoverable through `git reflog` when HEAD is detached. A named Module with uncommitted changes is still refused; with `-f`, what will be discarded is printed first, then the tracked modifications and untracked files of the named Modules that have to move are discarded (submodules included), and ignored files are kept. `-f` is used only with `--leave-local` and affects only the named Modules. + Setup also fails when two selected Modules define the same global Module class, when dependencies form a cycle, or when one Module resolves to different commits. --- @@ -103,7 +108,7 @@ BSPs and official Modules share one branch model: `dev` receives changes; `maste | `refs/heads/master`, `refs/heads/main`, `refs/tags/...` | the Module's `master` (or `main`) | | any other branch (such as `refs/heads/feature-x`) | not checked | -Explicitly requested tags count as released; a third-party Module without that line can only be pinned by an explicit commit. A commit that was not merged, or was merged by squash or rebase, is not on the target line: merge the Module first, then run `xrobot setup --update --context-ref refs/heads/`. +Explicitly requested tags count as released; a third-party Module without that line can only be pinned by an explicit commit. After a Module pull request is merged with a merge commit, the locked commit is on the target line and the BSP passes without refreshing the lock; after a squash or rebase merge or a history rewrite, the locked commit is no longer on the line, and the command printed by the gate refreshes it, such as `xrobot setup --update --context-ref refs/heads/dev`. The same rule applies to the tools: `xrobot:` in `Modules/modules.yaml` must be present, and `generator:` in `User/libxr_config.yaml` is checked when it is written; a commit pin must be on the tool repository's matching line, and a release version passes. From c7cd5e3bb24ed6c75619809d4767bcb03f43bcb0 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 10 Oct 2026 05:48:34 +0100 Subject: [PATCH 08/16] Instance config: bare names for pointer parameters, native YAML sync defaults --- docs/proj_man/config.md | 12 ++++++++---- docs/proj_man/create_mod.md | 2 +- .../current/proj_man/config.md | 12 ++++++++---- .../current/proj_man/create_mod.md | 2 +- 4 files changed, 18 insertions(+), 10 deletions(-) diff --git a/docs/proj_man/config.md b/docs/proj_man/config.md index 4d472b7..fbe0e0b 100644 --- a/docs/proj_man/config.md +++ b/docs/proj_man/config.md @@ -93,11 +93,15 @@ settings: 没有默认值的引用或指针参数是依赖参数,值可以是: -- 入口源文件中 `XR_REGISTER` 注册的名字; -- 排在前面的实例 `id`; -- `'&名字'` 或 `名字`(参数是指针时,两种写法都传入对象的地址); +- 入口源文件中 `XR_REGISTER` 注册的名字,或排在前面的实例 `id`; - `nullptr`(参数是指针时)。 +参数是指针时写名字本身,生成器自动取地址;带引号的 `'&名字'` 仍然接受,按写出的地址传递。不带引号的 `&名字` 是 YAML 锚点,值为空,`xrobot` 报错并建议改为裸名: + +```text +User/xrobot.yaml:5: &LED1 使 - led 的值成为空的 YAML 锚点;请去掉 & 只写名字,例如 `- led: LED1` +``` + 可选依赖在模块中声明为没有默认值的指针参数,配置中写 `nullptr` 即不使用。名字错误时给出同类型的候选: ```text @@ -127,7 +131,7 @@ User/xrobot.yaml: status_led.args.led: LED_X 既不是 XR_REGISTER 名字,也 - pid_param: '{.p = 30.0, .d = 1.0, .cycle = true}' # 一行指定初始化器 ``` -模块新版本增减字段或参数后运行 `xrobot sync`:新增的写入源码默认值,删除的去掉,已有的值保持不变。`xrobot setup --update` 会自动执行这一步。 +模块新版本增减字段或参数后运行 `xrobot sync`:新增的写入源码默认值,删除的去掉,已有的值保持不变。新增的默认值是按位置的初始化器时写成原生列表(`gains: [0.5, 1.5]`),是指定初始化器时写成原生映射(`keep: {k: 2, on: true}`),不再带引号;索引之外或转不回原文的值保留为单引号字符串。`xrobot setup --update` 会自动执行这一步。 ### 常量 diff --git a/docs/proj_man/create_mod.md b/docs/proj_man/create_mod.md index db1eca1..f67bf44 100644 --- a/docs/proj_man/create_mod.md +++ b/docs/proj_man/create_mod.md @@ -63,7 +63,7 @@ class MySensor }; ``` -`xrobot module show <目录、头文件或模块 id>` 显示模块的 manifest 和构造函数;给出 `owner/Repo` 或 `Repo` 时读取当前 BSP 中锁定的模块。 +`xrobot module show <目录、头文件或模块 id>` 显示模块的 manifest 和构造函数;给出 `owner/Repo` 或 `Repo` 时读取当前 BSP 中锁定的模块。manifest 的 YAML 写错时,报错给出头文件中的行列号。 --- diff --git a/i18n/en/docusaurus-plugin-content-docs/current/proj_man/config.md b/i18n/en/docusaurus-plugin-content-docs/current/proj_man/config.md index fd8e54e..7570170 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/proj_man/config.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/proj_man/config.md @@ -93,11 +93,15 @@ In the generated code `topic_name` is `"bmi088_gyro"`; the other values are as w A reference or pointer parameter without a default is a dependency. Its value is one of: -- a name registered with `XR_REGISTER` in the entry source; -- the `id` of an earlier instance; -- `'&name'` or `name` (for a pointer parameter; both pass the object's address); +- a name registered with `XR_REGISTER` in the entry source, or the `id` of an earlier instance; - `nullptr` (for a pointer parameter). +For a pointer parameter, write the name itself; the generator takes its address. The quoted `'&name'` is still accepted and passes the address as written. Without quotes, `&name` is a YAML anchor with an empty value, and `xrobot` reports it and suggests the bare name: + +```text +User/xrobot.yaml:5: &LED1 makes the value of - led an empty YAML anchor; write the name without &, e.g. `- led: LED1` +``` + An optional dependency is declared by the Module as a pointer parameter without a default; `nullptr` leaves it unused. A wrong name is reported with the candidates of the right type: ```text @@ -127,7 +131,7 @@ Take LibXR's `PID::Param`: when a Module writes the default as `{.k = 1.0 - pid_param: '{.p = 30.0, .d = 1.0, .cycle = true}' # designated initializer ``` -After a new Module version adds or removes fields or parameters, run `xrobot sync`: new ones are written with their source defaults, removed ones are dropped, and existing values are kept. `xrobot setup --update` does this automatically. +After a new Module version adds or removes fields or parameters, run `xrobot sync`: new ones are written with their source defaults, removed ones are dropped, and existing values are kept. A new positional initializer default becomes a native YAML list (`gains: [0.5, 1.5]`), a designated one a native mapping (`keep: {k: 2, on: true}`), without quotes; values outside the index or that cannot round-trip stay as single-quoted strings. `xrobot setup --update` does this automatically. ### Constants diff --git a/i18n/en/docusaurus-plugin-content-docs/current/proj_man/create_mod.md b/i18n/en/docusaurus-plugin-content-docs/current/proj_man/create_mod.md index b1121ba..7769063 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/proj_man/create_mod.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/proj_man/create_mod.md @@ -63,7 +63,7 @@ class MySensor }; ``` -`xrobot module show ` prints the manifest and constructors; with `owner/Repo` or `Repo` it reads the locked Module of the current BSP. +`xrobot module show ` prints the manifest and constructors; with `owner/Repo` or `Repo` it reads the locked Module of the current BSP. A YAML error in the manifest names the line and column in the header file. --- From 011cf8d9db1a582ef73425e2002054ceea67a902 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 10 Oct 2026 11:48:18 +0100 Subject: [PATCH 09/16] LibXR: the build option, RamFS commands, the power managers, ObjectPool and LatestSnapshot --- docs/basic_coding/cmake.md | 2 +- docs/basic_coding/core/core-assert.md | 2 +- docs/basic_coding/driver/power.md | 16 +- docs/basic_coding/middleware/ramfs.md | 20 +-- docs/basic_coding/middleware/terminal.md | 2 +- docs/basic_coding/structure/README.md | 1 + .../basic_coding/structure/latest_snapshot.md | 77 ++++++++++ docs/basic_coding/structure/object_pool.md | 141 ++++++----------- .../current/basic_coding/cmake.md | 2 +- .../current/basic_coding/core/core-assert.md | 2 +- .../current/basic_coding/driver/power.md | 22 ++- .../current/basic_coding/middleware/ramfs.md | 20 +-- .../basic_coding/middleware/terminal.md | 2 +- .../current/basic_coding/structure/README.md | 1 + .../basic_coding/structure/latest_snapshot.md | 77 ++++++++++ .../basic_coding/structure/object_pool.md | 143 +++++++----------- 16 files changed, 319 insertions(+), 211 deletions(-) create mode 100644 docs/basic_coding/structure/latest_snapshot.md create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/latest_snapshot.md diff --git a/docs/basic_coding/cmake.md b/docs/basic_coding/cmake.md index a51d145..52d63ea 100644 --- a/docs/basic_coding/cmake.md +++ b/docs/basic_coding/cmake.md @@ -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`。 ## 日志与格式化 diff --git a/docs/basic_coding/core/core-assert.md b/docs/basic_coding/core/core-assert.md index 129058d..0a080cc 100644 --- a/docs/basic_coding/core/core-assert.md +++ b/docs/basic_coding/core/core-assert.md @@ -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 内部开发检查 | diff --git a/docs/basic_coding/driver/power.md b/docs/basic_coding/driver/power.md index b5aaa3b..3ac3f6e 100644 --- a/docs/basic_coding/driver/power.md +++ b/docs/basic_coding/driver/power.md @@ -24,6 +24,12 @@ public: // 跳转到启动加载器(默认退化为 Reset) virtual void JumpToBootloader() { Reset(); } + + // 在 RamFS 根目录注册 power 命令 + void RegisterCommand(RamFS& ramfs); + + // 读一次引脚,电平等于 level 时进入启动加载器 + void CheckBootloaderPin(GPIO& pin, bool level); }; ``` @@ -32,10 +38,18 @@ public: - `Reset()` 可用于软复位控制器、重新启动系统等; - `Shutdown()` 用于关机、掉电、进入睡眠等低功耗控制; - `JumpToBootloader()` 默认会退化为 `Reset()`,平台实现可按需改为真正的 Bootloader 跳转; +- `RegisterCommand(ramfs)` 在 RamFS 根目录注册 `power` 命令:终端中 `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 或 WAKEUP 引脚唤醒,没有 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()` 两个由基类实现的通用接口。 - 状态查询、事件回调、低功耗级别等由具体平台实现或上层代码提供。 diff --git a/docs/basic_coding/middleware/ramfs.md b/docs/basic_coding/middleware/ramfs.md index f74acca..dca35d5 100644 --- a/docs/basic_coding/middleware/ramfs.md +++ b/docs/basic_coding/middleware/ramfs.md @@ -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 目录类支持添加 / 查找: @@ -58,18 +61,16 @@ sidebar_position: 6 ```cpp RamFS fs; -int counter = 0; +static int counter = 0; -// 创建可执行文件(每次调用将计数器 +1) -auto exec_file = RamFS::CreateFile( - "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 + } ); // 创建读写文件 @@ -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 接口 diff --git a/docs/basic_coding/middleware/terminal.md b/docs/basic_coding/middleware/terminal.md index 4b06567..07347ed 100644 --- a/docs/basic_coding/middleware/terminal.md +++ b/docs/basic_coding/middleware/terminal.md @@ -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/` 调用,或先 `cd bin`; +- 命令通常用 `CreateCommand(name, exec)` 创建后加入 `ramfs.bin_`,在根目录下以 `/bin/` 调用,或先 `cd bin`; - 支持 ANSI 上下左右键移动与历史记录查阅; - Tab 键补全第一个参数的路径。 diff --git a/docs/basic_coding/structure/README.md b/docs/basic_coding/structure/README.md index 6ff23a1..ec31635 100644 --- a/docs/basic_coding/structure/README.md +++ b/docs/basic_coding/structure/README.md @@ -23,6 +23,7 @@ sidebar_position: 2 - [List(链表)](./list.md) - [LockFreeList(无锁链表)](./lockfree_list.md) - [ObjectPool(RAII 对象池)](./object_pool.md) +- [LatestSnapshot(最新值邮箱)](./latest_snapshot.md) - [RBTree(红黑树)](./rbt.md) - [DoubleBuffer(双缓冲区)](./double_buffer.md) diff --git a/docs/basic_coding/structure/latest_snapshot.md b/docs/basic_coding/structure/latest_snapshot.md new file mode 100644 index 0000000..aca182f --- /dev/null +++ b/docs/basic_coding/structure/latest_snapshot.md @@ -0,0 +1,77 @@ +--- +id: latest_snapshot +title: 最新值邮箱 +sidebar_position: 10 +--- + +# LatestSnapshot(最新值邮箱) + +`LibXR::LatestSnapshot` 是单生产者、单消费者的邮箱,只保留最新一份完整值。 + +它适用于只关心最新数据的场合。以接收中断与控制线程为例:中断每收到一帧反馈就发布一次,控制线程按自己的节奏读取,读到的始终是最近一次发布的值;控制线程来不及读取时,中间的发布被后来的覆盖,不排队、不积压。 + +## 核心特性 + +- 内部三个槽:生产者独占后槽,消费者独占前槽,中间槽由一个原子状态交给对方,承载最新一次完成的发布; +- 连续的 `Store()` 可以覆盖消费者尚未取走的中间值,但不会覆盖消费者正在拷贝的值; +- 三个槽随对象构造,`LatestSnapshot` 自身不分配内存; +- 对象不可拷贝、不可移动。 + +## 常用接口 + +```cpp +template +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{}); + +// 接收中断中发布最新的反馈帧 +void OnFeedbackFrame(const Feedback& frame) +{ + feedback.Store(frame); +} + +// 控制线程中读取;本次取到新的发布时 LoadLatest() 返回 true +void ControlStep() +{ + Feedback frame{}; + if (feedback.LoadLatest(frame)) + { + // frame 是本次取得的最新反馈 + } +} +``` + +## 选择建议 + +生产者与消费者各只有一个、且每次发布都必须被处理时用 `SPSCQueue`;只关心最新值、中间值可以丢弃时用 `LatestSnapshot`。任一侧不止一个时使用 `MPMCQueue`。 diff --git a/docs/basic_coding/structure/object_pool.md b/docs/basic_coding/structure/object_pool.md index df83c37..dbbeca2 100644 --- a/docs/basic_coding/structure/object_pool.md +++ b/docs/basic_coding/structure/object_pool.md @@ -6,98 +6,74 @@ sidebar_position: 7 # ObjectPool -`object_pool.hpp` 提供一组基于空闲索引队列的 RAII 槽池接口,核心模板为: +`object_pool.hpp` 提供带引用计数的固定槽对象池: ```cpp -LibXR::BasicObjectPool +LibXR::ObjectPool ``` -以及三个别名: - -- `LibXR::ObjectPool`:底层使用 `Queue` -- `LibXR::SPSCObjectPool`:底层使用 `SPSCQueue` -- `LibXR::MPMCObjectPool`:底层使用 `MPMCQueue` - -这一组对象池的特点是: - -- 通过 `Acquire()` 获取一个独占槽位; -- 通过 move-only `Handle` 在析构时自动归还槽位; -- 上层直接在槽位对象上原地构造和修改业务数据。 +槽位数量在构造时确定。写独占、读共享:`Acquire()` 得到一个只能移动的可写 `Handle`,写完数据后移动为可复制的只读 `ConstHandle` 分发出去,最后一个引用释放时槽位回到空闲栈。 --- ## 1. 设计要点 -### 1.1 最小队列约束 `PoolIndexQueue` +### 1.1 槽位与负载 + +槽位类型是 `ObjectPool::Slot`,由引用计数、空闲栈链接和常驻负载组成: -`BasicObjectPool` 不依赖某一个具体队列类型,而是要求底层空闲索引队列满足最小强类型接口: +- 负载随池构造、随池析构;引用释放时既不析构也不清空槽内对象,下一个申请方直接写入自己的数据; +- 用内部槽数组构造的池要求 `Data` 可默认构造;外部槽数组由调用方准备,`Slot` 另有 `Slot(std::in_place, args...)` 用于就地构造负载; +- 槽数组在构造时确定,其后的申请与释放不再分配内存。 -- `ValueType` -- `Push(const ValueType&)` -- `Pop(ValueType&)` -- `Size()` +### 1.2 可写句柄与只读句柄 -因此普通 `Queue`、`SPSCQueue`、`MPMCQueue` 都可以作为空闲索引队列。 +`Handle` 独占一个槽位,只能移动: -### 1.2 Move-only `Handle` +- 析构时释放槽位,`Reset()` 可以提前释放; +- `Get()`、`operator->()`、`operator*()` 访问槽内负载,`Index()` 返回槽位索引,`Valid()` 判断是否持有槽位; +- 禁止拷贝,避免同一个槽位被多个可写句柄持有。 -成功获取槽位后,对象池不会直接返回裸指针,而是返回一个 move-only `Handle`: +`ConstHandle` 共享一个槽位,可以复制:由 `Handle` 移动得到,或由另一个 `ConstHandle` 复制得到。复制增加引用,析构减少引用,最后一个引用释放时槽位回到空闲栈。它只提供负载的只读访问。 -- `Handle` 析构时会自动把槽位索引归还给对象池; -- 禁止拷贝,避免同一个槽位被多个句柄同时持有; -- 支持 `Get()`、`operator->()`、`operator*()` 访问槽内对象; -- 支持 `Index()` 查询当前槽位索引; -- 支持 `Reset()` 主动提前归还; -- 支持 `Valid()` 判断句柄是否持有槽位。 +### 1.3 并发约束 -这也是“RAII 对象池”这个名称的来源。 +同一池同一时刻只能有一个申请方,申请不得重叠或重入,Debug 构建会检查;重叠申请会让空闲栈出现 ABA,把同一个槽位交给两个申请方。释放可以在任意线程或 ISR 中并发进行,且不会失败。不同句柄对象可以并发使用,同一句柄对象的并发访问须由调用方同步。构造和析构须在静止状态下进行,不能在 ISR 中执行;池与外部槽存储必须比全部句柄活得更久。在 ISR 中使用要求目标平台提供 32 位原子 CAS。 --- ## 2. 构造方式 -`BasicObjectPool` 支持四类构造方式: - -1. 内部 queue + 内部 slots -2. 内部 queue + 外部 slots -3. 外部 queue + 内部 slots -4. 外部 queue + 外部 slots - -选择含义: - -- 槽位和队列都由对象池分配:使用内部 queue / 内部 slots。 -- 需要把槽位放在调用方控制的存储区:使用外部 `slots`。 -- 需要复用已有队列实现或精确控制队列行为:使用外部 `free_queue`。 - -使用外部 `free_queue` 时: +```cpp +explicit ObjectPool(size_t slot_count); +ObjectPool(size_t slot_count, Slot* slots); +``` -- 队列在传入时必须为空; -- 队列只供当前 pool 独占使用; -- 队列容量至少能容纳 `slot_count` 个索引。 +- `ObjectPool(slot_count)`:槽数组由池分配,要求 `Data` 可默认构造; +- `ObjectPool(slot_count, slots)`:槽数组由调用方提供,池既不构造也不析构其中的负载,`slots` 须指向至少 `slot_count` 个未被其他池使用的槽。 -此外,使用内部 slots 的构造要求 `Data` 可默认构造;`IndexType` 须为无符号整数类型。 +池不可拷贝、不可移动。 --- ## 3. 主要接口 -### 3.1 获取与归还 +### 3.1 获取与释放 - `ErrorCode Acquire(Handle& handle)` - `void Handle::Reset()` +- `void ConstHandle::Reset()` 行为要点: -- 成功时返回 `ErrorCode::OK`; -- 无空闲槽位时返回底层队列的弹出失败结果,当前常见表现为 `ErrorCode::EMPTY`; -- `Handle` 析构时会自动归还槽位,不必手工把索引放回队列; +- 成功时返回 `ErrorCode::OK`,没有空闲槽位时返回 `ErrorCode::EMPTY`,不等待; - `Acquire()` 要求传入的 `handle` 未持有槽位(Debug 构建下断言); -- 对象池析构前所有 `Handle` 必须已归还(Debug 构建下断言 `EmptySize() == Size()`),因此 pool 须比 handle 后析构。 +- 池析构前所有句柄必须已释放(Debug 构建下断言 `EmptySize() == Size()`)。 ### 3.2 容量查询 -- `size_t EmptySize() const`:当前仍可获取的空闲槽位数 -- `size_t Size() const`:对象池总槽位数 +- `size_t EmptySize() const`:当前的空闲槽位数,有并发申请或释放时为近似值,只用于监控; +- `size_t Size() const`:槽位总数。 ### 3.3 非所有权访问 @@ -106,40 +82,13 @@ LibXR::BasicObjectPool 这两个接口会绕过 `Acquire()` / `Handle` 的所有权语义,只适合调试、检查外部存储区,或调用方明确知道槽位状态的场景。 ---- - -## 4. 三个常用别名 - -### 4.1 `ObjectPool` - -```cpp -template -using ObjectPool = BasicObjectPool>; -``` +### 3.4 引用计数上限 -适合普通线程上下文中、对锁自由度没有额外要求的通用对象池场景。 - -### 4.2 `SPSCObjectPool` - -```cpp -template -using SPSCObjectPool = BasicObjectPool>; -``` - -适合明确是单生产者 / 单消费者的空闲槽位管理路径。 - -### 4.3 `MPMCObjectPool` - -```cpp -template -using MPMCObjectPool = BasicObjectPool>; -``` - -适合多生产者 / 多消费者并发获取与归还槽位的场景。 +每个槽位的引用数不得超过 `UINT32_MAX`。 --- -## 5. 使用示例 +## 4. 使用示例 ```cpp #include @@ -152,17 +101,27 @@ struct Packet LibXR::ObjectPool pool(16); -LibXR::ObjectPool::Handle handle; -if (pool.Acquire(handle) == LibXR::ErrorCode::OK) +LibXR::ObjectPool::Handle writer; +if (pool.Acquire(writer) == LibXR::ErrorCode::OK) { - handle->id = 42; - (*handle).payload[0] = 0xAA; + writer->id = 42; + (*writer).payload[0] = 0xAA; + + // 写完数据后移动为只读句柄分发,writer 变空 + LibXR::ObjectPool::ConstHandle frame = std::move(writer); + LibXR::ObjectPool::ConstHandle copy = frame; } -// handle 离开作用域后自动归还槽位 +// frame 与 copy 离开作用域后释放引用,最后一个引用归还槽位 ``` -如果需要提前归还: +引用可以提前释放:`Handle::Reset()` 直接归还槽位,`ConstHandle::Reset()` 减少一次引用。 ```cpp -handle.Reset(); +frame.Reset(); ``` + +--- + +## 5. 典型场景 + +采集与处理分离:采集端(一个中断或一个线程)用 `Acquire()` 取得槽位并写入一帧数据,再把只读句柄交给处理线程。处理线程可以把同一份数据再分发给多个下游,最后一个引用释放时槽位自动回到空闲栈。空闲槽位用完时 `Acquire()` 返回 `ErrorCode::EMPTY`,采集端不等待,槽位总数即同时在途的帧数上限。 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/cmake.md b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/cmake.md index 9c90684..a9da3a6 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/cmake.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/cmake.md @@ -72,7 +72,7 @@ Names are normalized to lowercase internally. Cross-compiling requires `LIBXR_SY | `LIBXR_SHARED_BUILD` | Build a shared library | | `LIBXR_OBJECT_BUILD` | Build an object library | -The default library kind is static. Debug builds define `LIBXR_DEBUG_BUILD`; `LIBXR_DEV_ASSERT_BUILD` separately controls `DEV_ASSERT`. +The default library kind is static. `LIBXR_DEBUG_BUILD` follows the build type by default: when it is not set explicitly, it is recomputed on every configure from the current build type (on for Debug, off otherwise) as a normal variable that is not written to the cache, so switching the build type in an existing build directory takes effect immediately; once set explicitly with `-DLIBXR_DEBUG_BUILD=ON/OFF`, the value becomes a cache entry and is kept on later reconfigures. `LIBXR_DEV_ASSERT_BUILD` separately controls `DEV_ASSERT`. ## Logging and formatting diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/core/core-assert.md b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/core/core-assert.md index 5fcec77..80530bd 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/core/core-assert.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/core/core-assert.md @@ -37,7 +37,7 @@ Accepts `LibXR::Assert::FatalCallback`, that is, `LibXR::Callback( - "runme", - [](int* arg, int argc, char** argv) { +// Create an executable file that needs no execution context (increments counter on each run) +auto exec_file = RamFS::CreateCommand("runme", + [](int argc, char** argv) { UNUSED(argc); UNUSED(argv); - (*arg)++; + counter++; return 0; - }, - &counter + } ); // Create read/write file @@ -108,6 +109,7 @@ for (int i = 1; i <= 5; ++i) { | `FindDir(name)` | Search for a directory | | `FindCustom(name)` | Search for a custom node | | `CreateCommand(name, exec, arg)` | Create an executable file, same as `CreateFile(name, exec, arg)` | +| `CreateCommand(name, exec)` | Create an executable file that needs no execution context | | `bin_` | The `bin` directory created under the root at construction | ### File Interface diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/middleware/terminal.md b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/middleware/terminal.md index a2cc26f..54b18b8 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/middleware/terminal.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/middleware/terminal.md @@ -79,7 +79,7 @@ LibXR::Timer::Start(terminal_task); - Input commands are buffered in `input_line_` and parsed/executed on Enter; - The only built-in commands are `cd` and `ls`; `ls` prints one line per entry with a type letter and the name: `d` directory, `x` executable, `f` regular file, `?` custom node; - Any other input treats the first argument as a RamFS file path: without `/` it is looked up in the current directory only, and a leading `/` resolves from the root; an executable file is run, a missing one prints `Command not found.`, and a non-executable one prints `Not an executable file.`; -- Commands are usually created with `CreateCommand()` and added to `ramfs.bin_`, then called as `/bin/` from the root, or after `cd bin`; +- Commands are usually created with `CreateCommand(name, exec)` and added to `ramfs.bin_`, then called as `/bin/` from the root, or after `cd bin`; - Supports ANSI-based cursor navigation and command history; - Tab completes the path in the first argument. 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 index ddc57a2..7b436bc 100644 --- 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 @@ -23,6 +23,7 @@ This chapter covers the general-purpose data structures LibXR uses for task sche - [List](./list.md) - [LockFreeList](./lockfree_list.md) - [ObjectPool](./object_pool.md) +- [LatestSnapshot](./latest_snapshot.md) - [RBTree](./rbt.md) - [DoubleBuffer](./double_buffer.md) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/latest_snapshot.md b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/latest_snapshot.md new file mode 100644 index 0000000..c939553 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/latest_snapshot.md @@ -0,0 +1,77 @@ +--- +id: latest_snapshot +title: Latest-Value Mailbox +sidebar_position: 10 +--- + +# LatestSnapshot (Latest-Value Mailbox) + +`LibXR::LatestSnapshot` is a single-producer, single-consumer mailbox that keeps only the latest complete value. + +It suits data of which only the latest value matters. Taking a receive interrupt and a control thread as an example, the interrupt publishes once per feedback frame it receives, and the control thread reads at its own pace, always getting the most recent publication; when the control thread is late, an intermediate publication is overwritten by a later one instead of being queued up. + +## Core features + +- Three internal slots: a back slot owned by the producer, a front slot owned by the consumer, and a middle slot handed over through one atomic state, which carries the latest completed publication; +- repeated `Store()` calls may overwrite a middle value the consumer has not taken, but never the value the consumer is copying; +- the three slots are constructed with the object, and `LatestSnapshot` allocates no memory itself; +- the object is neither copyable nor movable. + +## Common APIs + +```cpp +template +class LatestSnapshot +{ + public: + explicit LatestSnapshot(const T& initial); + + void Store(const T& value); + + bool LoadLatest(T& output); +}; +``` + +- `LatestSnapshot(initial)`: constructs all three slots with the same initial value, which `LoadLatest()` outputs before the first `Store()`; +- `Store(value)`: copies the value into the producer-owned back slot first, then releases that slot to the consumer as the newest middle slot; +- `LoadLatest(output)`: acquires a newer publication first; without one, `output` receives the value the consumer acquired last. It returns `true` when this call acquired a newer publication, otherwise `false`. + +`T` must be copy-constructible and copy-assignable. + +## Concurrency constraints + +- `Store()` may only be called by the single producer, and `LoadLatest()` only by the single serialized consumer, one call at a time; +- producer and consumer calls may overlap on different cores or in thread and interrupt contexts, since the handover between them uses one 32-bit atomic state; +- the value is copied whole on publication, so a read always returns one complete value rather than a half-written one. + +## Example + +```cpp +struct Feedback +{ + uint32_t seq = 0; + float position = 0.0f; +}; + +LibXR::LatestSnapshot feedback(Feedback{}); + +// Publish the latest feedback frame from the receive interrupt +void OnFeedbackFrame(const Feedback& frame) +{ + feedback.Store(frame); +} + +// Read from the control thread; LoadLatest() returns true when a newer publication was acquired +void ControlStep() +{ + Feedback frame{}; + if (feedback.LoadLatest(frame)) + { + // frame holds the latest feedback acquired by this call + } +} +``` + +## Choosing between the structures + +With one producer and one consumer where every publication has to be processed, use `SPSCQueue`; when only the latest value matters and intermediate ones may be dropped, use `LatestSnapshot`. With more than one on either side, use `MPMCQueue`. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/object_pool.md b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/object_pool.md index f43b651..15b741f 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/object_pool.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/object_pool.md @@ -6,96 +6,74 @@ sidebar_position: 7 # ObjectPool -`object_pool.hpp` provides a family of RAII slot pools built on a free-index queue. The core template is: +`object_pool.hpp` provides a fixed-slot object pool with reference counting: ```cpp -LibXR::BasicObjectPool +LibXR::ObjectPool ``` -and three aliases: - -- `LibXR::ObjectPool`: backed by `Queue` -- `LibXR::SPSCObjectPool`: backed by `SPSCQueue` -- `LibXR::MPMCObjectPool`: backed by `MPMCQueue` - -This family is built around: - -- acquiring one exclusive slot through `Acquire()` -- returning that slot automatically through a move-only `Handle` -- modifying user objects in place inside the slot +The number of slots is fixed at construction. One writer, shared readers: `Acquire()` yields a move-only writable `Handle`; after writing, move it into a copyable read-only `ConstHandle` to distribute the slot, and the final release returns the slot to the free stack. --- ## 1. Design points -### 1.1 Minimal queue constraint: `PoolIndexQueue` - -`BasicObjectPool` does not depend on one specific queue implementation. Instead, it requires the free-index queue to provide a minimal typed interface: +### 1.1 Slots and payloads -- `ValueType` -- `Push(const ValueType&)` -- `Pop(ValueType&)` -- `Size()` +The slot type is `ObjectPool::Slot`, made of a reference count, a free-stack link and a resident payload: -So the ordinary `Queue`, `SPSCQueue` and `MPMCQueue` can all serve as the free-index queue. +- payloads are constructed with the pool and destroyed with the pool; a release neither destroys nor clears the object in the slot, so the next acquirer writes its own data; +- a pool constructed with internal slots requires `Data` to be default-constructible; with external slots the caller prepares the storage, and `Slot` also has `Slot(std::in_place, args...)` to construct a payload in place; +- the slot storage is fixed at construction, and later acquisitions and releases allocate no memory. -### 1.2 Move-only `Handle` +### 1.2 Writable and read-only handles -On successful acquisition, the pool returns a move-only `Handle` instead of a raw pointer: +`Handle` owns one slot exclusively and is move-only: -- the handle returns the slot automatically on destruction -- copying is disabled, so one slot cannot be owned by multiple handles accidentally -- `Get()`, `operator->()`, and `operator*()` provide access to the object in the slot -- `Index()` returns the owned slot index -- `Reset()` returns the slot early if needed -- `Valid()` tells whether the handle owns a slot +- it releases the slot on destruction, and `Reset()` releases it early; +- `Get()`, `operator->()` and `operator*()` access the payload, `Index()` returns the slot index and `Valid()` tells whether it owns a slot; +- copying is disabled, so one slot cannot be held by two writable handles. ---- - -## 2. Construction forms +`ConstHandle` shares one slot and is copyable: it is obtained by moving a `Handle` or by copying another `ConstHandle`. A copy adds a reference and destruction drops one, and the final release returns the slot to the free stack. It provides read-only access to the payload only. -`BasicObjectPool` supports four construction patterns: +### 1.3 Concurrency -1. internal queue + internal slots -2. internal queue + external slots -3. external queue + internal slots -4. external queue + external slots +Only one acquirer may use a pool at a time, and acquisitions must not overlap or reenter; debug builds check this, because overlapping acquisitions cause ABA on the free stack and hand one slot to two acquirers. Releases may run concurrently from any thread or ISR and cannot fail. Distinct handle objects may be used concurrently, while concurrent access to one handle object requires caller synchronization. Construction and destruction require quiescence and cannot run in an ISR; the pool and any external slot storage must outlive all handles. ISR use requires 32-bit atomic CAS on the target. -Practical meaning: +--- -- internal queue and internal slots: the pool allocates both -- if slot storage must live in caller-controlled memory, provide external `slots` -- to reuse or precisely control the queue, provide an external `free_queue` +## 2. Construction -When an external `free_queue` is used: +```cpp +explicit ObjectPool(size_t slot_count); +ObjectPool(size_t slot_count, Slot* slots); +``` -- the queue must be empty when passed in -- it must be dedicated to the pool -- its capacity must be at least `slot_count` +- `ObjectPool(slot_count)`: the pool allocates the slot array and `Data` must be default-constructible; +- `ObjectPool(slot_count, slots)`: the caller provides the slot array, and the pool neither constructs nor destroys its payloads; `slots` must point to at least `slot_count` slots not used by another pool. -Constructors with internal slots require `Data` to be default-constructible; `IndexType` must be an unsigned integer type. +The pool is neither copyable nor movable. --- ## 3. Main APIs -### 3.1 Acquire and return +### 3.1 Acquire and release - `ErrorCode Acquire(Handle& handle)` - `void Handle::Reset()` +- `void ConstHandle::Reset()` Behavior notes: -- success returns `ErrorCode::OK` -- when no free slot is available, the result comes from the underlying queue pop failure, commonly `ErrorCode::EMPTY` -- the slot is also returned automatically when the handle is destroyed -- `Acquire()` expects a handle that owns no slot (asserted in Debug builds) -- all handles must be returned before the pool is destroyed (Debug builds assert `EmptySize() == Size()`), so the pool must outlive its handles +- success returns `ErrorCode::OK`, and `ErrorCode::EMPTY` without waiting when no slot is free; +- `Acquire()` expects a handle that owns no slot (asserted in Debug builds); +- all handles must be released before the pool is destroyed (Debug builds assert `EmptySize() == Size()`). ### 3.2 Capacity queries -- `size_t EmptySize() const`: number of currently acquirable free slots -- `size_t Size() const`: total slot count +- `size_t EmptySize() const`: the number of free slots, approximate during concurrent acquire or release and for monitoring only; +- `size_t Size() const`: the total slot count. ### 3.3 Non-owning access @@ -104,40 +82,13 @@ Behavior notes: These APIs bypass the ownership semantics of `Acquire()` / `Handle`. They are intended for debugging, external-storage inspection, or situations where the caller already knows the slot state. ---- - -## 4. The three common aliases - -### 4.1 `ObjectPool` - -```cpp -template -using ObjectPool = BasicObjectPool>; -``` - -Suitable for general-purpose object-pool usage in ordinary thread context when strict lock-free queue semantics are not the main concern. - -### 4.2 `SPSCObjectPool` - -```cpp -template -using SPSCObjectPool = BasicObjectPool>; -``` - -Suitable when free-slot acquisition and return clearly follow a single-producer / single-consumer path. +### 3.4 Reference limit -### 4.3 `MPMCObjectPool` - -```cpp -template -using MPMCObjectPool = BasicObjectPool>; -``` - -Suitable for multi-producer / multi-consumer slot acquisition and return. +Each slot must have at most `UINT32_MAX` references. --- -## 5. Example +## 4. Example ```cpp #include @@ -150,17 +101,27 @@ struct Packet LibXR::ObjectPool pool(16); -LibXR::ObjectPool::Handle handle; -if (pool.Acquire(handle) == LibXR::ErrorCode::OK) +LibXR::ObjectPool::Handle writer; +if (pool.Acquire(writer) == LibXR::ErrorCode::OK) { - handle->id = 42; - (*handle).payload[0] = 0xAA; + writer->id = 42; + (*writer).payload[0] = 0xAA; + + // After writing, move it into a read-only handle to distribute the slot; writer becomes empty + LibXR::ObjectPool::ConstHandle frame = std::move(writer); + LibXR::ObjectPool::ConstHandle copy = frame; } -// the slot is returned automatically when handle leaves scope +// frame and copy release their references when they leave scope; the last one returns the slot ``` -To return early: +A reference can be released early: `Handle::Reset()` returns the slot directly, and `ConstHandle::Reset()` drops one reference. ```cpp -handle.Reset(); +frame.Reset(); ``` + +--- + +## 5. Typical scenario + +Separating acquisition from processing: the acquiring side (one interrupt or one thread) takes a slot with `Acquire()` and writes one frame of data, then hands the read-only handle to a processing thread. That thread can pass the same data on to several downstream readers, and the final release returns the slot to the free stack automatically. When no slot is free, `Acquire()` returns `ErrorCode::EMPTY` and the acquiring side does not wait, so the slot count is the number of frames in flight at once. From 652ebe1fa4c1a26c66648ce96b595c901568dc2a Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 10 Oct 2026 11:50:45 +0100 Subject: [PATCH 10/16] Code generation: the generated power manager object and the HPM pin data --- docs/code_gen/hpm/README.md | 6 ++++++ docs/code_gen/mspm0/README.md | 6 ++++++ docs/code_gen/pins.md | 2 +- .../current/code_gen/hpm/README.md | 6 ++++++ .../current/code_gen/mspm0/README.md | 6 ++++++ .../docusaurus-plugin-content-docs/current/code_gen/pins.md | 2 +- 6 files changed, 26 insertions(+), 2 deletions(-) diff --git a/docs/code_gen/hpm/README.md b/docs/code_gen/hpm/README.md index f96b380..ca2ab73 100644 --- a/docs/code_gen/hpm/README.md +++ b/docs/code_gen/hpm/README.md @@ -113,6 +113,7 @@ GPIO(2 个引脚): #include "libxr.hpp" #include "hpm_gpio.hpp" #include "hpm_i2c.hpp" +#include "hpm_power.hpp" #include "hpm_pwm.hpp" #include "hpm_soc.h" #include "hpm_timebase.hpp" @@ -131,6 +132,7 @@ extern "C" void app_main(void) // Timebase and platform static HPMTimebase timebase; PlatformInit(); + static HPMPowerManager power_manager; // GPIO: init_bsp_pins() configured pa10 (PA10) as an output pin, pa3 (PA03) as an input // pin with a pull-down. The interrupt edge comes from the pinmux and every object @@ -149,6 +151,8 @@ extern "C" void app_main(void) clock_gptmr0, 1, 0, HPMPWM::Polarity::NORMAL); // Hardware registration + XR_REGISTER(power_manager, LibXR::PowerManager); + XR_REGISTER(pa10, LibXR::GPIO); XR_REGISTER(pa3, LibXR::GPIO); @@ -170,6 +174,8 @@ extern "C" void app_main(void) 生成的对象来自 LibXR 有驱动的配置:每个 GPIO 引脚一个对象,每个同时选了 SCL 和 SDA 的 I2C 一个对象;GPTMR 上的 PWM 见下文。其余配置(UART、SPI、MCAN、ADC、ACMP、USB、缺 SCL 或 SDA 的 I2C、只有捕获输入的 GPTMR 等)列入配置摘要的 Other,只作展示。 +生成结果总是包含 `static HPMPowerManager power_manager;`,位置在 `PlatformInit()` 之后;使用 XRobot 时按 `PowerManager` 注册,且排在其他对象之前。`power_manager` 是保留名,GPIO 名字与它相同会使生成报错。生成的代码需要带 `PowerManager` 的 LibXR,即 v2.0.1 或更新版本。`power reset|shutdown|bootloader` 命令由用户代码调用 `power_manager.RegisterCommand(ramfs)` 注册,生成器不生成这条调用。 + 对象的命名: | 配置 | 对象名 | 例子 | diff --git a/docs/code_gen/mspm0/README.md b/docs/code_gen/mspm0/README.md index ecd9b69..5aa6e27 100644 --- a/docs/code_gen/mspm0/README.md +++ b/docs/code_gen/mspm0/README.md @@ -119,6 +119,7 @@ GPIO(4 个引脚): #include "libxr.hpp" #include "mspm0_gpio.hpp" #include "mspm0_i2c.hpp" +#include "mspm0_power.hpp" #include "mspm0_pwm.hpp" #include "mspm0_spi.hpp" #include "mspm0_timebase.hpp" @@ -160,6 +161,7 @@ extern "C" void app_main(void) // Timebase and platform static MSPM0Timebase timebase; PlatformInit(); + static MSPM0PowerManager power_manager; // GPIO: SysConfig configured LED1 (PB8), LED2 (PA16) as output pins and KEY1 (PB24), // KEY2 (PB20) as input pins. The interrupt edge comes from SysConfig; RegisterCallback @@ -199,6 +201,8 @@ extern "C" void app_main(void) Timer::Start(terminal_task); // Hardware registration + XR_REGISTER(power_manager, LibXR::PowerManager); + XR_REGISTER(LED1, LibXR::GPIO); // ... @@ -253,6 +257,8 @@ static void OnKeyInterrupt(bool in_isr, std::atomic* count) 生成的对象来自 LibXR 有驱动的配置:UART、控制器模式的 I2C 和 SPI、PWM;GPIO 引脚各生成一个对象。其余配置(ADC12、DAC12、MCAN、QEI、目标模式的 I2C、外设模式的 SPI 等)列入配置摘要的 Other,只作展示。 +生成结果总是包含 `static MSPM0PowerManager power_manager;`,位置在 `PlatformInit()` 之后;使用 XRobot 时按 `PowerManager` 注册,且排在其他对象之前。`power_manager` 是保留名,GPIO 标签与它相同会使生成报错并提示在 SysConfig 中给引脚改名。生成的代码需要带 `PowerManager` 的 LibXR,即 v2.0.1 或更新版本。终端的 `power reset|shutdown|bootloader` 命令由用户代码调用 `power_manager.RegisterCommand(ramfs)` 注册,生成器不生成这条调用。 + 对象的命名: | 配置 | 对象名 | 例子 | diff --git a/docs/code_gen/pins.md b/docs/code_gen/pins.md index a7a417e..b714e63 100644 --- a/docs/code_gen/pins.md +++ b/docs/code_gen/pins.md @@ -6,7 +6,7 @@ sidebar_position: 4 # 引脚布局(libxr pins) -`libxr pins` 打印一个型号的封装与引脚布局:每个引脚的位置、名称和可选的信号。数据来自各厂商的引脚数据:STM32 为 ST 的 STM32_open_pin_data,MSPM0 为 TI SysConfig 的器件数据,HPM 为 HPM SDK 的 `hpm_iomux.h`、`hpm_soc_ip.h` 和 HPM5300 数据手册的引脚表。 +`libxr pins` 打印一个型号的封装与引脚布局:每个引脚的位置、名称和可选的信号。数据来自各厂商的引脚数据:STM32 为 ST 的 STM32_open_pin_data,MSPM0 为 TI SysConfig 的器件数据,HPM 为 HPM SDK 的 `hpm_iomux.h`、`hpm_soc_ip.h` 和 HPM5300 数据手册的引脚表。HPM 的数据目前只含 IO 引脚,电源、复位、晶振等引脚不在其中,因此 HPM5301 的 QFN48 显示 29 个引脚。 --- diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md index 6839e69..8bc2e20 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md @@ -113,6 +113,7 @@ The following is the `app_main.cpp` of that first run: #include "libxr.hpp" #include "hpm_gpio.hpp" #include "hpm_i2c.hpp" +#include "hpm_power.hpp" #include "hpm_pwm.hpp" #include "hpm_soc.h" #include "hpm_timebase.hpp" @@ -131,6 +132,7 @@ extern "C" void app_main(void) // Timebase and platform static HPMTimebase timebase; PlatformInit(); + static HPMPowerManager power_manager; // GPIO: init_bsp_pins() configured pa10 (PA10) as an output pin, pa3 (PA03) as an input // pin with a pull-down. The interrupt edge comes from the pinmux and every object @@ -149,6 +151,8 @@ extern "C" void app_main(void) clock_gptmr0, 1, 0, HPMPWM::Polarity::NORMAL); // Hardware registration + XR_REGISTER(power_manager, LibXR::PowerManager); + XR_REGISTER(pa10, LibXR::GPIO); XR_REGISTER(pa3, LibXR::GPIO); @@ -170,6 +174,8 @@ The pins and clocks are configured by the pinmux functions `main.c` calls, and t Objects are generated for the configurations LibXR has drivers for: one object per GPIO pin and one per I2C that selects both SCL and SDA; PWM on a GPTMR is described below. The remaining configurations (UART, SPI, MCAN, ADC, ACMP, USB, an I2C without SCL or SDA, a GPTMR with capture inputs only and so on) are listed under Other in the summary for display only. +The output always contains `static HPMPowerManager power_manager;` after `PlatformInit()`; with XRobot it is registered as `PowerManager`, ahead of the other objects. `power_manager` is a reserved name, so a GPIO that uses it makes generation fail. The generated code needs a LibXR that carries `PowerManager`, that is v2.0.1 or newer. The `power reset|shutdown|bootloader` commands are registered by user code through `power_manager.RegisterCommand(ramfs)`; the generator does not emit that call. + The objects are named: | Configuration | Object name | Example | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md index 78b6ea8..e90e5a0 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md @@ -119,6 +119,7 @@ The following is an excerpt of the `app_main.cpp` of that first run, with `// .. #include "libxr.hpp" #include "mspm0_gpio.hpp" #include "mspm0_i2c.hpp" +#include "mspm0_power.hpp" #include "mspm0_pwm.hpp" #include "mspm0_spi.hpp" #include "mspm0_timebase.hpp" @@ -160,6 +161,7 @@ extern "C" void app_main(void) // Timebase and platform static MSPM0Timebase timebase; PlatformInit(); + static MSPM0PowerManager power_manager; // GPIO: SysConfig configured LED1 (PB8), LED2 (PA16) as output pins and KEY1 (PB24), // KEY2 (PB20) as input pins. The interrupt edge comes from SysConfig; RegisterCallback @@ -199,6 +201,8 @@ extern "C" void app_main(void) Timer::Start(terminal_task); // Hardware registration + XR_REGISTER(power_manager, LibXR::PowerManager); + XR_REGISTER(LED1, LibXR::GPIO); // ... @@ -253,6 +257,8 @@ static void OnKeyInterrupt(bool in_isr, std::atomic* count) Objects are generated for the configurations LibXR has drivers for: UART, I2C and SPI in controller mode, and PWM; every GPIO pin gets an object. The remaining configurations (ADC12, DAC12, MCAN, QEI, an I2C in target mode, an SPI in peripheral mode and so on) are listed under Other in the summary for display only. +The output always contains `static MSPM0PowerManager power_manager;` after `PlatformInit()`; with XRobot it is registered as `PowerManager`, ahead of the other objects. `power_manager` is a reserved name, so a GPIO label that uses it makes generation fail with a message to rename the pin in SysConfig. The generated code needs a LibXR that carries `PowerManager`, that is v2.0.1 or newer. The `power reset|shutdown|bootloader` commands of the terminal are registered by user code through `power_manager.RegisterCommand(ramfs)`; the generator does not emit that call. + The objects are named: | Configuration | Object name | Example | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/pins.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/pins.md index fd23d6e..785f39b 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/pins.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/pins.md @@ -6,7 +6,7 @@ sidebar_position: 4 # Pin Layout (libxr pins) -`libxr pins` prints the package and pin layout of a model: the position, name and selectable signals of every pin. The data comes from the vendors' pin data: ST's STM32_open_pin_data for STM32, the device data of TI SysConfig for MSPM0, and the `hpm_iomux.h` and `hpm_soc_ip.h` of the HPM SDK plus the pin tables of the HPM5300 datasheet for HPM. +`libxr pins` prints the package and pin layout of a model: the position, name and selectable signals of every pin. The data comes from the vendors' pin data: ST's STM32_open_pin_data for STM32, the device data of TI SysConfig for MSPM0, and the `hpm_iomux.h` and `hpm_soc_ip.h` of the HPM SDK plus the pin tables of the HPM5300 datasheet for HPM. The HPM data holds IO pins only for now, so pins such as the supplies, the reset and the oscillators are not in it and the QFN48 of an HPM5301 shows 29 pins. --- From 599342b65554696797140994621f838030e080f9 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 10 Oct 2026 11:53:07 +0100 Subject: [PATCH 11/16] Versions: the website follows the x.0.1 release --- docs/code_gen/hpm/README.md | 2 +- docs/code_gen/mspm0/README.md | 2 +- docs/code_gen/stm32/README.md | 2 +- docs/code_gen/xrobot_inter.md | 4 ++-- docs/env_setup/README.md | 14 +++++++------- docs/env_setup/hpm.md | 2 +- docs/env_setup/mspm0.md | 2 +- docs/proj_man/README.md | 2 +- docs/proj_man/setup.md | 2 +- docs/quick_start.md | 4 ++-- .../current/code_gen/hpm/README.md | 2 +- .../current/code_gen/mspm0/README.md | 2 +- .../current/code_gen/stm32/README.md | 2 +- .../current/code_gen/xrobot_inter.md | 4 ++-- .../current/env_setup/README.md | 14 +++++++------- .../current/env_setup/hpm.md | 2 +- .../current/env_setup/mspm0.md | 2 +- .../current/proj_man/README.md | 2 +- .../current/proj_man/setup.md | 2 +- .../current/quick_start.md | 4 ++-- 20 files changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/code_gen/hpm/README.md b/docs/code_gen/hpm/README.md index ca2ab73..e1a4f16 100644 --- a/docs/code_gen/hpm/README.md +++ b/docs/code_gen/hpm/README.md @@ -205,7 +205,7 @@ HPM 的生成器不创建 UART 对象(LibXR 的 HPM UART 驱动还没有合入 以下是 bsp-hpm5301evklite 首次生成的 `User/libxr_config.yaml`: ```yaml -generator: 6.0.0 +generator: 6.0.1 I2C: i2c3: speed: 100000 diff --git a/docs/code_gen/mspm0/README.md b/docs/code_gen/mspm0/README.md index 5aa6e27..3efc79c 100644 --- a/docs/code_gen/mspm0/README.md +++ b/docs/code_gen/mspm0/README.md @@ -304,7 +304,7 @@ GPIO 引脚的 `$name` 去掉 `PIN_` 前缀后不是合法标识符时(SysConf 以下是 bsp-mspm0g3507-mini 首次生成的 `User/libxr_config.yaml`: ```yaml -generator: 6.0.0 +generator: 6.0.1 terminal_source: uart0 SPI: spi1: diff --git a/docs/code_gen/stm32/README.md b/docs/code_gen/stm32/README.md index d08efbc..edca7cf 100644 --- a/docs/code_gen/stm32/README.md +++ b/docs/code_gen/stm32/README.md @@ -213,7 +213,7 @@ FreeRTOS 的接口(Interface)推荐选择 `CMSIS_V2`。STM32Cube FW_H7 V1.13 | 键 | 默认值 | 说明 | | --- | --- | --- | -| `generator` | 新建文件时写入已安装的版本,如 `6.0.0` | 固定代码生成器的版本,见[与XRobot集成](../xrobot_inter.md#生成器版本) | +| `generator` | 新建文件时写入已安装的版本,如 `6.0.1` | 固定代码生成器的版本,见[与XRobot集成](../xrobot_inter.md#生成器版本) | | `terminal_source` | `''` | 作为终端的串口,见[串口与终端](./uart.md) | | `software_timer` | `priority: 2`、`stack_depth: 1024` | 软件定时器线程,见[软件定时器](./timer.md) | | `SPI` | `tx_buffer_size: 32`、`rx_buffer_size: 32`、`dma_section: ''`;两个方向都开启了 DMA 时另有 `dma_enable_min_size: 3` | 见 [SPI](./spi.md) | diff --git a/docs/code_gen/xrobot_inter.md b/docs/code_gen/xrobot_inter.md index 2693c54..5a5cdb9 100644 --- a/docs/code_gen/xrobot_inter.md +++ b/docs/code_gen/xrobot_inter.md @@ -90,10 +90,10 @@ extern "C" void app_main(void) ## 生成器版本 -`User/libxr_config.yaml` 顶层的 `generator:` 固定代码生成器的版本(发布版本号或 40 位 commit),BSP CI 据此安装生成器。生成器新建这个文件时,在第一行写入已安装的版本,例如 `generator: 6.0.0`;重新生成时保留该键和文件中的注释。已有的文件没有这个键时,`libxr gen` 给出警告,生成照常进行: +`User/libxr_config.yaml` 顶层的 `generator:` 固定代码生成器的版本(发布版本号或 40 位 commit),BSP CI 据此安装生成器。生成器新建这个文件时,在第一行写入已安装的版本,例如 `generator: 6.0.1`;重新生成时保留该键和文件中的注释。已有的文件没有这个键时,`libxr gen` 给出警告,生成照常进行: ```text -[警告] libxr_config.yaml 没有固定 generator 的版本;请添加 `generator: 6.0.0`(BSP 的 CI 安装固定的版本) +[警告] libxr_config.yaml 没有固定 generator 的版本;请添加 `generator: 6.0.1`(BSP 的 CI 安装固定的版本) ``` ## 生成之后 diff --git a/docs/env_setup/README.md b/docs/env_setup/README.md index 0581621..dec9f56 100644 --- a/docs/env_setup/README.md +++ b/docs/env_setup/README.md @@ -39,8 +39,8 @@ Windows: ```powershell python -m pip install --user pipx python -m pipx ensurepath -python -m pipx install xrobot==1.0.0 -python -m pipx install libxr==6.0.0 +python -m pipx install xrobot==1.0.1 +python -m pipx install libxr==6.0.1 # 重新打开终端 ``` @@ -49,15 +49,15 @@ Linux: ```bash sudo apt install pipx pipx ensurepath -pipx install xrobot==1.0.0 -pipx install libxr==6.0.0 +pipx install xrobot==1.0.1 +pipx install libxr==6.0.1 # 重新打开终端 ``` 使用 `pip` 安装适用于 Windows 或已激活的虚拟环境: ```bash -pip install xrobot==1.0.0 libxr==6.0.0 +pip install xrobot==1.0.1 libxr==6.0.1 ``` Ubuntu 24.04 等 Debian 系发行版的系统 Python 由 apt 管理,直接用 `pip` 安装时报错 `externally-managed-environment`。在这些系统上使用上面的 `pipx`,或先创建虚拟环境,再在其中使用 `pip`: @@ -66,7 +66,7 @@ Ubuntu 24.04 等 Debian 系发行版的系统 Python 由 apt 管理,直接用 sudo apt install python3-venv python3 -m venv .venv . .venv/bin/activate -pip install xrobot==1.0.0 libxr==6.0.0 +pip install xrobot==1.0.1 libxr==6.0.1 ``` 以上方式只选其一,不要混用。系统中有多份安装时,命令行实际调用的版本可能与预期不同。当前使用的版本可通过 `xrobot --version` 和 `libxr --version` 查看。 @@ -79,7 +79,7 @@ VS Code 扩展 [`XRobot.xrobot`](https://marketplace.visualstudio.com/items?item LibXR 视图按工程根目录识别平台:根目录有 `.ioc` 的是 STM32CubeMX 工程,`app.yaml` 加 `boards/*/*.hpmpc` 的是 HPM 工程,SysConfig 的 `.syscfg` 是 MSPM0 工程。视图显示平台和 `User/libxr_config.yaml` 中的各项设置,设置可以直接修改,修改后重新生成代码;"Generate LibXR Code" 运行 `libxr parse` 和 `libxr gen`,还没有 `libxr_config.yaml` 时则是对应平台的 `libxr stm32 setup`、`libxr mspm0 setup` 或 `libxr hpm setup`。MSPM0 工程的 "Open in SysConfig" 用独立版 SysConfig 打开 `.syscfg`,HPM 工程的 "Open in HPM Pinmux Tool" 用 HPMicro 的 HPM Pinmux Tool 扩展打开 `.hpmpc`。LibXR 视图的 "Pin Layout" 打开芯片的封装图(引脚布局,`libxr pins`):已选引脚按外设类别着色,MSPM0 的封装取自 SysConfig 工程,面板只读。 -扩展要求 VS Code 1.108 及以上版本,MSPM0、HPM 工程和引脚布局需要扩展 2.1.0。XRobot 视图需要 xrobot 1.0.0 和 `git`;LibXR 视图需要 libxr,STM32 工程用 6.0.0 即可,MSPM0、HPM 工程和引脚布局需要 6.1.0;两者按上一节安装。扩展在 `PATH`、pip 的用户脚本目录和设置项 `xrobot.cli.extraPath` 中查找这些命令;命令装在虚拟环境中时,把虚拟环境中 `bin` 目录(Windows 上为 `Scripts` 目录)的完整路径写入 `xrobot.cli.extraPath`。MSPM0 工程的解析(运行 SysConfig)和 "Open in SysConfig" 使用设置项 `xrobot.libxr.sysconfigTool` 和 `xrobot.libxr.mspm0SdkDir`,留空时使用环境变量 `SYSCONFIG_TOOL` 与 `MSPM0_SDK_INSTALL_DIR`。 +扩展要求 VS Code 1.108 及以上版本,MSPM0、HPM 工程和引脚布局需要扩展 2.0.1。XRobot 视图需要 xrobot 1.0.0 和 `git`;LibXR 视图需要 libxr,STM32 工程用 6.0.0 即可,MSPM0、HPM 工程和引脚布局需要 6.0.1;两者按上一节安装。扩展在 `PATH`、pip 的用户脚本目录和设置项 `xrobot.cli.extraPath` 中查找这些命令;命令装在虚拟环境中时,把虚拟环境中 `bin` 目录(Windows 上为 `Scripts` 目录)的完整路径写入 `xrobot.cli.extraPath`。MSPM0 工程的解析(运行 SysConfig)和 "Open in SysConfig" 使用设置项 `xrobot.libxr.sysconfigTool` 和 `xrobot.libxr.mspm0SdkDir`,留空时使用环境变量 `SYSCONFIG_TOOL` 与 `MSPM0_SDK_INSTALL_DIR`。 ## 平台 diff --git a/docs/env_setup/hpm.md b/docs/env_setup/hpm.md index e566253..c8d9d11 100644 --- a/docs/env_setup/hpm.md +++ b/docs/env_setup/hpm.md @@ -93,5 +93,5 @@ set(LIBXR_NO_EIGEN True) ```bash docker run --rm -v "$PWD:/work" -w /work ghcr.io/xrobot-org/docker-image-hpm:main \ - bash -c 'pip install xrobot==1.0.0 && xrobot setup && cmake --preset release-flash-xip && cmake --build --preset release-flash-xip' + bash -c 'pip install xrobot==1.0.1 && xrobot setup && cmake --preset release-flash-xip && cmake --build --preset release-flash-xip' ``` diff --git a/docs/env_setup/mspm0.md b/docs/env_setup/mspm0.md index 0984583..5c17be1 100644 --- a/docs/env_setup/mspm0.md +++ b/docs/env_setup/mspm0.md @@ -88,7 +88,7 @@ cmake --build --preset debug ```bash docker run --rm -v "$PWD:/work" -w /work ghcr.io/xrobot-org/docker-image-mspm0:main \ - bash -c 'pip install xrobot==1.0.0 && xrobot setup && cmake --preset release && cmake --build --preset release' + bash -c 'pip install xrobot==1.0.1 && xrobot setup && cmake --preset release && cmake --build --preset release' ``` ## 常见问题 diff --git a/docs/proj_man/README.md b/docs/proj_man/README.md index b108fb8..9222a7c 100644 --- a/docs/proj_man/README.md +++ b/docs/proj_man/README.md @@ -12,7 +12,7 @@ XRobot 是配合 LibXR 使用的模块管理工具。它负责拉取模块、把 ## 安装 -pip 包 `xrobot` 的安装方法见[环境配置](../env_setup/README.md#安装)。BSP 使用的版本记录在 `Modules/modules.yaml` 的 `xrobot:` 字段中,安装时应与之一致,例如 `pipx install xrobot==1.0.0`。VS Code 扩展 `XRobot.xrobot` 显示 `xrobot describe` 的结果,所有修改都通过 `xrobot` 命令完成,见 [VS Code 扩展](../env_setup/README.md#vs-code-扩展)。 +pip 包 `xrobot` 的安装方法见[环境配置](../env_setup/README.md#安装)。BSP 使用的版本记录在 `Modules/modules.yaml` 的 `xrobot:` 字段中,安装时应与之一致,例如 `pipx install xrobot==1.0.1`。VS Code 扩展 `XRobot.xrobot` 显示 `xrobot describe` 的结果,所有修改都通过 `xrobot` 命令完成,见 [VS Code 扩展](../env_setup/README.md#vs-code-扩展)。 --- diff --git a/docs/proj_man/setup.md b/docs/proj_man/setup.md index 3faf090..f76aaac 100644 --- a/docs/proj_man/setup.md +++ b/docs/proj_man/setup.md @@ -13,7 +13,7 @@ sidebar_position: 1 ## modules.yaml ```yaml -xrobot: 1.0.0 +xrobot: 1.0.1 modules: - xrobot-org/BlinkLED@dev - xrobot-org/BMI088@same-or-dev diff --git a/docs/quick_start.md b/docs/quick_start.md index 337d612..1021bb6 100644 --- a/docs/quick_start.md +++ b/docs/quick_start.md @@ -14,9 +14,9 @@ sidebar_position: 2 ```text $ xrobot --version -xrobot 1.0.0 +xrobot 1.0.1 $ libxr --version -libxr 6.0.0 +libxr 6.0.1 ``` BSP 使用的 xrobot 版本记录在 `Modules/modules.yaml` 的 `xrobot:` 字段中,使用 CodeGenerator 的 STM32 工程另在 `User/libxr_config.yaml` 的 `generator:` 字段中记录 libxr 的版本,安装的版本应与之一致。 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md index 8bc2e20..d149187 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/hpm/README.md @@ -205,7 +205,7 @@ The HPM generator creates no UART (the HPM UART driver of LibXR has not been mer The following is the `User/libxr_config.yaml` generated on bsp-hpm5301evklite the first time: ```yaml -generator: 6.0.0 +generator: 6.0.1 I2C: i2c3: speed: 100000 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md index e90e5a0..3f87323 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/mspm0/README.md @@ -304,7 +304,7 @@ The settings sections: The following is the `User/libxr_config.yaml` generated on bsp-mspm0g3507-mini the first time: ```yaml -generator: 6.0.0 +generator: 6.0.1 terminal_source: uart0 SPI: spi1: diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/stm32/README.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/stm32/README.md index 4841f00..accace4 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/stm32/README.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/stm32/README.md @@ -215,7 +215,7 @@ The table lists the top-level keys; `config_version` is written by the user: | Key | Default | Description | | --- | --- | --- | -| `generator` | The installed version, such as `6.0.0`, written when the file is created | Pins the code generator version, see [Integrate with XRobot](../xrobot_inter.md#generator-version) | +| `generator` | The installed version, such as `6.0.1`, written when the file is created | Pins the code generator version, see [Integrate with XRobot](../xrobot_inter.md#generator-version) | | `terminal_source` | `''` | Serial port of the terminal, see [UART and Terminal](./uart.md) | | `software_timer` | `priority: 2`, `stack_depth: 1024` | Software timer thread, see [Software Timer](./timer.md) | | `SPI` | `tx_buffer_size: 32`, `rx_buffer_size: 32`, `dma_section: ''`; `dma_enable_min_size: 3` as well with DMA in both directions | See [SPI](./spi.md) | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/xrobot_inter.md b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/xrobot_inter.md index 7333c42..a43a29a 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/code_gen/xrobot_inter.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/code_gen/xrobot_inter.md @@ -90,10 +90,10 @@ The registered name is the generated C++ object name. The table gives the regist ## Generator Version -`generator:` at the top level of `User/libxr_config.yaml` pins the code generator (a release version or a 40-hex commit); BSP CI installs that version. When the generator creates this file, its first line holds the installed version, e.g. `generator: 6.0.0`; regeneration keeps the key and the file's comments. When an existing file has no such key, `libxr gen` warns and generates as usual: +`generator:` at the top level of `User/libxr_config.yaml` pins the code generator (a release version or a 40-hex commit); BSP CI installs that version. When the generator creates this file, its first line holds the installed version, e.g. `generator: 6.0.1`; regeneration keeps the key and the file's comments. When an existing file has no such key, `libxr gen` warns and generates as usual: ```text -[WARNING] libxr_config.yaml does not pin the generator; add `generator: 6.0.0` (the BSP CI installs the pinned version) +[WARNING] libxr_config.yaml does not pin the generator; add `generator: 6.0.1` (the BSP CI installs the pinned version) ``` ## After Generation diff --git a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/README.md b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/README.md index 83ab1d3..9570344 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/README.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/README.md @@ -39,8 +39,8 @@ Windows: ```powershell python -m pip install --user pipx python -m pipx ensurepath -python -m pipx install xrobot==1.0.0 -python -m pipx install libxr==6.0.0 +python -m pipx install xrobot==1.0.1 +python -m pipx install libxr==6.0.1 # Restart your terminal ``` @@ -49,15 +49,15 @@ Linux: ```bash sudo apt install pipx pipx ensurepath -pipx install xrobot==1.0.0 -pipx install libxr==6.0.0 +pipx install xrobot==1.0.1 +pipx install libxr==6.0.1 # Restart your terminal ``` Installing with `pip` applies to Windows or to an activated virtual environment: ```bash -pip install xrobot==1.0.0 libxr==6.0.0 +pip install xrobot==1.0.1 libxr==6.0.1 ``` On Ubuntu 24.04 and other Debian-based distributions the system Python is managed by apt, and a plain `pip` install fails with `externally-managed-environment`. On these systems use `pipx` as above, or create a virtual environment first and use `pip` inside it: @@ -66,7 +66,7 @@ On Ubuntu 24.04 and other Debian-based distributions the system Python is manage sudo apt install python3-venv python3 -m venv .venv . .venv/bin/activate -pip install xrobot==1.0.0 libxr==6.0.0 +pip install xrobot==1.0.1 libxr==6.0.1 ``` Use only one of these methods. With several installations present, the command line may run a different version than expected. `xrobot --version` and `libxr --version` show the versions in use. @@ -79,7 +79,7 @@ The VS Code extension [`XRobot.xrobot`](https://marketplace.visualstudio.com/ite The LibXR view recognizes the platform from the workspace root: a project with an `.ioc` at its root is an STM32CubeMX project, an `app.yaml` with `boards/*/*.hpmpc` is an HPM project, and a SysConfig `.syscfg` is an MSPM0 project. The view shows the platform and the settings of `User/libxr_config.yaml`; the settings can be edited there and the code is regenerated. "Generate LibXR Code" runs `libxr parse` and `libxr gen`, or the platform's `libxr stm32 setup`, `libxr mspm0 setup` or `libxr hpm setup` while there is no `libxr_config.yaml` yet. For an MSPM0 project, "Open in SysConfig" opens the `.syscfg` in the standalone SysConfig; for an HPM project, "Open in HPM Pinmux Tool" opens the `.hpmpc` with HPMicro's HPM Pinmux Tool extension. "Pin Layout" in the LibXR view opens the package drawing of the chip (the pin layout, `libxr pins`): the selected pins are coloured by peripheral category, the package of an MSPM0 comes from its SysConfig project, and the panel is read-only. -The extension requires VS Code 1.108 or newer; MSPM0 and HPM projects and the pin layout need extension 2.1.0. The XRobot view needs xrobot 1.0.0 and `git`; the LibXR view needs libxr, 6.0.0 for STM32 projects and 6.1.0 for MSPM0 and HPM projects and the pin layout; both are installed as in the previous section. The extension looks up these commands on `PATH`, in pip's per-user script directories and in the `xrobot.cli.extraPath` setting; when the commands are installed in a virtual environment, put the full path of its `bin` directory (`Scripts` on Windows) in `xrobot.cli.extraPath`. Parsing an MSPM0 project (which runs SysConfig) and "Open in SysConfig" use the settings `xrobot.libxr.sysconfigTool` and `xrobot.libxr.mspm0SdkDir`; when they are empty, the environment variables `SYSCONFIG_TOOL` and `MSPM0_SDK_INSTALL_DIR` are used. +The extension requires VS Code 1.108 or newer; MSPM0 and HPM projects and the pin layout need extension 2.0.1. The XRobot view needs xrobot 1.0.0 and `git`; the LibXR view needs libxr, 6.0.0 for STM32 projects and 6.0.1 for MSPM0 and HPM projects and the pin layout; both are installed as in the previous section. The extension looks up these commands on `PATH`, in pip's per-user script directories and in the `xrobot.cli.extraPath` setting; when the commands are installed in a virtual environment, put the full path of its `bin` directory (`Scripts` on Windows) in `xrobot.cli.extraPath`. Parsing an MSPM0 project (which runs SysConfig) and "Open in SysConfig" use the settings `xrobot.libxr.sysconfigTool` and `xrobot.libxr.mspm0SdkDir`; when they are empty, the environment variables `SYSCONFIG_TOOL` and `MSPM0_SDK_INSTALL_DIR` are used. ## Platforms diff --git a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md index bc74d63..8eaa96f 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/hpm.md @@ -93,5 +93,5 @@ The image `ghcr.io/xrobot-org/docker-image-hpm:main` ships the RISC-V toolchain ```bash docker run --rm -v "$PWD:/work" -w /work ghcr.io/xrobot-org/docker-image-hpm:main \ - bash -c 'pip install xrobot==1.0.0 && xrobot setup && cmake --preset release-flash-xip && cmake --build --preset release-flash-xip' + bash -c 'pip install xrobot==1.0.1 && xrobot setup && cmake --preset release-flash-xip && cmake --build --preset release-flash-xip' ``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/mspm0.md b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/mspm0.md index 81d0383..0b92f4e 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/env_setup/mspm0.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/env_setup/mspm0.md @@ -88,7 +88,7 @@ The image `ghcr.io/xrobot-org/docker-image-mspm0:main` ships `arm-none-eabi-gcc` ```bash docker run --rm -v "$PWD:/work" -w /work ghcr.io/xrobot-org/docker-image-mspm0:main \ - bash -c 'pip install xrobot==1.0.0 && xrobot setup && cmake --preset release && cmake --build --preset release' + bash -c 'pip install xrobot==1.0.1 && xrobot setup && cmake --preset release && cmake --build --preset release' ``` ## FAQ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/proj_man/README.md b/i18n/en/docusaurus-plugin-content-docs/current/proj_man/README.md index 6b666b4..2ae7a7a 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/proj_man/README.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/proj_man/README.md @@ -12,7 +12,7 @@ XRobot is the Module manager for LibXR. It fetches Modules, locks each one to a ## Installation -Installing the pip package `xrobot` is described in [Environment Setup](../env_setup/README.md#installation). The version a BSP uses is recorded in the `xrobot:` field of `Modules/modules.yaml`; install the same version, for example `pipx install xrobot==1.0.0`. The VS Code extension `XRobot.xrobot` shows what `xrobot describe` reports and makes every change through an `xrobot` command; see [VS Code Extension](../env_setup/README.md#vs-code-extension). +Installing the pip package `xrobot` is described in [Environment Setup](../env_setup/README.md#installation). The version a BSP uses is recorded in the `xrobot:` field of `Modules/modules.yaml`; install the same version, for example `pipx install xrobot==1.0.1`. The VS Code extension `XRobot.xrobot` shows what `xrobot describe` reports and makes every change through an `xrobot` command; see [VS Code Extension](../env_setup/README.md#vs-code-extension). --- diff --git a/i18n/en/docusaurus-plugin-content-docs/current/proj_man/setup.md b/i18n/en/docusaurus-plugin-content-docs/current/proj_man/setup.md index 44f4c41..07b3619 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/proj_man/setup.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/proj_man/setup.md @@ -13,7 +13,7 @@ sidebar_position: 1 ## modules.yaml ```yaml -xrobot: 1.0.0 +xrobot: 1.0.1 modules: - xrobot-org/BlinkLED@dev - xrobot-org/BMI088@same-or-dev diff --git a/i18n/en/docusaurus-plugin-content-docs/current/quick_start.md b/i18n/en/docusaurus-plugin-content-docs/current/quick_start.md index eaa1a5c..65b1890 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/quick_start.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/quick_start.md @@ -14,9 +14,9 @@ Installing the tools is described in [Environment Setup](./env_setup/README.md#i ```text $ xrobot --version -xrobot 1.0.0 +xrobot 1.0.1 $ libxr --version -libxr 6.0.0 +libxr 6.0.1 ``` The xrobot version a BSP uses is recorded in the `xrobot:` field of `Modules/modules.yaml`, and STM32 projects that use the CodeGenerator also record the libxr version in the `generator:` field of `User/libxr_config.yaml`; the installed versions should match. From d52ddb2f9a92c633d68186f30ccb4f07bd33a0f2 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 10 Oct 2026 11:56:21 +0100 Subject: [PATCH 12/16] Self-review: link the RamFS page and describe the pool and mailbox behavior by mechanism --- docs/basic_coding/driver/power.md | 2 +- docs/basic_coding/structure/latest_snapshot.md | 4 ++-- docs/basic_coding/structure/object_pool.md | 2 +- .../current/basic_coding/driver/power.md | 2 +- .../current/basic_coding/structure/latest_snapshot.md | 4 ++-- .../current/basic_coding/structure/object_pool.md | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/basic_coding/driver/power.md b/docs/basic_coding/driver/power.md index 3ac3f6e..5ad2a0e 100644 --- a/docs/basic_coding/driver/power.md +++ b/docs/basic_coding/driver/power.md @@ -38,7 +38,7 @@ public: - `Reset()` 可用于软复位控制器、重新启动系统等; - `Shutdown()` 用于关机、掉电、进入睡眠等低功耗控制; - `JumpToBootloader()` 默认会退化为 `Reset()`,平台实现可按需改为真正的 Bootloader 跳转; -- `RegisterCommand(ramfs)` 在 RamFS 根目录注册 `power` 命令:终端中 `power reset`、`power shutdown`、`power bootloader` 分别调用上述三个方法,不带参数或参数不认识时打印用法并返回 -1。命令文件在第一次注册时分配,之后不释放,同一个对象只注册一次; +- `RegisterCommand(ramfs)` 在 RamFS 根目录注册 `power` 命令(见[内存文件系统](../middleware/ramfs.md)):终端中 `power reset`、`power shutdown`、`power bootloader` 分别调用上述三个方法,不带参数或参数不认识时打印用法并返回 -1。命令文件在第一次注册时分配,之后不释放,同一个对象只注册一次; - `CheckBootloaderPin(pin, level)` 读一次引脚,电平等于 `level` 时调用 `JumpToBootloader()`,否则直接返回;在初始化早期调用一次,按住该引脚对应的按键再复位即可进入启动加载器,运行中该引脚仍归程序使用。引脚的输入方向和上下拉由工程配置决定,本函数不修改;悬空的引脚可能误触发; - 可用于平台的电源按钮、远程命令、低电量策略等情境; - 由具体平台实现其底层行为,接口保持一致,便于移植与抽象封装。 diff --git a/docs/basic_coding/structure/latest_snapshot.md b/docs/basic_coding/structure/latest_snapshot.md index aca182f..f40659d 100644 --- a/docs/basic_coding/structure/latest_snapshot.md +++ b/docs/basic_coding/structure/latest_snapshot.md @@ -13,7 +13,7 @@ sidebar_position: 10 ## 核心特性 - 内部三个槽:生产者独占后槽,消费者独占前槽,中间槽由一个原子状态交给对方,承载最新一次完成的发布; -- 连续的 `Store()` 可以覆盖消费者尚未取走的中间值,但不会覆盖消费者正在拷贝的值; +- 连续的 `Store()` 可以覆盖消费者尚未取走的中间值;消费者正在拷贝的值在它独占的前槽里,不受影响; - 三个槽随对象构造,`LatestSnapshot` 自身不分配内存; - 对象不可拷贝、不可移动。 @@ -42,7 +42,7 @@ class LatestSnapshot - `Store()` 只能由唯一的生产者调用,`LoadLatest()` 只能由唯一的消费者串行调用,同一时刻只有一次调用; - 生产者和消费者的调用可以在不同核、线程或中断中重叠,两者的交接用一个 32 位原子状态完成; -- 值在发布时整体拷贝,读到的始终是一份完整的值,不会读到写到一半的数据。 +- 值在发布时整体拷贝,因此每次读到的都是一份完整的值。 ## 使用示例 diff --git a/docs/basic_coding/structure/object_pool.md b/docs/basic_coding/structure/object_pool.md index dbbeca2..c40ef0d 100644 --- a/docs/basic_coding/structure/object_pool.md +++ b/docs/basic_coding/structure/object_pool.md @@ -38,7 +38,7 @@ LibXR::ObjectPool ### 1.3 并发约束 -同一池同一时刻只能有一个申请方,申请不得重叠或重入,Debug 构建会检查;重叠申请会让空闲栈出现 ABA,把同一个槽位交给两个申请方。释放可以在任意线程或 ISR 中并发进行,且不会失败。不同句柄对象可以并发使用,同一句柄对象的并发访问须由调用方同步。构造和析构须在静止状态下进行,不能在 ISR 中执行;池与外部槽存储必须比全部句柄活得更久。在 ISR 中使用要求目标平台提供 32 位原子 CAS。 +同一池同一时刻只能有一个申请方,申请不得重叠或重入,Debug 构建会检查;重叠申请会让空闲栈出现 ABA,把同一个槽位交给两个申请方。释放可以在任意线程或 ISR 中并发进行,这条路径没有失败分支。不同句柄对象可以并发使用,同一句柄对象的并发访问须由调用方同步。构造和析构须在静止状态下进行,不能在 ISR 中执行;池与外部槽存储必须比全部句柄活得更久。在 ISR 中使用要求目标平台提供 32 位原子 CAS。 --- diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/driver/power.md b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/driver/power.md index d8a1a33..928b7d4 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/driver/power.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/driver/power.md @@ -38,7 +38,7 @@ public: - `Reset()` can be used to perform a soft reset, restart the system, etc.; - `Shutdown()` is used for power-off, entering sleep, or other low-power control; - `JumpToBootloader()` falls back to `Reset()` by default, and platform implementations may replace it with a real bootloader jump; -- `RegisterCommand(ramfs)` registers the `power` command in the RamFS root: in the terminal, `power reset`, `power shutdown` and `power bootloader` call the three methods above, while a missing or unknown argument prints the usage and returns -1. The command file is allocated on the first registration and is not freed afterwards, so one object is registered once; +- `RegisterCommand(ramfs)` registers the `power` command in the RamFS root (see [In-Memory File System](../middleware/ramfs.md)): in the terminal, `power reset`, `power shutdown` and `power bootloader` call the three methods above, while a missing or unknown argument prints the usage and returns -1. The command file is allocated on the first registration and is not freed afterwards, so one object is registered once; - `CheckBootloaderPin(pin, level)` reads the pin once and calls `JumpToBootloader()` when it reads `level`, otherwise it returns; called once early during initialization, it enters the bootloader when the key on that pin is held through a reset, while the pin stays with the application at run time. The input direction and pull of the pin come from the project configuration and are left unchanged; a floating pin may trigger by accident; - Can be applied in scenarios such as power button handling, remote commands, low battery strategies, etc.; - The specific behavior is implemented by the platform, while the interface remains consistent to facilitate portability and abstraction. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/latest_snapshot.md b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/latest_snapshot.md index c939553..8b040d2 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/latest_snapshot.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/latest_snapshot.md @@ -13,7 +13,7 @@ It suits data of which only the latest value matters. Taking a receive interrupt ## Core features - Three internal slots: a back slot owned by the producer, a front slot owned by the consumer, and a middle slot handed over through one atomic state, which carries the latest completed publication; -- repeated `Store()` calls may overwrite a middle value the consumer has not taken, but never the value the consumer is copying; +- repeated `Store()` calls may overwrite a middle value the consumer has not taken, while the value the consumer is copying sits in its own front slot and is not affected; - the three slots are constructed with the object, and `LatestSnapshot` allocates no memory itself; - the object is neither copyable nor movable. @@ -42,7 +42,7 @@ class LatestSnapshot - `Store()` may only be called by the single producer, and `LoadLatest()` only by the single serialized consumer, one call at a time; - producer and consumer calls may overlap on different cores or in thread and interrupt contexts, since the handover between them uses one 32-bit atomic state; -- the value is copied whole on publication, so a read always returns one complete value rather than a half-written one. +- the value is copied whole on publication, so every read returns one complete value. ## Example diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/object_pool.md b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/object_pool.md index 15b741f..9951181 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/object_pool.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/object_pool.md @@ -38,7 +38,7 @@ The slot type is `ObjectPool::Slot`, made of a reference count, a free-sta ### 1.3 Concurrency -Only one acquirer may use a pool at a time, and acquisitions must not overlap or reenter; debug builds check this, because overlapping acquisitions cause ABA on the free stack and hand one slot to two acquirers. Releases may run concurrently from any thread or ISR and cannot fail. Distinct handle objects may be used concurrently, while concurrent access to one handle object requires caller synchronization. Construction and destruction require quiescence and cannot run in an ISR; the pool and any external slot storage must outlive all handles. ISR use requires 32-bit atomic CAS on the target. +Only one acquirer may use a pool at a time, and acquisitions must not overlap or reenter; debug builds check this, because overlapping acquisitions cause ABA on the free stack and hand one slot to two acquirers. Releases may run concurrently from any thread or ISR, and that path has no failure branch. Distinct handle objects may be used concurrently, while concurrent access to one handle object requires caller synchronization. Construction and destruction require quiescence and cannot run in an ISR; the pool and any external slot storage must outlive all handles. ISR use requires 32-bit atomic CAS on the target. --- From 426c38ae3bc913d50dc3866af7bb6b3c99195823 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 10 Oct 2026 12:42:32 +0100 Subject: [PATCH 13/16] Power: the HPM Shutdown() wakes up on RESETN --- docs/basic_coding/driver/power.md | 2 +- .../current/basic_coding/driver/power.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/basic_coding/driver/power.md b/docs/basic_coding/driver/power.md index 5ad2a0e..9a7b468 100644 --- a/docs/basic_coding/driver/power.md +++ b/docs/basic_coding/driver/power.md @@ -47,7 +47,7 @@ public: 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 或 WAKEUP 引脚唤醒,没有 PDGO 的 SoC 退化为关中断后执行 WFI;`JumpToBootloader()` 关中断后调用 ROM API 进入 ROM ISP,外设由 ROM 自动探测,调用正常不返回,返回时复位整机。经 USB 的 ROM ISP 在 HPM5301 和 HPM5361 上未能枚举。 +HPM 的 `HPMPowerManager` 中,`Reset()` 使能 PPOR 软件复位源后触发复位;`Shutdown()` 在带 PDGO 的 SoC 上设置关断计数后等待断电,由 RESETN 引脚唤醒,没有 PDGO 的 SoC 退化为关中断后执行 WFI;`JumpToBootloader()` 关中断后调用 ROM API 进入 ROM ISP,外设由 ROM 自动探测,调用正常不返回,返回时复位整机。经 USB 的 ROM ISP 在 HPM5301 和 HPM5361 上未能枚举。 ## 说明 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/driver/power.md b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/driver/power.md index 928b7d4..5fac0bd 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/driver/power.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/driver/power.md @@ -47,7 +47,7 @@ public: In the MSPM0 `MSPM0PowerManager`, `Reset()` triggers the boot configuration routine, resets most of the core logic and power-cycles the SRAM, so the device restarts from Flash like a fresh power-up; `Shutdown()` enters the SHUTDOWN mode, woken up by NRST, SWD activity or a wake-up capable IO, and leaving SHUTDOWN triggers a BOR, so waking up is equivalent to a reset; `JumpToBootloader()` resets into the ROM BSL and, following the SDK example, clears the SRAM data and ECC codes before the reset to work around `BSL_ERR_01`. The MSPM0 ROM BSL runs over the serial port, so firmware can be flashed over that port after `power bootloader`. -In the HPM `HPMPowerManager`, `Reset()` enables the PPOR software reset source and then issues the reset; `Shutdown()` sets the turn-off counter and waits for the power down on SoCs with a PDGO, woken up by the RESETN or WAKEUP pin, and falls back to disabling interrupts and executing WFI on SoCs without one; `JumpToBootloader()` disables the interrupts and calls the ROM API to enter the ROM ISP, with the peripheral auto-detected by the ROM; the call does not return normally, and a return resets the device. The ROM ISP over USB did not enumerate on the HPM5301 and HPM5361. +In the HPM `HPMPowerManager`, `Reset()` enables the PPOR software reset source and then issues the reset; `Shutdown()` sets the turn-off counter and waits for the power down on SoCs with a PDGO, woken up by the RESETN pin, and falls back to disabling interrupts and executing WFI on SoCs without one; `JumpToBootloader()` disables the interrupts and calls the ROM API to enter the ROM ISP, with the peripheral auto-detected by the ROM; the call does not return normally, and a return resets the device. The ROM ISP over USB did not enumerate on the HPM5301 and HPM5361. ## Notes From 94ac59162537735a5d96f4b876e380716b4fda74 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 10 Oct 2026 18:47:21 +0100 Subject: [PATCH 14/16] docs: add the SlotPool page and adjust the MPMC queue selection advice Adds the SlotPool page (core features, common APIs, concurrency constraints, example and selection advice) in both languages, links it from the structure index, and updates the MPMCQueue selection advice with the same division of labor: SlotPool for interrupt-facing pools where FULL/EMPTY must be accurate, MPMCQueue where callers can wait or retry and for large or multi-core heavy queues. The CAN TX queue example now points at SlotPool, matching the driver change in the same release. --- docs/basic_coding/structure/README.md | 1 + docs/basic_coding/structure/mpmc_queue.md | 7 +- docs/basic_coding/structure/slot_pool.md | 86 +++++++++++++++++++ .../current/basic_coding/structure/README.md | 1 + .../basic_coding/structure/mpmc_queue.md | 7 +- .../basic_coding/structure/slot_pool.md | 86 +++++++++++++++++++ 6 files changed, 182 insertions(+), 6 deletions(-) create mode 100644 docs/basic_coding/structure/slot_pool.md create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/slot_pool.md diff --git a/docs/basic_coding/structure/README.md b/docs/basic_coding/structure/README.md index ec31635..724a29b 100644 --- a/docs/basic_coding/structure/README.md +++ b/docs/basic_coding/structure/README.md @@ -19,6 +19,7 @@ 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) diff --git a/docs/basic_coding/structure/mpmc_queue.md b/docs/basic_coding/structure/mpmc_queue.md index 149072c..0006638 100644 --- a/docs/basic_coding/structure/mpmc_queue.md +++ b/docs/basic_coding/structure/mpmc_queue.md @@ -50,9 +50,10 @@ queue.Pop(value); - 中断与线程、多个线程共同访问的公共队列; - 驱动内部需要有界并发队列的地方。 -例如 CAN 驱动的发送队列使用 `MPMCQueue`。 +例如数据在任务和线程之间传递、调用方能等待或稍后重试的公共队列。单核上若某个操作在占槽与发布之间被抢占,其他上下文会看到瞬时的 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`。 diff --git a/docs/basic_coding/structure/slot_pool.md b/docs/basic_coding/structure/slot_pool.md new file mode 100644 index 0000000..1bfc48e --- /dev/null +++ b/docs/basic_coding/structure/slot_pool.md @@ -0,0 +1,86 @@ +--- +id: slot_pool +title: SlotPool +sidebar_position: 11 +--- + +# SlotPool(消息槽池) + +`LibXR::SlotPool` 是面向任务与中断的小容量消息槽池:每个槽一个原子状态,写完的槽按发布顺序出队。 + +以 CAN 发送队列为例:任务和发送完成中断都会调用 `AddMessage()` 入队,发送服务出队。任务在入队或出队做到一半时被中断打断,是无锁队列里最常见的场景;`MPMCQueue` 在这个场景下会返回瞬时的 FULL/EMPTY(假的满/空),`SlotPool` 保证一个被打断的操作只占住它自己的槽,中断拿到的 FULL/EMPTY 反映那一刻的真实状态。 + +## 核心特性 + +- 每个槽一个原子状态:空闲、写入中、就绪、读取中。所有转换用 CAS 完成,同一时刻一个槽只属于一个执行上下文; +- `Publish()` 时取一个全局递增的发布序号,`Take()` 选序号最小的就绪槽:出队顺序是发布完成的先后,同一发布者内部保序; +- `Acquire()`/`Take()` 扫描全部槽位,被其他上下文占着的槽直接跳过,一个还没写完的槽不会挡住其他槽; +- 释放计数和发布计数用于扫描后的重扫判断,最多重扫一次;序号用带符号差值比较,允许回绕; +- 槽在构造时分配,运行期不再分配;对象不可拷贝、不可移动; +- 适用于几到几十个槽的小容量场合,`Acquire()`/`Take()` 是 O(N) 扫描。 + +## 常用接口 + +```cpp +template +class SlotPool +{ + public: + explicit SlotPool(size_t slot_count); + + ErrorCode Acquire(size_t& index); // 空闲 → 写入中;没有空闲槽返回 FULL + void Publish(size_t index); // 写入中 → 就绪,并取得发布序号 + ErrorCode Take(size_t& index); // 序号最小的就绪槽 → 读取中;没有就绪槽返回 EMPTY + void Release(size_t index); // 写入中或读取中 → 空闲,不会失败 + T& At(size_t index); // 访问自己持有的槽 + + ErrorCode Put(const T& value); // Acquire + 拷贝 + Publish + ErrorCode Get(T& value); // Take + 拷贝 + Release + + size_t Size() const; // 槽总数 +}; +``` + +- `Acquire()`、`Publish()`、`Take()`、`Release()` 是底层接口,数据通过 `At()` 在槽内原地读写,适合"数据在槽里原地写、原地发送,发送完成后再释放"的用法; +- `Put()`/`Get()` 是便捷接口,一次调用完成入队或出队,要求 `T` 平凡可拷贝; +- 只用 `Acquire()`/`Release()` 时,槽池可以当固定容量的分配器使用,放弃一个只认领未发布的槽也是合法用法。 + +## 并发约束 + +- 任意数量的生产者和消费者都可以,任务和普通中断里都能调用;不要在 NMI 里使用; +- 单核上,中断扫描期间低优先级上下文不会改动槽,中断里拿到的 FULL/EMPTY 反映那一刻的真实状态;被打断的操作占着的槽算作占用; +- 出队顺序是发布完成的先后:同一发布者内部保序,不保证跨发布者的全局先进先出; +- `Publish()` 和 `Release()` 的调用方必须持有对应槽,重复发布或释放其他上下文持有的槽是调用方错误。 + +## 使用示例 + +```cpp +LibXR::SlotPool tx_pool(8); + +// 任务或中断中提交一帧;FULL 表示确实没有空闲槽 +void AddMessage(const LibXR::CAN::ClassicPack& pack) +{ + if (tx_pool.Put(pack) != LibXR::ErrorCode::OK) + { + // 池满:稍后重试 + } +} + +// 发送服务中取出并交给硬件 +void TxService() +{ + LibXR::CAN::ClassicPack pack{}; + if (tx_pool.Get(pack) == LibXR::ErrorCode::OK) + { + // pack 已拷出,槽已释放,可以直接交给硬件发送 + } +} +``` + +## 选择建议 + +- 中断会读写、拿到 FULL 只能丢数据的场合(例如中断与任务共享的发送队列):用 `SlotPool`,一个被打断的操作只占自己的槽,FULL/EMPTY 是准的; +- 调用方能等待或稍后重试、大容量或多核高争用的场合:用 `MPMCQueue`,单次入队出队 O(1),`SlotPool` 是 O(N); +- 生产者和消费者各只有一个:`SPSCQueue`; +- 只关心最新一份完整值:`LatestSnapshot`; +- 管理可复用的对象而不是消息:`ObjectPool`。 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 index 7b436bc..74ef0b3 100644 --- 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 @@ -19,6 +19,7 @@ This chapter covers the general-purpose data structures LibXR uses for task sche - [Queue (ordinary 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) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/mpmc_queue.md b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/mpmc_queue.md index d7bbdb6..3295ed7 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/mpmc_queue.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/mpmc_queue.md @@ -50,9 +50,10 @@ Good fit: - public concurrent queues accessed by interrupts and threads, or by multiple threads; - internal driver queues that need bounded concurrent behavior. -For example, the CAN drivers use `MPMCQueue` for their TX queues. +For example, a public queue passing data between tasks and threads where callers can wait or retry later. On a single core, when one context is preempted between claiming a cell and publishing it, other contexts observe transient FULL/EMPTY; when interrupts both read and write and a FULL can only drop data (for example a TX queue shared by an interrupt and a task), use [SlotPool](./slot_pool.md) instead. -## How to Choose Between `SPSCQueue` and `MPMCQueue` +## How to Choose Between `SPSCQueue`, `MPMCQueue` and `SlotPool` - one producer and one consumer: use `SPSCQueue`; -- multiple producers or consumers: use `MPMCQueue`. +- multiple producers or consumers: use `MPMCQueue`; +- interrupts read and write, a FULL can only drop data, and FULL/EMPTY should be accurate: use [SlotPool](./slot_pool.md), where an interrupted operation only occupies its own slot; a single enqueue or dequeue is O(1) on `MPMCQueue` and O(N) on `SlotPool`, so large capacities, high multi-core contention and callers that can wait or retry remain a good fit for `MPMCQueue`. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/slot_pool.md b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/slot_pool.md new file mode 100644 index 0000000..7cce922 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/slot_pool.md @@ -0,0 +1,86 @@ +--- +id: slot_pool +title: SlotPool +sidebar_position: 11 +--- + +# SlotPool (Message Slot Pool) + +`LibXR::SlotPool` is a small message slot pool shared between tasks and interrupts: each slot carries one atomic state, and fully written slots dequeue in publication order. + +Take a CAN TX queue as an example: both the task and the TX-complete interrupt call `AddMessage()` to enqueue, and the TX service dequeues. A task interrupted halfway through an enqueue or a dequeue is the most common scenario for lock-free queues; `MPMCQueue` returns a transient FULL/EMPTY (spurious full/empty) in this scenario, while `SlotPool` guarantees that an interrupted operation only occupies its own slot, so the FULL/EMPTY observed from an interrupt reflects the true state at that moment. + +## Core features + +- Each slot carries one atomic state: free, writing, ready, or reading. Every transition is a CAS, so at any moment a slot belongs to exactly one execution context; +- `Publish()` takes a globally increasing publish sequence, and `Take()` picks the ready slot with the smallest sequence: the dequeue order is publish-completion order, and the order inside one publisher is preserved; +- `Acquire()`/`Take()` scan the whole slot array and skip slots owned by other contexts, so a slot that has not been written yet never blocks the others; +- the release counter and the publish counter drive a bounded rescan of at most one extra pass; sequence numbers are compared with signed deltas, so wraparound is allowed; +- the slots are allocated at construction and never at run time; the object is neither copyable nor movable; +- the pool targets small capacities of a few to a few dozen slots, where the O(N) scans of `Acquire()`/`Take()` are cheap. + +## Common APIs + +```cpp +template +class SlotPool +{ + public: + explicit SlotPool(size_t slot_count); + + ErrorCode Acquire(size_t& index); // free -> writing; FULL when no slot is free + void Publish(size_t index); // writing -> ready, and takes a publish sequence + ErrorCode Take(size_t& index); // smallest-sequence ready slot -> reading; EMPTY when none is ready + void Release(size_t index); // writing or reading -> free; cannot fail + T& At(size_t index); // access an owned slot + + ErrorCode Put(const T& value); // Acquire + copy + Publish + ErrorCode Get(T& value); // Take + copy + Release + + size_t Size() const; // total number of slots +}; +``` + +- `Acquire()`, `Publish()`, `Take()` and `Release()` are the low-level interface; the data is written and read in place through `At()`, which fits the pattern of writing in the slot, sending from the slot, and releasing after the send completes; +- `Put()`/`Get()` are the convenience interface and complete an enqueue or a dequeue in one call; they require `T` to be trivially copyable; +- using only `Acquire()`/`Release()`, the pool serves as a fixed-capacity allocator, and abandoning a slot that was acquired but not published is also valid. + +## Concurrency constraints + +- any number of producers and consumers may run concurrently; calls are allowed from tasks and normal interrupts, but not from NMI; +- on a single core, low-priority contexts cannot change the slots while an interrupt is scanning, so the FULL/EMPTY an interrupt observes reflects the true state at that moment; a slot held by an interrupted operation counts as occupied; +- the dequeue order is publish-completion order: the order inside one publisher is preserved, and no global cross-publisher FIFO is guaranteed; +- the callers of `Publish()` and `Release()` must own the slot; double publishing or releasing a slot owned by another context is a caller error. + +## Example + +```cpp +LibXR::SlotPool tx_pool(8); + +// Submit a frame from a task or an interrupt; FULL means no free slot +void AddMessage(const LibXR::CAN::ClassicPack& pack) +{ + if (tx_pool.Put(pack) != LibXR::ErrorCode::OK) + { + // Pool full: retry later + } +} + +// Take one frame in the TX service and hand it to the hardware +void TxService() +{ + LibXR::CAN::ClassicPack pack{}; + if (tx_pool.Get(pack) == LibXR::ErrorCode::OK) + { + // pack has been copied out, the slot is released, ready for the hardware + } +} +``` + +## Choosing between the structures + +- when interrupts both read and write and a FULL can only drop data (for example a TX queue shared by an interrupt and a task): use `SlotPool`; an interrupted operation only occupies its own slot, and FULL/EMPTY are accurate; +- when callers can wait or retry later, or with large capacities and high multi-core contention: use `MPMCQueue`; a single enqueue or dequeue is O(1), while `SlotPool` is O(N); +- one producer and one consumer: `SPSCQueue`; +- only the latest complete value matters: `LatestSnapshot`; +- reusable objects instead of messages: `ObjectPool`. From 590f28e9c6d010ebba4d9fc7847ffcec12e9ae81 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 10 Oct 2026 21:31:55 +0100 Subject: [PATCH 15/16] SlotPool page: who calls AddMessage, and the example's full branch --- docs/basic_coding/structure/slot_pool.md | 4 ++-- .../current/basic_coding/structure/slot_pool.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/basic_coding/structure/slot_pool.md b/docs/basic_coding/structure/slot_pool.md index 1bfc48e..668013d 100644 --- a/docs/basic_coding/structure/slot_pool.md +++ b/docs/basic_coding/structure/slot_pool.md @@ -8,7 +8,7 @@ sidebar_position: 11 `LibXR::SlotPool` 是面向任务与中断的小容量消息槽池:每个槽一个原子状态,写完的槽按发布顺序出队。 -以 CAN 发送队列为例:任务和发送完成中断都会调用 `AddMessage()` 入队,发送服务出队。任务在入队或出队做到一半时被中断打断,是无锁队列里最常见的场景;`MPMCQueue` 在这个场景下会返回瞬时的 FULL/EMPTY(假的满/空),`SlotPool` 保证一个被打断的操作只占住它自己的槽,中断拿到的 FULL/EMPTY 反映那一刻的真实状态。 +以 CAN 发送队列为例:任务和中断回调都会调用 `AddMessage()` 入队,发送服务在任务或发送完成中断里出队。任务在入队或出队做到一半时可能被中断打断;`MPMCQueue` 在这种情况下会返回瞬时的 FULL/EMPTY(假的满/空),`SlotPool` 保证一个被打断的操作只占住它自己的槽,中断拿到的 FULL/EMPTY 反映那一刻的真实状态。 ## 核心特性 @@ -62,7 +62,7 @@ void AddMessage(const LibXR::CAN::ClassicPack& pack) { if (tx_pool.Put(pack) != LibXR::ErrorCode::OK) { - // 池满:稍后重试 + // 池满:这一帧没有入队 } } diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/slot_pool.md b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/slot_pool.md index 7cce922..b28c357 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/slot_pool.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/slot_pool.md @@ -8,7 +8,7 @@ sidebar_position: 11 `LibXR::SlotPool` is a small message slot pool shared between tasks and interrupts: each slot carries one atomic state, and fully written slots dequeue in publication order. -Take a CAN TX queue as an example: both the task and the TX-complete interrupt call `AddMessage()` to enqueue, and the TX service dequeues. A task interrupted halfway through an enqueue or a dequeue is the most common scenario for lock-free queues; `MPMCQueue` returns a transient FULL/EMPTY (spurious full/empty) in this scenario, while `SlotPool` guarantees that an interrupted operation only occupies its own slot, so the FULL/EMPTY observed from an interrupt reflects the true state at that moment. +Take a CAN TX queue as an example: tasks and interrupt callbacks call `AddMessage()` to enqueue, and the TX service dequeues in a task or in the TX-complete interrupt. A task may be interrupted halfway through an enqueue or a dequeue; `MPMCQueue` then returns a transient FULL/EMPTY (spurious full/empty), while `SlotPool` guarantees that an interrupted operation only occupies its own slot, so the FULL/EMPTY observed from an interrupt reflects the true state at that moment. ## Core features @@ -62,7 +62,7 @@ void AddMessage(const LibXR::CAN::ClassicPack& pack) { if (tx_pool.Put(pack) != LibXR::ErrorCode::OK) { - // Pool full: retry later + // Pool full: this frame was not enqueued } } From bd7d8aceaf9442ff55e88885cabb060a321dc462 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 10 Oct 2026 22:28:40 +0100 Subject: [PATCH 16/16] SlotPool page: dequeue order follows the publish sequence --- docs/basic_coding/structure/slot_pool.md | 4 ++-- .../current/basic_coding/structure/slot_pool.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/basic_coding/structure/slot_pool.md b/docs/basic_coding/structure/slot_pool.md index 668013d..9662f38 100644 --- a/docs/basic_coding/structure/slot_pool.md +++ b/docs/basic_coding/structure/slot_pool.md @@ -13,7 +13,7 @@ sidebar_position: 11 ## 核心特性 - 每个槽一个原子状态:空闲、写入中、就绪、读取中。所有转换用 CAS 完成,同一时刻一个槽只属于一个执行上下文; -- `Publish()` 时取一个全局递增的发布序号,`Take()` 选序号最小的就绪槽:出队顺序是发布完成的先后,同一发布者内部保序; +- `Publish()` 开始时取一个全局递增的发布序号,`Take()` 在已就绪的槽中选序号最小的:同一发布者内部保序; - `Acquire()`/`Take()` 扫描全部槽位,被其他上下文占着的槽直接跳过,一个还没写完的槽不会挡住其他槽; - 释放计数和发布计数用于扫描后的重扫判断,最多重扫一次;序号用带符号差值比较,允许回绕; - 槽在构造时分配,运行期不再分配;对象不可拷贝、不可移动; @@ -49,7 +49,7 @@ class SlotPool - 任意数量的生产者和消费者都可以,任务和普通中断里都能调用;不要在 NMI 里使用; - 单核上,中断扫描期间低优先级上下文不会改动槽,中断里拿到的 FULL/EMPTY 反映那一刻的真实状态;被打断的操作占着的槽算作占用; -- 出队顺序是发布完成的先后:同一发布者内部保序,不保证跨发布者的全局先进先出; +- 出队顺序按发布序号:同一发布者内部保序;一个还没发布完的槽不会挡住其他就绪槽,因此不保证跨发布者的全局先进先出; - `Publish()` 和 `Release()` 的调用方必须持有对应槽,重复发布或释放其他上下文持有的槽是调用方错误。 ## 使用示例 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/slot_pool.md b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/slot_pool.md index b28c357..376c6b0 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/slot_pool.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/basic_coding/structure/slot_pool.md @@ -13,7 +13,7 @@ Take a CAN TX queue as an example: tasks and interrupt callbacks call `AddMessag ## Core features - Each slot carries one atomic state: free, writing, ready, or reading. Every transition is a CAS, so at any moment a slot belongs to exactly one execution context; -- `Publish()` takes a globally increasing publish sequence, and `Take()` picks the ready slot with the smallest sequence: the dequeue order is publish-completion order, and the order inside one publisher is preserved; +- `Publish()` takes a globally increasing publish sequence when it begins, and `Take()` picks the ready slot with the smallest sequence: the order inside one publisher is preserved; - `Acquire()`/`Take()` scan the whole slot array and skip slots owned by other contexts, so a slot that has not been written yet never blocks the others; - the release counter and the publish counter drive a bounded rescan of at most one extra pass; sequence numbers are compared with signed deltas, so wraparound is allowed; - the slots are allocated at construction and never at run time; the object is neither copyable nor movable; @@ -49,7 +49,7 @@ class SlotPool - any number of producers and consumers may run concurrently; calls are allowed from tasks and normal interrupts, but not from NMI; - on a single core, low-priority contexts cannot change the slots while an interrupt is scanning, so the FULL/EMPTY an interrupt observes reflects the true state at that moment; a slot held by an interrupted operation counts as occupied; -- the dequeue order is publish-completion order: the order inside one publisher is preserved, and no global cross-publisher FIFO is guaranteed; +- the dequeue order follows the publish sequence: the order inside one publisher is preserved; a slot that is not published yet never hides other ready slots, so no global cross-publisher FIFO is guaranteed; - the callers of `Publish()` and `Release()` must own the slot; double publishing or releasing a slot owned by another context is a caller error. ## Example