定义,创建和控制线程函数。更多...
数据结构 |
|
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) |
枚举活动线程。更多... |
|
线程管理功能组允许在系统中定义,创建和控制线程功能。
线程可以处于以下状态:
CMSIS-RTOS 假定线程按照线程状态和状态转换图所示进行调度。线程状态更改如下:
以下示例显示了创建线程的各种方案:
示例 1 - 创建一个简单的线程
使用全局内存池中线程属性和内存的所有默认值,从函数 thread1 中创建一个线程。
示例 2 - 使用堆栈非默认堆栈大小创建线程
类似于简单的线程,所有的属性都是默认的。该堆栈是从全局内存池动态分配的
osThreadAttr_t::stack_size 用于将字节中的堆栈大小传递给 osThreadNew 。
示例 3 - 使用静态分配的堆栈创建线程
类似于简单的线程,所有的属性都是默认的。使用 uint64_t 数组 thread1_stk_1 静态分配堆栈。这分配 64 * 8 字节(= 512 字节),对齐 8 字节(Cortex-M 堆栈内存是必需的)。
osThreadAttr_t::stack_mem 保存一个指向堆栈最低地址的指针。
osThreadAttr_t::stack_size 用于将字节中的堆栈大小传递给 osThreadNew 。
示例 4 - 具有静态分配的任务控制块的线程
通常,此方法与静态分配的堆栈一起选择,如示例 2 中所示。
示例 5 - 使用不同的优先级创建线程
RTX 的默认优先级是 osPriorityNormal 。通常你想运行一个更高或更低优先级的任务。使用 osThreadAttr_t 控制结构,您可以设置所需的任何初始优先级。
示例 6 - 可连接的线程
在这个例子中,主线程使用 osThreadJoinable 属性创建四个线程。这些将完成一些工作,并在完成后使用 osThreadExit 调用返回。osThreadJoin 用于同步线程终止。
struct osThreadAttr_t |
用于配置线程的属性。
有关使用的详细信息,请参阅内存管理
数据字段 | ||||||||
---|---|---|---|---|---|---|---|---|
const char * | name | 线程的名称 指向具有线程对象的人类可读名称的字符串。 |
||||||
uint32_t | attr_bits | 属性位 可以分配以下预定义位掩码来设置线程对象的选项。
|
||||||
void * | cb_mem | 内存控制块 指向线程控制块对象的内存位置。这可以选择用于定制内存管理系统。 |
||||||
uint32_t | cb_size | 为控制块提供的内存大小 内存块的大小与 cb_mem 一起传递。必须是线程控制块对象的大小或更大。 |
||||||
void * | stack_mem | 内存的堆栈 指向线程堆栈的内存位置的指针必须是 64 位对齐的。这可以选择用于定制内存管理系统。 |
||||||
uint32_t | stack_size | 堆栈大小 由 stack_mem 指定的堆栈大小。 |
||||||
osPriority_t | priority | 初始线程优先级(默认:osPriorityNormal) 使用 osPriority_t 中的值指定初始线程优先级。 |
||||||
TZ_ModuleId_t | tz_module | TrustZone 模块标识符。 TrustZone 线程上下文管理标识符为线程分配上下文内存。以非安全状态运行的 RTOS 内核调用由头文件 TZ_context.h 定义的接口函数。对于根本不使用安全调用的线程,可以安全地设置为零。请参阅 TrustZone RTOS 上下文管理。 |
||||||
uint32_t | reserved | 保留(必须为 0) 保留以供将来使用(设为 '0')。 |
#define osThreadJoinable 0x00000001U |
处于此状态的线程可以使用 osThreadJoin 进行连接。
#define osThreadDetached 0x00000000U |
处于此状态的线程不能使用 osThreadJoin 进行连接。
void(* osThreadFunc_t)(void *argument) |
线程的输入功能。建立一个新的线程(osThreadNew)将通过调用这个入口函数来开始执行。可选参数可用于将任意用户数据移交给线程,即标识线程或运行时参数。
[in] | argument | 在 osThreadNew 上设置任意用户数据。 |
osThreadId_t |
线程标识标识线程。
返回者:
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:默认值。 |
函数 osThreadNew 通过将线程函数添加到活动线程列表中并将其设置为 READY 状态来启动线程函数。线程函数的参数使用参数指针 * 参数传递。当创建的线程函数的优先级高于当前的 RUNNING 线程时,创建的线程函数立即启动并成为新的 RUNNING 线程。线程属性用参数指针 attr 定义。属性包括线程优先级,堆栈大小或内存分配的设置。
在 RTOS 启动(调用 osKernelStart)之前,可以安全地调用该函数,但在初始化(调用 osKernelInitialize)之前不可以安全地调用该函数。
函数 osThreadNew 返回指向线程对象标识符的指针,或者在出现错误时返回 NULL 。
代码示例
请参阅线程示例部分。
const char * osThreadGetName | ( | osThreadId_t | thread_id | ) |
[in] | thread_id | 线程 ID 由 osThreadNew 或 osThreadGetId 获取。 |
函数 osThreadGetName 返回指向由参数 thread_id 标识的线程的名称字符串的指针,或者在出现错误时返回 NULL 。
代码示例
osThreadId_t osThreadGetId | ( | void | ) |
函数 osThreadGetId 返回当前正在运行的线程的线程对象 ID 或者在出现错误时返回 NULL 。
代码示例
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 返回值:
代码示例
osPriority_t osThreadGetPriority | ( | osThreadId_t | thread_id | ) |
[in] | thread_id | 线程 ID 由 osThreadNew 或 osThreadGetId 获取。 |
函数 osThreadGetPriority 返回由参数 thread_id 指定的活动线程的优先级。
可能的 osPriority_t 返回值:
代码示例
osStatus_t osThreadYield | ( | void | ) |
函数 osThreadYield 将控制权交给下一个具有相同优先级并处于 READY 状态的线程。如果在状态 READY 中没有其他具有相同优先级的线程,则当前线程继续执行并且不发生线程切换。osThreadYield 不会将线程设置为状态 BLOCKED 。因此,即使状态为 READY 的线程可用,也不会调度具有较低优先级的线程。
可能的 osStatus_t 返回值:
代码示例
osStatus_t osThreadSuspend | ( | osThreadId_t | thread_id | ) |
[in] | thread_id | 线程 ID 由 osThreadNew 或 osThreadGetId 获取。 |
函数 osThreadSuspend 挂起参数 thread_id 标识的线程的执行。线程被置于 BLOCKED 状态(osThreadBlocked)。 挂起正在运行的线程将导致上下文立即切换到处于 READY 状态的另一个线程。直到用函数 osThreadResume 明确地继续之后,挂起的线程才会被执行。
已经被阻塞的线程将从任何等待列表中删除,并在恢复时准备就绪。因此不建议暂停已经被阻塞的线程。
可能的 osStatus_t 返回值:
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 返回值:
osStatus_t osThreadDetach | ( | osThreadId_t | thread_id | ) |
[in] | thread_id | 线程 ID 由 osThreadNew 或 osThreadGetId 获取。 |
函数 osThreadDetach 将线程的属性(由 thread_id 指定)更改为 osThreadDetached 。分离的线程不能与 osThreadJoin 连接。当分离的线程终止时,所有资源都会返回到系统。osThreadDetach 在已经分离的线程上的行为是未定义的。
可能的 osStatus_t 返回值:
osStatus_t osThreadJoin | ( | osThreadId_t | thread_id | ) |
[in] | thread_id | 线程 ID 由 osThreadNew 或 osThreadGetId 获取。 |
函数 osThreadJoin 等待由 thread_id 指定的线程终止。如果该线程已经终止,则 osThreadJoin 立即返回。该线程必须可以连接。默认情况下,线程是使用 osThreadDetached 属性创建的。
可能的 osStatus_t 返回值:
__NO_RETURN void osThreadExit | ( | void | ) |
函数 osThreadExit 终止调用线程。这允许线程与 osThreadJoin 同步。
代码示例
osStatus_t osThreadTerminate | ( | osThreadId_t | thread_id | ) |
[in] | thread_id | 线程 ID 由 osThreadNew 或 osThreadGetId 获取。 |
函数 osThreadTerminate 从活动线程列表中删除由参数 thread_id 指定的线程。如果线程当前正在运行,则线程终止,并继续执行下一个 READY 线程。如果不存在这样的线程,则该函数不会终止正在运行的线程,而是返回 osErrorResource 。
可能的 osStatus_t 返回值:
代码示例
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 。