FreeRTOS 中文参考手册 /4 信号量 API

第 4 章 · 原书 212–256 页 · 18 个函数信号量 API

Chapter 4 · Semaphore API

FreeRTOS 的信号量(semaphore)在实现上就是“特化过的队列”,因此 API 里的 Take/Give 与队列的 Receive/Send 是同一套底层逻辑。但在语义上,它们是两类完全不同的工具:一类用来同步(通知事件发生),一类用来互斥(保护共享资源)。

本章涉及的四种对象,差别先摆清楚:

类型创建函数典型用途关键特性
二进制信号量 BinaryxSemaphoreCreateBinary()任务与中断之间、任务与任务之间的“事件通知”只有 0/1 两个值;中断里可 Give
计数信号量 CountingxSemaphoreCreateCounting()统计可用资源个数、记录事件次数有最大值与初始值;每 Give 一次加 1
互斥量 MutexxSemaphoreCreateMutex()保护共享资源(临界区语义)支持优先级继承,缓解优先级反转;谁 Take 谁必须 Give
递归互斥量 RecursivexSemaphoreCreateRecursiveMutex()同一任务可重复进入的临界区同一持有者可多次 Take,需等次数 Give 才真正释放
最容易踩的坑:二值信号量不能当互斥量用。用二值信号量保护共享资源时没有优先级继承,中等优先级任务会长期抢占低优先级持锁任务,造成优先级反转;要互斥就用互斥量。反过来,互斥量也不适合做中断到任务的通知(互斥量不能在中断里 Give)。

三类宏配置决定哪些函数被编译进来:configUSE_MUTEXES(互斥量)、configUSE_COUNTING_SEMAPHORES(计数信号量)、configUSE_RECURSIVE_MUTEXES(递归互斥量)。二值信号量默认可用。

下面各节中,Give 表示“释放/给”(让信号量可用或计数加 1),Take 表示“获取/取”(把信号量拿到手,计数减 1;不可用时按超时阻塞)。

4.1vSemaphoreCreateBinary()

信号量 · 二值 semphr.h
void vSemaphoreCreateBinary( SemaphoreHandle_t xSemaphore );

参数

参数方向说明
xSemaphorein用于接收创建出的信号量句柄的变量(注意是变量本身,不是指针)。

说明

创建二进制信号量的旧版宏,已经过时。它创建出的信号量初始状态与 xSemaphoreCreateBinary() 也不同:旧宏创建后信号量是可用(1)的,而新函数创建后是不可用(0)的。

保留它只是为了兼容老代码。新代码请一律使用 xSemaphoreCreateBinary()。

注意

4.2xSemaphoreCreateBinary()

信号量 · 二值 semphr.h
SemaphoreHandle_t xSemaphoreCreateBinary( void );

返回值

创建成功返回信号量句柄;堆内存不足返回 NULL。

说明

动态创建一个二进制信号量,初始状态为不可用(0)。也就是说:创建之后必须先 Give 一次,等待方的 Take 才能成功。

这是最常用的“事件通知”原语:中断里 Give,任务里 Take。

注意

典型用法

SemaphoreHandle_t xBinSem = xSemaphoreCreateBinary();
if( xBinSem == NULL ) { /* 创建失败 */ }

/* 任务侧等待 */
xSemaphoreTake( xBinSem, portMAX_DELAY );

/* 中断侧通知 */
xSemaphoreGiveFromISR( xBinSem, &xWoken );

4.3xSemaphoreCreateBinaryStatic()

信号量 · 二值 semphr.h
SemaphoreHandle_t xSemaphoreCreateBinaryStatic( StaticSemaphore_t *pxSemaphoreBuffer );

参数

参数方向说明
pxSemaphoreBufferin应用提供的 StaticSemaphore_t 结构,用作信号量控制块。

返回值

创建成功返回信号量句柄;pxSemaphoreBuffer 为 NULL 时返回 NULL。

说明

静态创建二进制信号量,语义与 xSemaphoreCreateBinary() 一致,初始为不可用。

注意

4.4xSemaphoreCreateCounting()

信号量 · 计数 semphr.h
SemaphoreHandle_t xSemaphoreCreateCounting( UBaseType_t uxMaxCount,
                                            UBaseType_t uxInitialCount );

参数

参数方向说明
uxMaxCountin计数上限,即信号量的最大计数值。
uxInitialCountin初始计数值,通常是 0。

返回值

创建成功返回句柄;堆内存不足返回 NULL。

说明

动态创建计数信号量。每 Give 一次计数加 1(到上限为止),每 Take 一次计数减 1(到 0 为止,减到 0 时 Take 会阻塞)。

两种典型用法:统计可用资源数(例如缓冲区里有多少个空闲槽位);累计事件发生次数(例如中断里记录脉冲个数,任务侧批量处理)。

注意

典型用法

/* 初始 0,最多累积 10 次事件 */
SemaphoreHandle_t xCounting = xSemaphoreCreateCounting( 10, 0 );

4.5xSemaphoreCreateCountingStatic()

信号量 · 计数 semphr.h
SemaphoreHandle_t xSemaphoreCreateCountingStatic( UBaseType_t uxMaxCount,
                                                  UBaseType_t uxInitialCount,
                                                  StaticSemaphore_t *pxSemaphoreBuffer );

参数

参数方向说明
uxMaxCountin计数上限。
uxInitialCountin初始计数值。
pxSemaphoreBufferin应用提供的 StaticSemaphore_t 结构。

返回值

创建成功返回句柄;pxSemaphoreBuffer 为 NULL 或初始值大于上限时返回 NULL。

说明

静态创建计数信号量,语义与 xSemaphoreCreateCounting() 相同。

注意

4.6xSemaphoreCreateMutex()

信号量 · 互斥 semphr.h
SemaphoreHandle_t xSemaphoreCreateMutex( void );

返回值

创建成功返回互斥量句柄;堆内存不足返回 NULL。

说明

动态创建互斥量(mutex),初始为可用状态(相当于二值信号量为 1),即第一个 Take 会立即成功。

互斥量的核心价值是优先级继承:当高优先级任务 Take 一个已被低优先级任务持有的互斥量时,低优先级任务会临时被提升到高优先级,从而尽快执行完并释放互斥量,缩短高优先级任务的等待时间(缓解优先级反转)。

注意

典型用法

SemaphoreHandle_t xMutex = xSemaphoreCreateMutex();

xSemaphoreTake( xMutex, portMAX_DELAY );
/* 访问共享资源(如 LCD、SPI 总线、全局结构体) */
xSemaphoreGive( xMutex );

4.7xSemaphoreCreateMutexStatic()

信号量 · 互斥 semphr.h
SemaphoreHandle_t xSemaphoreCreateMutexStatic( StaticSemaphore_t *pxMutexBuffer );

参数

参数方向说明
pxMutexBufferin应用提供的 StaticSemaphore_t 结构。

返回值

创建成功返回互斥量句柄;pxMutexBuffer 为 NULL 时返回 NULL。

说明

静态创建互斥量,语义与 xSemaphoreCreateMutex() 一致。

注意

4.8xSemaphoreCreateRecursiveMutex()

信号量 · 递归互斥 semphr.h
SemaphoreHandle_t xSemaphoreCreateRecursiveMutex( void );

返回值

创建成功返回递归互斥量句柄;堆内存不足返回 NULL。

说明

动态创建递归互斥量。它允许同一个任务多次 Take 同一个互斥量(每次计数加 1),必须调用同样次数的 xSemaphoreGiveRecursive() 才真正释放。

典型场景:一组函数彼此调用,且每个入口都要“加锁”保护同一资源;用普通互斥量会自己把自己锁死(死锁),用递归互斥量则安全。

注意

4.9xSemaphoreCreateRecursiveMutexStatic()

信号量 · 递归互斥 semphr.h
SemaphoreHandle_t xSemaphoreCreateRecursiveMutexStatic( StaticSemaphore_t *pxMutexBuffer );

参数

参数方向说明
pxMutexBufferin应用提供的 StaticSemaphore_t 结构。

返回值

创建成功返回句柄;pxMutexBuffer 为 NULL 时返回 NULL。

说明

静态创建递归互斥量。

注意

4.10vSemaphoreDelete()

信号量 semphr.h
void vSemaphoreDelete( SemaphoreHandle_t xSemaphore );

参数

参数方向说明
xSemaphorein要删除的信号量句柄(二值、计数、互斥、递归互斥均可)。

说明

删除信号量并释放其内存(静态创建的不释放内存)。若有任务正阻塞等待该信号量,它们会被唤醒并返回失败。

注意

4.11uxSemaphoreGetCount()

信号量 semphr.h
UBaseType_t uxSemaphoreGetCount( SemaphoreHandle_t xSemaphore );

参数

参数方向说明
xSemaphorein要查询的信号量句柄。

返回值

信号量当前的计数值。二进制信号量返回 0 或 1。

说明

查询信号量的当前计数。对计数信号量来说,就是“还剩几个可用资源”;对二值信号量来说,1 表示可用、0 表示不可用。

注意

4.12xSemaphoreGetMutexHolder()

信号量 · 互斥 semphr.h
TaskHandle_t xSemaphoreGetMutexHolder( SemaphoreHandle_t xMutex );

参数

参数方向说明
xMutexin要查询的互斥量句柄。

返回值

当前持有该互斥量的任务句柄;互斥量未被持有时返回 NULL。

说明

查询“谁正持有这个互斥量”。用于调试优先级反转、诊断死锁(例如发现持锁任务长期不释放)。

注意

4.13xSemaphoreGive()

信号量 semphr.h
BaseType_t xSemaphoreGive( SemaphoreHandle_t xSemaphore );

参数

参数方向说明
xSemaphorein要释放/给(Give)的信号量句柄。

返回值

pdPASS 表示成功;pdFAIL 表示失败(二值信号量已可用、计数信号量已达上限、或非持有者给互斥量)。

说明

释放信号量:二值信号量变为可用,计数信号量计数加 1,互斥量被归还。若有任务正阻塞等待该信号量,其中一个会被解除阻塞(按优先级挑选)。

互斥量的 Give 只能由持有它的任务执行,否则返回失败。

注意

典型用法

/* 任务发布事件 */
xSemaphoreGive( xBinSem );

/* 互斥量使用范式 */
xSemaphoreTake( xMutex, portMAX_DELAY );
/* ... */
xSemaphoreGive( xMutex );

4.14xSemaphoreGiveFromISR()

信号量 · 中断 semphr.h
BaseType_t xSemaphoreGiveFromISR( SemaphoreHandle_t xSemaphore,
                                    BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xSemaphorein要释放的信号量句柄。
pxHigherPriorityTaskWokenout初始化为 pdFALSE。若 Give 解除了一个更高优先级任务的阻塞,则被置为 pdTRUE。

返回值

pdPASS 表示成功;pdFAIL 表示失败(信号量已满或已可用)。

说明

在中断里 Give 信号量,是“中断通知任务”的标准做法。

注意

典型用法

void vTimerISR( void )
{
    BaseType_t xWoken = pdFALSE;
    xSemaphoreGiveFromISR( xBinSem, &xWoken );
    portYIELD_FROM_ISR( xWoken );
}

4.15xSemaphoreGiveRecursive()

信号量 · 递归互斥 semphr.h
BaseType_t xSemaphoreGiveRecursive( SemaphoreHandle_t xMutex );

参数

参数方向说明
xMutexin要归还的递归互斥量句柄。

返回值

pdPASS 表示成功;pdFAIL 表示调用者并非持有者,或已无嵌套计数可归还。

说明

归还一次递归互斥量(嵌套计数减 1)。只有嵌套计数减到 0 时,互斥量才真正可用,其它等待任务才会被唤醒。

注意

4.16xSemaphoreTake()

信号量 semphr.h
BaseType_t xSemaphoreTake( SemaphoreHandle_t xSemaphore,
                            TickType_t xTicksToWait );

参数

参数方向说明
xSemaphorein要获取(Take)的信号量句柄。
xTicksToWaitin信号量不可用时的最长阻塞节拍数。0 表示立即返回;portMAX_DELAY 表示无限等待(需 INCLUDE_vTaskSuspend 为 1)。

返回值

pdPASS 表示获取成功;pdFAIL 表示在超时时间内始终未可用。

说明

获取信号量:二进制信号量被清零(变为不可用),计数信号量计数减 1,互斥量被占用。若当前不可用,调用任务进入阻塞态等待,直到可用或超时。

多个任务等待同一个信号量时,内核按优先级挑选被唤醒者,而不是先来先得。

注意

典型用法

/* 无限等待事件 */
if( xSemaphoreTake( xBinSem, portMAX_DELAY ) == pdPASS )
{
    /* 事件已发生,处理它 */
}

/* 只试一次,不等待 */
if( xSemaphoreTake( xMutex, 0 ) == pdPASS ) { /* 拿到锁 */ }

4.17xSemaphoreTakeFromISR()

信号量 · 中断 semphr.h
BaseType_t xSemaphoreTakeFromISR( SemaphoreHandle_t xSemaphore,
                                    BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xSemaphorein要获取的信号量句柄。
pxHigherPriorityTaskWokenout初始化为 pdFALSE;若本次 Take 可能影响就绪任务,则由内核按需置位。

返回值

pdPASS 表示获取成功;pdFAIL 表示信号量当前不可用。

说明

在中断里获取信号量(不阻塞)。这个函数在实际工程中用得很少:中断通常只负责 Give,Take 是任务的活。

注意

4.18xSemaphoreTakeRecursive()

信号量 · 递归互斥 semphr.h
BaseType_t xSemaphoreTakeRecursive( SemaphoreHandle_t xMutex,
                                     TickType_t xTicksToWait );

参数

参数方向说明
xMutexin要获取的递归互斥量句柄。
xTicksToWaitin无法获取时的最长阻塞节拍数。若调用者已是持有者,则立即成功(嵌套计数加 1)。

返回值

pdPASS 表示获取成功;pdFAIL 表示超时未获取到。

说明

获取递归互斥量。若当前任务已持有它,则直接成功并把嵌套计数加 1(这是递归互斥量的价值所在);若被别的任务持有,则按超时阻塞等待。

注意

典型用法

void vOuterFunc( void )
{
    xSemaphoreTakeRecursive( xRecMutex, portMAX_DELAY );
    vInnerFunc();                       /* 内部再次 Take,不会死锁 */
    xSemaphoreGiveRecursive( xRecMutex );
}