CMSIS-RTOS2 文档翻译 之 参考（CMSIS-RTOS2 API 之 消息队列）

消息队列

CMSIS-RTOS2 API

在类似 FIFO 的操作中交换线程之间的消息。更多...

数据结构
struct	osMessageQueueAttr_t
	消息队列的属性结构体。更多...

函数
osMessageQueueId_t	osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr)
	创建并初始化消息队列对象。更多...
const char *	osMessageQueueGetName (osMessageQueueId_t mq_id)
	获取消息队列对象的名称。更多...
osStatus_t	osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout)
	如果队列已满，请将消息放入队列或超时。更多...
osStatus_t	osMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t timeout)
	如果队列为空，则从队列获取消息或超时。更多...
uint32_t	osMessageQueueGetCapacity (osMessageQueueId_t mq_id)
	在消息队列中获取最大数量的消息。更多...
uint32_t	osMessageQueueGetMsgSize (osMessageQueueId_t mq_id)
	获取内存池中的最大消息大小。更多...
uint32_t	osMessageQueueGetCount (osMessageQueueId_t mq_id)
	获取消息队列中排队的消息数量。更多...
uint32_t	osMessageQueueGetSpace (osMessageQueueId_t mq_id)
	获取消息队列中消息的可用插槽数量。更多...
osStatus_t	osMessageQueueReset (osMessageQueueId_t mq_id)
	将消息队列重置为初始空状态。更多...
osStatus_t	osMessageQueueDelete (osMessageQueueId_t mq_id)
	删除一个消息队列对象。更多...

描述

消息传递是线程之间的另一种基本通信模型。在消息传递模型中，一个线程显式地发送数据，而另一个线程接收它。该操作更像是某种 I/O ，而不是直接访问要共享的信息。在 CMSIS-RTOS 中，这种机制被称为消息队列。数据通过类似 FIFO 的操作从一个线程传递到另一个线程。使用消息队列功能，您可以控制，发送，接收或等待消息。要传递的数据可以是整数或指针类型：

CMSIS-RTOS 消息队列

与内存池相比，消息队列通常效率较低，但解决了更广泛的问题。有时，线程没有共同的地址空间，或者共享内存的使用引发了诸如互斥等问题。

注意

可以从中断服务例程调用osMessageQueuePut，osMessageQueueGet，osMessageQueueGetCapacity，osMessageQueueGetMsgSize，osMessageQueueGetCount，osMessageQueueGetSpace 函数。

有关 RTX5 配置选项，请参阅消息队列配置。

---

数据结构文档

struct osMessageQueueAttr_t

用于配置消息队列的属性。

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

• osMessageQueueAttr_t::cb_mem
• osMessageQueueAttr_t::cb_size
• osMessageQueueAttr_t::mq_mem
• osMessageQueueAttr_t::mq_size

数据字段
const char *	name	消息队列的名称 指向具有人类可读名称的消息队列对象的字符串。 默认值：NULL 。
uint32_t	attr_bits	属性位 保留以供将来使用（设为 '0'）。 默认值：0 。
void *	cb_mem	内存控制块 指向消息队列控制块对象的内存位置。这可以选择用于定制内存管理系统。 默认值：NULL（使用内核内存管理）。
uint32_t	cb_size	为控制块提供的内存大小 内存块的大小与 cb_mem 一起传递。必须是消息队列控制块对象的大小或更大。
void *	mq_mem	内存数据存储 指向消息队列对象数据的内存位置。 默认值：NULL 。
uint32_t	mq_size	为数据存储提供的内存大小 通过 mq_mem 传递的内存大小。

函数文档

osMessageQueueId_t osMessageQueueNew	(	uint32_t	msg_count,
		uint32_t	msg_size,
		const osMessageQueueAttr_t *	attr
	)

参数

[in]	msg_count	队列中消息的最大数量。
[in]	msg_size	最大消息大小以字节为单位
[in]	attr	消息队列属性; NULL：默认值。

返回

消息队列 ID 以供其他功能参考，或者在发生错误时为 NULL 。

函数 osMessageQueueNew 创建并初始化消息队列对象，并返回指向消息队列对象标识符的指针，或者在发生错误时返回 NULL 。它可以在 RTOS 启动之前（调用 osKernelStart）安全地调用，但不能在它初始化之前（调用 osKernelInitialize）调用。

注意

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

代码示例

请参阅 osMessageQueuePut

const char * osMessageQueueGetName

(

osMessageQueueId_t

mq_id

)

参数

[in]

mq_id

消息队列 ID 由 osMessageQueueNew 获取。

返回

名称为 NULL 终止的字符串。

osMessageQueueGetName 函数返回指向由参数 mq_id 标识的消息队列的名称字符串的指针，或者在发生错误时返回 NULL 。

注意

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

osStatus_t osMessageQueuePut	(	osMessageQueueId_t	mq_id,
		const void *	msg_ptr,
		uint8_t	msg_prio,
		uint32_t	timeout
	)

参数

[in]	mq_id	消息队列 ID 由 osMessageQueueNew 获取。
[in]	msg_ptr	指向具有消息的缓冲区以放入队列。
[in]	msg_prio	消息优先级。
[in]	timeout	超时值或 0 在没有超时的情况下。

返回

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

阻塞函数 osMessageQueuePut 将 msg_ptr 指向的消息放入由参数 mq_id 指定的消息队列中。参数 msg_prio 用于根据插入的优先级对消息进行排序（较高的数字表示较高的优先级）。

参数超时指定系统等待将消息放入队列的时间。系统等待时，调用此函数的线程将进入 BLOCKED 状态。参数超时可以有以下值：

• 当超时为 0 时，函数立即返回（即尝试语义）。
• 当超时设置为 osWaitForever 时，该函数将等待无限的时间直到消息被传递（即等待语义）。
• 所有其他值都指定了内核中的超时时间（即定时等待语义）。

可能的 osStatus_t 返回值：

• osOK: 该消息已被放入队列中。
• osErrorTimeout: 在给定时间内消息不能被放入队列（等待时间语义）。
• osErrorResource: 队列中没有足够的空间（尝试语义）。
• osErrorParameter: 参数 mq_id 不正确，在 ISR 中指定的非零超时。

注意

如果参数 timeout 设置为 0，可以从中断服务例程调用。

代码示例:

#include "cmsis_os2.h" // CMSIS RTOS header file

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

* Message Queue creation & usage

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

void Thread_MsgQueue1 ( void *argument); // thread function 1

void Thread_MsgQueue2 ( void *argument); // thread function 2

osThreadId_t tid_Thread_MsgQueue1; // thread id 1

osThreadId_t tid_Thread_MsgQueue2; // thread id 2

#define MSGQUEUE_OBJECTS 16 // number of Message Queue Objects

typedef struct { // object data type

uint8_t Buf[32];

uint8_t Idx;

} MSGQUEUE_OBJ_t;

osMessageQueueId_t mid_MsgQueue; // message queue id

int Init_MsgQueue ( void) {

mid_MsgQueue = osMessageQueueNew(MSGQUEUE_OBJECTS, sizeof(MSGQUEUE_OBJ_t), NULL);

if (!mid_MsgQueue) {

; // Message Queue object not created, handle failure

}

tid_Thread_MsgQueue1 = osThreadNew (Thread_MsgQueue1, NULL, NULL);

if (!tid_Thread_MsgQueue1) return(-1);

tid_Thread_MsgQueue2 = osThreadNew (Thread_MsgQueue2, NULL, NULL);

if (!tid_Thread_MsgQueue2) return(-1);

return(0);

}

void Thread_MsgQueue1 ( void *argument) {

MSGQUEUE_OBJ_t msg;

while (1) {

; // Insert thread code here...

msg.Buf[0] = 0x55; // do some work...

msg.Idx = 0;

osMessageQueuePut (mid_MsgQueue, &msg, 0, NULL);

osThreadYield (); // suspend thread

}

}

void Thread_MsgQueue2 ( void *argument) {

MSGQUEUE_OBJ_t msg;

osStatus_t status;

while (1) {

; // Insert thread code here...

status = osMessageQueueGet (mid_MsgQueue, &msg, NULL, NULL); // wait for message

if (status == osOK) {

; // process data

}

}

}

osStatus_t osMessageQueueGet	(	osMessageQueueId_t	mq_id,
		void *	msg_ptr,
		uint8_t *	msg_prio,
		uint32_t	timeout
	)

参数

[in]	mq_id	消息队列 ID 由 osMessageQueueNew 获取。
[out]	msg_ptr	指向缓冲区的消息以从队列中获取消息。
[out]	msg_prio	指向缓冲区的消息优先级或 NULL 。
[in]	timeout	超时值或 0 在没有超时的情况下。

返回

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

osMessageQueueGet 函数从参数 mq_id 指定的消息队列中检索消息，并将其保存到参数 msg_ptr 所指向的缓冲区中。如果不是令牌{NULL}，则消息优先级存储到参数 msg_prio 。

参数 timeout 指定系统等待从队列中检索消息的时间。系统等待时，调用此函数的线程将进入 BLOCKED 状态。参数超时可以有以下值：

• 当超时为 0 时，函数立即返回（即尝试语义）。
• 当超时设置为 osWaitForever 时，该函数将等待无限时间，直到检索到消息（即等待语义）。
• 所有其他值都指定了内核中的超时时间（即定时等待语义）。

可能的 osStatus_t 返回值：

• osOK: 该消息已从队列中检索出来。
• osErrorTimeout: 在给定时间内无法从队列中检索消息（定时等待语义）。
• osErrorResource: 没有什么可以从队列中获得（尝试语义）。
• osErrorParameter: 参数 mq_id 不正确，在 ISR 中指定的非零超时。

注意

如果参数 timeout 设置为 0 ，可以从中断服务例程调用。

代码示例

请参阅 osMessageQueuePut

uint32_t osMessageQueueGetCapacity

(

osMessageQueueId_t

mq_id

)

参数

[in]

mq_id

消息队列 ID 由 osMessageQueueNew 获取。

返回

消息的最大数量。

函数 osMessageQueueGetCapacity 返回消息队列对象中由参数 mq_id 或 0 指定的最大消息数量，以防出现错误。

注意

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

uint32_t osMessageQueueGetMsgSize

(

osMessageQueueId_t

mq_id

)

参数

[in]

mq_id

消息队列 ID 由 osMessageQueueNew 获取。

返回

最大消息大小以字节为单位

函数 osMessageQueueGetMsgSize 返回由参数 mq_id 指定的消息队列对象的最大消息大小（以字节为单位）或在出现错误时返回 0 。

注意

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

uint32_t osMessageQueueGetCount

(

osMessageQueueId_t

mq_id

)

参数

[in]

mq_id

消息队列 ID 由 osMessageQueueNew 获取。

返回

排队的消息数量。

函数 osMessageQueueGetCount 返回由参数 mq_id 或 0 指定的消息队列对象中排队的消息数量，以防出现错误。

注意

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

uint32_t osMessageQueueGetSpace

(

osMessageQueueId_t

mq_id

)

参数

[in]

mq_id

消息队列 ID 由 osMessageQueueNew 获取。

返回

消息的可用插槽数量。

函数 osMessageQueueGetSpace 返回由参数 mq_id 指定的消息队列对象中的消息的可用槽数量，如果发生错误，则返回 0 。

注意

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

osStatus_t osMessageQueueReset

(

osMessageQueueId_t

mq_id

)

参数

[in]

mq_id

消息队列 ID 由 osMessageQueueNew 获取。

返回

状态代码，指示该函数的执行状态。

函数 osMessageQueueReset 重置由参数 mq_id 指定的消息队列。

可能的 osStatus_t 返回值：

• osOK: 消息队列已被重置。
• osErrorParameter: 参数 mq_id 是 NULL 或无效。
• osErrorResource: 由参数 mq_id 指定的消息队列处于无效消息队列状态。
• osErrorISR: osMessageQueueReset 不能从中断服务例程调用。

注意

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

osStatus_t osMessageQueueDelete

(

osMessageQueueId_t

mq_id

)

参数

[in]

mq_id

消息队列 ID 由 osMessageQueueNew 获取。

返回

状态代码，指示该函数的执行状态。

osMessageQueueDelete 函数删除由参数 mq_id 指定的消息队列对象。它释放为消息队列处理而获得的内部内存。在这个调用之后，mq_id 不再有效并且不能使用。消息队列可以使用函数 osMessageQueueNew 再次创建。

可能的 osStatus_t 返回值：

• osOK: 消息队列对象已被删除。
• osErrorParameter: 参数 mq_id 是 NULL 或无效。
• osErrorResource: 由参数 mq_id 指定的消息队列处于无效消息队列状态。
• osErrorISR: osMessageQueueDelete 不能从中断服务例程调用。

注意

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