CMSIS RTOS V1.0 核心函数全解析与实战指南

CMSIS RTOS V1.0 核心函数全解析与实战指南 HAL STM32 CubeMX CubeIDE ....

引言

CMSIS RTOS 是 ARM 公司为 Cortex-M 系列微控制器推出的一套实时操作系统接口标准。它为不同的 RTOS 内核（如 FreeRTOS、Keil RTX 等）提供了统一的 API，使得开发者可以更容易地在不同的 RTOS 之间切换，同时也简化了嵌入式实时系统的开发流程。

本文将详细介绍 CMSIS RTOS 中最常用的核心函数，包括内核控制、线程管理、定时器、信号量、互斥量、内存池、消息队列和邮件队列等。通过本文的学习，你将能够快速上手 CMSIS RTOS，并熟练运用这些函数来构建你的实时嵌入式应用。

---

一、内核控制函数

这类函数主要用于控制 RTOS 内核的启动和运行状态查询。

1. osStatus osKernelStart (void)

• 功能：通过执行指定的线程启动 RTOS 内核。
• 返回值：osOK表示系统正常启动。
• 备注：通常在main函数中，完成所有初始化后调用此函数。

2. int32_t osKernelRunning(void)

• 功能：检查 RTOS 内核是否已经启动。
• 返回值：
  • 1：RTOS 已启动。
  • 0：RTOS 未启动。
  • -1：在FreeRTOSConfig.h中禁止了此函数。

3. uint32_t osKernelSysTick(void)

• 功能：获取内核 SysTick 计时器的值。
• 返回值：当前 SysTick 计数器的值。
• 备注：此值在osKernelStart之后开始递增，可用于实现高精度延时或时间戳。

---

二、线程管理函数

线程是 RTOS 中任务调度的基本单位。

1. osThreadId osThreadCreate (const osThreadDef_t *thread_def, void *argument)

• 功能：创建一个线程并将其添加到活动线程列表，设置为就绪状态。
• 参数：
  • thread_def：指向osThreadDef_t结构体的指针，该结构体定义了线程的名称、入口函数、优先级、堆栈大小等属性。

  c

  运行

  typedef struct os_thread_def {
    char                   *name;        ///< 线程名称
    os_pthread             pthread;      ///< 线程函数的地址
    osPriority             tpriority;    ///< 线程的初始优先级
    uint32_t               instances;    ///< 该线程函数的最大实例数
    uint32_t               stacksize;    ///< 堆栈大小(字节); 0为默认堆栈大小
  #if( configSUPPORT_STATIC_ALLOCATION == 1 )
    uint32_t               *buffer;      ///< 静态分配的堆栈缓冲区; NULL为动态分配
    osStaticThreadDef_t    *controlblock; ///< 静态分配的控制块; NULL为动态分配
  #endif
  } osThreadDef_t;
  

  • argument：传递给线程函数的参数指针。
• 返回值：成功返回线程 ID，失败返回NULL。

2. osThreadId osThreadGetId (void)

• 功能：返回当前正在运行的线程的线程 ID。
• 返回值：当前线程 ID，出错返回NULL。

3. osStatus osThreadTerminate (osThreadId thread_id)

• 功能：终止一个线程的执行，并将其从活动线程列表中删除。
• 参数：thread_id：要终止的线程 ID。
• 返回值：osOK表示成功，其他值表示失败。

4. osStatus osThreadYield (void)

• 功能：主动放弃 CPU 控制权，将控制权传递给下一个就绪状态的线程。
• 返回值：osOK表示成功。

5. osStatus osThreadSetPriority (osThreadId thread_id, osPriority priority)

• 功能：更改活动线程的优先级。
• 参数：
  • thread_id：目标线程 ID。
  • priority：新的优先级（osPriorityIdle, osPriorityLow, osPriorityBelowNormal, osPriorityNormal, osPriorityAboveNormal, osPriorityHigh, osPriorityRealtime）。
• 返回值：osOK表示成功。

6. osPriority osThreadGetPriority (osThreadId thread_id)

• 功能：获取活动线程的当前优先级。
• 参数：thread_id：目标线程 ID。
• 返回值：返回线程的当前优先级。

7. osStatus osDelay (uint32_t millisec)

• 功能：线程延时函数，使当前线程进入阻塞状态。
• 参数：millisec：延时时间（毫秒）。
• 返回值：osOK表示成功。
• 备注：延时时间是相对的，且不精确到毫秒级别，具体取决于系统时钟节拍。

8. osStatus osDelayUntil (uint32_t *PreviousWakeTime, uint32_t millisec)

• 功能：延迟任务直到指定的绝对时间点。
• 参数：
  • PreviousWakeTime：指向保存上一次唤醒时间的变量的指针。第一次使用前必须用osKernelSysTick()初始化。
  • millisec：延时时间（毫秒）。
• 返回值：osOK表示成功。
• 备注：适用于需要周期性执行的任务，能保证固定的执行间隔。

9. osThreadState osThreadGetState(osThreadId thread_id)

• 功能：获取指定线程的状态。
• 参数：thread_id：目标线程 ID。
• 返回值：返回线程的状态（osThreadInactive, osThreadReady, osThreadRunning, osThreadBlocked, osThreadTerminated）。

10. osStatus osThreadSuspend (osThreadId thread_id)

• 功能：暂停指定线程的执行。
• 参数：thread_id：目标线程 ID。
• 返回值：osOK表示成功。

11. osStatus osThreadResume (osThreadId thread_id)

• 功能：恢复被暂停的线程的执行。
• 参数：thread_id：目标线程 ID。
• 返回值：osOK表示成功。

---

三、定时器函数

定时器用于实现延时触发或周期性触发某些操作。

1. osTimerId osTimerCreate (const osTimerDef_t *timer_def, os_timer_type type, void *argument)

• 功能：创建一个定时器。
• 参数：
  • timer_def：指向osTimerDef_t结构体的指针，定义了定时器的回调函数。

  c

  运行

  typedef struct os_timer_def {
    os_ptimer                 ptimer;    ///< 计时器函数的起始地址
  #if( configSUPPORT_STATIC_ALLOCATION == 1 )
    osStaticTimerDef_t        *controlblock; ///< 静态分配的控制块
  #endif
  } osTimerDef_t;
  

  • type：定时器类型（osTimerOnce为单次触发，osTimerPeriodic为周期性触发）。
  • argument：传递给定时器回调函数的参数指针。
• 返回值：成功返回定时器 ID，失败返回NULL。

2. osStatus osTimerStart (osTimerId timer_id, uint32_t millisec)

• 功能：启动或重启定时器。
• 参数：
  • timer_id：定时器 ID。
  • millisec：定时器触发周期（毫秒）。
• 返回值：osOK表示成功。

3. osStatus osTimerStop (osTimerId timer_id)

• 功能：停止定时器。
• 参数：timer_id：定时器 ID。
• 返回值：osOK表示成功。

4. osStatus osTimerDelete (osTimerId timer_id)

• 功能：删除定时器。
• 参数：timer_id：定时器 ID。
• 返回值：osOK表示成功。

---

四、信号量函数

信号量用于实现线程间的同步与互斥。

1. osSemaphoreId osSemaphoreCreate (const osSemaphoreDef_t *semaphore_def, int32_t count)

• 功能：创建并初始化一个信号量对象。
• 参数：
  • semaphore_def：指向osSemaphoreDef_t结构体的指针。

  c

  运行

  typedef struct os_semaphore_def {
    uint32_t                   dummy;    ///< 占位符
  #if( configSUPPORT_STATIC_ALLOCATION == 1 )
    osStaticSemaphoreDef_t     *controlblock; ///< 静态分配的控制块
  #endif
  } os_semaphore_def_t;
  

  • count：信号量的初始计数值。
• 返回值：成功返回信号量 ID，失败返回NULL。

2. int32_t osSemaphoreWait (osSemaphoreId semaphore_id, uint32_t millisec)

• 功能：等待信号量（P 操作）。
• 参数：
  • semaphore_id：信号量 ID。
  • millisec：等待超时时间（毫秒），osWaitForever表示永久等待。
• 返回值：成功返回信号量的当前计数值，失败返回 - 1。

3. osStatus osSemaphoreRelease (osSemaphoreId semaphore_id)

• 功能：释放信号量（V 操作）。
• 参数：semaphore_id：信号量 ID。
• 返回值：osOK表示成功。

4. osStatus osSemaphoreDelete (osSemaphoreId semaphore_id)

• 功能：删除信号量。
• 参数：semaphore_id：信号量 ID。
• 返回值：osOK表示成功。

5. uint32_t osSemaphoreGetCount(osSemaphoreId semaphore_id)

• 功能：获取信号量的当前计数值。
• 参数：semaphore_id：信号量 ID。
• 返回值：返回信号量的当前计数值。

---

五、互斥量函数

互斥量用于实现线程间的互斥访问共享资源。

1. osMutexId osMutexCreate (const osMutexDef_t *mutex_def)

• 功能：创建并初始化一个互斥量对象。
• 参数：mutex_def：指向osMutexDef_t结构体的指针。

  c

  运行

  typedef struct os_mutex_def {
    uint32_t                   dummy;    ///< 占位符
  #if( configSUPPORT_STATIC_ALLOCATION == 1 )
    osStaticMutexDef_t         *controlblock; ///< 静态分配的控制块
  #endif
  } os_mutex_def_t;
  

• 返回值：成功返回互斥量 ID，失败返回NULL。

2. osStatus osMutexWait (osMutexId mutex_id, uint32_t millisec)

• 功能：等待互斥量（加锁）。
• 参数：
  • mutex_id：互斥量 ID。
  • millisec：等待超时时间（毫秒）。
• 返回值：osOK表示成功。

3. osStatus osMutexRelease (osMutexId mutex_id)

• 功能：释放互斥量（解锁）。
• 参数：mutex_id：互斥量 ID。
• 返回值：osOK表示成功。

4. osStatus osMutexDelete (osMutexId mutex_id)

• 功能：删除互斥量。
• 参数：mutex_id：互斥量 ID。
• 返回值：osOK表示成功。

5. osMutexId osRecursiveMutexCreate (const osMutexDef_t *mutex_def)

• 功能：创建并初始化一个递归互斥量。
• 参数：mutex_def：指向osMutexDef_t结构体的指针。
• 返回值：成功返回递归互斥量 ID，失败返回NULL。
• 备注：递归互斥量允许同一个线程多次获取，但获取和释放的次数必须相等。

6. osStatus osRecursiveMutexWait (osMutexId mutex_id, uint32_t millisec)

• 功能：等待递归互斥量。
• 参数：
  • mutex_id：递归互斥量 ID。
  • millisec：等待超时时间（毫秒）。
• 返回值：osOK表示成功。

7. osStatus osRecursiveMutexRelease (osMutexId mutex_id)

• 功能：释放递归互斥量。
• 参数：mutex_id：递归互斥量 ID。
• 返回值：osOK表示成功。

---

六、内存池函数

内存池用于高效地分配和释放固定大小的内存块。

1. osPoolId osPoolCreate (const osPoolDef_t *pool_def)

• 功能：创建并初始化一个内存池。
• 参数：pool_def：指向osPoolDef_t结构体的指针，定义了内存池的大小和每个内存块的大小。

  c

  运行

  typedef struct os_pool_def {
    uint32_t                 pool_sz;    ///< 池中的内存块数量
    uint32_t                 item_sz;    ///< 每个内存块的大小(字节)
    void                     *pool;      ///< 内存池的起始地址
  } os_pool_def_t;
  

• 返回值：成功返回内存池 ID，失败返回NULL。

2. void *osPoolAlloc (osPoolId pool_id)

• 功能：从内存池中分配一个内存块。
• 参数：pool_id：内存池 ID。
• 返回值：成功返回分配的内存块地址，失败返回NULL。
• 备注：分配的内存块未初始化。

3. void *osPoolCAlloc (osPoolId pool_id)

• 功能：从内存池中分配一个内存块，并将其初始化为零。
• 参数：pool_id：内存池 ID。
• 返回值：成功返回分配的内存块地址，失败返回NULL。

4. osStatus osPoolFree (osPoolId pool_id, void *block)

• 功能：将分配的内存块释放回内存池。
• 参数：
  • pool_id：内存池 ID。
  • block：要释放的内存块地址。
• 返回值：osOK表示成功。

---

七、消息队列函数

消息队列用于线程间传递数据。

1. osMessageQId osMessageCreate (const osMessageQDef_t *queue_def, osThreadId thread_id)

• 功能：创建并初始化一个消息队列。
• 参数：
  • queue_def：指向osMessageQDef_t结构体的指针，定义了消息队列的大小和每个消息的大小。

  c

  运行

  typedef struct os_messageQ_def {
    uint32_t                queue_sz;    ///< 队列可存储的消息数量
    uint32_t                item_sz;     ///< 每个消息的大小(字节)
  #if( configSUPPORT_STATIC_ALLOCATION == 1 )
    uint8_t                 *buffer;     ///< 静态分配的队列缓冲区
    osStaticMessageQDef_t   *controlblock; ///< 静态分配的控制块
  #endif
  } os_messageQ_def_t;
  

  • thread_id：通常为NULL。
• 返回值：成功返回消息队列 ID，失败返回NULL。

2. osStatus osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec)

• 功能：将一个 32 位的消息放入消息队列。
• 参数：
  • queue_id：消息队列 ID。
  • info：要发送的 32 位消息。
  • millisec：等待队列有空间的超时时间（毫秒）。
• 返回值：osOK表示成功。

3. osEvent osMessageGet (osMessageQId queue_id, uint32_t millisec)

• 功能：从消息队列中获取一个消息。
• 参数：
  • queue_id：消息队列 ID。
  • millisec：等待消息的超时时间（毫秒）。
• 返回值：返回一个osEvent结构体，其中value.v包含接收到的 32 位消息，status表示操作状态。

4. osEvent osMessagePeek (osMessageQId queue_id, uint32_t millisec)

• 功能：从消息队列中查看一个消息，但不将其从队列中移除。
• 参数：
  • queue_id：消息队列 ID。
  • millisec：等待消息的超时时间（毫秒）。
• 返回值：返回一个osEvent结构体，包含查看的消息和操作状态。

5. uint32_t osMessageWaiting(osMessageQId queue_id)

• 功能：获取消息队列中当前等待的消息数量。
• 参数：queue_id：消息队列 ID。
• 返回值：返回队列中的消息数量。

6. osStatus osMessageDelete (osMessageQId queue_id)

• 功能：删除消息队列。
• 参数：queue_id：消息队列 ID。
• 返回值：osOK表示成功。

---

八、邮件队列函数

邮件队列用于在线程间传递指针类型的数据。

1. osMailQId osMailCreate (const osMailQDef_t *queue_def, osThreadId thread_id)

• 功能：创建并初始化一个邮件队列。
• 参数：
  • queue_def：指向osMailQDef_t结构体的指针，定义了邮件队列的大小和每个邮件的大小。

  c

  运行

  typedef struct os_mailQ_def {
    uint32_t                queue_sz;    ///< 队列可存储的邮件数量
    uint32_t                item_sz;     ///< 每个邮件的大小(字节)
    struct os_mailQ_cb      **cb;
  } os_mailQ_def_t;
  

  • thread_id：通常为NULL。
• 返回值：成功返回邮件队列 ID，失败返回NULL。

2. void *osMailAlloc (osMailQId queue_id, uint32_t millisec)

• 功能：从邮件队列的内存池中分配一个邮件内存块。
• 参数：
  • queue_id：邮件队列 ID。
  • millisec：等待内存块的超时时间（毫秒）。
• 返回值：成功返回分配的邮件内存块地址，失败返回NULL。

3. osStatus osMailPut (osMailQId queue_id, void *mail)

• 功能：将一个邮件（指针）放入邮件队列。
• 参数：
  • queue_id：邮件队列 ID。
  • mail：指向已分配并填充数据的邮件内存块的指针。
• 返回值：osOK表示成功。

4. osEvent osMailGet (osMailQId queue_id, uint32_t millisec)

• 功能：从邮件队列中获取一个邮件。
• 参数：
  • queue_id：邮件队列 ID。
  • millisec：等待邮件的超时时间（毫秒）。
• 返回值：返回一个osEvent结构体，其中value.p包含接收到的邮件指针，status表示操作状态。

5. osStatus osMailFree (osMailQId queue_id, void *mail)

• 功能：将邮件内存块释放回邮件队列的内存池。
• 参数：
  • queue_id：邮件队列 ID。
  • mail：要释放的邮件内存块指针。
• 返回值：osOK表示成功。