内核函数详解 - freertos使用指南与各类型函数详细说明

三：内核函数

 启动实时内核处理

头文件：task.h

void vTaskStartScheduler （ void ）;

说明：当 vTaskStartScheduler（） 被调用时，空闲任务自动创建。如果 vTaskStartScheduler（） 成功调用，这个函数不返回，直到执行任务调用vTaskEndScheduler（）。如果可供给空闲任务的RAM 不足，那么函数调用失败，并立即返回。

 停止实时内核运行

头文件：task.h

void vTaskEndScheduler （ void ）;

说明：所有创建的任务将自动删除，并且多任务（优先级或合作式）将停止。当vTaskStartScheduler（）调用时，执行将再次开始，像vTaskStartScheduler（）仅仅返回。

注意：vPortEndScheduler （）导致所有由内核分配的资源释放——但是不会释放由应用程序的任务分配的资源。

 挂起所有活动的实时内核，同时允许中断（包括内核滴答）

头文件：task.h

void vTaskSuspendAll （ void ）;

说明：任务在调用vTaskSuspendAll （）后，这个任务将继续执行，不会有任何被切换的危险，直到调用xTaskResumeAll （）函数重启内核。

注意：API 中有可能影响影响上下文切换的函数（例如，vTaskDelayUntil（）， xQueueSend（）等等），一定不能在调度器挂起时被调用。

四：队列管理

队列是内部通信的主要形式。它可以用于在任务和任务之间以及任务和中断之间发送消息。在大多数情况下使用线程安全 FIFO（先进先出）缓存，新数据放在队列的最后，虽然数据也可以放在前面。

队列可以包含固定大小的 ‘项目’ - 每个项目的大小和队列可以保存项目的最大数量在创建队列时就已经定义了。

项目以复制而不是引用的方式放入队列，因此最好使放入队列项目的大小成为最小。以复制的方式放入队列可以使你的系统设计极大的简化，因为两个任务不会同时访问数据。队列帮助你管理所有的互斥问题。

如果你希望在队列中使用大的项目，可能最好用插入队列指针 - 但是这样做必须注意要确保你的系统明确定义任务和/或中断是数据的“所以者”。

队列 API 函数可以指定阻塞的时间。阻塞时间代表任务进入阻塞状态或者等待队列中数据时（当任务读取队列但是队列是空的时候）的最大‘节拍’数，或者等待队列空间变为可以使用（当任务需要写数据到队列，但是队列已满时）。当一个以上任务在同一个队列中被阻塞时，高优先级的任务先解除阻塞。

 创建一个新的队列

头文件：queue. H

xQueueHandle xQueueCreate （

unsigned portBASE_TYPE uxQueueLength， 队列中包含最大项目数量

unsigned portBASE_TYPE uxItemSize 队列中每个项目所需的字节数

）;

说明：创建一个新的队列。为新的队列分配所需的存储内存，并返回一个队列处理。

注意：项目通过复制而不是引用排队，因此，所需的字节数，将复制给每个项目。队列中每个项目必须分配同样大小。

返回：如果队列成功创建，则返回一个新建队列的处理。如果不能创建队列，将返回0。

 传递一个项目到队列

头文件：queue. H

portBASE_TYPE xQueueSend （

xQueueHandle xQueue， 将项目传进的队列

const void * pvItemToQueue， 项目的指针【源数据】

portTickType xTicksToWait 等待的最大时间量【时间使用滴答周期】

）;

说明：传递一个项目到队列。这个项目通过复制而不是通过引用排队。这个函数不能从中断服务程序调用。

注意：当队列满时，肯定传递不成功，则等待xTicksToWait 个滴答周期后再传递，但如果xTicksToWait 设置为0，调用将立即返回。

返回：pdTRUE：项目成功传递。否则为：errQUEUE_FULL.

 传递项目到一个队列中的后面

头文件：queue. H

portBASE_TYPE xQueueSendToBack （

xQueueHandle xQueue， 将项目传进的队列

const void * pvItemToQueue， 项目的指针【源数据】

portTickType xTicksToWait 等待的最大时间量

）;

说明：这个与xQueueSend 是一样的，参照xQueueSend 的用法

 从队列接收一个项目

头文件：queue. H

portBASE_TYPE xQueueReceive （

xQueueHandle xQueue， 发送项目的队列句柄

void *pvBuffer， 指向缓冲区的指针，将接收的项目被复制进去

portTickType xTicksToWait 任务中断并等待队列中可用空间的最大时间

）;

说明：这个项目通过复制接收，因此缓冲器必须提供足够大的空间。这个函数一定不能在中断服务程序中使用当队列空时，肯定复制传递不成功，则等待xTicksToWait 个滴答周期后再复制，但如果xTicksToWait 设置为0，调用将立即返回。

返回：如果项目成功被队列接收为pdTRUE ，否则为 pdFALSE。

 从中断传递一个项目到队列的后面

头文件：queue. H

portBASE_TYPE xQueueSendFromISR （

xQueueHandle pxQueue， 将项目传进的队列

const void *pvItemToQueue， 项目的指针【源数据】

portBASE_TYPE *pxHigherPriorityTaskWoken 因空间数据问题被挂起的任务是否解锁

）;

说明： 如果传进队列而导致因空间数据问题被挂起的任务解锁，并且解锁的任务的优先级高于当前运行任务，xQueueSendFromISR 将设置 *pxHigherPriorityTaskWoken 到 pdTRUE。当pxHigherPriorityTaskWoken被设置为pdTRUE 时，则在中断退出之前将请求任务切换。

返回：pdTRUE：数据成功传递进队列。否则为：errQUEUE_FULL。

 从中断传递项目到一个队列中的后面

头文件：queue. H

portBASE_TYPE xQueueSendToBackFromISR （

xQueueHandle pxQueue，

const void *pvItemToQueue，

portBASE_TYPE *pxHigherPriorityTaskWoken

）;

说明：参照xQueueSendFromISR

 从中断传递一个项到队列的前面

头文件：queue. H

portBASE_TYPE xQueueSendToFrontFromISR （

xQueueHandle pxQueue，

const void *pvItemToQueue，

portBASE_TYPE *pxHigherPriorityTaskWoken

）;

说明：参照xQueueSendFromISR

 中断时从队列接收一个项目

头文件：queue. H

portBASE_TYPE xQueueReceiveFromISR （

xQueueHandle pxQueue， 发送项目的队列句柄

void *pvBuffer， 指向缓冲区的指针，将接收的项目被复制进去

portBASE_TYPE *pxTaskWoken 任务将锁住，等待队列中的可用空间

）;

说明： 如果xQueueReceiveFromISR 引起一个任务解锁，*pxTaskWoken 将设置为pdTRUE，否则*pxTaskWoken保留不变

返回：pdTRUE ：如果项目成功从队列接收。否则为： pdFALSE

 为队列命名，并加入队列到登记管理中

头文件：queue.h

void vQueueAddToRegistry （

xQueueHandle xQueue， 将要添加登记的队列句柄

signed portCHAR *pcQueueName， 为指定的队列命名。 仅仅是文本串，方便调试。

）;

说明：队列登记有两个特点， 均与内核的相关调试有关：

允许文本式名字，使队列在调试GUI 中方便定义。

包含调试器需要的信息，如：定位每个已经登记的队列和信号量。

队列的登记没有目的，除非使用内核相关的调试。

configQUEUE_REGISTRY_SIZE 定义了队列和信号量的最大数目。仅当使用内核相关的调试时需要显示已经登记的信号量和队列。

 从登记管理中移除队列

头文件：queue.h

void vQueueUnregisterQueue （

xQueueHandle xQueue， 从登记管理处中移出的队列句柄

）;

说明：队列登记有两个特点， 均与内核的相关调试有关：

允许文本式名字，使队列在调试GUI 中方便定义。

包含调试器需要的信息，如：定位每个已经登记的队列和信号量。

队列的登记没有目的，除非使用内核相关的调试。

configQUEUE_REGISTRY_SIZE 定义了队列和信号量的最大数目。仅当使用内核相关的调试时需要显示已经登记的信号量和队列。