FreeRTOS常用API函数详细说明使用(FreeRTOS从入门到放弃）

只会HelloWorld.

已于 2023-09-25 21:42:18 修改

阅读量1.1k

点赞数 5

文章标签： stm32 单片机

于 2023-09-25 21:20:12 首次发布

本文链接：https://blog.csdn.net/m0_63211938/article/details/133280685

版权

文章目录

1. 任务的创建与删除
2. 任务调度
3. 队列
4. 二值信号量
5. 计数型信号量
6. 互斥量
7. 事件标志位
8. 任务通知(可以用来模拟)
9. 延迟函数
- 9.1 vTaskDelay与HAL_Delay的区别
10. 软件定时器
11. 中断管理
12. STM32小车+FreeRTOS

1. 任务的创建与删除

任务创建与删除相关函数：

函数名称	函数作用
xTaskCreate()	动态方式创建任务
xTaskCreateStatic()	静态方式创建任务
vTaskDelete()	删除任务

要注意的是

1.FreeRTOS中创建任务的函数是xTaskCreate() 和 xTaskCreateStatic()，但在 CubeMX 中被封装为osThreadCreate()

2.FreeRTOS中删除任务的函数是vTaskDelete()，但在 CubeMX 中被封装为osThreadTerminate()

xTaskCreate函数原型

BaseType_t xTaskCreate
(
    TaskFunction_t                  pxTaskCode,     //指向任务函数的指针
    const char* const               pcName,         //任务名字，最大长度为configMAX_TASK_NAME_LEN,可以自己定义
    const configSTACK_DEPTH_TYPE    usStackDepth,   //任务堆栈大小，以字为单位
    void* const                     pvParameters,   //传递给任务函数的参数
    UBaseType_t                     uxPriority,     //任务优先级，0~configMAX_PRIORITIES-1
    TaskHandle_t* const             pxCreatedTask   //任务句柄，就是任务控制模块
)

1.pvTaskCode：指向任务函数的指针，任务必须实现为永不返回（即连续循环）；
2.pcName：任务的名字，主要是用来调试，默认情况下最大长度是16；
3.pvParameters：指定的任务栈的大小；
4.uxPriority：任务优先级，数值越大，优先级越大；
5.pxCreatedTask：用于返回已创建任务的句柄可以被引用。

返回值	描述
pdPASS	任务创建成功
errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY	任务创建失败

2. 任务调度

FreeRTOS中任务共存在4种状态：

1.Runnin运行：当任务处于实际运行状态称之为运行态，即CPU的使用权被这个任务占用（同一时间仅一个任务处于运行态）。

2.Ready就绪态：处于就绪态的任务是指那些能够运行（没有被阻塞和挂起），但是当前没有运行的任务，因为同优先级或更高优先级的任务正在运行。

3.Blocked阻塞态：如果一个任务因延时，或等待信号量、消息队列、事件标志组等而处于的状态被称之为阻塞态。

4.Suspended挂起态：类似暂停，通过调用函数 vTaskSuspend() 对指定任务进行挂起，挂起后这个任务将不被执行，只有调用函数 xTaskResume() 才可以将这个任务从挂起态恢复。

任务调度函数

vTaskStartScheduler()           //开启任务调度
//FreeRTOS中开启任务调度的函数是 vTaskStartScheduler() ，但在 CubeMX 中被封装为osKernelStart() 。
osThreadSuspend();              //暂停任务
osThreadResume(taskLED2Handle)  //恢复任务

3. 队列

特点：先进先出

创建队列

QueueHandle_t xQueueCreate
(
UBaseType_t       uxQueueLength,
UBaseType_t         uxItemSize 
);

1.uxQueueLength：队列可同时容纳的最大项目数。

2.uxItemSize：存储队列中的每个数据项所需的大小（以字节为单位）。

返回值：如果队列创建成功，则返回所创建队列的句柄。如果创建队列所需的内存无法分配，

则返回 NULL。

写队列

函数	描述
xQueueSend()	往队列的尾部写入消息
xQueueSendToBack()	同 xQueueSend()
xQueueSendToFront()	往队列的头部写入消息
xQueueOverwrite()	覆写队列消息（只用于队列长度为 1 的情况）
xQueueSendFromISR()	在中断中往队列的尾部写入消息
xQueueSendToBackFromISR()	同 xQueueSendFromISR()
xQueueSendToFrontFromISR()	在中断中往队列的头部写入消息
xQueueOverwriteFromISR()	在中断中覆写队列消息（只用于队列长度为 1 的情况）

BaseType_t xQueueSend
 (
QueueHandle_t       xQueue,
const void *        pvItemToQueue,
TickType_t          xTicksToWait
);

1.xQueue：队列的句柄，数据项将发送到此队列
pvItemToQueue：待写入数据
xTicksToWait：阻塞超时时间
返回值：如果成功写入数据，返回 pdTRUE，否则返回 errQUEUE_FULL。

读队列

函数	描述
xQueueReceive()	从队列头部读取消息，并删除消息
xQueuePeek()	从队列头部读取消息，但是不删除消息
xQueueReceiveFromISR()	在中断中从队列头部读取消息，并删除消息
xQueuePeekFromISR()	在中断中从队列头部读取消息

BaseType_t xQueueReceive(
QueueHandle_t      xQueue,
void*             pvBuffer,
TickType_t        xTicksToWait
);

1.xQueue：待读取的队列
2.pvItemToQueue：数据读取缓冲区
3.xTicksToWait：阻塞超时时间
返回值：成功返回 pdTRUE，否则返回 pdFALSE

4. 二值信号量

二值信号量其实就是一个长度为1，大小为零的队列，只有0和1两种状态，通常情况下，我们用

它来进行互斥访问或任务同步。

二值信号量相关函数

函数	描述
xSemaphoreCreateBinary()	使用动态方式创建二值信号量
xSemaphoreCreateBinaryStatic()	使用静态方式创建二值信号量
xSemaphoreGive()	释放信号量
xSemaphoreGiveFromISR()	在中断中释放信号量
xSemaphoreTake()	获取信号量
xSemaphoreTakeFromISR()	在中断中获取信号量

1.创建二值信号量

SemaphoreHandle_t xSemaphoreCreateBinary( void )

返回值：成功，返回对应二值信号量的句柄，失败，返回 NULL 。
2.释放二值信号量

BaseType_t xSemaphoreGive( SemaphoreHandle_t xSemaphore )

xSemaphore：要释放的信号量句柄
返回值：成功，返回 pdPASS ，失败，返回 errQUEUE_FULL 。

3.获取二值信号量

BaseType_t xSemaphoreTake( SemaphoreHandle_t xSemaphore,
                           TickType_t   xTicksToWait 
);

xSemaphore：要获取的信号量句柄
xTicksToWait：超时时间，0 表示不超时，portMAX_DELAY表示卡死等待；
返回值：成功，返回 pdPASS ，失败，返回 errQUEUE_FULL 。

5. 计数型信号量

计数型信号量相当于队列长度大于1 的队列，因此计数型信号量能够容纳多个资源，这在计数型

信号量被创建的时候确定的。

计数型信号量相关函数

函数	描述
xSemaphoreCreateCounting()	使用动态方法创建计数型信号量。
xSemaphoreCreateCountingStatic()	使用静态方法创建计数型信号量
uxSemaphoreGetCount()	获取信号量的计数值

计数型信号量的释放和获取与二值信号量完全相同！

SemaphoreHandle_t xSemaphoreCreateCounting( UBaseType_t uxMaxCount,
                                            UBaseType_t uxInitialCount);

uxMaxCount：可以达到的最大计数值 uxInitialCount：创建信号量时分配给信号量的计数值
返回值：成功，返回对应计数型信号量的句柄；失败，返回 NULL 。

6. 互斥量

在多数情况下，互斥型信号量和二值型信号量非常相似，但是从功能上二值型信号量用于同步，

而互斥型信号量用于资源保护。

互斥型信号量和二值型信号量还有一个最大的区别，互斥型信号量可以有效解决优先级反转现

象。

互斥量相关函数

互斥信号量不能用于中断服务函数中！

函数	描述
xSemaphoreCreateMutex()	使用动态方法创建互斥信号量。
xSemaphoreCreateMutexStatic()	使用静态方法创建互斥信号量。

SemaphoreHandle_t xSemaphoreCreateMutex( void )

7. 事件标志位

事件标志组本质是一个 16 位或 32 位无符号的数据类型 EventBits_t ，由 configUSE_16_BIT_TICKS

决定。

虽然使用了 32 位无符号的数据类型变量来存储事件标志，但其中的高8位用作存储事件标志组的

控制信息，低 24 位用作存储事件标志，所以说一个事件组最多可以存储 24 个事件标志！

事件标志组相关API函数

函数	描述
xEventGroupCreate()	使用动态方式创建事件标志组
xEventGroupCreateStatic()	使用静态方式创建事件标志组
xEventGroupClearBits()	清零事件标志位
xEventGroupClearBitsFromISR()	在中断中清零事件标志位
xEventGroupSetBits()	设置事件标志位
xEventGroupSetBitsFromISR()	在中断中设置事件标志位
xEventGroupWaitBits()	等待事件标志位

1.创建事件标志组

EventGroupHandle_t xEventGroupCreate( void );

返回值：成功，返回对应事件标志组的句柄；失败，返回 NULL 。

2.设置事件标志位

EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup,
                                const EventBits_t uxBitsToSet );

xEventGroup：对应事件组句柄
uxBitsToSet：指定要在事件组中设置的一个或多个位的按位值。
返回值：设置之后事件组中的事件标志位值。

1. 清除事件标志位

EventBits_t xEventGroupClearBits(EventGroupHandle_t xEventGroup,
                                 const EventBits_t uxBitsToClear );

xEventGroup：对应事件组句柄
uxBitsToClear：指定要在事件组中清除的一个或多个位的按位值
返回值：清零之前事件组中事件标志位的值。

4.等待事件标志位

EventBits_t xEventGroupWaitBits(
                       const EventGroupHandle_t xEventGroup,
                       const EventBits_t uxBitsToWaitFor,
                       const BaseType_t xClearOnExit,
                       const BaseType_t xWaitForAllBits,
                       TickType_t xTicksToWait );

xEventGroup：对应的事件标志组句柄

uxBitsToWaitFor：指定事件组中要等待的一个或多个事件位的按位值

xClearOnExit：pdTRUE——清除对应事件位，pdFALSE——不清除

xWaitForAllBits：pdTRUE——所有等待事件位全为1（逻辑与），pdFALSE——等待的事件位有一个为1（逻辑或）

xTicksToWait：超时

返回值：等待的事件标志位值：等待事件标志位成功，返回等待到的事件标志位其他值：等待事件标志位

失败，返回事件组中的事件标志位

8. 任务通知(可以用来模拟)

8.1 任务通知介绍

FreeRTOS 从版本 V8.2.0 开始提供任务通知这个功能，每个任务都有一个 32 位的通知值。按照

FreeRTOS 官方的说法，使用消息通知比通过二进制信号量方式解除阻塞任务快 45%，并且更加

省内存（无需创建队列）。

在大多数情况下，任务通知可以替代二值信号量、计数信号量、事件标志组，可以替代长度为 1

的队列（可以保存一个 32 位整数或指针值），并且任务通知速度更快、使用的RAM更少！

FreeRTOS 提供以下几种方式发送通知给任务：

1.发送消息给任务，如果有通知未读，不覆盖通知值

2.发送消息给任务，直接覆盖通知值

3.发送消息给任务，设置通知值的一个或者多个位

4.发送消息给任务，递增通知值

通过对以上方式的合理使用，可以在一定场合下替代原本的队列、信号量、事件标志组等。

任务通知的优势

使用任务通知向任务发送事件或数据，比使用队列、事件标志组或信号量快得多
使用其他方法时都要先创建对应的结构体，使用任务通知时无需额外创建结构体

任务通知的劣势

只有任务可以等待通知，中断服务函数中不可以，因为中断没有 TCB

通知只能一对一，因为通知必须指定任务

等待通知的任务可以被阻塞，但是发送消息的任务，任何情况下都不会被阻塞等待。

任务通知是通过更新任务通知值来发送数据的，任务结构体中只有一个任务通知值，只能保

持一个数据

8.2 任务通知相关API函数

1.发送通知

函数	描述
xTaskNotify()	发送通知，带有通知值
xTaskNotifyAndQuery()	发送通知，带有通知值并且保留接收任务的原通知值
xTaskNotifyGive()	发送通知，不带通知值
xTaskNotifyFromISR()	在中断中发送任务通知
xTaskNotifyAndQueryFromISR()	在中断中发送任务通知
vTaskNotifyGiveFromISR()	在中断中发送任务通知

1.发送通知，带有通知值

BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify,
                        uint32_t ulValue,
                        eNotifyAction eAction );

xTaskToNotify：需要接收通知的任务句柄；
ulValue：用于更新接收任务通知值，具体如何更新由形参 eAction 决定；
eAction：一个枚举，代表如何使用任务通知的值

枚举值	描述
eNoAction	发送通知，但不更新值（参数ulValue未使用）
eSetBits	被通知任务的通知值按位或ulValue。（某些场景下可代替事件组，效率更高）
eIncrement	被通知任务的通知值增加1（参数ulValue未使用），相当于xTaskNotifyGive
eSetValueWithOverWrite	被通知任务的通知值设置为 ulValue。（某些场景下可代替xQueueOverwrite ，效率更高）
eSetValueWithoutOverwrite	如果被通知的任务当前没有通知，则被通知的任务的通知值设为ulValue。如果被通知任务没有取走上一个通知，又接收到了一个通知，则这次通知值丢弃，在这种情况下视为调用失败并返回pdFALSE（某些场景下可代替 xQueueSend ，效率更高）

返回值：如果被通知任务还没取走上一个通知，又接收了一个通知，则这次通知值未能更新并返回pdFALSE，而其他情况均返回pdPASS。
2.发送通知，带有通知值并且保留接收任务的原通知值

BaseType_t xTaskNotifyAndQuery( TaskHandle_t xTaskToNotify,
                                uint32_t ulValue,
                                eNotifyAction eAction,
                                uint32_t *pulPreviousNotifyValue )

xTaskToNotify：需要接收通知的任务句柄；

ulValue：用于更新接收任务通知值，具体如何更新由形参 eAction 决定；

eAction：一个枚举，代表如何使用任务通知的值；

pulPreviousNotifyValue：对象任务的上一个任务通知值，如果为 NULL，则不需要回传，这个时

候就等价于函数 xTaskNotify()。

返回值：如果被通知任务还没取走上一个通知，又接收了一个通知，则这次通知值未能更新并返回pdFALSE，而其他情况均返回pdPASS。

3.发送通知，不带通知值

BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify );

xTaskToNotify：接收通知的任务句柄，并让其自身的任务通知值加 1。

返回值：总是返回 pdPASS

4.等待通知

等待通知API函数只能用在任务，不可应用于中断中！

枚举值	描述
ulTaskNotifyTake()	获取任务通知，可以设置在退出此函数的时候将任务通知值清零或者减一。当任务通知用作二值信号量或者计数信号量的时候，使用此函数来获取信号量。
xTaskNotifyWait()	获取任务通知，比 ulTaskNotifyTak()更为复杂，可获取通知值和清除通知值的指定位

ulTaskNotifyTake()

uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit,
                           TickType_t xTicksToWait );

xClearCountOnExit：指定在成功接收通知后，将通知值清零或减 1
pdTRUE：把通知值清零（二值信号量）
pdFALSE：把通知值减一（计数型信号量）；
xTicksToWait：阻塞等待任务通知值的最大时间；
返回值：0：接收失败非0：接收成功，返回任务通知的通知值

xTaskNotifyWait()

BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry,
                            uint32_t ulBitsToClearOnExit,
                            uint32_t *pulNotificationValue,
                            TickType_t xTicksToWait );

ulBitsToClearOnEntry：函数执行前清零任务通知值那些位。

ulBitsToClearOnExit：表示在函数退出前，清零任务通知值那些位，在清 0 前，接收到的任务通知值会先被保存到形*pulNotificationValue 中。

pulNotificationValue：用于保存接收到的任务通知值。如果不需要使用，则设置为 NULL 即可。

xTicksToWait：等待消息通知的最大等待时间。

8.1.1 模拟(可以自己去写)

模拟二值信号量
模拟计数型信号量
模拟事件标志组
模拟邮箱

9. 延迟函数

相对延时(用到比较多)：vTaskDelay()：
绝对延时：vTaskDelayUntil()
CubeMAX延迟函数： HAL_Delay()

9.1 vTaskDelay与HAL_Delay的区别

1.vTaskDelay 作用是让任务阻塞，任务阻塞后，RTOS系统调用其它处于就绪状态的优先级最高的任务来执行。

2.HAL_Delay 一直不停的调用获取系统时间的函数，直到指定的时间流逝然后退出，故其占用了全部CPU时间。

10. 软件定时器

单次定时器：只超时一次，调用一次回调函数。可手动再开启定时器
周期定时器：多次超时，多次调用回调函数。
软件定时器相关函数:

函数	描述
xTimerCreate()	动态方式创建软件定时器
xTimerCreateStatic()	静态方式创建软件定时器
xTimerStart()	开启软件定时器定时
xTimerStop()	停止软件定时器定时
xTimerReset()	复位软件定时器定时
xTimerChangePeriod()	更改软件定时器的定时超时时间
xTimerStartFromISR()	在中断中开启软件定时器定时
xTimerStopFromISR()	在中断中停止软件定时器定时
xTimerResetFromISR()	在中断中复位软件定时器定时
xTimerChangePeriodFromISR()	在中断中更改定时超时时间

1.创建定时器

TimerHandle_t xTimerCreate(const char * const pcTimerName,
                           const TickType_t xTimerPeriod,
                           const UBaseType_t uxAutoReload,
                           void * const pvTimerID,
                           TimerCallbackFunction_t pxCallbackFunction );

pcTimerName：软件定时器名称

xTimerPeriodInTicks：定时超时时间，单位：系统时钟节拍。宏pdMS_TO_TICKS() 可用于将以毫秒为单位指定的时间转换为以 tick 为单位指定的时间。

uxAutoReload：定时器模式， pdTRUE：周期定时器， pdFALSE：单次定时器 pvTimerID：软件定时器 ID，用于多个软件定时器公用一个超时回调函数

pxCallbackFunction：软件定时器超时回调函数

返回值：成功：定时器句柄，失败：NULL

2.开启定时器

BaseType_t xTimerStart( TimerHandle_t xTimer,
                        TickType_t xBlockTime );

xTimer：待开启的软件定时器的句柄
xTickToWait：发送命令到软件定时器命令队列的最大等待时间
返回值：pdPASS：开启成功 pdFAIL：开启失败

3.停止软件定时器

BaseType_t xTimerStop( TimerHandle_t xTimer,
                       TickType_t xBlockTime );

xTimer：待开启的软件定时器的句柄
xTickToWait：发送命令到软件定时器命令队列的最大等待时间
返回值：pdPASS：开启成功 pdFAIL：开启失败

4.复位定时器

BaseType_t xTimerReset( TimerHandle_t xTimer,
                        TickType_t xBlockTime );

xTimer：待开启的软件定时器的句柄
xTickToWait：发送命令到软件定时器命令队列的最大等待时间
返回值：pdPASS：开启成功 pdFAIL：开启失败
该功能将使软件定时器的重新开启定时，复位后的软件定时器以复位时的时刻作为开启时刻重新定时。

更改定时器定时时间

BaseType_t xTimerChangePeriod( TimerHandle_t xTimer,
                               TickType_t xNewPeriod,
                               TickType_t xBlockTime );

xNewPeriod：新的定时超时时间，单位：系统时钟节拍
xTimer：待开启的软件定时器的句柄
xTickToWait：发送命令到软件定时器命令队列的最大等待时间
返回值：pdPASS：开启成功 pdFAIL：开启失败

11. 中断管理

1. 任何中断的优先级都大于任务！
1. 在中断中必需使用中断相关的函数；
1. 中断服务函数运行时间越短越好。

上面的内容都有相关中断函数的解析和说明

12. STM32小车+FreeRTOS

待更新

只会HelloWorld.

关注

5
点赞
踩
29

收藏

觉得还不错? 一键收藏
1
评论
FreeRTOS常用API函数详细说明使用(FreeRTOS从入门到放弃）

1. 任务的创建与删除2. 任务调度3. 队列4. 二值信号量5. 计数型信号量6. 互斥量7. 事件标志位8. 任务通知(可以用来模拟)9. 延迟函数10. 软件定时器11. 中断管理12. STM32小车+FreeRTOS
复制链接

扫一扫