1. 任务管理 (Task Management)
xTaskCreate(): 创建任务。功能: 动态创建一个新的任务，并将其加入到 FreeRTOS 的任务调度器中。
常用场景: 在系统初始化阶段或运行时动态创建任务，用于执行不同的功能模块。
关键参数
:
pvTaskCode: 指向任务函数的指针，任务代码的入口。pcName: 任务名称，字符串形式，方便调试和追踪。usStackDepth: 任务堆栈大小，以字 (word) 为单位，需要根据任务需求合理配置。pvParameters: 传递给任务函数的参数，void 指针类型，可以传递任意类型数据。uxPriority: 任务优先级，数值越大优先级越高，FreeRTOS 会根据优先级进行任务调度。pxCreatedTask: 任务句柄指针，用于存储创建的任务句柄，后续操作任务时需要使用该句柄。
vTaskDelete(): 删除任务。功能: 删除指定的任务。可以删除自身任务或其它任务。
常用场景: 任务执行完成后不再需要，或者需要动态管理任务生命周期时。
关键参数
:
xTaskToDelete: 要删除的任务句柄。如果为NULL，则删除自身任务。
vTaskDelay(): 任务延时。功能: 使当前任务进入阻塞态，延时指定的时间。
常用场景: 周期性任务的延时，或在不需要立即执行的任务中加入延时以降低 CPU 占用率。
关键参数
:
xTicksToDelay: 延时的时间，以 tick 为单位。tick 的时间长度由configTICK_RATE_HZ配置宏定义，例如configTICK_RATE_HZ为 1000，则 1 tick 为 1ms。
vTaskSuspend(): 挂起任务。功能: 将指定的任务挂起，使其进入挂起态，不再参与任务调度。
常用场景: 暂时停止某个任务的执行，例如调试时暂停某个功能模块。
关键参数
:
xTaskToSuspend: 要挂起的任务句柄。如果为NULL，则挂起自身任务。
vTaskResume(): 恢复任务。功能: 恢复被挂起的任务，使其进入就绪态，重新参与任务调度。
常用场景: 与
vTaskSuspend()配对使用，在需要时恢复被挂起的任务。关键参数
:
xTaskToResume: 要恢复的任务句柄。
uxTaskGetStackHighWaterMark(): 获取任务堆栈剩余空间。功能: 获取任务堆栈当前剩余空间的大小，用于评估堆栈使用情况，避免堆栈溢出。
常用场景: 调试阶段或性能优化时，检查任务堆栈是否足够，预防潜在的堆栈溢出问题。
关键参数
:
xTask: 要查询的任务句柄。如果为NULL，则查询自身任务。
pcTaskGetName(): 获取任务名称。功能: 获取指定任务的任务名称字符串。
常用场景: 调试信息输出，日志记录等，方便识别任务。
关键参数
:
xTaskToQuery: 要查询的任务句柄。如果为NULL，则查询自身任务。
2. 队列管理 (Queue Management)
xQueueCreate(): 创建队列。功能: 创建一个新的队列，用于任务间或 ISR 与任务间的数据传递。
常用场景: 任务间通信，数据缓冲，消息传递。
关键参数
:
uxQueueLength: 队列的长度，即队列可以存储的最大消息数量。uxItemSize: 队列中每个消息的长度，以字节为单位。如果消息是结构体，则为结构体的大小。
xQueueSend()/xQueueSendToBack(): 发送消息到队列尾部 (前者是宏定义，后者是函数)。功能: 向队列的尾部发送一条消息。
常用场景: 任务向队列发送数据。
关键参数
:
xQueue: 要发送消息的队列句柄。pvItemToQueue: 指向要发送的消息数据的指针。xTicksToWait: 阻塞等待时间，如果队列已满，任务将阻塞等待，直到队列有空间或超时。设置为 0 表示非阻塞发送，队列满则立即返回错误。portMAX_DELAY表示永久阻塞等待。
xQueueSendToFront(): 发送消息到队列头部。- 功能: 向队列的头部发送一条消息。
- 常用场景: 发送高优先级消息，需要优先处理的消息。
- 参数: 与
xQueueSend()类似。
xQueueReceive(): 接收队列消息。功能: 从队列中接收一条消息。
常用场景: 任务从队列接收数据。
关键参数
:
xQueue: 要接收消息的队列句柄。pvBuffer: 指向接收消息数据缓冲区的指针。xTicksToWait: 阻塞等待时间，如果队列为空，任务将阻塞等待，直到队列有消息或超时。设置为 0 表示非阻塞接收，队列空则立即返回错误。portMAX_DELAY表示永久阻塞等待。
uxQueueMessagesWaiting(): 获取队列中消息数量。功能: 获取当前队列中已有的消息数量。
常用场景: 查询队列状态，判断队列是否为空或已满。
关键参数
:
xQueue: 要查询的队列句柄。
vQueueDelete(): 删除队列。功能: 删除指定的队列，释放队列占用的内存。
常用场景: 队列不再需要时，释放资源。
关键参数
:
xQueueToDelete: 要删除的队列句柄。
3. 信号量管理 (Semaphore Management)
xSemaphoreCreateBinary(): 创建二值信号量。- 功能: 创建一个二值信号量，初始状态可以为可用或不可用。二值信号量只能取 0 和 1 两个值。
- 常用场景: 互斥访问共享资源，任务同步 (例如事件触发)。
- 返回: 信号量句柄，创建失败返回
NULL。
xSemaphoreCreateCounting(): 创建计数信号量。功能: 创建一个计数信号量，可以设定最大计数值和初始计数值。计数信号量可以允许多个任务访问资源 (但访问数量有限制)。
常用场景: 资源计数，例如控制访问具有多个槽位的资源池 (例如缓冲区管理)。
关键参数
:
uxMaxCount: 信号量的最大计数值。uxInitialCount: 信号量的初始计数值。
返回: 信号量句柄，创建失败返回
NULL。
xSemaphoreCreateMutex(): **创建互斥信号量 (互斥锁)**。- 功能: 创建一个互斥信号量，用于保护共享资源，防止多个任务同时访问造成数据竞争。互斥信号量具有优先级继承机制，可以避免优先级反转问题。
- 常用场景: 保护临界区，例如访问共享外设、全局变量等。
- 返回: 互斥信号量句柄，创建失败返回
NULL。
xSemaphoreTake(): 获取信号量。功能: 尝试获取信号量，如果信号量不可用，则任务进入阻塞态等待信号量可用。
常用场景: 任务访问共享资源前，先获取信号量。
关键参数
:
xSemaphore: 要获取的信号量句柄。xTicksToWait: 阻塞等待时间，如果信号量不可用，任务将阻塞等待，直到信号量可用或超时。portMAX_DELAY表示永久阻塞等待。
xSemaphoreGive(): 释放信号量。功能: 释放信号量，使信号量可用。
常用场景: 任务访问完共享资源后，释放信号量，允许其他任务访问。
关键参数
:
xSemaphore: 要释放的信号量句柄。
vSemaphoreDelete(): 删除信号量。功能: 删除指定的信号量，释放信号量占用的内存。
常用场景: 信号量不再需要时，释放资源。
关键参数
:
xSemaphoreToDelete: 要删除的信号量句柄。
4. 互斥量 (Mutex) 管理
- 互斥信号量
xSemaphoreCreateMutex()实际上就是互斥量，因此互斥量管理 API 与信号量管理 API 在互斥量部分是重合的。 常用的互斥量操作 API 实际上就是xSemaphoreTake()和xSemaphoreGive()。
5. 事件组管理 (Event Group Management)
xEventGroupCreate(): 创建事件组。- 功能: 创建一个事件组，用于任务间的事件同步。一个事件组可以包含多个事件标志位。
- 常用场景: 多事件同步，一个任务需要等待多个事件发生后才能执行。
- 返回: 事件组句柄，创建失败返回
NULL。
xEventGroupSetBits(): 设置事件位。功能: 设置事件组中指定的事件位。
常用场景: 事件发生时，设置对应的事件位。
关键参数
:
xEventGroup: 要设置事件位的事件组句柄。uxBitsToSet: 要设置的事件位掩码。可以使用位操作来设置多个事件位。
xEventGroupWaitBits(): 等待事件位。功能: 等待事件组中指定的事件位被设置。
常用场景: 任务等待指定的事件发生。
关键参数
:
xEventGroup: 要等待事件位的事件组句柄。uxBitsToWaitFor: 要等待的事件位掩码。xClearOnExit: 退出时是否清除等待的事件位。xWaitForAllBits: 是否等待所有指定的事件位都被设置。xTicksToWait: 阻塞等待时间。
返回: 实际触发的事件位掩码。
xEventGroupClearBits(): 清除事件位。功能: 清除事件组中指定的事件位。
常用场景: 事件处理完成后，清除事件位，准备下一次事件触发。
关键参数
:
xEventGroup: 要清除事件位的事件组句柄。uxBitsToClear: 要清除的事件位掩码。
vEventGroupDelete(): 删除事件组。功能: 删除指定的事件组，释放事件组占用的内存。
常用场景: 事件组不再需要时，释放资源。
关键参数
:
xEventGroupToDelete: 要删除的事件组句柄。
6. 软件定时器管理 (Software Timer Management)
xTimerCreate(): 创建软件定时器。功能: 创建一个软件定时器，可以设置定时器周期和回调函数。
常用场景: 周期性任务触发，延时操作，事件触发等。
关键参数
:
pcTimerName: 定时器名称，字符串形式。xTimerPeriodInTicks: 定时器周期，以 tick 为单位。uxAutoReload: 自动重载标志，pdTRUE为自动重载 (周期定时器)，pdFALSE为单次触发定时器。pvTimerID: 定时器 ID，用户自定义数据，可以传递给定时器回调函数。pxCallbackFunction: 定时器回调函数指针，定时器超时后执行的函数。
返回: 定时器句柄，创建失败返回
NULL。
xTimerStart(): 启动定时器。功能: 启动指定的定时器。
常用场景: 在需要开始定时时启动定时器。
关键参数
:
xTimer: 要启动的定时器句柄。xTicksToWait: 阻塞等待时间 (通常设置为 0 或portMAX_DELAY，在定时器服务任务上下文中可以阻塞等待，在其他任务上下文中不应该阻塞等待)。
xTimerStop(): 停止定时器。功能: 停止指定的定时器。
常用场景: 在不需要定时器触发时停止定时器。
关键参数
:
xTimer: 要停止的定时器句柄。xTicksToWait: 阻塞等待时间 (同xTimerStart())。
xTimerChangePeriod(): 修改定时器周期。功能: 动态修改定时器的周期。
常用场景: 在运行时根据需要调整定时器周期。
关键参数
:
xTimer: 要修改周期的定时器句柄。xNewPeriodInTicks: 新的定时器周期，以 tick 为单位。xTicksToWait: 阻塞等待时间 (同xTimerStart())。
xTimerIsTimerActive(): 判断定时器是否激活。功能: 判断指定的定时器是否处于激活状态。
常用场景: 查询定时器状态。
关键参数
:
xTimer: 要查询的定时器句柄。
返回:
pdTRUE表示激活，pdFALSE表示未激活。
xTimerDelete(): 删除定时器。功能: 删除指定的定时器，释放定时器占用的内存。
常用场景: 定时器不再需要时，释放资源。
关键参数
:
xTimerToDelete: 要删除的定时器句柄。xTicksToWait: 阻塞等待时间 (同xTimerStart())。
7. 内存管理 (Memory Management)
pvPortMalloc(): 动态内存分配 (FreeRTOS 的内存分配函数)。功能: 从 FreeRTOS 的堆内存中分配指定大小的内存块。
常用场景: 动态创建 FreeRTOS 对象 (例如队列、信号量、任务等) 或应用程序需要动态内存分配时。
关键参数
:
xWantedSize: 要分配的内存块大小，以字节为单位。
返回: 指向分配的内存块的指针，分配失败返回
NULL。
vPortFree(): 动态内存释放 (FreeRTOS 的内存释放函数)。功能: 释放由
pvPortMalloc()分配的内存块。常用场景: 释放不再使用的动态分配内存，避免内存泄漏。
关键参数
:
pvBlockToFree: 指向要释放的内存块的指针，必须是由pvPortMalloc()分配的内存块。
8. 中断管理 (Interrupt Management)
xSemaphoreGiveFromISR(): 在中断服务例程 (ISR) 中释放信号量。功能: 在 ISR 中释放信号量，用于通知任务发生了某个事件。
常用场景: ISR 中检测到硬件事件，需要通知任务进行处理时。
关键参数
:
xSemaphore: 要释放的信号量句柄。pxHigherPriorityTaskWoken: 输出参数，用于指示是否有更高优先级的任务因为释放信号量而进入就绪态，需要进行上下文切换。通常需要根据该参数判断是否需要手动触发上下文切换 (portYIELD_FROM_ISR()或taskYIELD_FROM_ISR())。
xQueueSendFromISR()/xQueueSendToBackFromISR(): 在 ISR 中发送消息到队列尾部。功能: 在 ISR 中向队列发送消息，用于 ISR 与任务间的数据传递。
常用场景: ISR 中接收到数据，需要传递给任务进行处理时。
关键参数
:
xQueue: 要发送消息的队列句柄。pvItemToQueue: 指向要发送的消息数据的指针。pxHigherPriorityTaskWoken: 输出参数，同xSemaphoreGiveFromISR()。
xQueueSendToFrontFromISR(): 在 ISR 中发送消息到队列头部。- 功能: 在 ISR 中向队列头部发送消息。
- 参数: 与
xQueueSendFromISR()类似。
portYIELD_FROM_ISR()/taskYIELD_FROM_ISR(): 在 ISR 中触发上下文切换 (与具体的 FreeRTOS 移植有关)。功能: 在 ISR 中手动触发上下文切换，将 CPU 使用权交给更高优先级的就绪态任务。
常用场景: 当 ISR 中释放信号量或发送消息到队列，导致更高优先级的任务进入就绪态时，需要触发上下文切换，立即执行高优先级任务，提高系统实时性。
参数
:
- 无参数，根据
xSemaphoreGiveFromISR()或xQueueSendFromISR()的pxHigherPriorityTaskWoken参数判断是否需要调用。
- 无参数，根据
二、CMSIS-V2 RTOS API (在 STM32CubeMX 中常用)
CMSIS-V2 RTOS API 提供了一套标准化的 RTOS 接口，在 STM32CubeMX 中，如果您选择了 CMSIS_RTOS_V2，则可以使用 CMSIS-V2 标准接口来操作 FreeRTOS 内核对象。CMSIS-V2 RTOS API 实际上是对原生 FreeRTOS API 的一层封装，其底层实现仍然是调用原生 FreeRTOS API。
使用 CMSIS-V2 RTOS API 的好处是可以提高代码的可移植性，如果将来需要更换 RTOS，只需要修改 RTOS 适配层即可，应用程序代码可以基本保持不变。
以下是一些常用的 CMSIS-V2 RTOS API 接口，对应于原生 FreeRTOS API 的功能模块：
1. 任务管理 (Thread Management) (CMSIS-V2 中任务称为线程)
osThreadNew(): 创建线程 (对应xTaskCreate())。功能: 创建并启动一个新的线程。
关键参数
:
thread_def: 线程定义结构体指针，包含线程入口函数、名称、优先级、堆栈大小等信息。thread_attr: 线程属性结构体指针，可以配置线程属性，例如堆栈、优先级等，可以设置为NULL使用默认属性。
返回: 线程 ID (
osThreadId_t)，创建失败返回NULL。
osThreadTerminate(): 终止线程 (对应vTaskDelete())。功能: 终止指定的线程。
关键参数
:
thread_id: 要终止的线程 ID。
osDelay(): 线程延时 (对应vTaskDelay())。功能: 使当前线程进入延时状态。
关键参数
:
ticks: 延时的时间，以 tick 为单位。
osThreadSuspend(): 挂起线程 (对应vTaskSuspend())。功能: 挂起指定的线程。
关键参数
:
thread_id: 要挂起的线程 ID。
osThreadResume(): 恢复线程 (对应vTaskResume())。功能: 恢复被挂起的线程。
关键参数
:
thread_id: 要恢复的线程 ID。
osThreadGetStackSpace(): 获取线程堆栈剩余空间 (对应uxTaskGetStackHighWaterMark())。功能: 获取线程堆栈当前剩余空间的大小。
关键参数
:
thread_id: 要查询的线程 ID。
osThreadGetName(): 获取线程名称 (对应pcTaskGetName())。功能: 获取指定线程的线程名称字符串。
关键参数
:
thread_id: 要查询的线程 ID。
2. 队列管理 (Message Queue Management) (CMSIS-V2 中队列称为消息队列)
osMessageQueueNew(): 创建消息队列 (对应xQueueCreate())。功能: 创建一个新的消息队列。
关键参数
:
msg_count: 消息队列的长度，即队列可以存储的最大消息数量。msg_size: 队列中每个消息的长度，以字节为单位。queue_attr: 队列属性结构体指针，可以配置队列属性，可以设置为NULL使用默认属性。
返回: 消息队列 ID (
osMessageQueueId_t)，创建失败返回NULL。
osMessageQueuePut(): 发送消息到消息队列尾部 (对应xQueueSend()/xQueueSendToBack())。功能: 向消息队列的尾部发送一条消息。
关键参数
:
mq_id: 要发送消息的消息队列 ID。msg_ptr: 指向要发送的消息数据的指针。timeout: 阻塞等待时间，以 tick 为单位。
osMessageQueueGet(): 接收消息队列消息 (对应xQueueReceive())。功能: 从消息队列中接收一条消息。
关键参数
:
mq_id: 要接收消息的消息队列 ID。msg_ptr: 指向接收消息数据缓冲区的指针。timeout: 阻塞等待时间，以 tick 为单位。
osMessageQueueGetCount(): 获取消息队列中消息数量 (对应uxQueueMessagesWaiting())。功能: 获取当前消息队列中已有的消息数量。
关键参数
:
mq_id: 要查询的消息队列 ID。
osMessageQueueDelete(): 删除消息队列 (对应vQueueDelete())。功能: 删除指定的消息队列。
关键参数
:
mq_id: 要删除的消息队列 ID。
3. 信号量管理 (Semaphore Management)
osSemaphoreNew(): 创建信号量 (对应xSemaphoreCreateBinary()和xSemaphoreCreateCounting())。功能
: 创建一个信号量，可以创建二值信号量或计数信号量，根据
max_signals参数决定。
- 如果
max_signals为 1，则创建二值信号量。 - 如果
max_signals大于 1，则创建计数信号量。
- 如果
关键参数
:
max_signals: 信号量的最大计数数量 (二值信号量为 1，计数信号量大于 1)。initial_signals: 信号量的初始计数数量。semaphore_attr: 信号量属性结构体指针，可以配置信号量属性，可以设置为NULL使用默认属性。
返回: 信号量 ID (
osSemaphoreId_t)，创建失败返回NULL。
osSemaphoreAcquire(): 获取信号量 (对应xSemaphoreTake())。功能: 尝试获取信号量。
关键参数
:
semaphore_id: 要获取的信号量 ID。timeout: 阻塞等待时间，以 tick 为单位。
osSemaphoreRelease(): 释放信号量 (对应xSemaphoreGive())。功能: 释放信号量。
关键参数
:
semaphore_id: 要释放的信号量 ID。
osSemaphoreDelete(): 删除信号量 (对应vSemaphoreDelete())。功能: 删除指定的信号量。
关键参数
:
semaphore_id: 要删除的信号量 ID。
4. 互斥锁 (Mutex) 管理
osMutexNew(): 创建互斥锁 (对应xSemaphoreCreateMutex())。功能: 创建一个互斥锁。
关键参数
:
mutex_attr: 互斥锁属性结构体指针，可以配置互斥锁属性，可以设置为NULL使用默认属性。
返回: 互斥锁 ID (
osMutexId_t)，创建失败返回NULL。
osMutexAcquire(): 获取互斥锁 (对应xSemaphoreTake())。功能: 尝试获取互斥锁。
关键参数
:
mutex_id: 要获取的互斥锁 ID。timeout: 阻塞等待时间，以 tick 为单位。
osMutexRelease(): 释放互斥锁 (对应xSemaphoreGive())。功能: 释放互斥锁。
关键参数
:
mutex_id: 要释放的互斥锁 ID。
osMutexDelete(): 删除互斥锁 (对应vSemaphoreDelete())。功能: 删除指定的互斥锁。
关键参数
:
mutex_id: 要删除的互斥锁 ID。
5. 事件标志 (Event Flags) 管理 (CMSIS-V2 中事件组称为事件标志)
osEventFlagsNew(): 创建事件标志 (对应xEventGroupCreate())。功能: 创建一个事件标志组。
关键参数
:
ef_attr: 事件标志属性结构体指针，可以配置事件标志属性，可以设置为NULL使用默认属性。
返回: 事件标志 ID (
osEventFlagsId_t)，创建失败返回NULL。
osEventFlagsSet(): 设置事件标志位 (对应xEventGroupSetBits())。功能: 设置事件标志组中指定的事件位。
关键参数
:
ef_id: 要设置事件位的事件标志 ID。flags: 要设置的事件位掩码。
osEventFlagsWait(): 等待事件标志位 (对应xEventGroupWaitBits())。功能: 等待事件标志组中指定的事件位被设置。
关键参数
:
ef_id: 要等待事件位的事件标志 ID。flags: 要等待的事件位掩码。options: 等待选项，例如osFlagsWaitAny(等待任意一个事件位被设置) 或osFlagsWaitAll(等待所有指定的事件位都被设置)。timeout: 阻塞等待时间，以 tick 为单位。
返回: 实际触发的事件位掩码。
osEventFlagsClear(): 清除事件标志位 (对应xEventGroupClearBits())。功能: 清除事件标志组中指定的事件位。
关键参数
:
ef_id: 要清除事件位的事件标志 ID。flags: 要清除的事件位掩码。
osEventFlagsDelete(): 删除事件标志 (对应vEventGroupDelete())。功能: 删除指定的事件标志组。
关键参数
:
ef_id: 要删除的事件标志 ID。
6. 定时器 (Timer) 管理 (CMSIS-V2 中软件定时器称为定时器)
osTimerNew(): 创建定时器 (对应xTimerCreate())。功能: 创建一个定时器。
关键参数
:
callback: 定时器回调函数指针。type: 定时器类型，osTimerOnce(单次触发) 或osTimerPeriodic(周期触发)。timer_attr: 定时器属性结构体指针，可以配置定时器属性，可以设置为NULL使用默认属性。
返回: 定时器 ID (
osTimerId_t)，创建失败返回NULL。
osTimerStart(): 启动定时器 (对应xTimerStart())。功能: 启动指定的定时器。
关键参数
:
timer_id: 要启动的定时器 ID。period: 定时器周期，以 tick 为单位。
osTimerStop(): 停止定时器 (对应xTimerStop())。功能: 停止指定的定时器。
关键参数
:
timer_id: 要停止的定时器 ID。
osTimerIsRunning(): 判断定时器是否运行 (对应xTimerIsTimerActive())。功能: 判断指定的定时器是否处于运行状态。
关键参数
:
timer_id: 要查询的定时器 ID。
返回:
true表示运行，false表示停止。
osTimerDelete(): 删除定时器 (对应xTimerDelete())。功能: 删除指定的定时器。
关键参数
:
timer_id: 要删除的定时器 ID。
7. 内存管理 (Memory Pool Management) (CMSIS-V2 中没有直接对应 pvPortMalloc() 和 vPortFree() 的标准 API，CMSIS-V2 提供了内存池管理，用于管理固定大小的内存块，如果需要动态内存分配，仍然需要使用原生 FreeRTOS 的 pvPortMalloc() 和 vPortFree() 或者 C 标准库的 malloc() 和 free() )
osMemoryPoolNew(): 创建内存池。功能: 创建一个内存池，用于管理固定大小的内存块。
关键参数
:
block_count: 内存池中内存块的数量。block_size: 每个内存块的大小，以字节为单位。mp_attr: 内存池属性结构体指针，可以配置内存池属性，可以设置为NULL使用默认属性。
返回: 内存池 ID (
osMemoryPoolId_t)，创建失败返回NULL。
osMemoryPoolAlloc(): 从内存池分配内存块。功能: 从内存池中分配一个内存块。
关键参数
:
mp_id: 要分配内存的内存池 ID。timeout: 阻塞等待时间，以 tick 为单位。
返回: 指向分配的内存块的指针，分配失败返回
NULL。
osMemoryPoolFree(): 释放内存块到内存池。功能: 将从内存池分配的内存块释放回内存池。
关键参数
:
mp_id: 要释放内存的内存池 ID。block: 指向要释放的内存块的指针。
osMemoryPoolDelete(): 删除内存池。功能: 删除指定的内存池。
关键参数
:
mp_id: 要删除的内存池 ID。
