Skip to content

Commit b40010f

Browse files
Jiu-xiaoJiu-xiao
committed
Update.
1 parent f3abf8b commit b40010f

File tree

5 files changed

+271
-0
lines changed

5 files changed

+271
-0
lines changed

‎docs/code_gen/README.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
id: code-gen
3+
title: 代码生成
4+
sidebar_position: 3
5+
---
6+
7+
# 本页将介绍LibXR的代码生成器(CodeGenerator)的使用方法。
8+
9+
CodeGenerator本质上是根据SDK的工程文件生成对应的代码，例如依靠STM32CubeMX的IOC文件，生成相应的C++外设初始化代码。

‎docs/code_gen/stm32/README.md

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
id: code-gen-stm32
3+
title: STM32 代码生成
4+
sidebar_position: 1
5+
---
6+
7+
# STM32 代码生成
8+
9+
LibXR 提供 `xr_cubemx_cfg` 命令用于从 STM32CubeMX 工程中一键生成符合 LibXR 架构的 C++ 初始化代码。该命令集成了配置解析、代码生成、中断补丁、CMake 集成等多个子工具。
10+
11+
---
12+
13+
## 快速使用
14+
15+
在 STM32CubeMX 工程根目录下执行：
16+
17+
```bash
18+
xr_cubemx_cfg -d .
19+
```
20+
21+
该命令将自动完成以下流程：
22+
23+
1. 初始化或更新 `libxr` 子模块；
24+
2. 查找 `.ioc` 文件并解析为 `.config.yaml`；
25+
3. 生成 `app_main.cpp` 初始化代码；
26+
4. 补丁中断处理函数；
27+
5. 修改 `CMakeLists.txt`，集成 LibXR 构建配置。
28+
29+
---
30+
31+
## 示例输出
32+
33+
```text
34+
[INFO] LibXR submodule already exists. Checking for updates...
35+
[INFO] [OK] cd . && git submodule update --init --recursive
36+
[INFO] LibXR submodule updated.
37+
Found .ioc file: .\atom.ioc
38+
Parsing .ioc file...
39+
[INFO] [OK] xr_parse_ioc -d . -o .\.config.yaml
40+
Generating C++ code...
41+
[INFO] [OK] xr_gen_code_stm32 -i .\.config.yaml -o .\User\app_main.cpp
42+
Modifying STM32 interrupt files...
43+
[INFO] [OK] xr_stm32_it .\Core/Src
44+
[INFO] [OK] xr_stm32_cmake .
45+
[INFO] [Pass] All tasks completed successfully!
46+
```
47+
48+
---
49+
50+
## 输出结构
51+
52+
执行完成后，项目将包含以下新增或修改文件：
53+
54+
```txt
55+
.
56+
├── .config.yaml # 解析生成的配置文件
57+
├── User/
58+
│ │── app_main.cpp # 主入口初始化代码
59+
│ │── app_main.h # 主入口初始化代码的头文件
60+
│ │── libxr_config.yaml # LibXR 配置文件
61+
│ └── flash_map.hpp # FLASH 地址映射表
62+
├── Core/Src/stm32f1xx_it.c # 补丁后的中断处理函数
63+
├── cmake/LibXR.CMake # LibXR 构建配置
64+
├── CMakeLists.txt # 自动集成 LibXR
65+
└── Middlewares\Third_Party\LibXR # Git 子模块：LibXR 本体
66+
```
67+
68+
---
69+
70+
## 使用说明
71+
72+
在工程入口处调用 `app_main()`：
73+
74+
### 裸机项目
75+
76+
```cpp
77+
#include "app_main.h"
78+
79+
int main() {
80+
HAL_Init();
81+
SystemClock_Config();
82+
...
83+
app_main(); // 初始化外设并启动应用层
84+
while (1){
85+
...
86+
}
87+
}
88+
```
89+
90+
### FreeRTOS 项目
91+
92+
将 `app_main()` 放入主线程入口函数中调用。
93+
94+
---
95+
96+
## 可选参数
97+
98+
| 参数 | 说明 |
99+
| ---------- | --------------------------- |
100+
| `-d` | 指定 STM32 工程根目录 |
101+
| `-t` | 设置终端外设（如 `usart1`） |
102+
| `-c` | 启用 Clang 构建支持 |
103+
| `--xrobot` | 生成 XRobot 模块 glue 代码 |
104+
105+
---
106+
107+
## 项目要求
108+
109+
- 必须为 STM32CubeMX 导出的 CMake 工程；
110+
- 必须存在 `.ioc` 文件；
111+
112+
---
113+
114+
## 相关命令（由 `xr_cubemx_cfg` 内部调用，可单独执行）
115+
116+
| 工具名 | 功能说明 |
117+
| ------------------- | ------------------------------------ |
118+
| `xr_parse_ioc` | 解析 `.ioc`，生成 `.config.yaml` |
119+
| `xr_gen_code_stm32` | 根据 YAML 配置生成 `app_main.cpp` |
120+
| `xr_stm32_it` | 补丁中断文件，插入 UART/USB 回调支持 |
121+
| `xr_stm32_cmake` | 修改 CMake 构建文件，集成 LibXR |
122+
123+
## 参考
124+
125+
[LibXR 命令行工具以及文档](https://pypi.org/project/libxr/)

‎i18n/en/docusaurus-plugin-content-docs/current/code_gen/README.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
id: code-gen
3+
title: Code Generation
4+
sidebar_position: 3
5+
---
6+
7+
# This page introduces how to use the `CodeGenerator` in LibXR.
8+
9+
The `CodeGenerator` essentially generates corresponding source code based on the SDK's project files. For example, it can use an STM32CubeMX IOC file to generate the relevant C++ peripheral initialization code.

‎i18n/en/docusaurus-plugin-content-docs/current/code_gen/stm32/README.md

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
id: code-gen-stm32
3+
title: STM32 Code Generation
4+
sidebar_position: 1
5+
---
6+
7+
# STM32 Code Generation
8+
9+
LibXR provides the `xr_cubemx_cfg` command to automatically generate C++ initialization code from an STM32CubeMX project. This command wraps several tools including configuration parsing, code generation, interrupt patching, and CMake integration.
10+
11+
---
12+
13+
## Quick Start
14+
15+
In the root directory of your STM32CubeMX project, run:
16+
17+
```bash
18+
xr_cubemx_cfg -d .
19+
```
20+
21+
This command will perform the following steps automatically:
22+
23+
1. Initialize or update the `libxr` submodule
24+
2. Locate the `.ioc` file and convert it into `.config.yaml`
25+
3. Generate `app_main.cpp` with initialization code
26+
4. Patch interrupt handler files
27+
5. Modify `CMakeLists.txt` to integrate LibXR
28+
29+
---
30+
31+
## Example Output
32+
33+
```text
34+
[INFO] LibXR submodule already exists. Checking for updates...
35+
[INFO] [OK] cd . && git submodule update --init --recursive
36+
[INFO] LibXR submodule updated.
37+
Found .ioc file: .\atom.ioc
38+
Parsing .ioc file...
39+
[INFO] [OK] xr_parse_ioc -d . -o .\.config.yaml
40+
Generating C++ code...
41+
[INFO] [OK] xr_gen_code_stm32 -i .\.config.yaml -o .\User\app_main.cpp
42+
Modifying STM32 interrupt files...
43+
[INFO] [OK] xr_stm32_it .\Core/Src
44+
[INFO] [OK] xr_stm32_cmake .
45+
[INFO] [Pass] All tasks completed successfully!
46+
```
47+
48+
---
49+
50+
## Output Structure
51+
52+
After execution, your project directory will contain the following generated or modified files:
53+
54+
```txt
55+
.
56+
├── .config.yaml # Parsed configuration from .ioc
57+
├── User/
58+
│ ├── app_main.cpp # Main initialization code
59+
│ ├── app_main.h # Header for app_main
60+
│ ├── libxr_config.yaml # LibXR runtime configuration
61+
│ └── flash_map.hpp # Flash address mapping table
62+
├── Core/Src/stm32f1xx_it.c # Patched interrupt handlers
63+
├── cmake/LibXR.CMake # CMake build config for LibXR
64+
├── CMakeLists.txt # Modified to include LibXR
65+
└── Middlewares/Third_Party/LibXR # LibXR as a Git submodule
66+
```
67+
68+
---
69+
70+
## How to Use
71+
72+
Call `app_main()` at the appropriate entry point in your project:
73+
74+
### Bare-metal Project
75+
76+
```cpp
77+
#include "app_main.h"
78+
79+
int main() {
80+
HAL_Init();
81+
SystemClock_Config();
82+
...
83+
app_main(); // Initialize peripherals and start application
84+
while (1) {
85+
...
86+
}
87+
}
88+
```
89+
90+
### FreeRTOS Project
91+
92+
Place `app_main()` in the entry function of the main thread.
93+
94+
---
95+
96+
## Optional Arguments
97+
98+
| Argument | Description |
99+
| ---------- | --------------------------------------- |
100+
| `-d` | Specify STM32 project root directory |
101+
| `-t` | Set terminal peripheral (e.g. `usart1`) |
102+
| `-c` | Enable Clang build support |
103+
| `--xrobot` | Generate glue code for XRobot modules |
104+
105+
---
106+
107+
## Project Requirements
108+
109+
- Must be a CMake project exported from STM32CubeMX
110+
- Must contain a valid `.ioc` file
111+
112+
---
113+
114+
## Subcommands (Internally used by `xr_cubemx_cfg`, can also be run separately)
115+
116+
| Tool | Description |
117+
| ------------------- | ------------------------------------------------ |
118+
| `xr_parse_ioc` | Parses `.ioc` and generates `.config.yaml` |
119+
| `xr_gen_code_stm32` | Generates `app_main.cpp` from the YAML config |
120+
| `xr_stm32_it` | Patches interrupt handlers with UART/USB support |
121+
| `xr_stm32_cmake` | Integrates LibXR into the project build system |
122+
123+
---
124+
125+
## References
126+
127+
[LibXR CLI tool and documentation (PyPI)](https://pypi.org/project/libxr/)

‎i18n/en/docusaurus-plugin-content-docs/current/intro.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
id: intro
33
title: Welcome
4+
sidebar_position: 1
45
---
56

67
This documentation provides a modular introduction to the environment setup, basic usage, and advanced features of LibXR, CodeGenerator, and XRobot. If you have any questions, feel free to submit an issue in the corresponding repository or send email.

0 commit comments

Comments
 (0)