: v) `5 N0 z2 z/ {- R* g
$ K4 l1 Y9 x' ]( Q功能概述
1 |# Y5 Z2 Y$ f% _2 {4 r# }, Z

CMSIS-RTOS v2 提供了多种 API 接口：

- E. p; Y( p6 m& {7 h

• CMSIS-RTOS2 是支持动态对象创建和 Armv8-M（Arm Cortex-M23 和 Cortex-M33）的新 C 函数 API 。
• CMSIS-RTOS C API v1 是与 CMSIS-RTOS v1 向后兼容的 C 函数 API 。
• CMSIS-RTOS C++ API 是一个 C++ 类函数 API 。
  + K" B$ _# Y- d' q1 y% z

可以在同一应用程序中混合使用不同的 API 版本，甚至可以在同一个 C/C++ 源码模块中混用不同的 API 版本。 但是，在未来版本的 CMSIS-RTOS 中，C API v1 的功能可能会被弃用。

( N; Q% k/ k4 \: p0 iCMSIS-RTOS2

在 cmsis_os2.h 头文件中实现的所有 CMSIS-RTOS C API v2 函数的概述。

通用设计概念

所有的 RTOS 对象都有一个共同的设计概念。对象的整个生命周期可以概括为创建 -> 使用 -> 销毁。

创建对象

' t- |" x) \. |( M9 `

通过调用它的 osXxxNew 函数创建一个对象。新函数返回一个可用于与新对象一起操作的标识符。一个对象的实际状态通常存储在一个对象特定的控制块中。控制块的内存布局（和所需的大小）是特定于实现的。人们不应该对控制块做任何具体的假设。控制块布局可能会发生变化，因此应视为实现内部的细节。

为了公开有关对象特定选项的控制，所有 osXxxNew 函数都提供了一个可选的 attr 参数，默认情况下它可以保留为 NULL 。它需要一个指向特定于对象的属性结构的指针，通常包含这些字段

  C1 A. q4 M! d; `0 M! z' `1 `, |

• name 为了标识附加可读的名称，
• attr_bits 控制对象特定的选项，
• cb_mem 手动为控制块提供内存
• cb_size 量化为控制块提供的内存大小。
  

, Z- V# ]1 O- r  R

name 属性仅用于对象识别，例如，使用 RTOS 感知调试。附加的字符串不用于内部任何其他的作用。

2 `3 E5 H" ?5 Q& [" @; h

可以使用 cb_mem 和 cb_size 属性手动为控制块提供内存，而不是依赖实现内部的内存分配。必须确保 cb_mem 指向的内存量足够用于对象控制块的结构。如果以 cb_size 给出的大小不足，则 osXxxNew 函数返回一个错误，即返回 NULL 。此外手动提供控制块存储器的便携性较差。因此，例如，人们必须关注实现特定的对齐和放置要求。有关详细信息，请参阅内存管理。

对象使用

对象创建成功后，可以使用该对象直到它被销毁。为对象定义的动作取决于其类型。通常，所有 osXxxDoSomething 访问函数都需要引用该对象作为第一个 xxx_id 参数。

5 }0 T# h2 u' M+ a: [: E) e

访问函数可以假定对 id 参数进行某种理智检查。这样就可以确保不会意外地用 NULL 对象引用调用访问函数。此外，验证具体对象类型，即不能通过引用另一对象类型来调用一个对象类型的访问函数。

% r6 R, C; }! j$ _; G2 i

应用的所有其他参数检查都是对象和操作特定的，或者甚至可能是特定于实现的。因此，应该总是检查 osErrorParameter 的动作函数返回值，以确认提供的参数被接受。

; e7 a' [6 b$ ^

根据经验，中断服务程序（Interrupt Service Routines，ISR）只能使用非阻塞访问功能。这包含 osXxxWait 函数（以及类似的），仅限于在参数timeout 设置为 0 的情况下调用，即使用 try-semantics 。

7 r9 h! r0 R  S/ G. r/ E: D8 u

对象销毁

不再需要的对象可以根据需要销毁以释放控制块内存。对象不会隐式地被破坏。因此可以假定一个对象 id 是有效的，直到 osXxxDelete 被显式调用。删除功能最终释放控制块内存。如果用户提供了控制块存储器，请参见上文，存储器也必须手动释放。

9 Z+ c; X4 ^# C9 d  A

唯一需要注意的例外是没有显式 osThreadDelete 函数的线程。线程可以是分离的或可连接的。分离线程在终止时自动销毁，即调用 osThreadTerminate 或 osThreadExit 或从线程函数返回。另一方面，可连接线程保持活动状态，直到明确调用 osThreadJoin 。

4 {- @- i( b. p  }/ m0 B

函数参考

: B6 a1 k" ^; M, f0 ?

• 内核信息和控制
  
  • osKernelGetInfo : 获取 RTOS 内核信息。
  • osKernelGetState : 获取当前 RTOS 内核状态。
  • osKernelGetSysTimerCount : 获取 RTOS 内核的系统计时器的计数。
  • osKernelGetSysTimerFreq : 获取 RTOS 内核的系统定时器的频率。
  • osKernelInitialize : 初始化 RTOS 内核。
  • osKernelLock : 锁定 RTOS 内核调度程序。
  • osKernelUnlock : 解锁 RTOS 内核调度程序。
  • osKernelRestoreLock : 恢复 RTOS 内核调度程序的锁定状态。
  • osKernelResume : 恢复 RTOS 内核调度程序。
  • osKernelStart : 启动 RTOS 内核调度程序。
  • osKernelSuspend : 挂起 RTOS 内核调度程序。
  • osKernelGetTickCount : 获取 RTOS 内核计数。
  • osKernelGetTickFreq : 获取 RTOS 内核滴答频率。
    ' S) W" Z/ I# Y
  
  # U; k$ w/ j1 z$ i% B

• 线程管理
  
  • osThreadDetach : 分离一个线程（当线程终止时线程存储可以被回收）。
  • osThreadEnumerate : 枚举活动线程。
  • osThreadExit : 终止当前正在运行的线程。
  • osThreadGetCount : 获取活动线程的数量。
  • osThreadGetId : 返回当前正在运行的线程的线程 ID 。
  • osThreadGetName : 获取线程的名称。
  • osThreadGetPriority : 获取线程的当前优先级。
  • osThreadGetStackSize : 获取线程的堆栈大小。
  • osThreadGetStackSpace : 在执行期间基于堆栈水印记录获取线程的可用堆栈空间。
  • osThreadGetState : 获取线程的当前线程状态。
  • osThreadJoin : 等待指定的线程终止。
  • osThreadNew : 创建一个线程并将其添加到活动线程。
  • osThreadResume : 恢复线程的执行。
  • osThreadSetPriority : 更改线程的优先级。
  • osThreadSuspend : 暂停执行一个线程。
  • osThreadTerminate : 终止线程的执行。
  • osThreadYield : 将控制权交给状态为 READY 的下一个线程。
    
  
    L9 u+ Z3 L3 f! [& {

• 线程标志
  $ C0 O0 ?/ @- t& \0 C6 Q
  • osThreadFlagsSet : 设置线程指定的线程标志。
  • osThreadFlagsClear : 清除当前运行线程指定的线程标志。
  • osThreadFlagsGet : 获取当前正在运行的线程的当前线程标志。
  • osThreadFlagsWait : 等待当前正在运行的线程的一个或多个线程标志发出信号。
    
• 事件标志
  * r) w7 R( n( l$ D& z4 V5 g+ R
  • osEventFlagsGetName : 获取事件标志对象的名称。
  • osEventFlagsNew : 创建并初始化事件标志对象。
  • osEventFlagsDelete : 删除事件标志对象。
  • osEventFlagsSet : 设置指定的事件标志。
  • osEventFlagsClear : 清除指定的事件标志。
  • osEventFlagsGet : 获取当前的事件标志。
  • osEventFlagsWait : 等待一个或多个事件标志发出信号。
    # r# E# a5 Y3 \/ p
  
  

• 通用等待函数
  
  • osDelay : 等待超时（时间延迟）。
  • osDelayUntil : 等到指定的时间。
    
• 定时器管理
  & `8 J: E" q; M' s
  • osTimerDelete : 删除一个定时器。
  • osTimerGetName : 获取定时器的名称。
  • osTimerIsRunning : 检查定时器是否正在运行。
  • osTimerNew : 创建并初始化一个定时器。
  • osTimerStart : 启动或重新启动定时器。
  • osTimerStop : 停止一个定时器。
    1 G6 p: l0 t' o0 V1 x- w; G
• 互斥管理
  
  • osMutexAcquire : 如果它被锁定，则获取互斥锁或超时值。
  • osMutexDelete : 删除互斥对象。
  • osMutexGetName : 获取互斥对象的名称。
  • osMutexGetOwner : 获取拥有互斥对象的线程。
  • osMutexNew : 创建并初始化一个互斥对象。
  • osMutexRelease : 释放由 osMutexAcquire 获取的互斥锁。
    
  
  7 Y# Y; I& `* ^' \/ I" N

• 信号量
    O1 b7 q2 Y7 e0 P7 A4 F) L7 v
  • osSemaphoreAcquire : 如果没有令牌可用，请获取信号量令牌或超时。
  • osSemaphoreDelete : 删除一个信号量对象。
  • osSemaphoreGetCount : 获取当前的信号量令牌计数。
  • osSemaphoreGetName : 获取信号量对象的名称。
  • osSemaphoreNew : 创建并初始化信号量对象。
  • osSemaphoreRelease : 释放一个信号量令牌直到最初的最大数量。
    
• 内存池
  
  • osMemoryPoolAlloc : 从内存池中分配内存块。
  • osMemoryPoolDelete : 删除一个内存池对象。
  • osMemoryPoolFree : 将分配的内存块返还给内存池。
  • osMemoryPoolGetBlockSize : 获取内存池中的内存块大小。
  • osMemoryPoolGetCapacity : 获取内存池中的最大内存块数。
  • osMemoryPoolGetCount : 获取内存池中使用的内存块数量。
  • osMemoryPoolGetName : 获取内存池对象的名称。
  • osMemoryPoolGetSpace : 获取内存池中可用的内存块数量。
  • osMemoryPoolNew : 创建并初始化一个内存池对象。
    . G& l* H+ g4 [
  
  ( Z( r; J  J  G3 u) {

• 消息队列
  
  • osMessageQueueDelete : 删除一个消息队列对象。
  • osMessageQueueGet : 如果队列为空，则从队列获取消息或超时。
  • osMessageQueueGetCapacity : 在消息队列中获取最大数量的消息。
  • osMessageQueueGetCount : 获取消息队列中排队的消息数量。
  • osMessageQueueGetMsgSize : 获取内存池中的最大消息大小。
  • osMessageQueueGetName : 获取消息队列对象的名称。
  • osMessageQueueGetSpace : 获取消息队列中消息的可用插槽数量。
  • osMessageQueueNew : 创建并初始化消息队列对象。
  • osMessageQueuePut : 如果队列已满，请将消息放入队列或超时。
  • osMessageQueueReset : 将消息队列重置为初始空状态。
    
• OS Tick API
  
  • OS_Tick_Setup : 建立 OS Tick 。
  • OS_Tick_Enable : 启用 OS Tick 。
  • OS_Tick_Disable : 禁用 OS Tick 。
  • OS_Tick_AcknowledgeIRQ : 确认 OS Tick IRQ 。
  • OS_Tick_GetIRQn : 获取 OS Tick IRQ 编号。
  • OS_Tick_GetClock : 获取 OS Tick 时钟。
  • OS_Tick_GetInterval : 获取 OS Tick 间隔。
  • OS_Tick_GetCount : 获取 OS Tick 计数值。
  • OS_Tick_GetOverflow : 获取 OS Tick 溢出状态。
    
• RTX5 特定的 API
  
  • osRtxErrorNotify : OS 错误回调函数。
  • osRtxIdleThread : OS 空闲线程。
    ) {  T2 y4 i! n( n6 }
  
  

可以从线程和中断服务程序（ISR）调用以下 CMSIS-RTOS2 函数：

$ V( a9 n1 }& r* F' E1 w) N) M

• osKernelGetInfo, osKernelGetState, osKernelGetTickCount, osKernelGetTickFreq, osKernelGetSysTimerCount, osKernelGetSysTimerFreq
• osThreadFlagsSet
• osEventFlagsSet, osEventFlagsClear, osEventFlagsGet, osEventFlagsWait
• osSemaphoreAcquire, osSemaphoreRelease, osSemaphoreGetCount
• osMemoryPoolAlloc, osMemoryPoolFree, osMemoryPoolGetCapacity, osMemoryPoolGetBlockSize, osMemoryPoolGetCount, osMemoryPoolGetSpace
• osMessageQueuePut, osMessageQueueGet, osMessageQueueGetCapacity, osMessageQueueGetMsgSize, osMessageQueueGetCount, osMessageQueueGetSpace
  

( q7 }' X  o0 I" ]  y$ ~; l' Z2 E% V归档链接：
CMSIS-RTOS2 文档翻译 之 简介
CMSIS-RTOS2 文档翻译 之 修订记录
* M6 J+ {- P8 yCMSIS-RTOS2 文档翻译 之 通用 RTOS 接口
CMSIS-RTOS2 文档翻译 之 RTOS 验证