FreeRTOS函数功能大全

BaseType_t xTaskCreate( TaskFunction_t pxTaskCode, // 函数指针, 任务函数
                        const char * const pcName, // 任务的名字
                        const configSTACK_DEPTH_TYPE usStackDepth, // 栈大小,单位为word,10表示40字节
                        void * const pvParameters, // 调用任务函数时传入的参数
                        UBaseType_t uxPriority,    // 优先级
                        TaskHandle_t * const pxCreatedTask ); // 任务句柄, 以后使用它来操作这个任务

参数说明：

参数	描述
pvTaskCode	函数指针，可以简单地认为任务就是一个C函数。它稍微特殊一点：永远不退出，或者退出时要调用"vTaskDelete(NULL)"
pcName	任务的名字，FreeRTOS内部不使用它，仅仅起调试作用。长度为：configMAX_TASK_NAME_LEN
usStackDepth	每个任务都有自己的栈，这里指定栈大小。单位是word，比如传入100，表示栈大小为100 word，也就是400字节。最大值为uint16_t的最大值。怎么确定栈的大小，并不容易，很多时候是估计。精确的办法是看反汇编码。
pvParameters	调用pvTaskCode函数指针时用到：pvTaskCode(pvParameters)
uxPriority	优先级范围：0~(configMAX_PRIORITIES – 1) 数值越小优先级越低，如果传入过大的值，xTaskCreate会把它调整为(configMAX_PRIORITIES – 1)
pxCreatedTask	用来保存xTaskCreate的输出结果：task handle。以后如果想操作这个任务，比如修改它的优先级，就需要这个handle。如果不想使用该handle，可以传入NULL。
返回值	成功：pdPASS；失败：errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY(失败原因只有内存不足) 注意：文档里都说失败时返回值是pdFAIL，这不对。 pdFAIL是0，errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY是-1。

1.2 删除任务vTaskDelete

void vTaskDelete( TaskHandle_t xTaskToDelete );

参数说明：

参数	描述
pvTaskCode	任务句柄，使用xTaskCreate创建任务时可以得到一个句柄。也可传入NULL，这表示删除自己。

怎么删除任务？举个不好的例子：

自杀：vTaskDelete(NULL)
被杀：别的任务执行vTaskDelete(pvTaskCode)，pvTaskCode是自己的句柄
杀人：执行vTaskDelete(pvTaskCode)，pvTaskCode是别的任务的句柄

1.3 暂停任务vTaskSuspend

FreeRTOS中的任务也可以进入暂停状态，唯一的方法是通过vTaskSuspend函数。函数原型如下：

void vTaskSuspend( TaskHandle_t xTaskToSuspend );

参数xTaskToSuspend表示要暂停的任务，如果为NULL，表示暂停自己。

1.4 优先级相关函数

1.4.1 获得任务的优先级uxTaskPriorityGet

UBaseType_t uxTaskPriorityGet( const TaskHandle_t xTask );

使用参数xTask来指定任务，设置为NULL表示获取自己的优先级。

1.4.2 设置任务的优先级vTaskPrioritySet

void vTaskPrioritySet( TaskHandle_t xTask,
                       UBaseType_t uxNewPriority );

使用参数xTask来指定任务，设置为NULL表示设置自己的优先级；参数uxNewPriority表示新的优先级，取值范围是0~(configMAX_PRIORITIES – 1)。

1.5 启动任务调度器vTaskStartScheduler

1.6 空闲任务钩子函数vApplicationIdleHook

空闲任务(Idle任务)的作用：释放被删除的任务的内存。

除了上述目的之外，为什么必须要有空闲任务？一个良好的程序，它的任务都是事件驱动的：平时大部分时间处于阻塞状态。有可能我们自己创建的所有任务都无法执行，但是调度器必须能找到一个可以运行的任务：所以，我们要提供空闲任务。在使用vTaskStartScheduler() 函数来创建、启动调度器时，这个函数内部会创建空闲任务：

空闲任务优先级为0：它不能阻碍用户任务运行
空闲任务要么处于就绪态，要么处于运行态，永远不会阻塞

空闲任务的优先级为0，这意味着一旦某个用户的任务变为就绪态，那么空闲任务马上被切换出去，让这个用户任务运行。在这种情况下，我们说用户任务"抢占"(pre-empt)了空闲任务，这是由调度器实现的。

要注意的是：如果使用vTaskDelete() 来删除任务，那么你就要确保空闲任务有机会执行，否则就无法释放被删除任务的内存。

我们可以添加一个空闲任务的钩子函数(Idle Task Hook Functions)，空闲任务的循环每执行一次，就会调用一次钩子函数。钩子函数的作用有这些：

执行一些低优先级的、后台的、需要连续执行的函数
测量系统的空闲时间：空闲任务能被执行就意味着所有的高优先级任务都停止了，所以测量空闲任务占据的时间，就可以算出处理器占用率。
让系统进入省电模式：空闲任务能被执行就意味着没有重要的事情要做，当然可以进入省电模式了。

空闲任务的钩子函数的限制：

不能导致空闲任务进入阻塞状态、暂停状态
如果你会使用vTaskDelete() 来删除任务，那么钩子函数要非常高效地执行。如果空闲任务移植卡在钩子函数里的话，它就无法释放内存。

使用钩子函数的前提

在FreeRTOS\Source\tasks.c中，可以看到如下代码，所以前提就是：

把这个宏定义为1：configUSE_IDLE_HOOK
实现vApplicationIdleHook函数

2. Tick相关函数

2.1 延时函数vTaskDelay

至少等待指定个数的Tick Interrupt才能变为就绪状态

vTaskDelay(2);  // 等待2个Tick，假设configTICK_RATE_HZ=100, Tick周期时10ms, 等待20ms

// 还可以使用pdMS_TO_TICKS宏把ms转换为tick
vTaskDelay(pdMS_TO_TICKS(100));	 // 等待100ms

注意，基于Tick实现的延时并不精确，比如vTaskDelay(2)的本意是延迟2个Tick周期，有可能经过1个Tick多一点就返回了。

使用vTaskDelay函数时，建议以ms为单位，使用pdMS_TO_TICKS把时间转换为Tick。

这样的代码就与configTICK_RATE_HZ无关，即使配置项configTICK_RATE_HZ改变了，我们也不用去修改代码。

2.2 绝对延时函数vTaskDelayUntil

等待到指定的绝对时刻，才能变为就绪态。

BaseType_t xTaskDelayUntil( TickType_t * const pxPreviousWakeTime,
                            const TickType_t xTimeIncrement );

下面画图说明：

使用vTaskDelay(n)时，进入、退出vTaskDelay的时间间隔至少是n个Tick中断
使用xTaskDelayUntil(&Pre, n)时，前后两次退出xTaskDelayUntil的时间至少是n个Tick中断
- 退出xTaskDelayUntil时任务就进入的就绪状态，一般都能得到执行机会
- 所以可以使用xTaskDelayUntil来让任务周期性地运行

示例：

void vTask1( void *pvParameters )
{
	const TickType_t xDelay50ms = pdMS_TO_TICKS( 50UL );
	TickType_t xLastWakeTime;
	int i;
	
	/* 获得当前的Tick Count */
	xLastWakeTime = xTaskGetTickCount();
			
	for( ;; )
	{
		flag = 1;
		
		/* 故意加入多个循环，让程序运行时间长一点 */
		for (i = 0; i <5; i++)
			printf( "Task 1 is running\r\n" );

#if 1		
		vTaskDelay(xDelay50ms);
#else		
		vTaskDelayUntil(&xLastWakeTime, xDelay50ms);
#endif		
	}
}

2.3 Heap相关的函数

2.3.1 pvPortMalloc/vPortFree

函数原型：

void * pvPortMalloc( size_t xWantedSize );	// 分配内存，如果分配内存不成功，则返回值为NULL。
void vPortFree( void * pv );	// 释放内存

作用：分配内存、释放内存。

如果分配内存不成功，则返回值为NULL。

2.3.2 xPortGetFreeHeapSize

函数原型：

size_t xPortGetFreeHeapSize( void );

当前还有多少空闲内存，这函数可以用来优化内存的使用情况。比如当所有内核对象都分配好后，执行此函数返回2000，那么configTOTAL_HEAP_SIZE就可减小2000。

注意：在heap_3中无法使用。

2.3.3 xPortGetMinimumEverFreeHeapSize

函数原型：

size_t xPortGetMinimumEverFreeHeapSize( void );

返回：程序运行过程中，空闲内存容量的最小值。

注意：只有heap_4、heap_5支持此函数。

2.3.4 malloc失败的钩子函数

在pvPortMalloc函数内部：

void * pvPortMalloc( size_t xWantedSize )
{
    ......
    #if ( configUSE_MALLOC_FAILED_HOOK == 1 )
        {
            if( pvReturn == NULL )
            {
                extern void vApplicationMallocFailedHook( void );
                vApplicationMallocFailedHook();
            }
        }
    #endif
    
    return pvReturn;        
}

所以，如果想使用这个钩子函数：

在FreeRTOSConfig.h中，把configUSE_MALLOC_FAILED_HOOK定义为1
提供vApplicationMallocFailedHook函数
pvPortMalloc失败时，才会调用此函数

3. 队列相关函数

3.1 创建队列

队列的创建有两种方法：动态分配内存、静态分配内存，

3.1.1 动态分配内存创建队列xQueueCreate

队列的内存在函数内部动态分配

函数原型如下：

QueueHandle_t xQueueCreate( UBaseType_t uxQueueLength, UBaseType_t uxItemSize );

参数	说明
uxQueueLength	队列长度，最多能存放多少个数据(item)
uxItemSize	每个数据(item)的大小：以字节为单位
返回值	非0：成功，返回句柄，以后使用句柄来操作队列 NULL：失败，因为内存不足

3.1.2 静态分配内存创建队列xQueueCreateStatic

队列的内存要事先分配好

函数原型如下：

QueueHandle_t xQueueCreateStatic(
                           UBaseType_t uxQueueLength,
                           UBaseType_t uxItemSize,
                           uint8_t *pucQueueStorageBuffer,
                           StaticQueue_t *pxQueueBuffer
                       );

参数	说明
uxQueueLength	队列长度，最多能存放多少个数据(item)
uxItemSize	每个数据(item)的大小：以字节为单位
pucQueueStorageBuffer	如果uxItemSize非0，pucQueueStorageBuffer必须指向一个uint8_t数组，此数组大小至少为"uxQueueLength * uxItemSize"
pxQueueBuffer	必须执行一个StaticQueue_t结构体，用来保存队列的数据结构
返回值	非0：成功，返回句柄，以后使用句柄来操作队列 NULL：失败，因为pxQueueBuffer为NULL

示例代码：

// 示例代码
 #define QUEUE_LENGTH 10
 #define ITEM_SIZE sizeof( uint32_t )
 
 // xQueueBuffer用来保存队列结构体
 StaticQueue_t xQueueBuffer;
 
 // ucQueueStorage 用来保存队列的数据
 // 大小为：队列长度 * 数据大小
 uint8_t ucQueueStorage[ QUEUE_LENGTH * ITEM_SIZE ];
 
 void vATask( void *pvParameters )
 {
	QueueHandle_t xQueue1;
 
	// 创建队列: 可以容纳QUEUE_LENGTH个数据，每个数据大小是ITEM_SIZE
	xQueue1 = xQueueCreateStatic( QUEUE_LENGTH,
						  ITEM_SIZE,
						  ucQueueStorage,
						  &xQueueBuffer ); 
 }

3.2 复位队列`xQueueReset`

队列刚被创建时，里面没有数据；使用过程中可以调用xQueueReset()把队列恢复为初始状态，此函数原型为：

/* pxQueue : 复位哪个队列;
 * 返回值: pdPASS(必定成功)
 */
BaseType_t xQueueReset( QueueHandle_t pxQueue);

3.3 删除队列`vQueueDelete`

删除队列的函数为vQueueDelete()，只能删除使用动态方法创建的队列，它会释放内存。原型如下：

void vQueueDelete( QueueHandle_t xQueue );

3.4 写队列

可以把数据写到队列头部，也可以写到尾部，这些函数有两个版本：在任务中使用、在ISR中使用。函数原型如下：

/* 等同于xQueueSendToBack
 * 往队列尾部写入数据，如果没有空间，阻塞时间为xTicksToWait
 */
BaseType_t xQueueSend(
                                QueueHandle_t    xQueue,
                                const void       *pvItemToQueue,
                                TickType_t       xTicksToWait
                            );

/* 
 * 往队列尾部写入数据，如果没有空间，阻塞时间为xTicksToWait
 */
BaseType_t xQueueSendToBack(
                                QueueHandle_t    xQueue,
                                const void       *pvItemToQueue,
                                TickType_t       xTicksToWait
                            );


/* 
 * 往队列尾部写入数据，此函数可以在中断函数中使用，不可阻塞
 */
BaseType_t xQueueSendToBackFromISR(
                                      QueueHandle_t xQueue,
                                      const void *pvItemToQueue,
                                      BaseType_t *pxHigherPriorityTaskWoken
                                   );

/* 
 * 往队列头部写入数据，如果没有空间，阻塞时间为xTicksToWait
 */
BaseType_t xQueueSendToFront(
                                QueueHandle_t    xQueue,
                                const void       *pvItemToQueue,
                                TickType_t       xTicksToWait
                            );

/* 
 * 往队列头部写入数据，此函数可以在中断函数中使用，不可阻塞
 */
BaseType_t xQueueSendToFrontFromISR(
                                      QueueHandle_t xQueue,
                                      const void *pvItemToQueue,
                                      BaseType_t *pxHigherPriorityTaskWoken
                                   );

这些函数用到的参数是类似的，统一说明如下：

参数	说明
xQueue	队列句柄，要写哪个队列
pvItemToQueue	数据指针，这个数据的值会被复制进队列，复制多大的数据？在创建队列时已经指定了数据大小
xTicksToWait	如果队列满则无法写入新数据，可以让任务进入阻塞状态， xTicksToWait表示阻塞的最大时间(Tick Count)。如果被设为0，无法写入数据时函数会立刻返回；如果被设为portMAX_DELAY，则会一直阻塞直到有空间可写
返回值	pdPASS：数据成功写入了队列 errQUEUE_FULL：写入失败，因为队列满了。

3.5 读队列`xQueueReceive`

使用xQueueReceive()函数读队列，读到一个数据后，队列中该数据会被移除。这个函数有两个版本：在任务中使用、在ISR中使用。函数原型如下：

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

BaseType_t xQueueReceiveFromISR(
                                    QueueHandle_t    xQueue,
                                    void             *pvBuffer,
                                    BaseType_t       *pxTaskWoken
                                );

参数说明如下：

参数	说明
xQueue	队列句柄，要读哪个队列
pvBuffer	bufer指针，队列的数据会被复制到这个buffer 复制多大的数据？在创建队列时已经指定了数据大小
xTicksToWait	果队列空则无法读出数据，可以让任务进入阻塞状态， xTicksToWait表示阻塞的最大时间(Tick Count)。如果被设为0，无法读出数据时函数会立刻返回；如果被设为portMAX_DELAY，则会一直阻塞直到有数据可写
返回值	pdPASS：从队列读出数据入 errQUEUE_EMPTY：读取失败，因为队列空了。

3.6 查询队列

可以查询队列中有多少个数据、有多少空余空间。函数原型如下：

/*
 * 返回队列中可用数据的个数
 */
UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue );

/*
 * 返回队列中可用空间的个数
 */
UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue );

3.7 覆盖/偷看

当队列长度为1时，可以使用xQueueOverwrite()或xQueueOverwriteFromISR()来覆盖数据。注意，队列长度必须为1。当队列满时，这些函数会覆盖里面的数据，这也意味着这些函数不会被阻塞。函数原型如下：

/* 覆盖队列
 * xQueue: 写哪个队列
 * pvItemToQueue: 数据地址
 * 返回值: pdTRUE表示成功, pdFALSE表示失败
 */
BaseType_t xQueueOverwrite(
                           QueueHandle_t xQueue,
                           const void * pvItemToQueue
                      );

BaseType_t xQueueOverwriteFromISR(
                           QueueHandle_t xQueue,
                           const void * pvItemToQueue,
                           BaseType_t *pxHigherPriorityTaskWoken
                      );

如果想让队列中的数据供多方读取，也就是说读取时不要移除数据，要留给后来人。那么可以使用"窥视"，也就是xQueuePeek()或xQueuePeekFromISR()。这些函数会从队列中复制出数据，但是不移除数据。这也意味着，如果队列中没有数据，那么"偷看"时会导致阻塞；一旦队列中有数据，以后每次"偷看"都会成功。函数原型如下：

/* 偷看队列
 * xQueue: 偷看哪个队列
 * pvItemToQueue: 数据地址, 用来保存复制出来的数据
 * xTicksToWait: 没有数据的话阻塞一会
 * 返回值: pdTRUE表示成功, pdFALSE表示失败
 */
BaseType_t xQueuePeek(
                          QueueHandle_t xQueue,
                          void * const pvBuffer,
                          TickType_t xTicksToWait
                      );

BaseType_t xQueuePeekFromISR(
                                 QueueHandle_t xQueue,
                                 void *pvBuffer,
                             );

4. 信号量函数

使用信号量时，先创建、然后去添加资源、获得资源。使用句柄来表示一个信号量。

4.1 创建信号量

使用信号量之前，要先创建，得到一个句柄；使用信号量时，要使用句柄来表明使用哪个信号量。

对于二进制信号量、计数型信号量，它们的创建函数不一样：

	二进制信号量	计数型信号量
动态创建	xSemaphoreCreateBinary 计数值初始值为0	xSemaphoreCreateCounting
	vSemaphoreCreateBinary(过时了) 计数值初始值为1
静态创建	xSemaphoreCreateBinaryStatic	xSemaphoreCreateCountingStatic

创建二进制信号量的函数原型如下：

/* 创建一个二进制信号量，返回它的句柄。
 * 此函数内部会分配信号量结构体 
 * 返回值: 返回句柄，非NULL表示成功
 */
SemaphoreHandle_t xSemaphoreCreateBinary( void );

/* 创建一个二进制信号量，返回它的句柄。
 * 此函数无需动态分配内存，所以需要先有一个StaticSemaphore_t结构体，并传入它的指针
 * 返回值: 返回句柄，非NULL表示成功
 */
SemaphoreHandle_t xSemaphoreCreateBinaryStatic( StaticSemaphore_t *pxSemaphoreBuffer );

创建计数型信号量的函数原型如下：

/* 创建一个计数型信号量，返回它的句柄。
 * 此函数内部会分配信号量结构体 
 * uxMaxCount: 最大计数值
 * uxInitialCount: 初始计数值
 * 返回值: 返回句柄，非NULL表示成功
 */
SemaphoreHandle_t xSemaphoreCreateCounting(UBaseType_t uxMaxCount, UBaseType_t uxInitialCount);

/* 创建一个计数型信号量，返回它的句柄。
 * 此函数无需动态分配内存，所以需要先有一个StaticSemaphore_t结构体，并传入它的指针
 * uxMaxCount: 最大计数值
 * uxInitialCount: 初始计数值
 * pxSemaphoreBuffer: StaticSemaphore_t结构体指针
 * 返回值: 返回句柄，非NULL表示成功
 */
SemaphoreHandle_t xSemaphoreCreateCountingStatic( UBaseType_t uxMaxCount, 
                                                 UBaseType_t uxInitialCount, 
                                                 StaticSemaphore_t *pxSemaphoreBuffer );

4.2 删除信号量vSemaphoreDelete

对于动态创建的信号量，不再需要它们时，可以删除它们以回收内存。

vSemaphoreDelete可以用来删除二进制信号量、计数型信号量，函数原型如下：

/*
 * xSemaphore: 信号量句柄，你要删除哪个信号量
 */
void vSemaphoreDelete( SemaphoreHandle_t xSemaphore );

4.3 give/take

二进制信号量、计数型信号量的give、take操作函数是一样的。这些函数也分为2个版本：给任务使用，给ISR使用。列表如下：

	在任务中使用	在ISR中使用
give	xSemaphoreGive	xSemaphoreGiveFromISR
take	xSemaphoreTake	xSemaphoreTakeFromISR

xSemaphoreGive的函数原型如下：

BaseType_t xSemaphoreGive( SemaphoreHandle_t xSemaphore );

xSemaphoreGive函数的参数与返回值列表如下：

参数	说明
xSemaphore	信号量句柄，释放哪个信号量
返回值	pdTRUE表示成功, 如果二进制信号量的计数值已经是1，再次调用此函数则返回失败；如果计数型信号量的计数值已经是最大值，再次调用此函数则返回失败

pxHigherPriorityTaskWoken的函数原型如下：

BaseType_t xSemaphoreGiveFromISR(
                        SemaphoreHandle_t xSemaphore,
                        BaseType_t *pxHigherPriorityTaskWoken
                    );

xSemaphoreGiveFromISR函数的参数与返回值列表如下：

参数	说明
xSemaphore	信号量句柄，释放哪个信号量
pxHigherPriorityTaskWoken	如果释放信号量导致更高优先级的任务变为了就绪态，则*pxHigherPriorityTaskWoken = pdTRUE
返回值	pdTRUE表示成功, 如果二进制信号量的计数值已经是1，再次调用此函数则返回失败；如果计数型信号量的计数值已经是最大值，再次调用此函数则返回失败

xSemaphoreTake的函数原型如下：

BaseType_t xSemaphoreTake(
                   SemaphoreHandle_t xSemaphore,
                   TickType_t xTicksToWait
               );

xSemaphoreTake函数的参数与返回值列表如下：

参数	说明
xSemaphore	信号量句柄，获取哪个信号量
xTicksToWait	如果无法马上获得信号量，阻塞一会： 0：不阻塞，马上返回 portMAX_DELAY: 一直阻塞直到成功其他值: 阻塞的Tick个数，可以使用`pdMS_TO_TICKS()`来指定阻塞时间为若干ms
返回值	pdTRUE表示成功

xSemaphoreTakeFromISR的函数原型如下：

BaseType_t xSemaphoreTakeFromISR(
                        SemaphoreHandle_t xSemaphore,
                        BaseType_t *pxHigherPriorityTaskWoken
                    );

xSemaphoreTakeFromISR函数的参数与返回值列表如下：

参数	说明
xSemaphore	信号量句柄，获取哪个信号量
pxHigherPriorityTaskWoken	如果获取信号量导致更高优先级的任务变为了就绪态，则*pxHigherPriorityTaskWoken = pdTRUE
返回值	pdTRUE表示成功

5. 互斥量函数

5.1 创建互斥量

互斥量是一种特殊的二进制信号量。

使用互斥量时，先创建、然后去获得、释放它。使用句柄来表示一个互斥量。

创建互斥量的函数有2种：动态分配内存，静态分配内存，函数原型如下：

/* 创建一个互斥量，返回它的句柄。
 * 此函数内部会分配互斥量结构体 
 * 返回值: 返回句柄，非NULL表示成功
 */
SemaphoreHandle_t xSemaphoreCreateMutex( void );

/* 创建一个互斥量，返回它的句柄。
 * 此函数无需动态分配内存，所以需要先有一个StaticSemaphore_t结构体，并传入它的指针
 * 返回值: 返回句柄，非NULL表示成功
 */
SemaphoreHandle_t xSemaphoreCreateMutexStatic( StaticSemaphore_t *pxMutexBuffer );

要想使用互斥量，需要在配置文件FreeRTOSConfig.h中定义：

#define configUSE_MUTEXES 1

5.2 互斥量其他函数

要注意的是，互斥量不能在ISR中使用。

各类操作函数，比如删除、give/take，跟一般是信号量是一样的。

/*
 * xSemaphore: 信号量句柄，你要删除哪个信号量, 互斥量也是一种信号量
 */
void vSemaphoreDelete( SemaphoreHandle_t xSemaphore );

/* 释放 */
BaseType_t xSemaphoreGive( SemaphoreHandle_t xSemaphore );

/* 释放(ISR版本) */
BaseType_t xSemaphoreGiveFromISR(
                       SemaphoreHandle_t xSemaphore,
                       BaseType_t *pxHigherPriorityTaskWoken
                   );

/* 获得 */
BaseType_t xSemaphoreTake(
                   SemaphoreHandle_t xSemaphore,
                   TickType_t xTicksToWait
               );
/* 获得(ISR版本) */
xSemaphoreGiveFromISR(
                       SemaphoreHandle_t xSemaphore,
                       BaseType_t *pxHigherPriorityTaskWoken
                   );

6. 递归锁

递归锁(Recursive Mutexes)，它的特性如下：

任务A获得递归锁M后，它还可以多次去获得这个锁
"take"了N次，要"give"N次，这个锁才会被释放

递归锁的函数根一般互斥量的函数名不一样，参数类型一样，列表如下：

	递归锁	一般互斥量
创建	xSemaphoreCreateRecursiveMutex	xSemaphoreCreateMutex
获得	xSemaphoreTakeRecursive	xSemaphoreTake
释放	xSemaphoreGiveRecursive	xSemaphoreGive

函数原型如下：

/* 创建一个递归锁，返回它的句柄。
 * 此函数内部会分配互斥量结构体 
 * 返回值: 返回句柄，非NULL表示成功
 */
SemaphoreHandle_t xSemaphoreCreateRecursiveMutex( void );


/* 释放 */
BaseType_t xSemaphoreGiveRecursive( SemaphoreHandle_t xSemaphore );

/* 获得 */
BaseType_t xSemaphoreTakeRecursive(
                   SemaphoreHandle_t xSemaphore,
                   TickType_t xTicksToWait
               );

7. 事件组函数

7.1 创建事件组

使用事件组之前，要先创建，得到一个句柄；使用事件组时，要使用句柄来表明使用哪个事件组。

有两种创建方法：动态分配内存、静态分配内存。函数原型如下：

/* 创建一个事件组，返回它的句柄。
 * 此函数内部会分配事件组结构体 
 * 返回值: 返回句柄，非NULL表示成功
 */
EventGroupHandle_t xEventGroupCreate( void );

/* 创建一个事件组，返回它的句柄。
 * 此函数无需动态分配内存，所以需要先有一个StaticEventGroup_t结构体，并传入它的指针
 * 返回值: 返回句柄，非NULL表示成功
 */
EventGroupHandle_t xEventGroupCreateStatic( StaticEventGroup_t * pxEventGroupBuffer );

7.2 删除事件组vEventGroupDelete

对于动态创建的事件组，不再需要它们时，可以删除它们以回收内存。

vEventGroupDelete可以用来删除事件组，函数原型如下：

/*
 * xEventGroup: 事件组句柄，你要删除哪个事件组
 */
void vEventGroupDelete( EventGroupHandle_t xEventGroup )

7.3 设置事件`xEventGroupSetBits`

可以设置事件组的某个位、某些位，使用的函数有2个：

在任务中使用xEventGroupSetBits()
在ISR中使用xEventGroupSetBitsFromISR()

有一个或多个任务在等待事件，如果这些事件符合这些任务的期望，那么任务还会被唤醒。

函数原型如下：

/* 设置事件组中的位
 * xEventGroup: 哪个事件组
 * uxBitsToSet: 设置哪些位? 
 *              如果uxBitsToSet的bitX, bitY为1, 那么事件组中的bitX, bitY被设置为1
 *               可以用来设置多个位，比如 0x15 就表示设置bit4, bit2, bit0
 * 返回值: 返回原来的事件值(没什么意义, 因为很可能已经被其他任务修改了)
 */
EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup,
                                    const EventBits_t uxBitsToSet );


/* 设置事件组中的位
 * xEventGroup: 哪个事件组
 * uxBitsToSet: 设置哪些位? 
 *              如果uxBitsToSet的bitX, bitY为1, 那么事件组中的bitX, bitY被设置为1
 *               可以用来设置多个位，比如 0x15 就表示设置bit4, bit2, bit0
 * pxHigherPriorityTaskWoken: 有没有导致更高优先级的任务进入就绪态? pdTRUE-有, pdFALSE-没有
 * 返回值: pdPASS-成功, pdFALSE-失败
 */
BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup,
									  const EventBits_t uxBitsToSet,
									  BaseType_t * pxHigherPriorityTaskWoken );

值得注意的是，ISR中的函数，比如队列函数xQueueSendToBackFromISR、信号量函数xSemaphoreGiveFromISR，它们会唤醒某个任务，最多只会唤醒1个任务。

但是设置事件组时，有可能导致多个任务被唤醒，这会带来很大的不确定性。所以xEventGroupSetBitsFromISR函数不是直接去设置事件组，而是给一个FreeRTOS后台任务(daemon task)发送队列数据，由这个任务来设置事件组。

如果后台任务的优先级比当前被中断的任务优先级高，xEventGroupSetBitsFromISR会设置*pxHigherPriorityTaskWoken为pdTRUE。

如果daemon task成功地把队列数据发送给了后台任务，那么xEventGroupSetBitsFromISR的返回值就是pdPASS。

7.4 等待事件xEventGroupWaitBits

使用xEventGroupWaitBits来等待事件，可以等待某一位、某些位中的任意一个，也可以等待多位；等到期望的事件后，还可以清除某些位。

函数原型如下：

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

先引入一个概念：unblock condition。一个任务在等待事件发生时，它处于阻塞状态；当期望的时间发生时，这个状态就叫"unblock condition"，非阻塞条件，或称为"非阻塞条件成立"；当"非阻塞条件成立"后，该任务就可以变为就绪态。

函数参数说明列表如下：

参数	说明
xEventGroup	等待哪个事件组？
uxBitsToWaitFor	等待哪些位？哪些位要被测试？
xWaitForAllBits	怎么测试？是"AND"还是"OR"？ pdTRUE: 等待的位，全部为1; pdFALSE: 等待的位，某一个为1即可
xClearOnExit	函数提出前是否要清除事件？ pdTRUE: 清除uxBitsToWaitFor指定的位 pdFALSE: 不清除
xTicksToWait	如果期待的事件未发生，阻塞多久。可以设置为0：判断后即刻返回；可设置为portMAX_DELAY：一定等到成功才返回；可以设置为期望的Tick Count，一般用`pdMS_TO_TICKS()`把ms转换为Tick Count
返回值	返回的是事件值，如果期待的事件发生了，返回的是"非阻塞条件成立"时的事件值；如果是超时退出，返回的是超时时刻的事件值。

举例如下：

事件组的值	uxBitsToWaitFor	xWaitForAllBits	说明
0100	0101	pdTRUE	任务期望bit0,bit2都为1，当前值只有bit2满足，任务进入阻塞态；当事件组中bit0,bit2都为1时退出阻塞态
0100	0110	pdFALSE	任务期望bit0,bit2某一个为1，当前值满足，所以任务成功退出
0100	0110	pdTRUE	任务期望bit1,bit2都为1，当前值不满足，任务进入阻塞态；当事件组中bit1,bit2都为1时退出阻塞态

你可以使用xEventGroupWaitBits()等待期望的事件，它发生之后再使用xEventGroupClearBits()来清除。但是这两个函数之间，有可能被其他任务或中断抢占，它们可能会修改事件组。

可以使用设置xClearOnExit为pdTRUE，使得对事件组的测试、清零都在xEventGroupWaitBits()函数内部完成，这是一个原子操作。

7.5 同步`xEventGroupSync`

有一个事情需要多个任务协同，比如：

任务A：炒菜
任务B：买酒
任务C：摆台
A、B、C做好自己的事后，还要等别人做完；大家一起做完，才可开饭

使用xEventGroupSync()函数可以同步多个任务：

可以设置某位、某些位，表示自己做了什么事
可以等待某位、某些位，表示要等等其他任务
期望的时间发生后，xEventGroupSync()才会成功返回。
xEventGroupSync成功返回后，会清除事件

xEventGroupSync函数原型如下：

EventBits_t xEventGroupSync(    EventGroupHandle_t xEventGroup,
                                const EventBits_t uxBitsToSet,
                                const EventBits_t uxBitsToWaitFor,
                                TickType_t xTicksToWait );

参数列表如下：

参数	说明
xEventGroup	哪个事件组？
uxBitsToSet	要设置哪些事件？我完成了哪些事件？比如0x05(二进制为0101)会导致事件组的bit0,bit2被设置为1
uxBitsToWaitFor	等待那个位、哪些位？比如0x15(二级制10101)，表示要等待bit0,bit2,bit4都为1
xTicksToWait	如果期待的事件未发生，阻塞多久。可以设置为0：判断后即刻返回；可设置为portMAX_DELAY：一定等到成功才返回；可以设置为期望的Tick Count，一般用`pdMS_TO_TICKS()`把ms转换为Tick Count
返回值	返回的是事件值，如果期待的事件发生了，返回的是"非阻塞条件成立"时的事件值；如果是超时退出，返回的是超时时刻的事件值。

8. 任务通知函数

8.1 发出/取出通知

任务通知有2套函数，简化版、专业版，列表如下：

简化版函数的使用比较简单，它实际上也是使用专业版函数实现的
专业版函数支持很多参数，可以实现很多功能

	简化版	专业版
发出通知	xTaskNotifyGive vTaskNotifyGiveFromISR	xTaskNotify xTaskNotifyFromISR
取出通知	ulTaskNotifyTake	xTaskNotifyWait

8.2 xTaskNotifyGive/ulTaskNotifyTake

在任务中使用xTaskNotifyGive函数，在ISR中使用vTaskNotifyGiveFromISR函数，都是直接给其他任务发送通知：

使得通知值加一
并使得通知状态变为"pending"，也就是taskNOTIFICATION_RECEIVED，表示有数据了、待处理

可以使用ulTaskNotifyTake函数来取出通知值：

如果通知值等于0，则阻塞(可以指定超时时间)
当通知值大于0时，任务从阻塞态进入就绪态
在ulTaskNotifyTake返回之前，还可以做些清理工作：把通知值减一，或者把通知值清零

使用ulTaskNotifyTake函数可以实现轻量级的、高效的二进制信号量、计数型信号量。

这几个函数的原型如下：

BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify );

void vTaskNotifyGiveFromISR( TaskHandle_t xTaskHandle, BaseType_t *pxHigherPriorityTaskWoken );

uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait );

xTaskNotifyGive函数的参数说明如下：

参数	说明
xTaskToNotify	任务句柄(创建任务时得到)，给哪个任务发通知
返回值	必定返回pdPASS

vTaskNotifyGiveFromISR函数的参数说明如下：

参数	说明
xTaskHandle	任务句柄(创建任务时得到)，给哪个任务发通知
pxHigherPriorityTaskWoken	被通知的任务，可能正处于阻塞状态。此函数发出通知后，会把它从阻塞状态切换为就绪态。如果被唤醒的任务的优先级，高于当前任务的优先级，则"*pxHigherPriorityTaskWoken"被设置为pdTRUE，这表示在中断返回之前要进行任务切换。

ulTaskNotifyTake函数的参数说明如下：

参数	说明
xClearCountOnExit	函数返回前是否清零： pdTRUE：把通知值清零 pdFALSE：如果通知值大于0，则把通知值减一
xTicksToWait	任务进入阻塞态的超时时间，它在等待通知值大于0。 0：不等待，即刻返回； portMAX_DELAY：一直等待，直到通知值大于0；其他值：Tick Count，可以用`pdMS_TO_TICKS()`把ms转换为Tick Count
返回值	函数返回之前，在清零或减一之前的通知值。如果xTicksToWait非0，则返回值有2种情况： 1. 大于0：在超时前，通知值被增加了 2. 等于0：一直没有其他任务增加通知值，最后超时返回0

8.3 xTaskNotify/xTaskNotifyWait

xTaskNotify 函数功能更强大，可以使用不同参数实现各类功能，比如：

让接收任务的通知值加一：这时xTaskNotify()等同于xTaskNotifyGive()
设置接收任务的通知值的某一位、某些位，这就是一个轻量级的、更高效的事件组
把一个新值写入接收任务的通知值：上一次的通知值被读走后，写入才成功。这就是轻量级的、长度为1的队列
用一个新值覆盖接收任务的通知值：无论上一次的通知值是否被读走，覆盖都成功。类似xQueueOverwrite()函数，这就是轻量级的邮箱。

xTaskNotify()比xTaskNotifyGive()更灵活、强大，使用上也就更复杂。xTaskNotifyFromISR()是它对应的ISR版本。

这两个函数用来发出任务通知，使用哪个函数来取出任务通知呢？

使用xTaskNotifyWait()函数！它比ulTaskNotifyTake()更复杂：

可以让任务等待(可以加上超时时间)，等到任务状态为"pending"(也就是有数据)
还可以在函数进入、退出时，清除通知值的指定位

这几个函数的原型如下：

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

BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify,
                               uint32_t ulValue, 
                               eNotifyAction eAction, 
                               BaseType_t *pxHigherPriorityTaskWoken );

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

xTaskNotify函数的参数说明如下：

参数	说明
xTaskToNotify	任务句柄(创建任务时得到)，给哪个任务发通知
ulValue	怎么使用ulValue，由eAction参数决定
eAction	见下表
返回值	pdPASS：成功，大部分调用都会成功 pdFAIL：只有一种情况会失败，当eAction为eSetValueWithoutOverwrite，并且通知状态为"pending"(表示有新数据未读)，这时就会失败。

eNotifyAction参数说明：

eNotifyAction取值	说明
eNoAction	仅仅是更新通知状态为"pending"，未使用ulValue。这个选项相当于轻量级的、更高效的二进制信号量。
eSetBits	通知值 = 原来的通知值 \| ulValue，按位或。相当于轻量级的、更高效的事件组。
eIncrement	通知值 = 原来的通知值 + 1，未使用ulValue。相当于轻量级的、更高效的二进制信号量、计数型信号量。相当于`xTaskNotifyGive()`函数。
eSetValueWithoutOverwrite	不覆盖。如果通知状态为"pending"(表示有数据未读)，则此次调用xTaskNotify不做任何事，返回pdFAIL。如果通知状态不是"pending"(表示没有新数据)，则：通知值 = ulValue。
eSetValueWithOverwrite	覆盖。无论如何，不管通知状态是否为"pendng"，通知值 = ulValue。

xTaskNotifyFromISR函数跟xTaskNotify很类似，就多了最后一个参数pxHigherPriorityTaskWoken。在很多ISR函数中，这个参数的作用都是类似的，使用场景如下：

被通知的任务，可能正处于阻塞状态
xTaskNotifyFromISR函数发出通知后，会把接收任务从阻塞状态切换为就绪态
如果被唤醒的任务的优先级，高于当前任务的优先级，则"*pxHigherPriorityTaskWoken"被设置为pdTRUE，这表示在中断返回之前要进行任务切换。

xTaskNotifyWait函数列表如下：

参数	说明
ulBitsToClearOnEntry	在xTaskNotifyWait入口处，要清除通知值的哪些位？通知状态不是"pending"的情况下，才会清除。它的本意是：我想等待某些事件发生，所以先把"旧数据"的某些位清零。能清零的话：通知值 = 通知值 & ~(ulBitsToClearOnEntry)。比如传入0x01，表示清除通知值的bit0；传入0xffffffff即ULONG_MAX，表示清除所有位，即把值设置为0
ulBitsToClearOnExit	在xTaskNotifyWait出口处，如果不是因为超时推出，而是因为得到了数据而退出时：通知值 = 通知值 & ~(ulBitsToClearOnExit)。在清除某些位之前，通知值先被赋给"*pulNotificationValue"。比如入0x03，表示清除通知值的bit0、bit1；传入0xffffffff即ULONG_MAX，表示清除所有位，即把值设置为0
pulNotificationValue	用来取出通知值。在函数退出时，使用ulBitsToClearOnExit清除之前，把通知值赋给"*pulNotificationValue"。如果不需要取出通知值，可以设为NULL。
xTicksToWait	任务进入阻塞态的超时时间，它在等待通知状态变为"pending"。 0：不等待，即刻返回； portMAX_DELAY：一直等待，直到通知状态变为"pending"；其他值：Tick Count，可以用`pdMS_TO_TICKS()`把ms转换为Tick Count
返回值	1. pdPASS：成功这表示xTaskNotifyWait成功获得了通知：可能是调用函数之前，通知状态就是"pending"；也可能是在阻塞期间，通知状态变为了"pending"。 2. pdFAIL：没有得到通知。

9. 软件定时器

9.1 创建定时器

要使用定时器，需要先创建它，得到它的句柄。

有两种方法创建定时器：动态分配内存、静态分配内存。函数原型如下：

/* 使用动态分配内存的方法创建定时器
 * pcTimerName:定时器名字, 用处不大, 尽在调试时用到
 * xTimerPeriodInTicks: 周期, 以Tick为单位
 * uxAutoReload: 类型, pdTRUE表示自动加载, pdFALSE表示一次性
 * pvTimerID: 回调函数可以使用此参数, 比如分辨是哪个定时器
 * pxCallbackFunction: 回调函数
 * 返回值: 成功则返回TimerHandle_t, 否则返回NULL
 */
TimerHandle_t xTimerCreate( const char * const pcTimerName, 
							const TickType_t xTimerPeriodInTicks,
							const UBaseType_t uxAutoReload,
							void * const pvTimerID,
							TimerCallbackFunction_t pxCallbackFunction );

/* 使用静态分配内存的方法创建定时器
 * pcTimerName:定时器名字, 用处不大, 尽在调试时用到
 * xTimerPeriodInTicks: 周期, 以Tick为单位
 * uxAutoReload: 类型, pdTRUE表示自动加载, pdFALSE表示一次性
 * pvTimerID: 回调函数可以使用此参数, 比如分辨是哪个定时器
 * pxCallbackFunction: 回调函数
 * pxTimerBuffer: 传入一个StaticTimer_t结构体, 将在上面构造定时器
 * 返回值: 成功则返回TimerHandle_t, 否则返回NULL
 */
TimerHandle_t xTimerCreateStatic(const char * const pcTimerName,
                                 TickType_t xTimerPeriodInTicks,
                                 UBaseType_t uxAutoReload,
                                 void * pvTimerID,
                                 TimerCallbackFunction_t pxCallbackFunction,
                                 StaticTimer_t *pxTimerBuffer );

回调函数的类型是：

void ATimerCallback( TimerHandle_t xTimer );

typedef void (* TimerCallbackFunction_t)( TimerHandle_t xTimer );

9.2 删除定时器

动态分配的定时器，不再需要时可以删除掉以回收内存。删除函数原型如下：

/* 删除定时器
 * xTimer: 要删除哪个定时器
 * xTicksToWait: 超时时间
 * 返回值: pdFAIL表示"删除命令"在xTicksToWait个Tick内无法写入队列
 *        pdPASS表示成功
 */
BaseType_t xTimerDelete( TimerHandle_t xTimer, TickType_t xTicksToWait );

定时器的很多API函数，都是通过发送"命令"到命令队列，由守护任务来实现。

如果队列满了，"命令"就无法即刻写入队列。我们可以指定一个超时时间xTicksToWait，等待一会。

9.3 启动/停止定时器

启动定时器就是设置它的状态为运行态(Running、Active)。

停止定时器就是设置它的状态为冬眠(Dormant)，让它不能运行。

涉及的函数原型如下：

/* 启动定时器
 * xTimer: 哪个定时器
 * xTicksToWait: 超时时间
 * 返回值: pdFAIL表示"启动命令"在xTicksToWait个Tick内无法写入队列
 *        pdPASS表示成功
 */
BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xTicksToWait );

/* 启动定时器(ISR版本)
 * xTimer: 哪个定时器
 * pxHigherPriorityTaskWoken: 向队列发出命令使得守护任务被唤醒,
 *                            如果守护任务的优先级比当前任务的高,
 *                            则"*pxHigherPriorityTaskWoken = pdTRUE",
 *                            表示需要进行任务调度
 * 返回值: pdFAIL表示"启动命令"无法写入队列
 *        pdPASS表示成功
 */
BaseType_t xTimerStartFromISR(   TimerHandle_t xTimer,
                                 BaseType_t *pxHigherPriorityTaskWoken );

/* 停止定时器
 * xTimer: 哪个定时器
 * xTicksToWait: 超时时间
 * 返回值: pdFAIL表示"停止命令"在xTicksToWait个Tick内无法写入队列
 *        pdPASS表示成功
 */
BaseType_t xTimerStop( TimerHandle_t xTimer, TickType_t xTicksToWait );

/* 停止定时器(ISR版本)
 * xTimer: 哪个定时器
 * pxHigherPriorityTaskWoken: 向队列发出命令使得守护任务被唤醒,
 *                            如果守护任务的优先级比当前任务的高,
 *                            则"*pxHigherPriorityTaskWoken = pdTRUE",
 *                            表示需要进行任务调度
 * 返回值: pdFAIL表示"停止命令"无法写入队列
 *        pdPASS表示成功
 */
BaseType_t xTimerStopFromISR(    TimerHandle_t xTimer,
                                 BaseType_t *pxHigherPriorityTaskWoken );

注意，这些函数的xTicksToWait表示的是，把命令写入命令队列的超时时间。命令队列可能已经满了，无法马上把命令写入队列里，可以等待一会。

xTicksToWait不是定时器本身的超时时间，不是定时器本身的"周期"。

创建定时器时，设置了它的周期(period)。xTimerStart()函数是用来启动定时器。假设调用xTimerStart()的时刻是tX，定时器的周期是n，那么在tX+n时刻定时器的回调函数被调用。

如果定时器已经被启动，但是它的函数尚未被执行，再次执行xTimerStart()函数相当于执行xTimerReset()，重新设定它的启动时间。

9.4 复位定时器

从定时器的状态转换图可以知道，使用xTimerReset()函数可以让定时器的状态从冬眠态转换为运行态，相当于使用xTimerStart()函数。

如果定时器已经处于运行态，使用xTimerReset()函数就相当于重新确定超时时间。假设调用xTimerReset()的时刻是tX，定时器的周期是n，那么tX+n就是重新确定的超时时间。

复位函数的原型如下：

/* 复位定时器
 * xTimer: 哪个定时器
 * xTicksToWait: 超时时间
 * 返回值: pdFAIL表示"复位命令"在xTicksToWait个Tick内无法写入队列
 *        pdPASS表示成功
 */
BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xTicksToWait );

/* 复位定时器(ISR版本)
 * xTimer: 哪个定时器
 * pxHigherPriorityTaskWoken: 向队列发出命令使得守护任务被唤醒,
 *                            如果守护任务的优先级比当前任务的高,
 *                            则"*pxHigherPriorityTaskWoken = pdTRUE",
 *                            表示需要进行任务调度
 * 返回值: pdFAIL表示"停止命令"无法写入队列
 *        pdPASS表示成功
 */
BaseType_t xTimerResetFromISR(   TimerHandle_t xTimer,
                                 BaseType_t *pxHigherPriorityTaskWoken );

9.5 修改定时器周期`xTimerChangePeriod`

从定时器的状态转换图可以知道，使用xTimerChangePeriod()函数，处理能修改它的周期外，还可以让定时器的状态从冬眠态转换为运行态。

修改定时器的周期时，会使用新的周期重新计算它的超时时间。假设调用xTimerChangePeriod()函数的时间tX，新的周期是n，则tX+n就是新的超时时间。

9.6 获取/设置定时器ID

定时器的结构体如下，里面有一项pvTimerID，它就是定时器ID：

怎么使用定时器ID，完全由程序来决定：

可以用来标记定时器，表示自己是什么定时器
可以用来保存参数，给回调函数使用

它的初始值在创建定时器时由xTimerCreate()这类函数传入，后续可以使用这些函数来操作：

更新ID：使用vTimerSetTimerID()函数
查询ID：查询pvTimerGetTimerID()函数

这两个函数不涉及命令队列，它们是直接操作定时器结构体。

函数原型如下：

/* 获得定时器的ID
 * xTimer: 哪个定时器
 * 返回值: 定时器的ID
 */
void *pvTimerGetTimerID( TimerHandle_t xTimer );

/* 设置定时器的ID
 * xTimer: 哪个定时器
 * pvNewID: 新ID
 * 返回值: 无
 */
void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID );

10. 资源管理

10.1 屏蔽中断

屏蔽中断有两套宏：任务中使用、ISR中使用：

任务中使用：taskENTER_CRITICA()/taskEXIT_CRITICAL()
ISR中使用：taskENTER_CRITICAL_FROM_ISR()/taskEXIT_CRITICAL_FROM_ISR()

10.1.1 在任务中屏蔽中断

在任务中屏蔽中断的示例代码如下：

/* 在任务中，当前时刻中断是使能的
 * 执行这句代码后，屏蔽中断
 */
taskENTER_CRITICAL();

/* 访问临界资源 */

/* 重新使能中断 */
taskEXIT_CRITICAL();

在taskENTER_CRITICA()/taskEXIT_CRITICAL()之间：

低优先级的中断被屏蔽了：优先级低于、等于configMAX_SYSCALL_INTERRUPT_PRIORITY
高优先级的中断可以产生：优先级高于configMAX_SYSCALL_INTERRUPT_PRIORITY
- 但是，这些中断ISR里，不允许使用FreeRTOS的API函数
任务调度依赖于中断、依赖于API函数，所以：这两段代码之间，不会有任务调度产生

这套taskENTER_CRITICA()/taskEXIT_CRITICAL()宏，是可以递归使用的，它的内部会记录嵌套的深度，只有嵌套深度变为0时，调用taskEXIT_CRITICAL()才会重新使能中断。

使用taskENTER_CRITICA()/taskEXIT_CRITICAL()来访问临界资源是很粗鲁的方法：

中断无法正常运行
任务调度无法进行
所以，之间的代码要尽可能快速地执行

10.1.2 在ISR中屏蔽中断

要使用含有"FROM_ISR"后缀的宏，示例代码如下：

void vAnInterruptServiceRoutine( void )
{
    /* 用来记录当前中断是否使能 */
    UBaseType_t uxSavedInterruptStatus;
    
    /* 在ISR中，当前时刻中断可能是使能的，也可能是禁止的
     * 所以要记录当前状态, 后面要恢复为原先的状态
     * 执行这句代码后，屏蔽中断
     */
    uxSavedInterruptStatus = taskENTER_CRITICAL_FROM_ISR();
    
    /* 访问临界资源 */

    /* 恢复中断状态 */
    taskEXIT_CRITICAL_FROM_ISR( uxSavedInterruptStatus );
    /* 现在，当前ISR可以被更高优先级的中断打断了 */
}

在taskENTER_CRITICA_FROM_ISR()/taskEXIT_CRITICAL_FROM_ISR()之间：

低优先级的中断被屏蔽了：优先级低于、等于configMAX_SYSCALL_INTERRUPT_PRIORITY
高优先级的中断可以产生：优先级高于configMAX_SYSCALL_INTERRUPT_PRIORITY
- 但是，这些中断ISR里，不允许使用FreeRTOS的API函数
任务调度依赖于中断、依赖于API函数，所以：这两段代码之间，不会有任务调度产生

10.2 暂停/恢复调度器

如果有别的任务来跟你竞争临界资源，你可以把中断关掉：这当然可以禁止别的任务运行，但是这代价太大了。它会影响到中断的处理。

如果只是禁止别的任务来跟你竞争，不需要关中断，暂停调度器就可以了：在这期间，中断还是可以发生、处理。

使用这2个函数来暂停、恢复调度器：

/* 暂停调度器 */
void vTaskSuspendAll( void );

/* 恢复调度器
 * 返回值: pdTRUE表示在暂定期间有更高优先级的任务就绪了
 *        可以不理会这个返回值
 */
BaseType_t xTaskResumeAll( void );

示例代码如下：

vTaskSuspendScheduler();

/* 访问临界资源 */

xTaskResumeScheduler();

这套vTaskSuspendScheduler()/xTaskResumeScheduler()宏，是可以递归使用的，它的内部会记录嵌套的深度，只有嵌套深度变为0时，调用taskEXIT_CRITICAL()才会重新使能中断。

闪耀大叔

关注

10
点赞
踩
60

收藏

觉得还不错? 一键收藏
打赏
2
评论
FreeRTOS函数功能大全

单片机/嵌入式实时操作系统FreeRTOS函数功能大全
复制链接

扫一扫

专栏目录

FreeRTOS函数功能大全

1. 任务相关函数

1.1 创建任务xTaskCreate

1.2 删除任务vTaskDelete

1.3 暂停任务vTaskSuspend

1.4 优先级相关函数

1.4.1 获得任务的优先级uxTaskPriorityGet

1.4.2 设置任务的优先级vTaskPrioritySet

1.5 启动任务调度器vTaskStartScheduler

1.6 空闲任务钩子函数vApplicationIdleHook

2. Tick相关函数

2.1 延时函数vTaskDelay

2.2 绝对延时函数vTaskDelayUntil

2.3 Heap相关的函数

2.3.1 pvPortMalloc/vPortFree

2.3.2 xPortGetFreeHeapSize

2.3.3 xPortGetMinimumEverFreeHeapSize

2.3.4 malloc失败的钩子函数

3. 队列相关函数

3.1 创建队列

3.1.1 动态分配内存创建队列xQueueCreate

3.1.2 静态分配内存创建队列xQueueCreateStatic

3.2 复位队列xQueueReset

3.3 删除队列vQueueDelete

3.4 写队列

3.5 读队列xQueueReceive

3.6 查询队列

3.7 覆盖/偷看

4. 信号量函数

4.1 创建信号量

4.2 删除信号量vSemaphoreDelete

4.3 give/take

5. 互斥量函数

5.1 创建互斥量

5.2 互斥量其他函数

6. 递归锁

7. 事件组函数

7.1 创建事件组

7.2 删除事件组vEventGroupDelete

7.3 设置事件xEventGroupSetBits

7.4 等待事件xEventGroupWaitBits

7.5 同步xEventGroupSync

8. 任务通知函数

8.1 发出/取出通知

8.2 xTaskNotifyGive/ulTaskNotifyTake

8.3 xTaskNotify/xTaskNotifyWait

9. 软件定时器

9.1 创建定时器

9.2 删除定时器

9.3 启动/停止定时器

9.4 复位定时器

9.5 修改定时器周期xTimerChangePeriod

9.6 获取/设置定时器ID

10. 资源管理

10.1 屏蔽中断

10.1.1 在任务中屏蔽中断

10.1.2 在ISR中屏蔽中断

10.2 暂停/恢复调度器

“相关推荐”对你有帮助么？

3.2 复位队列`xQueueReset`

3.3 删除队列`vQueueDelete`

3.5 读队列`xQueueReceive`

7.3 设置事件`xEventGroupSetBits`

7.5 同步`xEventGroupSync`

9.5 修改定时器周期`xTimerChangePeriod`