CMSIS-RTOS2 文档翻译 之 参考（CMSIS-RTOS2 API 之 内核信息和控制）

内核信息和控制

CMSIS-RTOS2 API

提供版本/系统信息并启动/控制 RTOS 内核。更多...

数据结构
struct	osVersion_t
	版本信息。更多...

枚举
enum	osKernelState_t {   osKernelInactive = 0,   osKernelReady = 1,   osKernelRunning = 2,   osKernelLocked = 3,   osKernelSuspended = 4,   osKernelError = -1,   osKernelReserved = 0x7FFFFFFFU }
	内核状态。更多...

函数
osStatus_t	osKernelInitialize (void)
	初始化 RTOS 内核。更多...
osStatus_t	osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size)
	获取 RTOS 内核信息。更多...
osKernelState_t	osKernelGetState (void)
	获取当前的 RTOS 内核状态。更多...
osStatus_t	osKernelStart (void)
	启动 RTOS 内核调度程序。更多...
int32_t	osKernelLock (void)
	锁定 RTOS 内核调度程序。更多...
int32_t	osKernelUnlock (void)
	解锁 RTOS 内核调度程序。更多...
int32_t	osKernelRestoreLock (int32_t lock)
	恢复 RTOS 内核调度程序锁定状态。更多...
uint32_t	osKernelSuspend (void)
	挂起 RTOS 内核调度程序。更多...
void	osKernelResume (uint32_t sleep_ticks)
	恢复 RTOS 内核调度程序。更多...
uint32_t	osKernelGetTickCount (void)
	获取 RTOS 内核计数。更多...
uint32_t	osKernelGetTickFreq (void)
	获取 RTOS 内核节拍频率。更多...
uint32_t	osKernelGetSysTimerCount (void)
	获取 RTOS 内核系统定时器计数。更多...
uint32_t	osKernelGetSysTimerFreq (void)
	获取 RTOS 内核系统定时器频率。更多...

描述

内核信息和控制功能组允许：

• 获取有关系统和底层内核的信息。
• 获取有关 CMSIS-RTOS API 的版本信息。
• 初始化用于创建对象的 RTOS 内核。
• 启动 RTOS 内核和线程切换。
• 检查 RTOS 内核的执行状态。

注意

内核信息和控制功能不能从中断服务程序调用。

系统启动中记录了 RTX5 的内核初始化。

代码示例

/*----------------------------------------------------------------------------

* Application main thread

*---------------------------------------------------------------------------*/

void app_main ( void *argument) {

// ...

for (;;) {}

}

int main ( void) {

// System Initialization

SystemCoreClockUpdate();

#ifdef RTE_Compiler_EventRecorder

// Initialize and start Event Recorder

EventRecorderInitialize(EventRecordError, 1U);

#endif

// ...

osKernelInitialize(); // Initialize CMSIS-RTOS

osThreadNew(app_main, NULL, NULL); // Create application main thread

osKernelStart(); // Start thread execution

for (;;) {}

}

---

数据结构文档

struct osVersion_t

标识底层的 RTOS 内核和 API 版本号。该版本以格式为：major.minor.rev：mmnnnrrrr 的组合十进制数表示。

使用 osKernelGetInfo 来检索版本号。

数据字段
uint32_t	api	API 版本（major.minor.rev：mmnnnrrrr dec）。
uint32_t	kernel	内核版本（major.minor.rev：mmnnnrrrr dec）。

枚举类型文档

enum osKernelState_t

由 osKernelGetState 检索的内核状态。如果 osKernelGetState 失败或从 ISR 调用它，它将返回 osKernelError ，否则返回内核状态。

枚举
osKernelInactive	非活动。 内核还没有准备好。osKernelInitialize 需要成功执行。
osKernelReady	准备。 内核尚未运行。osKernelStart 将内核传输到运行状态。
osKernelRunning	运行。 内核已初始化并正在运行。
osKernelLocked	锁定。 内核被 osKernelLock 锁定。函数 osKernelUnlock 或 osKernelRestoreLock 将其解锁。
osKernelSuspended	暂停。 内核使用 osKernelSuspend 挂起。函数 osKernelResume 返回到正常操作。
osKernelError	错误。 发生错误。
osKernelReserved	防止枚举小型编译器优化。 保留。

函数文档

osStatus_t osKernelInitialize

(

void

)

返回

状态代码，指示该功能的执行状态。

函数 osKernelInitialize 初始化 RTOS 内核。在成功执行之前，只能调用 osKernelGetInfo 和 osKernelGetState 函数。

可能的 osStatus_t 返回值：

• osOK 如果成功。
• osError 如果发生未指定的错误。
• osErrorISR 如果从中断服务程序调用。
• osErrorNoMemory 如果没有内存可用于操作。

注意

该函数不能从中断服务程序调用。

代码示例

#include "RTE_Components.h"

#include CMSIS_device_header

#include "cmsis_os2.h"

/*----------------------------------------------------------------------------

* Application main thread

*---------------------------------------------------------------------------*/

void app_main ( void *argument) {

// ...

for (;;) {}

}

int main ( void) {

// System Initialization

SystemCoreClockUpdate();

// ...

osKernelInitialize(); // Initialize CMSIS-RTOS

osThreadNew(app_main, NULL, NULL); // Create application main thread

osKernelStart(); // Start thread execution

for (;;) {}

}

osStatus_t osKernelGetInfo	(	osVersion_t *	version,
		char *	id_buf,
		uint32_t	id_size
	)

参数

[out]	version	指向缓冲区的指针以检索版本信息。
[out]	id_buf	指向检索内核标识字符串的缓冲区的指针。
[in]	id_size	内核标识字符串的缓冲区大小。

返回

状态代码，指示该功能的执行状态。

函数 osKernelGetInfo 检索底层 RTOS 内核的 API 和内核版本以及内核的人类可读标识符字符串。可以在 RTOS 初始化或启动之前安全调用它（调用 osKernelInitialize 或 osKernelStart）。

可能的 osStatus_t 返回值：

• osOK 如果成功。
• osError 如果发生未指定的错误。

注意

这个函数可以从中断服务程序中调用。

代码示例

void info ( void) {

char infobuf[100];

osVersion_t osv;

osStatus_t status;

status = osKernelGetInfo(&osv, infobuf, sizeof(infobuf));

if(status == osOK) {

printf( "Kernel Information: %s\r\n", infobuf);

printf( "Kernel Version : %d\r\n", osv. kernel);

printf( "Kernel API Version: %d\r\n", osv. api);

}

}

osKernelState_t osKernelGetState

(

void

)

返回

当前 RTOS 内核状态。

函数 osKernelGetState 返回内核的当前状态，可以在 RTOS 初始化或启动之前安全调用（调用 osKernelInitialize 或 osKernelStart）。如果失败，将返回 osKernelError ，否则返回内核状态（请参阅 osKernelState_t 获取内核状态列表）。

可能的 osKernelState_t 返回值：

• osKernelError 如果发生未指定的错误。
• 实际的内核状态，否则。

注意

这个函数可以从中断服务程序中调用。

代码示例

int main ( void) {

// System Initialization

SystemCoreClockUpdate();

// ...

if( osKernelGetState() == osKernelInactive) { // Is the kernel initialized?

osKernelInitialize(); // Initialize CMSIS-RTOS kernel

}

;

}

osStatus_t osKernelStart

(

void

)

返回

状态代码，指示该功能的执行状态。

函数 osKernelStart 启动 RTOS 内核并开始线程切换。如果成功，它将不会返回到其调用函数。在成功执行之前，只能调用函数osKernelGetInfo ，osKernelGetState 和对象创建函数（osXxxNew）。

在 osKernelStart 之前至少应创建一个初始线程，请参阅 osThreadNew 。

可能的 osStatus_t 返回值：

• osError 如果发生未指定的错误。
• osErrorISR 如果从中断服务程序调用。

注意

该函数不能从中断服务程序调用。

代码示例

int main ( void) {

// System Initialization

SystemCoreClockUpdate();

// ...

if( osKernelGetState() == osKernelInactive) {

osKernelInitialize();

}

; // ... Start Threads

if ( osKernelGetState() == osKernelReady) { // If kernel is ready to run...

osKernelStart(); // ... start thread execution

}

while(1); // only reached in case of error

}

int32_t osKernelLock

(

void

)

返回

先前的锁定状态（1 - 锁定，0 - 未锁定，如果为负数，则为错误代码）。

函数 osKernelLock 允许锁定所有任务开关。它返回锁定状态的前一个值（如果锁定状态为 1 ，解锁为 0），否则返回代表错误代码的负数（请参阅 osStatus_t）。

可能的 osStatus_t 返回值：

• osError 如果发生未指定的错误。
• osErrorISR 如果从中断服务程序调用。

注意

该函数不能从中断服务程序调用。

代码示例

int32_t state = osKernelLock();

// ... critical code

osKernelRestore(state);

int32_t osKernelUnlock

(

void

)

返回

先前的锁定状态（1 - 锁定，0 - 未锁定，如果为负数，则为错误代码）。

osKernelUnlock 函数从 osKernelLock 继续。它返回锁定状态的前一个值（如果锁定状态为 1 ，解锁为 0），否则返回代表错误代码的负数（请参阅 osStatus_t）。

可能的 osStatus_t 返回值：

• osError 如果发生未指定的错误。
• osErrorISR 如果从中断服务程序调用。

注意

该函数不能从中断服务程序调用。

代码示例

int32_t sl = osKernelLock();

// ... critical code

{

int32_t su = osKernelUnlock();

// ... uncritical code

osKernelRestoreLock(su);

}

// ... critical code

osKernelRestoreLock(sl);

int32_t osKernelRestoreLock

(

int32_t

lock

)

参数

[in]

lock

锁状态由 osKernelLock 或 osKernelUnlock 获取。

返回

新的锁定状态（1 - 锁定，0 - 未锁定，错误代码为负数）。

osKernelRestoreLock 函数在 osKernelLock 或 osKernelUnlock 之后恢复先前的锁定状态。

参数 lock 指定由 osKernelLock 或 osKernelUnlock 获取的锁定状态。

该函数返回锁定状态的新值（如果锁定状态为锁定，则为 1，解锁为 0），否则返回代表错误代码的负数（请参阅 osStatus_t）。

可能的 osStatus_t 返回值：

• osError 如果发生未指定的错误。
• osErrorISR 如果从中断服务程序调用。

注意

该函数不能从中断服务程序调用。

代码示例

int32_t sl = osKernelLock();

// ... critical code

{

int32_t su = osKernelUnlock();

// ... uncritical code

osKernelRestoreLock(su);

}

// ... critical code

osKernelRestoreLock(sl);

uint32_t osKernelSuspend

(

void

)

返回

时间以刻度表示，系统可以睡多久或关闭电源。

CMSIS-RTOS 为无滴答操作提供了扩展，对于使用 SysTick 定时器也被禁用的广泛低功耗模式的应用非常有用。为了在这种省电模式下提供时间标记，使用唤醒定时器来导出定时器间隔。osKernelSuspend 函数暂停 RTX 内核调度程序，从而启用睡眠模式。

返回值可用于确定系统滴答的数量，直到下一个基于滴答的内核事件发生，即延迟的线程再次准备就绪。建议设置低功耗定时器以基于此返回值生成唤醒中断。

注意

该函数不能从中断服务程序调用。

代码示例

void osRtxIdleThread ( void) {

/* The idle thread is running

when no other thread is ready

to run. */

unsigned int sleep;

for (;;) {

/* HERE: include optional user

code to be executed when no

task runs. */

sleep = osKernelSuspend(); /* Suspend RTX thread scheduler */

if (sleep) { /* How long can we sleep? */

/* "sleep" is in RTX Timer Ticks

which is 1ms in this

configuration */

/* Setup wake-up e.g. watchdog */

__WFE(); /* Enter Power-down mode */

/* After Wake-up */

sleep = tc; /* Adjust with cycles slept */

}

osKernelResume(sleep); /* Resume thread scheduler */

}

}

void osKernelResume

(

uint32_t

sleep_ticks

)

参数

[in]

sleep_ticks

时间以系统处于睡眠或关机模式的时间为单位。

CMSIS-RTOS 为无滴答操作提供了扩展，对于使用 SysTick 定时器也被禁用的广泛低功耗模式的应用非常有用。为了在这种省电模式下提供时间标记，使用唤醒定时器来导出定时器间隔。函数 osKernelResume 启用 RTX 内核调度程序，从而将系统从睡眠模式中唤醒。

注意

该函数不能从中断服务程序调用。

代码示例

void osRtxIdleThread ( void) {

/* The idle thread is running

when no other thread is ready

to run. */

unsigned int sleep;

for (;;) {

/* HERE: include optional user

code to be executed when no

task runs. */

sleep = osKernelSuspend(); /* Suspend RTX thread scheduler */

if (sleep) { /* How long can we sleep? */

/* "sleep" is in RTX Timer Ticks

which is 1ms in this

configuration */

/* Setup wake-up e.g. watchdog */

__WFE(); /* Enter Power-down mode */

/* After Wake-up */

sleep = tc; /* Adjust with cycles slept */

}

osKernelResume(sleep); /* Resume thread scheduler */

}

}

uint32_t osKernelGetTickCount

(

void

)

返回

RTOS 内核当前滴答计数。

函数 osKernelGetTickCount 返回当前的 RTOS 内核滴答计数。

注意

这个函数可以从中断服务程序中调用。

代码示例

#include "cmsis_os2.h"

void Thread_1 ( void *arg) { // Thread function

uint32_t tick;

tick = osKernelGetTickCount(); // retrieve the number of system ticks

for (;;) {

tick += 1000; // delay 1000 ticks periodically

osDelayUntil(tick);

// ...

}

}

由于用于滴答计数的有限值范围，它可能会在运行时期间溢出，即在大约 49 天 @ 1ms 的滴答周期。通常情况下，除非需要单调计数器，否则不需要特别注意。对于这种情况，可以按如下方式执行额外的 64 位计时器计数器。给定的例子需要GetTick（）每个tick溢出至少调用两次才能正常工作。

代码示例

uint64_t GetTick( void) {

static uint32_t tick_h = 0U;

static uint32_t tick_l = 0U;

uint32_t tick;

tick = osKernelGetTickCount();

if (tick < tick_l) {

tick_h++;

}

tick_l = tick;

return (((uint64_t)tick_h << 32) | tick_l);

}

uint32_t osKernelGetTickFreq

(

void

)

返回

内核的频率以赫兹为单位，即每秒内核节拍个数。

函数 osKernelGetTickFreq 返回当前 RTOS 内核节拍的频率。

注意

这个函数可以从中断服务程序中调用。

uint32_t osKernelGetSysTimerCount

(

void

)

返回

RTOS 内核当前系统定时器计数为 32 位值。

函数 osKernelGetSysTimerCount 以 32 位值的形式返回当前的 RTOS 内核系统定时器的值。

注意

这个函数可以从中断服务程序中调用。

uint32_t osKernelGetSysTimerFreq

(

void

)

返回

以赫兹为单位的系统定时器的频率，即每秒定时器节拍个数。

函数 osKernelGetSysTimerFreq 返回当前 RTOS 内核系统定时器的频率。

注意

这个函数可以从中断服务程序中调用。