Data Structures
struct	k_msgq
	Message Queue Structure. More...

struct	k_msgq_attrs
	Message Queue Attributes. More...

Macros
#define	K_MSGQ_FLAG_ALLOC BIT(0)

#define	K_MSGQ_DEFINE(q_name, q_msg_size, q_max_msgs, q_align)
	Statically define and initialize a message queue. More...

Functions
void	k_msgq_init (struct k_msgq msgq, char buffer, size_t msg_size, uint32_t max_msgs)
	Initialize a message queue. More...

int	k_msgq_alloc_init (struct k_msgq *msgq, size_t msg_size, uint32_t max_msgs)
	Initialize a message queue. More...

int	k_msgq_cleanup (struct k_msgq *msgq)
	Release allocated buffer for a queue. More...

int	k_msgq_put (struct k_msgq msgq, const void data, k_timeout_t timeout)
	Send a message to a message queue. More...

int	k_msgq_get (struct k_msgq msgq, void data, k_timeout_t timeout)
	Receive a message from a message queue. More...

int	k_msgq_peek (struct k_msgq msgq, void data)
	Peek/read a message from a message queue. More...

int	k_msgq_peek_at (struct k_msgq msgq, void data, uint32_t idx)
	Peek/read a message from a message queue at the specified index. More...

void	k_msgq_purge (struct k_msgq *msgq)
	Purge a message queue. More...

uint32_t	k_msgq_num_free_get (struct k_msgq *msgq)
	Get the amount of free space in a message queue. More...

void	k_msgq_get_attrs (struct k_msgq msgq, struct k_msgq_attrs attrs)
	Get basic attributes of a message queue. More...

uint32_t	k_msgq_num_used_get (struct k_msgq *msgq)
	Get the number of messages in a message queue. More...

Detailed Description

Macro Definition Documentation

◆ K_MSGQ_DEFINE

#define K_MSGQ_DEFINE	(	q_name,
		q_msg_size,
		q_max_msgs,
		q_align
	)

#include <include/zephyr/kernel.h>

Value:

        static char __noinit __aligned(q_align)                         \
                _k_fifo_buf_##q_name[(q_max_msgs) * (q_msg_size)];      \
        STRUCT_SECTION_ITERABLE(k_msgq, q_name) =                       \
               Z_MSGQ_INITIALIZER(q_name, _k_fifo_buf_##q_name, \
                                  (q_msg_size), (q_max_msgs))

Statically define and initialize a message queue.

The message queue's ring buffer contains space for q_max_msgs messages, each of which is q_msg_size bytes long. The buffer is aligned to a q_align -byte boundary, which must be a power of 2. To ensure that each message is similarly aligned to this boundary, q_msg_size must also be a multiple of q_align.

The message queue can be accessed outside the module where it is defined using:

extern struct k_msgq <name>;

Parameters

q_name	Name of the message queue.
q_msg_size	Message size (in bytes).
q_max_msgs	Maximum number of messages that can be queued.
q_align	Alignment of the message queue's ring buffer.

◆ K_MSGQ_FLAG_ALLOC

#define K_MSGQ_FLAG_ALLOC BIT(0)

#include <include/zephyr/kernel.h>

Function Documentation

◆ k_msgq_alloc_init()

int k_msgq_alloc_init	(	struct k_msgq *	msgq,
		size_t	msg_size,
		uint32_t	max_msgs
	)

#include <include/zephyr/kernel.h>

Initialize a message queue.

This routine initializes a message queue object, prior to its first use, allocating its internal ring buffer from the calling thread's resource pool.

Memory allocated for the ring buffer can be released by calling k_msgq_cleanup(), or if userspace is enabled and the msgq object loses all of its references.

Parameters

msgq	Address of the message queue.
msg_size	Message size (in bytes).
max_msgs	Maximum number of messages that can be queued.

Returns: 0 on success, -ENOMEM if there was insufficient memory in the thread's resource pool, or -EINVAL if the size parameters cause an integer overflow.

◆ k_msgq_cleanup()

int k_msgq_cleanup ( struct k_msgq * msgq )

#include <include/zephyr/kernel.h>

Release allocated buffer for a queue.

Releases memory allocated for the ring buffer.

Parameters

msgq	message queue to cleanup

Return values

0	on success
-EBUSY	Queue not empty

◆ k_msgq_get()

int k_msgq_get	(	struct k_msgq *	msgq,
		void *	data,
		k_timeout_t	timeout
	)

#include <include/zephyr/kernel.h>

Receive a message from a message queue.

This routine receives a message from message queue q in a "first in, first out" manner.

Note: timeout must be set to K_NO_WAIT if called from ISR.

Function properties (list may not be complete): isr-ok

Parameters

msgq	Address of the message queue.
data	Address of area to hold the received message.
timeout	Waiting period to receive the message, or one of the special values K_NO_WAIT and K_FOREVER.

Return values

0	Message received.
-ENOMSG	Returned without waiting.
-EAGAIN	Waiting period timed out.

◆ k_msgq_get_attrs()

void k_msgq_get_attrs	(	struct k_msgq *	msgq,
		struct k_msgq_attrs *	attrs
	)

#include <include/zephyr/kernel.h>

Get basic attributes of a message queue.

This routine fetches basic attributes of message queue into attr argument.

Parameters

msgq	Address of the message queue.
attrs	pointer to message queue attribute structure.

◆ k_msgq_init()

void k_msgq_init	(	struct k_msgq *	msgq,
		char *	buffer,
		size_t	msg_size,
		uint32_t	max_msgs
	)

#include <include/zephyr/kernel.h>

Initialize a message queue.

This routine initializes a message queue object, prior to its first use.

The message queue's ring buffer must contain space for max_msgs messages, each of which is msg_size bytes long. The buffer must be aligned to an N-byte boundary, where N is a power of 2 (i.e. 1, 2, 4, ...). To ensure that each message is similarly aligned to this boundary, q_msg_size must also be a multiple of N.

Parameters

msgq	Address of the message queue.
buffer	Pointer to ring buffer that holds queued messages.
msg_size	Message size (in bytes).
max_msgs	Maximum number of messages that can be queued.

◆ k_msgq_num_free_get()

uint32_t k_msgq_num_free_get ( struct k_msgq * msgq )

#include <include/zephyr/kernel.h>

Get the amount of free space in a message queue.

This routine returns the number of unused entries in a message queue's ring buffer.

Parameters

msgq	Address of the message queue.

Returns: Number of unused ring buffer entries.

◆ k_msgq_num_used_get()

uint32_t k_msgq_num_used_get ( struct k_msgq * msgq )

#include <include/zephyr/kernel.h>

Get the number of messages in a message queue.

This routine returns the number of messages in a message queue's ring buffer.

Parameters

msgq	Address of the message queue.

Returns: Number of messages.

◆ k_msgq_peek()

int k_msgq_peek	(	struct k_msgq *	msgq,
		void *	data
	)

#include <include/zephyr/kernel.h>

Peek/read a message from a message queue.

This routine reads a message from message queue q in a "first in, first out" manner and leaves the message in the queue.

Function properties (list may not be complete): isr-ok

Parameters

msgq	Address of the message queue.
data	Address of area to hold the message read from the queue.

Return values

0	Message read.
-ENOMSG	Returned when the queue has no message.

◆ k_msgq_peek_at()

int k_msgq_peek_at	(	struct k_msgq *	msgq,
		void *	data,
		uint32_t	idx
	)

#include <include/zephyr/kernel.h>

Peek/read a message from a message queue at the specified index.

This routine reads a message from message queue at the specified index and leaves the message in the queue. k_msgq_peek_at(msgq, data, 0) is equivalent to k_msgq_peek(msgq, data)

Function properties (list may not be complete): isr-ok

Parameters

msgq	Address of the message queue.
data	Address of area to hold the message read from the queue.
idx	Message queue index at which to peek

Return values

0	Message read.
-ENOMSG	Returned when the queue has no message at index.

◆ k_msgq_purge()

void k_msgq_purge ( struct k_msgq * msgq )

#include <include/zephyr/kernel.h>

Purge a message queue.

This routine discards all unreceived messages in a message queue's ring buffer. Any threads that are blocked waiting to send a message to the message queue are unblocked and see an -ENOMSG error code.

Parameters

msgq	Address of the message queue.

◆ k_msgq_put()

int k_msgq_put	(	struct k_msgq *	msgq,
		const void *	data,
		k_timeout_t	timeout
	)

#include <include/zephyr/kernel.h>

Send a message to a message queue.

This routine sends a message to message queue q.

Note: The message content is copied from data into msgq and the data pointer is not retained, so the message content will not be modified by this function.

Function properties (list may not be complete): isr-ok

Parameters

msgq	Address of the message queue.
data	Pointer to the message.
timeout	Non-negative waiting period to add the message, or one of the special values K_NO_WAIT and K_FOREVER.

Return values

0	Message sent.
-ENOMSG	Returned without waiting or queue purged.
-EAGAIN	Waiting period timed out.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ K_MSGQ_DEFINE

◆ K_MSGQ_FLAG_ALLOC

Function Documentation

◆ k_msgq_alloc_init()

◆ k_msgq_cleanup()

◆ k_msgq_get()

◆ k_msgq_get_attrs()

◆ k_msgq_init()

◆ k_msgq_num_free_get()

◆ k_msgq_num_used_get()

◆ k_msgq_peek()

◆ k_msgq_peek_at()

◆ k_msgq_purge()

◆ k_msgq_put()