FreeRTOS--API函数
一、任务创建
1. xTaskCreate
task. h
portBASE_TYPE xTaskCreate(
pdTASK_CODE pvTaskCode,
const portCHAR * const pcName,
unsigned portSHORT usStackDepth,
void *pvParameters,
unsigned portBASE_TYPE uxPriority,
xTaskHandle *pvCreatedTask
);
创建新的任务并添加到任务队列中，准备运行
Parameters:
pvTaskCode | 指向任务的入口函数. 任务必须执行并且永不返回 (即：无限循环). |
pcName | 描述任务的名字。主要便于调试。最大长度由configMAX_TASK_NAME_LEN.定义 |
usStackDepth | 指定任务堆栈的大小 ，堆栈能保护变量的数目- 不是字节数. 例如，如果堆栈为16位宽度，usStackDepth定义为 100, 200 字节，这些将分配给堆栈。堆栈嵌套深度（堆栈宽度）不能超多最大值——包含了size_t类型的变量 |
pvParameters | 指针用于作为一个参数传向创建的任务 |
uxPriority | 任务运行时的优先级 |
pvCreatedTask | 用于传递一个处理——引用创建的任务 |
返回: pdPASS 是如果任务成功创建并且添加到就绪列中，另外错误代码在projdefs. H文件定义
2. vTaskDelete
task. h
void vTaskDelete( xTaskHandle pxTask );
INCLUDE_vTaskDelete必须定义为1，这个函数才能可用。查看配置部分获得更多信息。
从RTOS实时内核管理中移除任务。要删除的任务将从就绪，封锁，挂起，事件列表中移除。
注意：空闲任务负责释放内核分配给已删除任务的内存。因此，如果应用程序调用了vTaskDelete ()，微控制器执行时间，空闲任务不假死是很重要的。内存分配给任务的代码不会自动释放，应该在任务删除之前。
参数：
pxTask | 处理要删除的任务。传递NULL将引起调用任务删除 |
二、任务控制
3. vTaskDelay
task. h
void vTaskDelay( portTickType xTicksToDelay );
INCLUDE_vTaskDelay必须设置为1，这个函数才为可用。参考配置获得更多信息。
延时任务为已知时间片。任务被锁住剩余的实际时间由时间片率决定。portTICK_RATE_MS常量用来用来从时间片速率（一片周期代表着分辨率）来计算实际时间。
vTaskDelay()指定一个任务希望的时间段，这个时间之后（调用vTaskDelay() ）任务解锁。例如，指定周期段为100时间片，将使任务在调用vTaskDelay()100个时间片之后解锁。vTaskDelay()不提供一个控制周期性任务频率的好方法，像通过代码采取的路径，和其他任务和中断一样，在调用vTaskDelay()后 影响频率，因此任务所需的时间下一次执行。
参考 vTaskDelayUntil() ，这个交替的API函数设计了执行固定的频率。它是指定的一个绝对时间（而不是一个相对时间）后，调用任务解锁。
参数:
xTicksToDelay | 时间数量，调用任务应该锁住的时间片周期 |
4. vTaskDelayUntil
task. h
void vTaskDelayUntil( portTickType *pxPreviousWakeTime, portTickType xTimeIncrement );
INCLUDE_vTaskDelayUntil 必须定义为1，此函数才能用。参考配置获得更多信息。
延时一个任务到指定时间。这个函数用在循环任务以确保一定频率执行。这个函数在一个重要方面上不同于vTaskDelay()，vTaskDelay() 指定的这个时间（任务希望开启）是与vTaskDelay() 有关，而vTaskDelayUntil() 指定是一个绝对时间（任务希望开启） vTaskDelay()中断任务从调用这个函数开始到指定时间。很难使用vTaskDelay()自身来产生一个固定的执行频率，因为：随着调用vTaskDelay()一个任务开启的时间和任务下一次调用vTaskDelay()的时间，这两者之间可能不是固定的【任务可能采取不同方式，可能通过调用，可能来自中断，或者优先取得每次任务执行的时间】。 而vTaskDelay()指定的时间与调用这个函数相关，vTaskDelayUntil() 指定的是绝对时间(任务希望开启的)。
应该注意：vTaskDelayUntil() 如果指定的苏醒时间使用完，将立即返回。因此，一个使用vTaskDelayUntil() 来周期性的执行的任务，如果执行周期因为任何原因（例如任务是临时为悬挂状态）暂停而导致任务错过一个或多个执行周期，那么需要重新计算苏醒时间。通过检查像pxPreviousWakeTime可变的参数来组织当前时间片计数。然而在大多数使用中并不是必须的。 产量 portTICK_RATE_MS 用来计算时间片频率的实时时间- 按照一个时间片周期。
参数：
pxPreviousWakeTime | 指定一个变量来掌握任务最后开启的时间。这个变量在第一次使用中（参考下面的例子）必须使用当前时间来初始化。在vTaskDelayUntil()中，这个变量是自动修改的 |
xTimeIncrement | 循环周期时间。任务将在一定时间开启（*pxPreviousWakeTime + xTimeIncrement）。使用相同的xTimeIncrement参数值，来调用vTaskDelayUntil()将使任务按固定的周期执行。 |
5. uxTaskPriorityGet
task. h
unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle pxTask );
设置INCLUDE_vTaskPriorityGet 为1，此函数才能用。参考配置以获得更多信息。 获得任务的优先级。
参数：
pxTask | 需要处理的任务. 当传递NULL时，将返回所调用任务的优先级 |
Returns:
pxTask的优先级
6. vTaskPrioritySet
task. h
void vTaskPrioritySet( xTaskHandle pxTask, unsigned portBASE_TYPE uxNewPriority );
设置INCLUDE_vTaskPrioritySet为1，才能使用此函数。参考配置获得更多信息。 设置任务的优先级。 如果设置的优先级高于当前执行任务的优先级，则上下文切换将在此函数返回之前发生。
参数：
pxTask | 需要设置优先级的任务。当传递NULL，将设置调用任务的优先级 |
uxNewPriority | 任务需要设置的优先级 |
7. vTaskSuspend
task. h
void vTaskSuspend( xTaskHandle pxTaskToSuspend );
设置INCLUDE_vTaskSuspend 为1，此函数才能使用。参考配置获得更多信息。 挂起任务，当挂起一个任务时，不管优先级是多少，不需要占用任何微控制器处理器时间。调用vTaskSuspend不会累积——即：在统一任务中调用vTaskSuspend两次，但只需调用一次vTaskResume () 来是挂起的任务就绪。
参数：
pxTaskToSuspend | 处理需要挂起的任务。传递NULL将挂起调用此函数的任务。 |
8. vTaskResume
task. h
void vTaskResume( xTaskHandle pxTaskToResume );
设置INCLUDE_vTaskSuspend为1，此函数才能使用。参考配置获得更多信息。
唤醒挂起的任务。 必须是调用 vTaskSuspend () 后挂起的任务，才有可能通过调用 vTaskResume ()重新运行。
Parameters:
pxTaskToResume | 就绪的任务的句柄 |
9. vTaskResumeFromISR
task. h
portBASE_TYPE vTaskResumeFromISR( xTaskHandle pxTaskToResume );
设置INCLUDE_vTaskSuspend和INCLUDE_xTaskResumeFromISR都为1，才能使用此函数。参考配置获得更过信息。从ISR中唤醒挂起的任务。可能通过多个 调用vTaskSuspend()挂起的任务，可以通过调用 xTaskResumeFromISR()再次运行。vTaskResumeFromISR()不应该用于任务和中断同步，因为可能会在中断发生期间，任务已经挂起——这样导致错过中断。使用信号量最为同步机制将避免这种偶然性。
参数：
pxTaskToResume | 就绪任务的句柄 |
Returns:
pdTRUE： 如果唤醒了任务将，引起上下文切换。 pdFALSE.：用于ISR确定是否上下文切换 |
10. vTaskSetApplicationTaskTag
task. h
void vTaskSetApplicationTaskTag( xTaskHandle xTask, pdTASK_HOOK_CODE pxTagValue );
onfigUSE_APPLICATION_TASK_TAG必须定义为1，这个函数才能可用。参考配置获得更多信息。能为每个任务分配标签值。这个值仅在应用程序中使用，内核本身不使用它。 RTOS trace macros文档提供了一个很好的例子——应用程序如何利用这个特点。
参数:
xTask | 将分配给标签值的任务。传递NULL将分配标签给调用的任务。 |
pxTagValue | 分配给任务的标签值 类型为 pdTASK_HOOK_CODE ， 允许一个函数指针赋值给标签。因此实际上任何值都可以分配。参考下面的例子。 |
xTaskCallApplicationTaskHook
task. H
#define traceTASK_SWITCHED_OUT() xTaskCallApplicationTaskHook( pxCurrentTCB, 0 )
portBASE_TYPE xTaskCallApplicationTaskHook( xTaskHandle xTask, void *pvParameter );
configUSE_APPLICATION_TASK_TAG必须设置为1，这个函数才能使用。参考配置获得更多信息。
每个任务可以分配一个标签值。正常情况下，这个值仅用于应用程序，内核并不存储。然而，可以使用标签赋值给钩子（或回调）函数给任务——钩子函数将通过调用xTaskCallApplicationTaskHook()执行。每个任务定义自己的返回值，或者仅仅定义一个返回值。尽管可以使用第一个函数参数来调用任务中的钩子函数，最常见的使用是任务钩子函数——描述钩子宏，像每个如下的例子。任务钩子函数必须使用pdTASK_HOOK_CODE类型，传递void *参数，和返回portBASE_TYPE类型的值。Void *参数用来传递给钩子函数的任何信息。
参数:
xTask | 处理将被调用钩子函数的任务。xTask当作NULL传递，将调用钩子函数赋值给当前执行的任务 |
pvParameter | 传递给钩子函数的值。可以是指向结构或数值的指针 |
三、内核控制
11. vTaskStartScheduler
task. h
void vTaskStartScheduler( void );
启动实时内核处理。在调用之后，内核已经控制执行的任务。当 vTaskStartScheduler() 被调用时，空闲任务自动创建。如果 vTaskStartScheduler() 成功调用，这个函数不返回，直到执行任务调用vTaskEndScheduler()。如果可供给空闲任务的RAM不足，那么函数调用失败，并立即返回。
12. vTaskEndSchedule
task. h
void vTaskEndScheduler( void );
停止实时内核运行。所有创建的任务将自动删除，并且多任务（优先级或合作式）将停止。当vTaskStartScheduler()调用时，执行将再次开始，像vTaskStartScheduler()仅仅返回。在演示或PC路径的例子中，参考演示应用程序文件main.c，例子中使用vTaskEndScheduler ()。vTaskEndScheduler ()需要在便携层定义出口函数（参考在port.c提供PC接口的vPortEndScheduler () ）。执行硬件指定操作如停止内核执行。vPortEndScheduler () 导致所有由内核分配的资源释放——但是不会释放由应用程序的任务分配的资源。
13. vTaskSuspendAll
task. h
void vTaskSuspendAll( void );
挂起所有活动的实时内核，同时允许中断（包括内核滴答）。任务在调用vTaskSuspendAll ()后，这个任务将继续执行，不会有任何被切换的危险，直到调用xTaskResumeAll ()函数。API中有可能影响影响上下文切换的函数（例如，vTaskDelayUntil(), xQueueSend()等等），一定不能再调度器挂起时被调用。
四、队列管理
14. xQueueCreate[队列管理]
queue. h
xQueueHandle xQueueCreate(
unsigned portBASE_TYPE uxQueueLength,
unsigned portBASE_TYPE uxItemSize
);
创建一个新的队列。为新的队列分配所需的存储内存，并返回一个队列处理。
Parameters:
uxQueueLength | 队列中包含最大项目数量。 |
uxItemSize | 队列中每个项目所需的字节数。项目通过复制而不是引用排队，因为，所需的字节数，将复制给每个项目。队列中每个项目必须分配同样大小。 |
Returns:
如果队列成功创建，并返回一个新建队列的处理。
如果不能创建队列，将返回0。
15. xQueueSend[队列管理]
queue.h
portBASE_TYPE xQueueSend(
xQueueHandle xQueue,
const void * pvItemToQueue,
portTickType xTicksToWait
);
是一个调用xQueueGenericSend()的宏。能向后兼容FreeRTOS.org（没有包括xQueueSendToFront()和
xQueueSendToBack() 宏的）版本。与xQueueSendToBack()等效。 传递一个项目到队列。这个项目通过复制而不是通过引用排队。这个函数不能从中断服务程序调用。参考xQueueSendFromISR()，在ISR中交错使用。xQueueSend() 是全特点任务间通信API接口。xQueueSend() 等效于交叉API。版本不要同样的参数和同样的返回值。
Parameters:
xQueue | 处理将项目传递给队列 |
pvItemToQueue | 指向队列中放置的项目的指针。项目的大小，由队列创建时定义，因为许多字节可以从 pvItemToQueue复制到队列的储存区域 |
xTicksToWait | 最大时间量（任务应该锁住，等待队列中的可用空间）应该已经满了。如果设置为0，调用将立即返回。时间使用滴答周期来定义，因此如果需要，常量portTICK_RATE_MS应该用来转换实时时间 |
Returns:
pdTRUE：项目成功传递。
否则为：errQUEUE_FULL.
16. xQueueSendToBack[队列管理]
Only available from FreeRTOS.org V4.5.0 onwards.
queue.h
portBASE_TYPE xQueueSendToBack(
xQueueHandle xQueue,
const void * pvItemToQueue,
portTickType xTicksToWait
);
是一个调用xQueueGenericSend()的宏。相当于xQueueSend()。传递项目到一个队列中的后面。这个项是复制队列，不是引用。这个函数不能被中断服务函数调用。参考xQueueSendToBackFromISR ()，可以在ISR中交替使用。 xQueueSendToBack()是全功能任务间通信API接口。xQueueAltSendToBack()相当于API其中之一。版本需要相同的参数和相同的返回值 。
参数:
xQueue | 将要传进的队列句柄 |
pvItemToQueue | 指向将要放进队列的项目。项目的大小由队列定义（队列创建时），许多字节从 pvItemToQueue复制到队列存储区域 |
xTicksToWait | 任务中断并等待队列中可用空间的最大时间，应该是满的。如果设置为0，调用将立刻返回。时间在片区间中定义，如果需要，portTICK_RATE_MS常量用来转换为实际时间。 如果 INCLUDE_vTaskSuspend 定义为1 ，指定的中断时间（ portMAX_DELAY） 将导致任务无限期中断（没有时间溢出）。 |
Returns:
pdTRUE 如果任务成功传递。
否则为 errQUEUE_FULL.
17. xQueueSendToFront[队列管理]
仅适用于FreeRTOS.org V4.5.0 以前版本
queue.h
portBASE_TYPE xQueueSendToToFront(
xQueueHandle xQueue,
const void * pvItemToQueue,
portTickType xTicksToWait
);
是一个调用xQueueGenericSend()的宏。传递项目到一个队列中的前面。这个项是复制队列，不是引用。这个函数不能被中断服务函数调用。参考xQueueSendToBackFromISR ()，可以在ISR中交替使用。xQueueSendToFront() 是全功能任务间通信API接口。xQueueAltSendToFront() 相当于API其中之一。版本需要相同的参数和相同的返回值。
Parameters:
xQueue | 将要传进的队列句柄 |
pvItemToQueue | 指向将要放进队列的项目。项目的大小由队列定义（队列创建时），许多字节从 pvItemToQueue复制到队列存储区域 |
xTicksToWait | 任务中断并等待队列中可用空间的最大时间，应该是满的。如果设置为0，调用将立刻返回。时间在片区间中定义，如果需要，portTICK_RATE_MS常量用来转换为实际时间。 如果 INCLUDE_vTaskSuspend 定义为1 ，指定的中断时间（ portMAX_DELAY） 将导致任务无限期中断（没有时间溢出）。 |
Returns:
pdTRUE 如果任务成功传递。 否则为 errQUEUE_FULL.
18. xQueueReceive[队列管理]
queue. h
portBASE_TYPE xQueueReceive(
xQueueHandle xQueue,
void *pvBuffer,
portTickType xTicksToWait
);
一个调用 xQueueGenericReceive()函数的宏。从队列接收一个项目。这个项目通过复制接收，因此缓冲器必须提供足够大的空间。复制进缓冲器的字节数，在队列创建时已经定义。这个函数一定不能在中断服务程序中使用。参考xQueueReceiveFromISR获得能够的选择。xQueueReceive()是全功能任务间通信API接口。xQueueAltReceive() 相当于API其中之一。版本需要相同的参数和相同的返回值。
参数：
pxQueue | 将要接收项目的队列句柄 |
pvBuffer | 指向将要复制接收项目的缓冲器的指针。 |
xTicksToWait | 任务中断并等待队列中可用空间的最大时间，应该是满的。如果设置为0，调用将立刻返回。时间在片区间中定义，如果需要，portTICK_RATE_MS常量用来转换为实际时间。 如果 INCLUDE_vTaskSuspend 定义为1 ，指定的中断时间（ portMAX_DELAY） 将导致任务无限期中断（没有时间溢出）。 |
Returns:
如果项目成功被队列接收为pdTRUE 。 否则为 pdFALSE.
19. xQueuePeek[队列管理]
Only available from FreeRTOS.org V4.5.0 onwards.
queue.h
portBASE_TYPE xQueuePeek(
xQueueHandle xQueue,
void *pvBuffer,
portTickType xTicksToWait
);
一个调用 xQueueGenericReceive()函数的宏。从队列接收一个项目并从队列中移除该项目。这个项目通过复制接收，因此缓冲器必须提供足够大的空间。复制进缓冲器的字节数，在队列创建时已经定义。成功接收的项目在队列中保留，再下次调用时将再次返回，或者调用xQueueReceive() 这个函数一定不能在中断服务程序中使用。 xQueuePeek() 是全功能任务间通信API接口。xQueueAltPeek() 相当于API其中之一。版本需要相同的参数和相同的返回值。
参数：
xQueue | 将要接收项目的队列的句柄 |
pvBuffer | 指向将要复制接收项目的缓冲器的指针。项目的大小由队列定义（队列创建时），许多字节从 pvItemToQueue复制到队列存储区域 |
xTicksToWait | 任务中断并等待队列中可用空间的最大时间，应该是满的。如果设置为0，调用将立刻返回。时间在片区间中定义，如果需要，portTICK_RATE_MS常量用来转换为实际时间。 如果 INCLUDE_vTaskSuspend 定义为1 ，指定的中断时间（ portMAX_DELAY） 将导致任务无限期中断（没有时间溢出）。 |
返回值：
pdTRUE 如果项目成功被队列接收。
否则为 pdFALSE.
20. xQueueSendFromISR[队列管理]
queue.h
portBASE_TYPE xQueueSendFromISR(
xQueueHandle pxQueue,
const void *pvItemToQueue,
portBASE_TYPE *pxHigherPriorityTaskWoken
);
这是一个调用xQueueGenericSendFromISR()的宏。是为了兼容FreeRTOS.org以后的版本（没有包含xQueueSendToBackFromISR() 和 xQueueSendToFrontFromISR() 宏）传递一个项到队列的后面。在终端服务程序中可以安全使用。项在队列中是复制而不是引用，排列小项目更加灵活，特别是当从ISR调用时。在大多数情况下，使用一个指向项目的指针传进队列更加灵活
参数:
xQueue | 将项目传进的队列 |
pvItemToQueue | 一个指向将在队列中放置的项目的指针。项目的大小，队列在创建时已经定义了， 将从pvItemToQueue复制许多字节到队列的存储区域 |
pxHigherPriorityTaskWoken | 如果传进队列而导致任务解锁，并且解锁的任务的优先级高于当前运行任务的优先级xQueueSendFromISR将设置 *pxHigherPriorityTaskWoken到 pdTRUE 。如果xQueueSendFromISR()设置这个值到 pdTRUE，在中断推出之前将请求任务切换。 |
Returns:
pdTRUE：数据成功传递进队列。
否则为：errQUEUE_FULL。使用范例是缓冲IO（每次调用ISR能够更多的值）
21. xQueueSendToBackFromISR[队列管理]
queue.h
portBASE_TYPE xQueueSendToBackFromISR(
xQueueHandle pxQueue,
const void *pvItemToQueue,
portBASE_TYPE *pxHigherPriorityTaskWoken
);
这是一个调用 xQueueGenericSendFromISR()的宏。是为了兼容FreeRTOS.org以后的版本（没有包含xQueueSendToBackFromISR() 和 xQueueSendToFrontFromISR() 宏） 传递一个项到队列的后面。在终端服务程序中可以安全使用。项在队列中是复制而不是引用，排列小项目更加灵活，特别是当从ISR调用时。在大多数情况下，使用一个指向项目的指针传进队列更加灵活。.
参数：
xQueue | 将项目传进的队列 |
pvItemToQueue | 一个指向将在队列中放置的项目的指针。项目的大小，队列在创建时已经定义了， 将从pvItemToQueue复制许多字节到队列的存储区域 |
xTaskPreviouslyWoken | 如果传进队列而导致任务解锁，并且解锁的任务的优先级高于当前运行任务的优先级xQueueSendFromISR将设置 *pxHigherPriorityTaskWoken到 pdTRUE 。如果xQueueSendFromISR()设置这个值到 pdTRUE，在中断推出之前将请求任务切换。 |
Returns:
pdTRUE：数据成功传递进队列。
否则为：errQUEUE_FULL。使用范例是缓冲IO（每次调用ISR能够更多的值）
22. xQueueSendToFrontFromISR[队列管理]
queue.h
portBASE_TYPE xQueueSendToFrontFromISR(
xQueueHandle pxQueue,
const void *pvItemToQueue,
portBASE_TYPE *pxHigherPriorityTaskWoken
);
是一个调用xQueueGenericSendFromISR().的宏。传递一个项到队列的后面。在终端服务程序中可以安全使用。
项在队列中是复制而不是引用，排列小项目更加灵活，特别是当从ISR调用时。
参数：
xQueue | 将项目传进的队列 |
pvItemToQueue | 一个指向将在队列中放置的项目的指针。项目的大小，队列在创建时已经定义了， 将从pvItemToQueue复制许多字节到队列的存储区域 |
xTaskPreviouslyWoken | 如果传进队列而导致任务解锁，并且解锁的任务的优先级高于当前运行任务的优先级xQueueSendTobackFromISR() 将设置 *pxHigherPriorityTaskWoken到 pdTRUE 。如果xQueueSendToBackFromISR()设置这个值到 pdTRUE，在中断推出之前将请求任务切换。 |
Returns:
pdTRUE：数据成功传递进队列。否则为：errQUEUE_FULL。使用范例是缓冲IO（每次调用ISR能够更多的值）
23. xQueueReceiveFromISR[队列管理]
queue. h
portBASE_TYPE xQueueReceiveFromISR(
xQueueHandle pxQueue,
void *pvBuffer,
portBASE_TYPE *pxTaskWoken
);
从队列接收一个项目。在中断程序中使用此函数是安全的。
Parameters:
pxQueue | 发送项目的队列句柄 |
pvBuffer | 指向缓冲区的指针，将接收的项目被复制进去。 |
pxTaskWoken | 任务将锁住，等待队列中的可用空间。如果xQueueReceiveFromISR 引起一个任务解锁，*pxTaskWoken 将设置为pdTRUE，否则*pxTaskWoken保留不变 |
Returns:
pdTRUE ：如果项目成功从队列接收。
否则为： pdFALSE
24. vQueueAddToRegistry[队列管理]
queue.h
void vQueueAddToRegistry(
xQueueHandle xQueue,
signed portCHAR *pcQueueName,
);
为队列命名，并加入队列到登记管理中
Parameters:
xQueue | 将要添加登记的队列句柄 |
pcQueueName | 为指定的队列命名。 仅仅是文本串，方便调试。 |
队列登记有两个特点， 均与内核的相关调试有关：
允许文本式名字，使队列在调试GUI中方便定义。
包含调试器需要的信息，如：定位每个已经登记的队列和信号量。
队列的登记没有目的，除非使用内核相关的调试。configQUEUE_REGISTRY_SIZE定义了队列和信号量的最大数目.仅当使用内核相关的调试时需要显示已经登记的信号量和队列。
25. vQueueUnregisterQueue[队列管理]
queue.h
void vQueueUnregisterQueue(
xQueueHandle xQueue,
);
从登记管理中移除队列。
Parameters:
xQueue | 从登记管理处中移出的队列句柄 |
队列登记有两个特点， 均与内核的相关调试有关：
允许文本式名字，使队列在调试GUI中方便定义。
包含调试器需要的信息，如：定位每个已经登记的队列和信号量。
队列的登记没有目的，除非使用内核相关的调试。configQUEUE_REGISTRY_SIZE定义了队列和信号量的最大数目.仅当使用内核相关的调试时需要显示已经登记的信号量和队列。
五、信号量
26. xSemaphoreCreateCounting[信号量]
semphr. h
xSemaphoreHandle xSemaphoreCreateCounting( unsigned portBASE_TYPE uxMaxCount, unsigned portBASE_TYPE uxInitialCount )
使用已存在的队列结构来创建计数型信号量。计数型信号量有下面两种典型应用：
1 事件计数
在这种应用的情形下，事件处理程序会在每次事件发生时发送信号量（增加信号量计数值），而任务处理程序会在每次处理事件时请求信号量（减少信号量计数值）。因此计数值为事件发生与事件处理两者间的差值，在这种情况下计数值初始化为0是合适的。
2 资源管理
在这种应用情形下，计数值指示出可用的资源数量。任务必须首先“请求”信号量来获得资源的控制权--减少信号量计数值。当计数值降为0时表示没有空闲资源。任务使用完资源后“返还”信号量--增加信号量计数值。在这种情况下计数值初始化为与最大的计数值相一致是合适的，这指示出所有的空闲资源。
参数：
uxMaxCount | 可以达到的最大计数值。当信号量达到此值后将不能被“返还”。 |
uxInitialCount | 信号量创建时分配的初始值。 |
返回：
已创建的信号量句柄，为xSemaphoreHandle类型，
如果信号量无法创建则为NULL。
27. xSemaphoreCreateMutex[信号量]
只在FreeRTOS.org V4.5.0以后的版本中可用。
semphr. h
xSemaphoreHandle xSemaphoreCreateMutex( void )
使用已存在的队列结构来创建互斥锁信号量的宏。通过此宏创建的互斥锁可以使用xSemaphoreTake()与 xSemaphoreGive()宏来访问。不能使用xSemaphoreTakeRecursive()与 xSemaphoreGiveRecursive()宏。二元信号量与互斥锁十分相像，不过两者间有细微的差别：互斥锁包含一个优先级继承机制，而信号量没有。这种差别使得二元信号量更适合于实现同步（任务之间或任务与中断之间），互斥锁更适合于实现简单的互斥。当有另外一个具有更高优先级的任务试图获取同一个互斥锁时，已经获得互斥锁的任务的优先级会被提升。已经获得互斥锁的任务将继承试图获取同一互斥锁的任务的优先级。这意味着互斥锁必须总是要返还的，否则高优先级的任务将永远也不能获取互斥锁，而低优先级的任务将不会放弃优先级的继承。 xSemaphoreTake()页中提供了互斥锁用于互斥的范例。
二元信号量并不需要在得到后立即释放，因此任务同步可以通过一个任务/中断持续释放信号量而另外一个持续获得信号量来实现。xSemaphoreGiveFromISR()页中有此种方式的实现范例。互斥锁与二元信号量均赋值为xSemaphoreHandle类型，并且可以在任何此类型参数的API函数中使用。
Return:
已创建的信号量句柄，需要为xSemaphoreHandle类型. |
28. xSemaphoreCreateRecursiveMutex[信号量]
semphr. h
xSemaphoreHandle xSemaphoreCreateRecursiveMutex( void )
使用已存在的队列结构来创建递归互斥锁的宏。通过此宏创建的互斥锁可以使用xSemaphoreTakeRecursive()与 xSemaphoreGiveRecursive()宏 来访问。不能使用xSemaphoreTake()与 xSemaphoreGive()宏。一个递归的互斥锁可以重复地被其所有者“获取”。在其所有者为每次的成功“获取”请求调用xSemaphoreGiveRecursive()前，此互斥锁不会再次可用。例如，如果一个任务成功“获取”同一个互斥锁5次，则在其“释放”互斥锁恰好为5次后，其他任务才可以使用此互斥锁。这种类型的信号量使用一个优先级继承机制，因此已取得信号量的任务“必须总是”在不再需要信号量时立刻“释放”。互斥类型的信号量不能在中断服务程序中使用。可以参考vSemaphoreCreateBinary()来获得一个二选一运行的实现方式，可以在中断服务程序中实现纯粹的同步（一个任务或中断总是“释放”信号量，而另一个总是“获取”信号量）。
返回：
已创建的互斥锁信号量句柄，需要为xSemaphoreHandle类型.
29. xSemaphoreTake[信号量]
semphr. h
xSemaphoreTake(
xSemaphoreHandle xSemaphore,
portTickType xBlockTime
)
用于获取信号量的宏。信号量必须已经通过调用vSemaphoreCreateBinary(), xSemaphoreCreateMutex() 或 xSemaphoreCreateCounting()来创建。这个宏不能在服务中断程序中调用。如果有必要，可以调用xQueueReceiveFromISR() 来在中断服务程序中获取信号量，虽然这并不是一种正规的操作。xSemaphoreTake() 是一个全功能任务间通讯API， xSemaphoreAltTake() 是其等价的替代API 。这两个版本均需要同样的参数并返回同样的值。
Parameters:
xSemaphore | 将被获得的信号量句柄，此信号量必须已经被创建 |
xBlockTime | 等待信号量可用的时钟滴答次数，可以使用 portTICK_RATE_MS宏来转换为实际的时间 。当为0时可以用于 对信号量进行轮询（poll the semaphore） 如果INCLUDE_vTaskSuspend置位“1”，则指定xBlockTime为 portMAX_DELAY会导致任务阻塞时间不确定（不会超时） |
返回：
如果成功获取信号量则返回pdTRUE，
如果xBlockTime超时而信号量还未可用则返回pdFALSE。
30. xSemaphoreTakeRecursive[信号量]
semphr. h
xSemaphoreTakeRecursive( xSemaphoreHandle xMutex, portTickType xBlockTime )
用于递归获得互斥锁信号量的宏。此互斥锁必须已经通过调用xSemaphoreCreateRecursiveMutex()来创建。 FreeRTOSConfig.h中的configUSE_RECURSIVE_MUTEXES 必须设置为1才可以使用此宏。此宏不能用于由xSemaphoreCreateMutex()函数创建的信号量。一个递归型的互斥锁可以被其所有者重复地“获取”，一个递归的互斥锁可以重复地被其所有者“获取”。在其所有者为每次成功的“获取”请求调用 xSemaphoreGiveRecursive()前，此互斥锁不会再次可用。例如，如果一个任务成功“获取”同一个互斥锁5次，则在其“释放”互斥锁 恰好为5次后，其他任务才可以使用此互斥锁。
参数：
xMutex | 将被获得的互斥锁句柄，此句柄由xSemaphoreCreateRecursiveMutex()返回。 |
xBlockTime | 等待信号量可用的时钟滴答次数，可以使用 portTICK_RATE_MS宏来转换为实际的时间 。当为0时可以用于 对信号量进行轮询（poll the semaphore）。如果任务已经拥有此信号量则函数将立刻返回，而不管xBlockTime为何值。 |
返回值：
如果成功获取信号量则返回pdTRUE，
如果xBlockTime超时而信号量还未可用则返回pdFALSE。
31. xSemaphoreGive[信号量]
semphr. h
xSemaphoreGive( xSemaphoreHandle xSemaphore )
用于释放信号量的宏。这个信号量必须已经通过调用vSemaphoreCreateBinary()， xSemaphoreCreateMutex() 或 xSemaphoreCreateCounting()创建，并且使用sSemaphoreTake()获取。这个宏不能在中断服务程序中使用。参考xSemaphoreGiveFromISR()获取一个在中断中使用的替代。这个宏也不能应用于由xSemaphoreCreateRecursiveMutex()创建的信号量。xSemaphoreGive()是一个全功能任务间通讯API。xSemaphoreAltGive() 是其等价的替代API。这两个版本均需要相同的参数，并返回相同的值。
参数：
xSemaphore | 即将释放的信号量的句柄，在信号量创建是返回。 |
返回值：
如果信号量成功释放返回pdTRUE，如果发生错误则返回pdFALSE。信号量使用的是队列，因此如果队列没有位置用于发送消息就会发生一个错误——说明开始时没有正确获取信号量。
32. xSemaphoreGiveRecursive[信号量]
semphr. h
xSemaphoreGiveRecursive( xSemaphoreHandle xMutex )
用于递归释放，或‘返还’，互斥锁信号量的宏。这个互斥锁必须已经通过调用xSemaphoreCreateRecursiveMutex()来创建；FreeRTOSConfig.h文件中的configUSE_RECURSIVE_MUTEXES 必须设置为1来是此宏可用。 这个宏不能用与由xSemaphoreCreateMutex().创建的互斥锁。递归的互斥锁可以被其所有者重复地‘获取’，在其所有者为每次的成功“获取”请求调用xSemaphoreGiveRecursive()前，此互斥锁不会再次可用。例如，如果一个任务成功“获取”同一个互斥锁5次，则在其“释放”互斥锁恰好为5次后，其他任务才可以使用此互斥锁。
Parameters:
xMutex | 将被释放或‘返还’的互斥锁的句柄，由 xSemaphoreCreateRecursiveMutex()返回。 |
Returns:
如果信号量成功释放则为pdTRUE
33. xSemaphoreGiveFromISR[信号量]
semphr. h
xSemaphoreGiveFromISR(
xSemaphoreHandle xSemaphore,
portBASE_TYPE *pxHigherPriorityTaskWoken
)
用于释放一个信号量的宏。释放的信号量必须已经通过vSemaphoreCreateBinary() 或 xSemaphoreCreateCounting()函数创建。互斥信号量（通过 xSemaphoreCreateMutex()函数创建）不能使用此宏。此宏可以在中断服务程序中使用。
参数：
xSemaphore | 将被释放的信号量的句柄，此句柄在信号量创建时返回。 |
pxHigherPriorityTaskWoken | 如果释放此信号量会导致一个比当前任务具有更高优先级的任务解除阻塞，xSemaphoreGiveFromISR() 函数将设置*pxHigherPriorityTaskWoken为pdTRUE。如果xSemaphoreGiveFromISR() 函数将其置为pdTRUE，则必须在离开中断前进行上下文切换。 |
返回：
如果信号量成功释放则返回pdTRUE，
否则返回errQUEUE_FULL。
六、联合程序
34. xCoRoutineCreate[联合程序]
croutine.h
portBASE_TYPE xCoRoutineCreate(
crCOROUTINE_CODE pxCoRoutineCode,
unsigned portBASE_TYPE uxPriority,
unsigned portBASE_TYPE uxIndex
);
创建一个新的联合程序并且将其增加到联合程序的就绪列表中
参数：
pxCoRoutineCode | 联合程序函数的指针。联合程序函数需要使用特定的语法——参考联合程序部分获取更多信息。 |
uxPriority | 优先级，用于与其他联合程序确定哪个将运行 |
uxIndex | 当不同的联合程序使用同一个函数来运行时用于相互识别。参考下面的例子以及联合程序部分获取更多信息。 |
Returns:
如果联合程序成功创建并增加到就绪列表中则返回pdPASS，否则返回ProjDefs.h中定义的错误代码。
xCoRoutineHandle用于引用联合程序的类型，联合程序函数句柄可以自动的传入每一个使用联合程序的函数。
35. xCoRoutineCreate[联合程序]
croutine.h
portBASE_TYPE xCoRoutineCreate(
crCOROUTINE_CODE pxCoRoutineCode,
unsigned portBASE_TYPE uxPriority,
unsigned portBASE_TYPE uxIndex
);
创建一个新的联合程序并且将其增加到联合程序的就绪列表中
参数：
pxCoRoutineCode | 联合程序函数的指针。联合程序函数需要使用特定的语法——参考联合程序部分获取更多信息。 |
uxPriority | 优先级，用于与其他联合程序确定哪个将运行 |
uxIndex | 当不同的联合程序使用同一个函数来运行时用于相互识别。参考下面的例子以及联合程序部分获取更多信息。 |
Returns:
如果联合程序成功创建并增加到就绪列表中则返回pdPASS，否则返回ProjDefs.h中定义的错误代码。
xCoRoutineHandle用于引用联合程序的类型，联合程序函数句柄可以自动的传入每一个使用联合程序的函数。
36. crDELAY[联合程序]
croutine.h
void crDELAY( xCoRoutineHandle xHandle, portTickType xTicksToDelay )
crDELAY 是一个宏，上面原型的数据类型只作为参考。把一个联合程序延时一个特定的时间。crDELAY只能在联合程序函数自身内部使用——不能在联合程序函数调用的一个函数内部使用。这是因为联合函数没有维护自身的堆栈。
Parameters:
xHandle | 要延时的联合程序的句柄，这是联合程序函数的xHandle参数。 |
xTickToDelay | 联合程序要延时的时间片数。实际的时间相当于configTICK_RATE_HZ (位于 FreeRTOSConfig.h)。可以使用 portTICK_RATE_MS 来转换为毫秒。 |
37. crQUEUE_SEND[联合程序]
croutine.h
crQUEUE_SEND(
xCoRoutineHandle xHandle,
xQueueHandle pxQueue,
void *pvItemToQueue,
portTickType xTicksToWait,
portBASE_TYPE *pxResult
)
crQUEUE_SEND是一个宏，上面原型中的数据类型只用作参考。联合程序中使用的crQUEUE_SEND() 与 crQUEUE_RECEIVE()宏等价于任务中的xQueueSend() 与 xQueueReceive()函数。crQUEUE_SEND 与 crQUEUE_RECEIVE 只能被联合程序使用，而xQueueSend() 与 xQueueReceive()只能被任务使用。注意：联合程序只能向其他联合程序发送数据。联合程序不能使用队列来发送向任务发送数据，反之亦然。crQUEUE_SEND只能在联合程序函数内部访问——不能再联合程序函数调用的函数中使用，这是因为联合函数没有维护自身的堆栈。
参考联合程序部分获取关于任务与联合程序或中断服务程序与联合程序间传递数据的信息。
参数：
xHandle | 调用的联合程序的句柄，这是联合程序函数的xHandle参数。 |
pxQueue | 数据将被发送到的队列的句柄，这是队列使用 xQueueCreate() API 函数创建时的返回值。 |
pvItemToQueue | 将被发送到队列的数据的指针。队列中每个条目的数据量在队列创建是已指定，这个数量的字节数据将从pvItemToQueue中复制到队列。 |
xTickToDelay | 如果此刻队列没有可用空间，此值为联合程序用于阻塞等待队列空间可用的时间片数。实际的时间相当于configTICK_RATE_HZ (位于 FreeRTOSConfig.h)。可以使用 portTICK_RATE_MS 来转换为毫秒。 |
pxResult | 一个指向pxResult变量的指针，如果数据成功发送到队列就会被设置为pdPASS，否则设置为 ProjDefs.h中定义的错误码。 |
38. crQUEUE_RECEIVE[联合程序]
croutine.h
void crQUEUE_RECEIVE(
xCoRoutineHandle xHandle,
xQueueHandle pxQueue,
void *pvBuffer,
portTickType xTicksToWait,
portBASE_TYPE *pxResult
)
crQUEUE_RECEIVE 是一个宏。上面原型的数据类型只用作参考。联合程序中使用的crQUEUE_SEND() 与 crQUEUE_RECEIVE()宏等价于任务中的xQueueSend() 与 xQueueReceive()函数。crQUEUE_SEND 与 crQUEUE_RECEIVE 只能被联合程序使用，而xQueueSend() 与 xQueueReceive()只能被任务使用。注意：联合程序只能向其他联合程序发送数据。联合程序不能使用队列来发送向任务发送数据，反之亦然。crQUEUE_RECEIVE 只能在联合程序函数内部访问——不能再联合程序函数调用的函数中使用，这是因为联合函数没有维护自身的堆栈。 参考联合程序部分获取关于任务与联合程序或中断服务程序与联合程序间传递数据的信息。
参数：
xHandle | 调用的联合程序的句柄，这是联合程序函数的xHandle参数。 |
pxQueue | 数据将从其中接收的队列的句柄，这是队列使用 xQueueCreate() API 函数创建时的返回值。 |
pvBuffer | 用于复制接收到的条目的缓冲区，队列中每个条目的数据量在队列创建是已指定，这个数量的字节数据将复制到缓冲区。 |
xTickToDelay | 如果此刻队列没有可用空间，此值为联合程序用于阻塞等待队列空间可用的时间片数。实际的时间相当于configTICK_RATE_HZ (位于 FreeRTOSConfig.h)。可以使用 portTICK_RATE_MS 来转换为毫秒。 |
pxResult | 一个指向pxResult变量的指针，如果数据成功发送到队列就会被设置为pdPASS，否则设置为 ProjDefs.h中定义的错误码。 |
39. crQUEUE_SEND_FROM_ISR[联合程序]
croutine.h
portBASE_TYPE crQUEUE_SEND_FROM_ISR(
xQueueHandle pxQueue,
void *pvItemToQueue,
portBASE_TYPE xCoRoutinePreviouslyWoken
)
crQUEUE_SEND_FROM_ISR() 是一个宏。上面原型的数据类型只用作参考。联合程序中使用的crQUEUE_SEND_FROM_ISR() 与 crQUEUE_RECEIVE_FROM_ISR()宏等价于任务中的xQueueSendFromISR()与 xQueueReceiveFromISR()函数。crQUEUE_SEND_FROM_ISR() 与 crQUEUE_RECEIVE_FROM_ISR() 只能用于联合程序与中断服务程序之间传递数据，同样道理，xQueueSendFromISR() 与 xQueueReceiveFromISR() 只能用于任务与中断服务程序间传递数据。crQUEUE_SEND_FROM_ISR 只能在一个向队列发送数据的中断服务程序中调用，并且此队列在一个联合程序中使用。参考联合程序部分获取关于任务与联合程序或中断服务程序与联合程序间传递数据的信息。
参数：
xQueue | 将发送到的队列的句柄。 |
pvItemToQueue | 将被发送到队列的条目的指针。队列中每个条目的数据量在队列创建是已指定，这个数量的字节数据将从pvItemToQueue中复制到队列的储存空间。 |
xCoRoutinePreviouslyWoken | 包含此项使得一个中断服务程序可以在一次中断中多次向同一个队列发送数据。第一次调用时必须总是传入pdFALSE，后面的调用时应传入上一次调用返回的值。 |
Returns:
如果发送到队列使得一个联合程序唤醒则为pdTRUE。
这用来使中断服务程序决定是否需要在中断后进行上下文切换。
40. crQUEUE_RECEIVE_FROM_ISR[联合程序]
(注意：官方的文档此处的内容似乎有误，请参考源代码)
croutine.h
portBASE_TYPE crQUEUE_SEND_FROM_ISR(
xQueueHandle pxQueue,
void *pvBuffer,
portBASE_TYPE * pxCoRoutineWoken
)
是一个宏。上面原型的数据类型只用作参考。联合程序中使用的crQUEUE_SEND_FROM_ISR() 与 crQUEUE_RECEIVE_FROM_ISR()宏等价于任务中的xQueueSendFromISR()与 xQueueReceiveFromISR()函数。 crQUEUE_SEND_FROM_ISR() 与 crQUEUE_RECEIVE_FROM_ISR() 只能用于联合程序与中断服务程序之间传递数据，同样道理，xQueueSendFromISR() 与 xQueueReceiveFromISR() 只能用于任务与中断服务程序间传递数据。
crQUEUE_RECEIVE_FROM_ISR 只能在一个从队列接收数据的中断服务程序中调用，并且此队列在一个联合程序中使用（一个联合程序发送数据到此队列）。参考联合程序部分获取关于任务与联合程序或中断服务程序与联合程序间传递数据的信息。
Parameters:
xQueue | The handle to the queue on which the item is to be posted. |
pvBuffer | A pointer to a buffer into which the received item will be placed. The size of the items the queue will hold was defined when the queue was created, so this many bytes will be copied from the queue into pvBuffer. |
pxCoRoutineWoken | A co-routine may be blocked waiting for space to become available on the queue. If crQUEUE_RECEIVE_FROM_ISR causes such a co-routine to unblock *pxCoRoutineWoken will get set to pdTRUE, otherwise *pxCoRoutineWoken will remain unchanged |
Returns:
pdTRUE an item was successfully received from the queue, otherwise pdFALSE.
41. vCoRoutineSchedule[联合程序]
croutine.h
void vCoRoutineSchedule( void );
运行一个联合程序vCoRoutineSchedule() 与性具有最高优先级的就绪联合程序。此联合程序将运行，直到其阻塞，让出系统或被任务抢占。联合程序是合作式运行的，所以一个联合程序不会被另一个联合程序抢占，但是可以被任务抢占。如果一个应用程序同时包含任务与联合程序，则vCoRoutineSchedule应该在空闲任务中调用（在一个空闲任务钩子中）。
