第 4 章 · 原书 212–256 页 · 18 个函数信号量 API
FreeRTOS 的信号量(semaphore)在实现上就是“特化过的队列”,因此 API 里的 Take/Give 与队列的 Receive/Send 是同一套底层逻辑。但在语义上,它们是两类完全不同的工具:一类用来同步(通知事件发生),一类用来互斥(保护共享资源)。
本章涉及的四种对象,差别先摆清楚:
| 类型 | 创建函数 | 典型用途 | 关键特性 |
|---|---|---|---|
| 二进制信号量 Binary | xSemaphoreCreateBinary() | 任务与中断之间、任务与任务之间的“事件通知” | 只有 0/1 两个值;中断里可 Give |
| 计数信号量 Counting | xSemaphoreCreateCounting() | 统计可用资源个数、记录事件次数 | 有最大值与初始值;每 Give 一次加 1 |
| 互斥量 Mutex | xSemaphoreCreateMutex() | 保护共享资源(临界区语义) | 支持优先级继承,缓解优先级反转;谁 Take 谁必须 Give |
| 递归互斥量 Recursive | xSemaphoreCreateRecursiveMutex() | 同一任务可重复进入的临界区 | 同一持有者可多次 Take,需等次数 Give 才真正释放 |
三类宏配置决定哪些函数被编译进来:configUSE_MUTEXES(互斥量)、configUSE_COUNTING_SEMAPHORES(计数信号量)、configUSE_RECURSIVE_MUTEXES(递归互斥量)。二值信号量默认可用。
下面各节中,Give 表示“释放/给”(让信号量可用或计数加 1),Take 表示“获取/取”(把信号量拿到手,计数减 1;不可用时按超时阻塞)。
4.1vSemaphoreCreateBinary()
void vSemaphoreCreateBinary( SemaphoreHandle_t xSemaphore );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xSemaphore | in | 用于接收创建出的信号量句柄的变量(注意是变量本身,不是指针)。 |
说明
创建二进制信号量的旧版宏,已经过时。它创建出的信号量初始状态与 xSemaphoreCreateBinary() 也不同:旧宏创建后信号量是可用(1)的,而新函数创建后是不可用(0)的。
保留它只是为了兼容老代码。新代码请一律使用 xSemaphoreCreateBinary()。
注意
- 它是宏,没有返回值:失败时 xSemaphore 变量被置为 NULL,必须自己检查。
- 由于初始状态为 1,老代码在 Take 之前往往不需要先 Give——这正是它与新 API 最容易混用的地方。
4.2xSemaphoreCreateBinary()
SemaphoreHandle_t xSemaphoreCreateBinary( void );
返回值
创建成功返回信号量句柄;堆内存不足返回 NULL。
说明
动态创建一个二进制信号量,初始状态为不可用(0)。也就是说:创建之后必须先 Give 一次,等待方的 Take 才能成功。
这是最常用的“事件通知”原语:中断里 Give,任务里 Take。
注意
- configSUPPORT_DYNAMIC_ALLOCATION 必须为 1。
- 用完用 vSemaphoreDelete() 释放。
- 二值信号量不记录 Give 次数,连续多次 Give 只相当于一次有效信号(最多保持“可用”状态)。
典型用法
SemaphoreHandle_t xBinSem = xSemaphoreCreateBinary();
if( xBinSem == NULL ) { /* 创建失败 */ }
/* 任务侧等待 */
xSemaphoreTake( xBinSem, portMAX_DELAY );
/* 中断侧通知 */
xSemaphoreGiveFromISR( xBinSem, &xWoken );
4.3xSemaphoreCreateBinaryStatic()
SemaphoreHandle_t xSemaphoreCreateBinaryStatic( StaticSemaphore_t *pxSemaphoreBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pxSemaphoreBuffer | in | 应用提供的 StaticSemaphore_t 结构,用作信号量控制块。 |
返回值
创建成功返回信号量句柄;pxSemaphoreBuffer 为 NULL 时返回 NULL。
说明
静态创建二进制信号量,语义与 xSemaphoreCreateBinary() 一致,初始为不可用。
注意
- configSUPPORT_STATIC_ALLOCATION 必须为 1。
- 签名参数是 bIsRecursive(历史遗留),新代码不需要处理它。
4.4xSemaphoreCreateCounting()
SemaphoreHandle_t xSemaphoreCreateCounting( UBaseType_t uxMaxCount,
UBaseType_t uxInitialCount );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| uxMaxCount | in | 计数上限,即信号量的最大计数值。 |
| uxInitialCount | in | 初始计数值,通常是 0。 |
返回值
创建成功返回句柄;堆内存不足返回 NULL。
说明
动态创建计数信号量。每 Give 一次计数加 1(到上限为止),每 Take 一次计数减 1(到 0 为止,减到 0 时 Take 会阻塞)。
两种典型用法:统计可用资源数(例如缓冲区里有多少个空闲槽位);累计事件发生次数(例如中断里记录脉冲个数,任务侧批量处理)。
注意
- configUSE_COUNTING_SEMAPHORES 必须为 1。
- uxInitialCount 大于 uxMaxCount 时创建失败(返回 NULL)。
- 计数上限决定了可累积的事件数,给太小会漏事件。
典型用法
/* 初始 0,最多累积 10 次事件 */ SemaphoreHandle_t xCounting = xSemaphoreCreateCounting( 10, 0 );
4.5xSemaphoreCreateCountingStatic()
SemaphoreHandle_t xSemaphoreCreateCountingStatic( UBaseType_t uxMaxCount,
UBaseType_t uxInitialCount,
StaticSemaphore_t *pxSemaphoreBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| uxMaxCount | in | 计数上限。 |
| uxInitialCount | in | 初始计数值。 |
| pxSemaphoreBuffer | in | 应用提供的 StaticSemaphore_t 结构。 |
返回值
创建成功返回句柄;pxSemaphoreBuffer 为 NULL 或初始值大于上限时返回 NULL。
说明
静态创建计数信号量,语义与 xSemaphoreCreateCounting() 相同。
注意
- configUSE_COUNTING_SEMAPHORES 与 configSUPPORT_STATIC_ALLOCATION 必须都为 1。
4.6xSemaphoreCreateMutex()
SemaphoreHandle_t xSemaphoreCreateMutex( void );
返回值
创建成功返回互斥量句柄;堆内存不足返回 NULL。
说明
动态创建互斥量(mutex),初始为可用状态(相当于二值信号量为 1),即第一个 Take 会立即成功。
互斥量的核心价值是优先级继承:当高优先级任务 Take 一个已被低优先级任务持有的互斥量时,低优先级任务会临时被提升到高优先级,从而尽快执行完并释放互斥量,缩短高优先级任务的等待时间(缓解优先级反转)。
注意
- configUSE_MUTEXES 必须为 1。
- 互斥量必须由获取它的那个任务释放(谁 Take 谁 Give),不能在中断里 Give。
- 互斥量不是“中断到任务”的通知机制,那种场景用二值信号量或任务通知。
- Take 时的超时建议不要用 portMAX_DELAY 无限等待而没有兜底,资源设计缺陷会被它掩盖。
典型用法
SemaphoreHandle_t xMutex = xSemaphoreCreateMutex(); xSemaphoreTake( xMutex, portMAX_DELAY ); /* 访问共享资源(如 LCD、SPI 总线、全局结构体) */ xSemaphoreGive( xMutex );
4.7xSemaphoreCreateMutexStatic()
SemaphoreHandle_t xSemaphoreCreateMutexStatic( StaticSemaphore_t *pxMutexBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pxMutexBuffer | in | 应用提供的 StaticSemaphore_t 结构。 |
返回值
创建成功返回互斥量句柄;pxMutexBuffer 为 NULL 时返回 NULL。
说明
静态创建互斥量,语义与 xSemaphoreCreateMutex() 一致。
注意
- configUSE_MUTEXES 与 configSUPPORT_STATIC_ALLOCATION 必须都为 1。
4.8xSemaphoreCreateRecursiveMutex()
SemaphoreHandle_t xSemaphoreCreateRecursiveMutex( void );
返回值
创建成功返回递归互斥量句柄;堆内存不足返回 NULL。
说明
动态创建递归互斥量。它允许同一个任务多次 Take 同一个互斥量(每次计数加 1),必须调用同样次数的 xSemaphoreGiveRecursive() 才真正释放。
典型场景:一组函数彼此调用,且每个入口都要“加锁”保护同一资源;用普通互斥量会自己把自己锁死(死锁),用递归互斥量则安全。
注意
- configUSE_RECURSIVE_MUTEXES 与 configUSE_MUTEXES 必须都为 1。
- 只能由持有者释放,且释放次数必须与获取次数一致。
- 其它任务无法在你完全释放前获得该互斥量(这点与普通互斥量不同,普通互斥量重新 Take 会直接失败或阻塞)。
4.9xSemaphoreCreateRecursiveMutexStatic()
SemaphoreHandle_t xSemaphoreCreateRecursiveMutexStatic( StaticSemaphore_t *pxMutexBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pxMutexBuffer | in | 应用提供的 StaticSemaphore_t 结构。 |
返回值
创建成功返回句柄;pxMutexBuffer 为 NULL 时返回 NULL。
说明
静态创建递归互斥量。
注意
- configUSE_RECURSIVE_MUTEXES、configUSE_MUTEXES、configSUPPORT_STATIC_ALLOCATION 必须都为 1。
4.10vSemaphoreDelete()
void vSemaphoreDelete( SemaphoreHandle_t xSemaphore );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xSemaphore | in | 要删除的信号量句柄(二值、计数、互斥、递归互斥均可)。 |
说明
删除信号量并释放其内存(静态创建的不释放内存)。若有任务正阻塞等待该信号量,它们会被唤醒并返回失败。
注意
- 不要在任务仍可能使用该信号量时删除它,否则后续操作会访问已释放内存。
4.11uxSemaphoreGetCount()
UBaseType_t uxSemaphoreGetCount( SemaphoreHandle_t xSemaphore );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xSemaphore | in | 要查询的信号量句柄。 |
返回值
信号量当前的计数值。二进制信号量返回 0 或 1。
说明
查询信号量的当前计数。对计数信号量来说,就是“还剩几个可用资源”;对二值信号量来说,1 表示可用、0 表示不可用。
注意
- 返回值是瞬时值。
- 互斥量在未被持有时返回 1。
4.12xSemaphoreGetMutexHolder()
TaskHandle_t xSemaphoreGetMutexHolder( SemaphoreHandle_t xMutex );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xMutex | in | 要查询的互斥量句柄。 |
返回值
当前持有该互斥量的任务句柄;互斥量未被持有时返回 NULL。
说明
查询“谁正持有这个互斥量”。用于调试优先级反转、诊断死锁(例如发现持锁任务长期不释放)。
注意
- INCLUDE_xSemaphoreGetMutexHolder 与 configUSE_MUTEXES 必须都为 1。
- 只能在任务里可靠使用;中断里对上锁状态没有意义。
- 递归互斥量的持有者查询需注意:拿到的是最后一次 Take 的任务。
4.13xSemaphoreGive()
BaseType_t xSemaphoreGive( SemaphoreHandle_t xSemaphore );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xSemaphore | in | 要释放/给(Give)的信号量句柄。 |
返回值
pdPASS 表示成功;pdFAIL 表示失败(二值信号量已可用、计数信号量已达上限、或非持有者给互斥量)。
说明
释放信号量:二值信号量变为可用,计数信号量计数加 1,互斥量被归还。若有任务正阻塞等待该信号量,其中一个会被解除阻塞(按优先级挑选)。
互斥量的 Give 只能由持有它的任务执行,否则返回失败。
注意
- 中断里不能调用本函数,请用 xSemaphoreGiveFromISR()。
- 递归互斥量必须用 xSemaphoreGiveRecursive()。
- 二值信号量重复 Give 不会“累积”,仍然只有一个可用信号(多出来的丢失)。
典型用法
/* 任务发布事件 */ xSemaphoreGive( xBinSem ); /* 互斥量使用范式 */ xSemaphoreTake( xMutex, portMAX_DELAY ); /* ... */ xSemaphoreGive( xMutex );
4.14xSemaphoreGiveFromISR()
BaseType_t xSemaphoreGiveFromISR( SemaphoreHandle_t xSemaphore,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xSemaphore | in | 要释放的信号量句柄。 |
| pxHigherPriorityTaskWoken | out | 初始化为 pdFALSE。若 Give 解除了一个更高优先级任务的阻塞,则被置为 pdTRUE。 |
返回值
pdPASS 表示成功;pdFAIL 表示失败(信号量已满或已可用)。
说明
在中断里 Give 信号量,是“中断通知任务”的标准做法。
注意
- 互斥量不能在中断里 Give,中断里只能用二值信号量或计数信号量。
- pxHigherPriorityTaskWoken 必须被 portYIELD_FROM_ISR() 处理,否则被唤醒任务要等下一个节拍。
典型用法
void vTimerISR( void )
{
BaseType_t xWoken = pdFALSE;
xSemaphoreGiveFromISR( xBinSem, &xWoken );
portYIELD_FROM_ISR( xWoken );
}
4.15xSemaphoreGiveRecursive()
BaseType_t xSemaphoreGiveRecursive( SemaphoreHandle_t xMutex );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xMutex | in | 要归还的递归互斥量句柄。 |
返回值
pdPASS 表示成功;pdFAIL 表示调用者并非持有者,或已无嵌套计数可归还。
说明
归还一次递归互斥量(嵌套计数减 1)。只有嵌套计数减到 0 时,互斥量才真正可用,其它等待任务才会被唤醒。
注意
- 获取与归还次数必须严格一致,否则互斥量永远被占。
- 只能由持有者调用。
4.16xSemaphoreTake()
BaseType_t xSemaphoreTake( SemaphoreHandle_t xSemaphore,
TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xSemaphore | in | 要获取(Take)的信号量句柄。 |
| xTicksToWait | in | 信号量不可用时的最长阻塞节拍数。0 表示立即返回;portMAX_DELAY 表示无限等待(需 INCLUDE_vTaskSuspend 为 1)。 |
返回值
pdPASS 表示获取成功;pdFAIL 表示在超时时间内始终未可用。
说明
获取信号量:二进制信号量被清零(变为不可用),计数信号量计数减 1,互斥量被占用。若当前不可用,调用任务进入阻塞态等待,直到可用或超时。
多个任务等待同一个信号量时,内核按优先级挑选被唤醒者,而不是先来先得。
注意
- 中断里不能调用,请用 xSemaphoreTakeFromISR()。
- 递归互斥量必须用 xSemaphoreTakeRecursive();用普通 Take 会失败。
- Take 到的互斥量必须由同一个任务 Give。
- 信号量不可用时用 xTicksToWait = 0 做“非阻塞尝试”,这是轮询与超时控制的常用组合。
典型用法
/* 无限等待事件 */
if( xSemaphoreTake( xBinSem, portMAX_DELAY ) == pdPASS )
{
/* 事件已发生,处理它 */
}
/* 只试一次,不等待 */
if( xSemaphoreTake( xMutex, 0 ) == pdPASS ) { /* 拿到锁 */ }
4.17xSemaphoreTakeFromISR()
BaseType_t xSemaphoreTakeFromISR( SemaphoreHandle_t xSemaphore,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xSemaphore | in | 要获取的信号量句柄。 |
| pxHigherPriorityTaskWoken | out | 初始化为 pdFALSE;若本次 Take 可能影响就绪任务,则由内核按需置位。 |
返回值
pdPASS 表示获取成功;pdFAIL 表示信号量当前不可用。
说明
在中断里获取信号量(不阻塞)。这个函数在实际工程中用得很少:中断通常只负责 Give,Take 是任务的活。
注意
- 互斥量不适用(中断不能持有互斥量)。
- 若你在中断里 Take 成功后没有对应的 Give 路径,很容易把信号量彻底耗尽。
4.18xSemaphoreTakeRecursive()
BaseType_t xSemaphoreTakeRecursive( SemaphoreHandle_t xMutex,
TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xMutex | in | 要获取的递归互斥量句柄。 |
| xTicksToWait | in | 无法获取时的最长阻塞节拍数。若调用者已是持有者,则立即成功(嵌套计数加 1)。 |
返回值
pdPASS 表示获取成功;pdFAIL 表示超时未获取到。
说明
获取递归互斥量。若当前任务已持有它,则直接成功并把嵌套计数加 1(这是递归互斥量的价值所在);若被别的任务持有,则按超时阻塞等待。
注意
- configUSE_RECURSIVE_MUTEXES 与 configUSE_MUTEXES 必须都为 1。
- 每次 Take 都要有对应的 GiveRecursive,次数不符会导致互斥量永久占用。
典型用法
void vOuterFunc( void )
{
xSemaphoreTakeRecursive( xRecMutex, portMAX_DELAY );
vInnerFunc(); /* 内部再次 Take,不会死锁 */
xSemaphoreGiveRecursive( xRecMutex );
}