Skip to content

Commit 5691345

Browse files
Jiu-xiaoJiu-xiao
authored
Merge pull request #7 from xrobot-org/doc/thread-appmain-doc-update
docs: 补充 app_main.cpp 说明，线程用法和 Clang 构建参数已弃用说明
2 parents aa904dc + 28fa7a8 commit 5691345

File tree

7 files changed

+162
-11
lines changed

7 files changed

+162
-11
lines changed

‎docs/adv_coding/uart_driver.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ _以下所有驱动的接口都是一致的，以覆盖平台差异_
7777

7878
1. 检查ID是否合法。
7979
2. uart_handle->Init.Mode分别判断读写是否开启，然后注册读写函数。
80-
3. 为接收开始DMA，配置为环形，开启空闲中断，直接开始接收。
80+
3. 将接收DMA配置为环形，开启空闲中断，直接开始接收。
8181

8282
```cpp
8383
STM32UART::STM32UART(UART_HandleTypeDef *uart_handle, RawData dma_buff_rx,

‎docs/basic_coding/system/thread.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ sidebar_position: 3
3333
3434
## 典型用法
3535

36+
线程函数的参数一定要与 `Create` 函数的 `arg` 参数类型一致，否则无法识别。
37+
3638
```cpp
3739
#include <thread.hpp>
3840

@@ -47,7 +49,7 @@ void Blink(int* arg) {
4749
int main() {
4850
int arg = 0;
4951
LibXR::Thread t;
50-
t.Create((void*)&arg, Blink, "blink", 2048, LibXR::Thread::Priority::MEDIUM);
52+
t.Create(&arg, Blink, "blink", 2048, LibXR::Thread::Priority::MEDIUM);
5153
// 主线程继续执行其它任务 …
5254
for (;;) {
5355
LibXR::Thread::Yield();

‎docs/code_gen/stm32/README.md‎

Lines changed: 74 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,73 @@ Modifying STM32 interrupt files...
6767

6868
---
6969

70+
## app_main.cpp
71+
72+
`app_main.cpp` 文件包含了 LibXR 初始化函数 `app_main()`，可以放心的在User Code Begin xxx 和 User Code End xxx 之间插入自己的代码，重新生成后不会被覆盖。
73+
74+
> 此函数应当永不返回，一旦函数返回所有外设对象（如usart1）将会析构并释放资源，此时访问将会导致崩溃。推荐向线程/任务中传递外设对象的基类指针并操作，在本章的`与XRobot集成中`会有更好的方式实现。
75+
76+
```cpp
77+
#include "app_main.h"
78+
79+
#include "libxr.hpp"
80+
#include "main.h"
81+
#include "stm32_adc.hpp"
82+
#include "stm32_can.hpp"
83+
#include "stm32_dac.hpp"
84+
#include "stm32_gpio.hpp"
85+
#include "stm32_i2c.hpp"
86+
......
87+
88+
using namespace LibXR;
89+
90+
/* User Code Begin 1 */
91+
92+
/* User Code End 1 */
93+
/* External HAL Declarations */
94+
extern ADC_HandleTypeDef hadc1;
95+
extern CAN_HandleTypeDef hcan1;
96+
extern I2C_HandleTypeDef hi2c1;
97+
extern SPI_HandleTypeDef hspi1;
98+
extern TIM_HandleTypeDef htim1;
99+
......
100+
101+
/* DMA Resources */
102+
static uint16_t adc1_buf[64];
103+
static uint8_t spi1_tx_buf[32];
104+
static uint8_t spi1_rx_buf[32];
105+
static uint8_t usart1_tx_buf[128];
106+
static uint8_t usart1_rx_buf[128];
107+
static uint8_t i2c1_buf[32];
108+
......
109+
110+
extern "C" void app_main(void) {
111+
/* User Code Begin 2 */
112+
113+
/* User Code End 2 */
114+
STM32TimerTimebase timebase(&htim2);
115+
PlatformInit(2, 2048);
116+
STM32PowerManager power_manager;
117+
118+
/* GPIO Configuration */
119+
STM32GPIO USER_KEY(USER_KEY_GPIO_Port, USER_KEY_Pin, EXTI0_IRQn);
120+
STM32GPIO LED_B(LED_B_GPIO_Port, LED_B_Pin);
121+
STM32PWM pwm_tim1_ch1(&htim1, TIM_CHANNEL_1, false);
122+
STM32SPI spi1(&hspi1, spi1_rx_buf, spi1_tx_buf, 3);
123+
STM32UART usart1(&huart1,
124+
usart1_rx_buf, usart1_tx_buf, 5);
125+
STM32I2C i2c1(&hi2c1, i2c1_buf, 3);
126+
STM32CAN can1(&hcan1, 5);
127+
/* User Code Begin 3 */
128+
while (1) {
129+
LibXR::Thread::Sleep(1000);
130+
}
131+
/* User Code End 3 */
132+
}
133+
```
134+
135+
---
136+
70137
## 使用说明
71138
72139
在工程入口处调用 `app_main()`：
@@ -89,18 +156,18 @@ int main() {
89156

90157
### FreeRTOS 项目
91158

92-
将 `app_main()` 放入主线程入口（StartDefaultTask）中调用。
159+
将 `app_main()` 放入主线程入口（StartDefaultTask）中调用。注意更改STM32CubeMX中的初始线程大小，避免栈溢出。
93160

94161
---
95162

96163
## 可选参数
97164

98-
| 参数 | 说明 |
99-
| ---------- | --------------------------- |
100-
| `-d` | 指定 STM32 工程根目录 |
101-
| `-t` | 设置终端外设（如 `usart1`） |
102-
| `-c` | 启用 Clang 构建支持 |
103-
| `--xrobot` | 生成 XRobot 模块 glue 代码 |
165+
| 参数 | 说明 |
166+
| ---------- | ----------------------------- |
167+
| `-d` | 指定 STM32 工程根目录 |
168+
| `-t` | 设置终端外设（如 `usart1`） |
169+
| `-c` | 启用 Clang 构建支持（已弃用） |
170+
| `--xrobot` | 生成 XRobot 模块 glue 代码 |
104171

105172
---
106173

‎docs/env_setup/stm32.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,9 @@ sudo ln -s /opt/arm-gun-toolchain-xx.x/bin/* /usr/bin
3939

4040
clang编译器对clangd的支持更好，推荐使用。
4141

42+
2025-7-10：
43+
STM32CubeMX 15.0更新了对clang编译器的原生支持，不再需要下载llvm，直接使用VSCode插件即可。本节会在有能够独立安装的STARM-CLANG工具链后更新。
44+
4245
### Windows
4346

4447
下载[LLVM](https://github.com/llvm/llvm-project/tags)并安装，确保版本大于等于18.1。

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ sidebar_position: 3
3333
3434
## Typical Usage
3535

36+
The parameter type of the thread function must be consistent with the arg parameter type of the Create function; otherwise, it will not be recognized.
37+
3638
```cpp
3739
#include <thread.hpp>
3840

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

Lines changed: 76 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,79 @@ After execution, your project directory will contain the following generated or
6767

6868
---
6969

70+
## app_main.cpp
71+
72+
The `app_main.cpp` file contains the LibXR initialization function `app_main()`.
73+
74+
You can safely insert your own code between the `User Code Begin xxx` and `User Code End xxx` sections; these parts will not be overwritten when the code is regenerated.
75+
76+
> **Note:**
77+
> This function should **never return**. If it does, all peripheral objects (such as `usart1`) will be destructed and resources released, which will cause a crash if you try to access them afterwards.
78+
79+
It is recommended to pass base class pointers of peripheral objects to your threads or tasks and operate on them there.
80+
A better way to implement this will be introduced in the section **"Integrate with XRobot"** later in this chapter.
81+
82+
```cpp
83+
#include "app_main.h"
84+
85+
#include "libxr.hpp"
86+
#include "main.h"
87+
#include "stm32_adc.hpp"
88+
#include "stm32_can.hpp"
89+
#include "stm32_dac.hpp"
90+
#include "stm32_gpio.hpp"
91+
#include "stm32_i2c.hpp"
92+
......
93+
94+
using namespace LibXR;
95+
96+
/* User Code Begin 1 */
97+
98+
/* User Code End 1 */
99+
/* External HAL Declarations */
100+
extern ADC_HandleTypeDef hadc1;
101+
extern CAN_HandleTypeDef hcan1;
102+
extern I2C_HandleTypeDef hi2c1;
103+
extern SPI_HandleTypeDef hspi1;
104+
extern TIM_HandleTypeDef htim1;
105+
......
106+
107+
/* DMA Resources */
108+
static uint16_t adc1_buf[64];
109+
static uint8_t spi1_tx_buf[32];
110+
static uint8_t spi1_rx_buf[32];
111+
static uint8_t usart1_tx_buf[128];
112+
static uint8_t usart1_rx_buf[128];
113+
static uint8_t i2c1_buf[32];
114+
......
115+
116+
extern "C" void app_main(void) {
117+
/* User Code Begin 2 */
118+
119+
/* User Code End 2 */
120+
STM32TimerTimebase timebase(&htim2);
121+
PlatformInit(2, 2048);
122+
STM32PowerManager power_manager;
123+
124+
/* GPIO Configuration */
125+
STM32GPIO USER_KEY(USER_KEY_GPIO_Port, USER_KEY_Pin, EXTI0_IRQn);
126+
STM32GPIO LED_B(LED_B_GPIO_Port, LED_B_Pin);
127+
STM32PWM pwm_tim1_ch1(&htim1, TIM_CHANNEL_1, false);
128+
STM32SPI spi1(&hspi1, spi1_rx_buf, spi1_tx_buf, 3);
129+
STM32UART usart1(&huart1,
130+
usart1_rx_buf, usart1_tx_buf, 5);
131+
STM32I2C i2c1(&hi2c1, i2c1_buf, 3);
132+
STM32CAN can1(&hcan1, 5);
133+
/* User Code Begin 3 */
134+
while (1) {
135+
LibXR::Thread::Sleep(1000);
136+
}
137+
/* User Code End 3 */
138+
}
139+
```
140+
141+
---
142+
70143
## How to Use
71144
72145
<!-- 将 `app_main()` 放入主线程入口（StartDefaultTask）中调用。 -->
@@ -90,7 +163,8 @@ int main() {
90163

91164
### FreeRTOS Project
92165

93-
Place `app_main()` in the entry function of the main thread.
166+
Call `app_main()` in the main thread entry function (such as `StartDefaultTask`).
167+
Make sure to adjust the initial thread stack size in STM32CubeMX to avoid stack overflow.
94168

95169
---
96170

@@ -100,7 +174,7 @@ Place `app_main()` in the entry function of the main thread.
100174
| ---------- | --------------------------------------- |
101175
| `-d` | Specify STM32 project root directory |
102176
| `-t` | Set terminal peripheral (e.g. `usart1`) |
103-
| `-c` | Enable Clang build support |
177+
| `-c` | Enable Clang build support (Deprecated) |
104178
| `--xrobot` | Generate glue code for XRobot modules |
105179

106180
---

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,9 @@ sudo ln -s /opt/arm-gun-toolchain-xx.x/bin/* /usr/bin
4242

4343
clang compiler has better support for clangd, so we recommend using it.
4444

45+
2025-7-10:
46+
STM32CubeMX 15.0 has added native support for the Clang compiler. There is no need to download LLVM separately; you can use it directly through the VSCode plugin. This section will be updated once an independently installable STARM-CLANG toolchain becomes available.
47+
4548
### Windows
4649

4750
Download and install [LLVM](https://github.com/llvm/llvm-project/tags). Make sure the version is 18.1 or above.

0 commit comments

Comments
 (0)