CMSIS-RTOS2 文档翻译 之 参考（CMSIS-RTOS2 API 之 线程管理）

线程管理

CMSIS-RTOS2 API

定义，创建和控制线程函数。更多...

数据结构
struct	osThreadAttr_t
	线程的属性结构体。更多...

宏定义
#define	osThreadJoinable   0x00000001U
	线程在可连接模式下创建。更多...
#define	osThreadDetached   0x00000000U
	线程以分离模式创建（默认）。更多...

类型定义
typedef void(*	osThreadFunc_t )(void *argument)
	线程的入口点。更多...
typedef void *	osThreadId_t

枚举
enum	osThreadState_t {   osThreadInactive = 0,   osThreadReady = 1,   osThreadRunning = 2,   osThreadBlocked = 3,   osThreadTerminated = 4,   osThreadError = -1,   osThreadReserved = 0x7FFFFFFF }
	线程状态。更多...
enum	osPriority_t {   osPriorityNone = 0,   osPriorityIdle = 1,   osPriorityLow = 8,   osPriorityLow1 = 8+1,   osPriorityLow2 = 8+2,   osPriorityLow3 = 8+3,   osPriorityLow4 = 8+4,   osPriorityLow5 = 8+5,   osPriorityLow6 = 8+6,   osPriorityLow7 = 8+7,   osPriorityBelowNormal = 16,   osPriorityBelowNormal1 = 16+1,   osPriorityBelowNormal2 = 16+2,   osPriorityBelowNormal3 = 16+3,   osPriorityBelowNormal4 = 16+4,   osPriorityBelowNormal5 = 16+5,   osPriorityBelowNormal6 = 16+6,   osPriorityBelowNormal7 = 16+7,   osPriorityNormal = 24,   osPriorityNormal1 = 24+1,   osPriorityNormal2 = 24+2,   osPriorityNormal3 = 24+3,   osPriorityNormal4 = 24+4,   osPriorityNormal5 = 24+5,   osPriorityNormal6 = 24+6,   osPriorityNormal7 = 24+7,   osPriorityAboveNormal = 32,   osPriorityAboveNormal1 = 32+1,   osPriorityAboveNormal2 = 32+2,   osPriorityAboveNormal3 = 32+3,   osPriorityAboveNormal4 = 32+4,   osPriorityAboveNormal5 = 32+5,   osPriorityAboveNormal6 = 32+6,   osPriorityAboveNormal7 = 32+7,   osPriorityHigh = 40,   osPriorityHigh1 = 40+1,   osPriorityHigh2 = 40+2,   osPriorityHigh3 = 40+3,   osPriorityHigh4 = 40+4,   osPriorityHigh5 = 40+5,   osPriorityHigh6 = 40+6,   osPriorityHigh7 = 40+7,   osPriorityRealtime = 48,   osPriorityRealtime1 = 48+1,   osPriorityRealtime2 = 48+2,   osPriorityRealtime3 = 48+3,   osPriorityRealtime4 = 48+4,   osPriorityRealtime5 = 48+5,   osPriorityRealtime6 = 48+6,   osPriorityRealtime7 = 48+7,   osPriorityISR = 56,   osPriorityError = -1,   osPriorityReserved = 0x7FFFFFFF }
	优先级值。更多...

函数
osThreadId_t	osThreadNew (osThreadFunc_t func, void *argument, const osThreadAttr_t *attr)
	创建一个线程并将其添加到活动线程。更多...
const char *	osThreadGetName (osThreadId_t thread_id)
	获取线程的名称。更多...
osThreadId_t	osThreadGetId (void)
	返回当前正在运行的线程的线程 ID 。更多...
osThreadState_t	osThreadGetState (osThreadId_t thread_id)
	获取线程的当前线程状态。更多...
osStatus_t	osThreadSetPriority (osThreadId_t thread_id, osPriority_t priority)
	更改线程的优先级。更多...
osPriority_t	osThreadGetPriority (osThreadId_t thread_id)
	获取线程的当前优先级。更多...
osStatus_t	osThreadYield (void)
	将控制权交给状态为 READY 的下一个线程。更多...
osStatus_t	osThreadSuspend (osThreadId_t thread_id)
	暂停执行一个线程。更多...
osStatus_t	osThreadResume (osThreadId_t thread_id)
	恢复线程的执行。更多...
osStatus_t	osThreadDetach (osThreadId_t thread_id)
	分离一个线程（当线程终止时线程存储可以被回收）。更多...
osStatus_t	osThreadJoin (osThreadId_t thread_id)
	等待指定的线程终止。更多...
__NO_RETURN void	osThreadExit (void)
	终止当前正在运行的线程的执行。更多...
osStatus_t	osThreadTerminate (osThreadId_t thread_id)
	终止线程的执行。更多...
uint32_t	osThreadGetStackSize (osThreadId_t thread_id)
	获取线程的堆栈大小。更多...
uint32_t	osThreadGetStackSpace (osThreadId_t thread_id)
	在执行期间基于堆栈水印记录获取线程的可用堆栈空间。更多...
uint32_t	osThreadGetCount (void)
	获取活动线程的数量。更多...
uint32_t	osThreadEnumerate (osThreadId_t *thread_array, uint32_t array_items)
	枚举活动线程。更多...

描述

线程管理功能组允许在系统中定义，创建和控制线程功能。

注意

线程管理函数不能从中断服务例程调用。

线程状态

线程可以处于以下状态：

• RUNNING: 当前正在运行的线程处于 RUNNING 状态。一次只能有一个线程处于这种状态。
• READY: 准备运行的线程处于 READY 状态。一旦 RUNNING 线程终止或被 BLOCKED ，具有最高优先级的下一个 READY 线程将成为 RUNNING 线程。
• BLOCKED: 阻塞的线程被延迟，等待事件发生或挂起的线程处于 BLOCKED 状态。
• TERMINATED: 当调用 osThreadTerminate 时，线程将终止，资源尚未释放。
• INACTIVE: 未创建或已终止释放所有资源的线程处于 INACTIVE 状态。

线程状态和状态转换

CMSIS-RTOS 假定线程按照线程状态和状态转换图所示进行调度。线程状态更改如下：

• 一个线程是使用函数 osThreadNew 创建的。这使线程进入 READY 或 RUNNING 状态（取决于线程的优先级）。
• CMSIS-RTOS 是先发制人的。具有最高优先级的活动线程变成 RUNNING 线程，只要它不等待任何事件。线程的初始优先级用 osThreadAttr_t 定义，但可以在执行期间使用函数 osThreadSetPriority 更改。
• RUNNING 线程在延迟，等待事件或暂停时转入 BLOCKED 状态。
• 使用函数 osThreadTerminate 可以在任何时候终止活动线程。线程也可以通过从线程函数返回来终止。终止的线程处于 INACTIVE 状态，通常不会消耗任何动态内存资源。

注意

有关 RTX5 配置选项，请参阅线程配置。

线程示例

以下示例显示了创建线程的各种方案：

示例 1 - 创建一个简单的线程

使用全局内存池中线程属性和内存的所有默认值，从函数 thread1 中创建一个线程。

__NO_RETURN void thread1 ( void *argument) {

// ...

for (;;) {}

}

int main ( void) {

osKernelInitialize();

;

osThreadNew(thread1, NULL, NULL); // Create thread with default settings

;

osKernelStart();

}

示例 2 - 使用堆栈非默认堆栈大小创建线程

类似于简单的线程，所有的属性都是默认的。该堆栈是从全局内存池动态分配的

osThreadAttr_t::stack_size 用于将字节中的堆栈大小传递给 osThreadNew 。

__NO_RETURN void thread1 ( void *argument) {

// ...

for (;;) {}

}

const osThreadAttr_t thread1_attr = {

. stack_size = 1024 // Create the thread stack with a size of 1024 bytes

};

int main ( void) {

;

osThreadNew(thread1, NULL, &thread1_attr); // Create thread with custom sized stack memory

;

}

示例 3 - 使用静态分配的堆栈创建线程

类似于简单的线程，所有的属性都是默认的。使用 uint64_t 数组 thread1_stk_1 静态分配堆栈。这分配 64 * 8 字节（= 512 字节），对齐 8 字节（Cortex-M 堆栈内存是必需的）。

osThreadAttr_t::stack_mem 保存一个指向堆栈最低地址的指针。

osThreadAttr_t::stack_size 用于将字节中的堆栈大小传递给 osThreadNew 。

__NO_RETURN void thread1 ( void *argument) {

// ...

for (;;) {}

}

static uint64_t thread1_stk_1[64];

const osThreadAttr_t thread1_attr = {

. stack_mem = &thread1_stk_1[0],

.stack_size = sizeof(thread1_stk_1)

};

int main ( void) {

;

osThreadNew(thread1, NULL, &thread1_attr); // Create thread with statically allocated stack memory

;

}

示例 4 - 具有静态分配的任务控制块的线程

通常，此方法与静态分配的堆栈一起选择，如示例 2 中所示。

#include "cmsis_os2.h"

//include rtx_os.h for types of RTX objects

#include "rtx_os.h"

__NO_RETURN void thread1 ( void *argument) {

// ...

for (;;) {}

}

static osRtxThread_t thread1_tcb;

const osThreadAttr_t thread1_attr = {

. cb_mem = &thread1_tcb,

.cb_size = sizeof(thread1_tcb),

};

int main ( void) {

;

osThreadNew(thread1, NULL, &thread1_attr); // Create thread with custom tcb memory

;

}

示例 5 - 使用不同的优先级创建线程

RTX 的默认优先级是 osPriorityNormal 。通常你想运行一个更高或更低优先级的任务。使用 osThreadAttr_t 控制结构，您可以设置所需的任何初始优先级。

__NO_RETURN void thread1 ( void *argument) {

// ...

for (;;) {}

}

const osThreadAttr_t thread1_attr = {

. priority = osPriorityHigh //Set initial thread priority to high

};

int main ( void) {

;

osThreadNew(thread1, NULL, &thread1_attr);

;

}

示例 6 - 可连接的线程

在这个例子中，主线程使用 osThreadJoinable 属性创建四个线程。这些将完成一些工作，并在完成后使用 osThreadExit 调用返回。osThreadJoin 用于同步线程终止。

__NO_RETURN void worker ( void *argument) {

; // work a lot on data[]

osDelay(1000);

osThreadExit();

}

__NO_RETURN void thread1 ( void *argument) {

osThreadAttr_t worker_attr;

osThreadId_t worker_ids[4];

uint8_t data[4][10];

memset(&worker_attr, 0, sizeof(worker_attr));

worker_attr. attr_bits = osThreadJoinable;

worker_ids[0] = osThreadNew(worker, &data[0][0], &worker_attr);

worker_ids[1] = osThreadNew(worker, &data[1][0], &worker_attr);

worker_ids[2] = osThreadNew(worker, &data[2][0], &worker_attr);

worker_ids[3] = osThreadNew(worker, &data[3][0], &worker_attr);

osThreadJoin(worker_ids[0]);

osThreadJoin(worker_ids[1]);

osThreadJoin(worker_ids[2]);

osThreadJoin(worker_ids[3]);

osThreadExit();

}

---

数据结构文档

struct osThreadAttr_t

用于配置线程的属性。

有关使用的详细信息，请参阅内存管理

• osThreadAttr_t::cb_mem
• osThreadAttr_t::cb_size
• osThreadAttr_t::stack_mem
• osThreadAttr_t::stack_size

数据字段
const char *	name	线程的名称 指向具有线程对象的人类可读名称的字符串。 默认值：NULL 。
uint32_t	attr_bits	属性位 可以分配以下预定义位掩码来设置线程对象的选项。 位掩码 描述 osThreadDetached 在分离模式下创建线程（默认）。 osThreadJoinable 在可连接模式下创建线程，请参阅 osThreadJoin 。
void *	cb_mem	内存控制块 指向线程控制块对象的内存位置。这可以选择用于定制内存管理系统。 默认值：NULL（使用内核内存管理）。
uint32_t	cb_size	为控制块提供的内存大小 内存块的大小与 cb_mem 一起传递。必须是线程控制块对象的大小或更大。
void *	stack_mem	内存的堆栈 指向线程堆栈的内存位置的指针必须是 64 位对齐的。这可以选择用于定制内存管理系统。 默认值：NULL（使用内核内存管理）。
uint32_t	stack_size	堆栈大小 由 stack_mem 指定的堆栈大小。
osPriority_t	priority	初始线程优先级（默认：osPriorityNormal） 使用 osPriority_t 中的值指定初始线程优先级。 默认值：osPriorityNormal
TZ_ModuleId_t	tz_module	TrustZone 模块标识符。 TrustZone 线程上下文管理标识符为线程分配上下文内存。以非安全状态运行的 RTOS 内核调用由头文件 TZ_context.h 定义的接口函数。对于根本不使用安全调用的线程，可以安全地设置为零。请参阅 TrustZone RTOS 上下文管理。
uint32_t	reserved	保留（必须为 0） 保留以供将来使用（设为 '0'）。 默认值：0 。

宏定义文档

#define osThreadJoinable   0x00000001U

处于此状态的线程可以使用 osThreadJoin 进行连接。

#define osThreadDetached   0x00000000U

处于此状态的线程不能使用 osThreadJoin 进行连接。

类型定义文档

void(* osThreadFunc_t)(void *argument)

线程的输入功能。建立一个新的线程（osThreadNew）将通过调用这个入口函数来开始执行。可选参数可用于将任意用户数据移交给线程，即标识线程或运行时参数。

参数

[in]

argument

在 osThreadNew 上设置任意用户数据。

osThreadId_t

线程标识标识线程。

返回者：

• osThreadNew
• osThreadGetId
• osThreadEnumerate
• osMutexGetOwner

枚举类型文档

enum osThreadState_t

由 osThreadGetState 检索的线程的状态。如果 osThreadGetState 失败或从 ISR 调用，它将返回 osThreadError，否则返回线程状态。

枚举
osThreadInactive	非活动。 该线程已创建但未被主动使用，或已被终止。
osThreadReady	准备。 线程已准备好执行，但目前没有运行。
osThreadRunning	运行。 线程正在运行。
osThreadBlocked	阻止。 该线程当前被阻止（延迟，等待事件或暂停）。
osThreadTerminated	终止。 该线程被终止并释放其所有资源。
osThreadError	错误。 线程引发了错误情况，无法进行调度。
osThreadReserved	防止枚举小型编译器优化。

enum osPriority_t

osPriority_t 值指定线程的优先级。默认的线程优先级应该是 osPriorityNormal 。如果活动线程准备好比当前正在运行的线程具有更高优先级，则会立即发生线程切换。系统继续执行具有较高优先级的线程。

为了防止优先级反转，CMSIS-RTOS 兼容 OS 可以选择实现优先级继承方法。当高优先级的线程正在等待由具有较低优先级的线程控制的资源或事件时，发生优先级反转。从而导致高优先级线程潜在地被另一个优先级较低的线程永远阻塞。为了解决这个问题，控制资源的低优先级线程应该被视为拥有更高的优先级，直到它释放资源。

注意

优先级继承仅适用于互斥锁。

枚举
osPriorityNone	没有优先级（未初始化）。
osPriorityIdle	保留为空闲线程。 这个最低优先级不应该用于任何其他线程。
osPriorityLow	优先级：低。
osPriorityLow1	优先级：低 + 1 。
osPriorityLow2	优先级：低 + 2 。
osPriorityLow3	优先级：低 + 3 。
osPriorityLow4	优先级：低 + 4 。
osPriorityLow5	优先级：低 + 5 。
osPriorityLow6	优先级：低 + 6 。
osPriorityLow7	优先级：低 + 7 。
osPriorityBelowNormal	优先级：低于正常。
osPriorityBelowNormal1	优先级：低于正常 + 1 。
osPriorityBelowNormal2	优先级：低于正常 + 2 。
osPriorityBelowNormal3	优先级：低于正常 + 3 。
osPriorityBelowNormal4	优先级：低于正常 + 4 。
osPriorityBelowNormal5	优先级：低于正常 + 5 。
osPriorityBelowNormal6	优先级：低于正常 + 6 。
osPriorityBelowNormal7	优先级：低于正常 + 7 。
osPriorityNormal	优先级：正常。
osPriorityNormal1	优先级：正常 + 1。
osPriorityNormal2	优先级：正常 + 2 。
osPriorityNormal3	优先级：正常 + 3 。
osPriorityNormal4	优先级：正常 + 4 。
osPriorityNormal5	优先级：正常 + 5 。
osPriorityNormal6	优先级：正常 + 6 。
osPriorityNormal7	优先级：正常 + 7 。
osPriorityAboveNormal	优先级：高于正常。
osPriorityAboveNormal1	优先级：高于正常 + 1 。
osPriorityAboveNormal2	优先级：高于正常 + 2 。
osPriorityAboveNormal3	优先级：高于正常 + 3 。
osPriorityAboveNormal4	优先级：高于正常 + 4 。
osPriorityAboveNormal5	优先级：高于正常 + 5 。
osPriorityAboveNormal6	优先级：高于正常 + 6 。
osPriorityAboveNormal7	优先级：高于正常 + 7 。
osPriorityHigh	优先级：高。
osPriorityHigh1	优先级：高 + 1 。
osPriorityHigh2	优先级：高 + 2 。
osPriorityHigh3	优先级：高 + 3 。
osPriorityHigh4	优先级：高 + 4 。
osPriorityHigh5	优先级：高 + 5 。
osPriorityHigh6	优先级：高 + 6 。
osPriorityHigh7	优先级：高 + 7 。
osPriorityRealtime	优先级：实时。
osPriorityRealtime1	优先级：实时 + 1 。
osPriorityRealtime2	优先级：实时 + 2 。
osPriorityRealtime3	优先级：实时 + 3 。
osPriorityRealtime4	优先级：实时 + 4 。
osPriorityRealtime5	优先级：实时 + 5 。
osPriorityRealtime6	优先级：实时 + 6 。
osPriorityRealtime7	优先级：实时 + 7 。
osPriorityISR	为 ISR 延期线程保留。 这个最高优先级可能被 RTOS 实现使用，但不能用于任何用户线程。
osPriorityError	系统无法确定优先级或非法优先级。
osPriorityReserved	防止枚举小型编译器优化。

函数文档

osThreadId_t osThreadNew	(	osThreadFunc_t	func,
		void *	argument,
		const osThreadAttr_t *	attr
	)

参数

[in]	func	线程函数。
[in]	argument	作为启动参数传递给线程函数的指针。
[in]	attr	线程属性; NULL：默认值。

返回

线程标识以供其他函数参考，或者在错误情况下为 NULL 。

函数 osThreadNew 通过将线程函数添加到活动线程列表中并将其设置为 READY 状态来启动线程函数。线程函数的参数使用参数指针 * 参数传递。当创建的线程函数的优先级高于当前的 RUNNING 线程时，创建的线程函数立即启动并成为新的 RUNNING 线程。线程属性用参数指针 attr 定义。属性包括线程优先级，堆栈大小或内存分配的设置。

在 RTOS 启动（调用 osKernelStart）之前，可以安全地调用该函数，但在初始化（调用 osKernelInitialize）之前不可以安全地调用该函数。

函数 osThreadNew 返回指向线程对象标识符的指针，或者在出现错误时返回 NULL 。

注意

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

代码示例

请参阅线程示例部分。

const char * osThreadGetName

(

osThreadId_t

thread_id

)

参数

[in]

thread_id

线程 ID 由 osThreadNew 或 osThreadGetId 获取。

返回

名称为 NULL 终止的字符串。

函数 osThreadGetName 返回指向由参数 thread_id 标识的线程的名称字符串的指针，或者在出现错误时返回 NULL 。

注意

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

代码示例

void ThreadGetName_example ( void) {

osThreadId_t thread_id = osThreadGetId ();

const char* name = osThreadGetName (thread_id);

if (name == NULL) {

// Failed to get the thread name; not in a thread

}

}

osThreadId_t osThreadGetId

(

void

)

返回

线程标识以供其他函数参考，或者在错误情况下为 NULL 。

函数 osThreadGetId 返回当前正在运行的线程的线程对象 ID 或者在出现错误时返回 NULL 。

注意

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

代码示例

void ThreadGetId_example ( void) {

osThreadId_t id; // id for the currently running thread

id = osThreadGetId ();

if ( id == NULL) {

// Failed to get the id; not in a thread

}

}

osThreadState_t osThreadGetState

(

osThreadId_t

thread_id

)

参数

[in]

thread_id

线程 ID 由 osThreadNew 或 osThreadGetId 获取。

返回

指定线程的当前线程状态。

函数 osThreadGetState 返回由参数 thread_id 标识的线程的状态。如果失败或者从 ISR 调用，它将返回 osThreadError ，否则返回线程状态（请参阅 osThreadState_t 了解线程状态列表）。

注意

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

osStatus_t osThreadSetPriority	(	osThreadId_t	thread_id,
		osPriority_t	priority
	)

参数

[in]	thread_id	线程 ID 由 osThreadNew 或 osThreadGetId 获取。
[in]	priority	线程函数的新优先级。

返回

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

函数 osThreadSetPriority 将参数 thread_id 指定的活动线程的优先级更改为参数 priority 指定的优先级。

可能的 osStatus_t 返回值：

• osOK: 指定线程的优先级已成功更改。
• osErrorParameter: thread_id 为 NULL 或无效或优先级不正确。
• osErrorResource: 由参数 thread_id 指定的线程处于无效线程状态。
• osErrorISR: 不能从中断服务例程中调用函数 osThreadSetPriority 。

注意

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

代码示例

#include "cmsis_os2.h"

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

osThreadId_t id; // id for the currently running thread

osStatus_t status; // status of the executed function

:

id = osThreadGetId (); // Obtain ID of current running thread

status = osThreadSetPriority ( id, osPriorityBelowNormal); // Set thread priority

if (status == osOK) {

// Thread priority changed to BelowNormal

}

else {

// Failed to set the priority

}

:

}

osPriority_t osThreadGetPriority

(

osThreadId_t

thread_id

)

参数

[in]

thread_id

线程 ID 由 osThreadNew 或 osThreadGetId 获取。

返回

指定线程的当前优先级。

函数 osThreadGetPriority 返回由参数 thread_id 指定的活动线程的优先级。

可能的 osPriority_t 返回值：

• priority: 指定线程的优先级。
• osPriorityError: 优先级不能确定或是非法的。当从中断服务程序调用该函数时，它也会返回。

注意

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

代码示例

#include "cmsis_os2.h"

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

osThreadId_t id; // id for the currently running thread

osPriority_t priority; // thread priority

id = osThreadGetId (); // Obtain ID of current running thread

priority = osThreadGetPriority ( id); // Obtain the thread priority

}

osStatus_t osThreadYield

(

void

)

返回

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

函数 osThreadYield 将控制权交给下一个具有相同优先级并处于 READY 状态的线程。如果在状态 READY 中没有其他具有相同优先级的线程，则当前线程继续执行并且不发生线程切换。osThreadYield 不会将线程设置为状态 BLOCKED 。因此，即使状态为 READY 的线程可用，也不会调度具有较低优先级的线程。

可能的 osStatus_t 返回值：

• osOK: 控件已成功传递到下一个线程。
• osError: 发生未指定的错误。
• osErrorISR: 不能从中断服务例程中调用 osThreadYield 函数。

注意

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

这个函数在内核被锁定时调用没有作用，参见 osKernelLock 。

代码示例

#include "cmsis_os2.h"

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

osStatus_t status; // status of the executed function

:

while (1) {

status = osThreadYield(); //

if (status != osOK) {

// an error occurred

}

}

}

osStatus_t osThreadSuspend

(

osThreadId_t

thread_id

)

参数

[in]

thread_id

线程 ID 由 osThreadNew 或 osThreadGetId 获取。

返回

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

函数 osThreadSuspend 挂起参数 thread_id 标识的线程的执行。线程被置于 BLOCKED 状态（osThreadBlocked）。 挂起正在运行的线程将导致上下文立即切换到处于 READY 状态的另一个线程。直到用函数 osThreadResume 明确地继续之后，挂起的线程才会被执行。

已经被阻塞的线程将从任何等待列表中删除，并在恢复时准备就绪。因此不建议暂停已经被阻塞的线程。

可能的 osStatus_t 返回值：

• osOK: 线程已成功挂起。
• osErrorParameter: thread_id 是 NULL 或无效。
• osErrorResource: 由参数 thread_id 指定的线程处于无效线程状态。
• osErrorISR: 不能从中断服务例程调用函数 osThreadSuspend 。

注意

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

当内核被锁定时，不能调用该函数来挂起正在运行的线程，即 osKernelLock 。

osStatus_t osThreadResume

(

osThreadId_t

thread_id

)

参数

[in]

thread_id

线程 ID 由 osThreadNew 或 osThreadGetId 获取。

返回

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

osThreadResume 函数将由参数 thread_id 标识的线程（必须处于 BLOCKED 状态）返回到 READY 状态。如果恢复的线程比正在运行的线程具有更高的优先级，则会立即发生上下文切换。

无论线程被阻塞的原因，线程都已准备就绪。因此，不建议恢复未被 osThreadSuspend 挂起的线程。

将线程置于 BLOCKED 状态的函数是：osEventFlagsWait 和 osThreadFlagsWait ， osDelay 和 osDelayUntil ， osMutexAcquire 和 osSemaphoreAcquire ， osMessageQueueGet ， osMemoryPoolAlloc ， osThreadJoin ， osThreadSuspend 。

可能的 osStatus_t 返回值：

• osOK: 该线程已成功恢复。
• osErrorParameter: thread_id 是 NULL 或无效。
• osErrorResource: 由参数 thread_id 指定的线程处于无效线程状态。
• osErrorISR: osThreadResume 函数不能从中断服务例程中调用。

注意

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

当内核被锁定时（osKernelLock），可以调用该函数。在这种情况下，潜在的上下文切换会延迟，直到内核被解锁，即 osKernelUnlock或 osKernelRestoreLock 。

osStatus_t osThreadDetach

(

osThreadId_t

thread_id

)

参数

[in]

thread_id

线程 ID 由 osThreadNew 或 osThreadGetId 获取。

返回

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

函数 osThreadDetach 将线程的属性（由 thread_id 指定）更改为 osThreadDetached 。分离的线程不能与 osThreadJoin 连接。当分离的线程终止时，所有资源都会返回到系统。osThreadDetach 在已经分离的线程上的行为是未定义的。

可能的 osStatus_t 返回值：

• osOK: 指定线程的属性已更改为成功分离。
• osErrorParameter: thread_id 是 NULL 或无效。
• osErrorResource: 由参数 thread_id 指定的线程处于无效线程状态。
• osErrorISR: 函数 osThreadDetach 不能从中断服务例程调用。

注意

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

osStatus_t osThreadJoin

(

osThreadId_t

thread_id

)

参数

[in]

thread_id

线程 ID 由 osThreadNew 或 osThreadGetId 获取。

返回

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

函数 osThreadJoin 等待由 thread_id 指定的线程终止。如果该线程已经终止，则 osThreadJoin 立即返回。该线程必须可以连接。默认情况下，线程是使用 osThreadDetached 属性创建的。

可能的 osStatus_t 返回值：

• osOK: 如果线程已经终止并加入，或者一旦线程终止并且加入操作成功。
• osErrorParameter: thread_id 是 NULL 或无效。
• osErrorResource: 参数 thread_id 为 NULL 或引用不是活动线程的线程或线程不可连接。
• osErrorISR: 函数 osThreadJoin 不能从中断服务例程调用。

注意

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

__NO_RETURN void osThreadExit

(

void

)

函数 osThreadExit 终止调用线程。这允许线程与 osThreadJoin 同步。

注意

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

代码示例

__NO_RETURN void worker ( void *argument) {

// do something

osDelay(1000);

osThreadExit();

}

osStatus_t osThreadTerminate

(

osThreadId_t

thread_id

)

参数

[in]

thread_id

线程 ID 由 osThreadNew 或 osThreadGetId 获取。

返回

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

函数 osThreadTerminate 从活动线程列表中删除由参数 thread_id 指定的线程。如果线程当前正在运行，则线程终止，并继续执行下一个 READY 线程。如果不存在这样的线程，则该函数不会终止正在运行的线程，而是返回 osErrorResource 。

可能的 osStatus_t 返回值：

• osOK: 指定的线程已成功从活动线程列表中删除。
• osErrorParameter: thread_id 是 NULL 或无效。
• osErrorResource: 由参数 thread_id 指定的线程处于无效线程状态或者不存在其他 READY 线程。
• osErrorISR: 不能从中断服务例程中调用函数 osThreadTerminate 。

注意

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

避免使用不存在或已经终止的 thread_id 调用该函数。

代码示例

#include "cmsis_os2.h"

void Thread_1 ( void *arg); // function prototype for Thread_1

void ThreadTerminate_example ( void) {

osStatus_t status;

osThreadId_t id;

id = osThreadNew (Thread_1, NULL, NULL); // create the thread

// do something

status = osThreadTerminate ( id); // stop the thread

if (status == osOK) {

// Thread was terminated successfully

}

else {

// Failed to terminate a thread

}

}

uint32_t osThreadGetStackSize

(

osThreadId_t

thread_id

)

参数

[in]

thread_id

线程 ID 由 osThreadNew 或 osThreadGetId 获取。

返回

堆栈大小以字节为单位

函数 osThreadGetStackSize 返回由参数 thread_id 指定的线程的堆栈大小。如果发生错误，则返回 0 。

注意

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

uint32_t osThreadGetStackSpace

(

osThreadId_t

thread_id

)

参数

[in]

thread_id

线程 ID 由 osThreadNew 或 osThreadGetId 获取。

返回

剩余堆栈空间以字节为单位

函数 osThreadGetStackSpace 返回由参数 thread_id 指定的线程的未使用堆栈空间的大小。在执行期间需要启用堆栈水印记录（请参阅线程配置）。如果发生错误，则返回 0 。

注意

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

uint32_t osThreadGetCount

(

void

)

返回

活动线程的个数。

函数 osThreadGetCount 返回活动线程的数量或者在出现错误时返回 0 。

注意

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

uint32_t osThreadEnumerate	(	osThreadId_t *	thread_array,
		uint32_t	array_items
	)

参数

[out]	thread_array	指向数组以检索线程 ID 的指针。
[in]	array_items	数组中用于检索线程 ID 的最大项目数。

返回

枚举线程数量。

函数 osThreadEnumerate 返回枚举线程的数量或者在发生错误时返回 0 。

注意

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