The Message Manager provides communication and synchronization capabilities using RTEMS message queues. More...

Data Structures
struct	rtems_message_queue_config
	This structure defines the configuration of a message queue constructed by rtems_message_queue_construct(). More...

Macros
#define	RTEMS_MESSAGE_QUEUE_BUFFER(_maximum_message_size)
	Defines a structure which can be used as a message queue buffer for messages of the specified maximum size. More...

Functions
rtems_status_code	rtems_message_queue_create (rtems_name name, uint32_t count, size_t max_message_size, rtems_attribute attribute_set, rtems_id *id)
	Creates a message queue. More...

rtems_status_code	rtems_message_queue_construct (const rtems_message_queue_config config, rtems_id id)
	Constructs a message queue from the specified the message queue configuration. More...

rtems_status_code	rtems_message_queue_ident (rtems_name name, uint32_t node, rtems_id *id)
	Identifies a message queue by the object name. More...

rtems_status_code	rtems_message_queue_delete (rtems_id id)
	Deletes the message queue. More...

rtems_status_code	rtems_message_queue_send (rtems_id id, const void *buffer, size_t size)
	Puts the message at the rear of the queue. More...

rtems_status_code	rtems_message_queue_urgent (rtems_id id, const void *buffer, size_t size)
	Puts the message at the front of the queue. More...

rtems_status_code	rtems_message_queue_broadcast (rtems_id id, const void buffer, size_t size, uint32_t count)
	Broadcasts the messages to the tasks waiting at the queue. More...

rtems_status_code	rtems_message_queue_receive (rtems_id id, void buffer, size_t size, rtems_option option_set, rtems_interval timeout)
	Receives a message from the queue. More...

rtems_status_code	rtems_message_queue_get_number_pending (rtems_id id, uint32_t *count)
	Gets the number of messages pending on the queue. More...

rtems_status_code	rtems_message_queue_flush (rtems_id id, uint32_t *count)
	Flushes all messages on the queue. More...

Detailed Description

The Message Manager provides communication and synchronization capabilities using RTEMS message queues.

Macro Definition Documentation

◆ RTEMS_MESSAGE_QUEUE_BUFFER

#define RTEMS_MESSAGE_QUEUE_BUFFER ( _maximum_message_size )

Value:

  struct { \
    CORE_message_queue_Buffer _buffer; \
    char _message[ _maximum_message_size ]; \
  }

Defines a structure which can be used as a message queue buffer for messages of the specified maximum size.

Parameters

_maximum_message_size is the maximum message size in bytes.

Notes: Use this macro to define the message buffer storage area for rtems_message_queue_construct().

Function Documentation

◆ rtems_message_queue_broadcast()

rtems_status_code rtems_message_queue_broadcast	(	rtems_id	id,
		const void *	buffer,
		size_t	size,
		uint32_t *	count
	)

Broadcasts the messages to the tasks waiting at the queue.

Parameters

	id	is the queue identifier.
	buffer	is the begin address of the message buffer to broadcast.
	size	is the size in bytes of the message buffer to broadcast.
[out]	count	is the pointer to an uint32_t object. When the directive call is successful, the number of unblocked tasks will be stored in this object.

This directive causes all tasks that are waiting at the queue specified by id to be unblocked and sent the message contained in buffer. Before a task is unblocked, the message buffer of size bytes in length is copied to that task's message buffer. The number of tasks that were unblocked is returned in count.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no queue associated with the identifier specified by `id`.
RTEMS_INVALID_ADDRESS	The `buffer` parameter was NULL.
RTEMS_INVALID_ADDRESS	The `count` parameter was NULL.
RTEMS_INVALID_SIZE	The size of the message exceeded the maximum message size of the queue as defined by rtems_message_queue_create() or rtems_message_queue_construct().

Notes: The execution time of this directive is directly related to the number of tasks waiting on the message queue, although it is more efficient than the equivalent number of invocations of rtems_message_queue_send().

Constraints

The following constraints apply to this directive:

The directive may be called from within task context.
The directive may be called from within interrupt context.
The directive may unblock a task. This may cause the calling task to be preempted.
When the directive operates on a remote object, the directive sends a message to the remote node and waits for a reply. This will preempt the calling task.

◆ rtems_message_queue_construct()

rtems_status_code rtems_message_queue_construct	(	const rtems_message_queue_config *	config,
		rtems_id *	id
	)

Constructs a message queue from the specified the message queue configuration.

Parameters

	config	is the pointer to an rtems_message_queue_config object. It configures the message queue.
[out]	id	is the pointer to an rtems_id object. When the directive call is successful, the identifier of the constructed message queue will be stored in this object.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The `config` parameter was NULL.
RTEMS_INVALID_NAME	The message queue name in the configuration was invalid.
RTEMS_INVALID_ADDRESS	The `id` parameter was NULL.
RTEMS_INVALID_NUMBER	The maximum number of pending messages in the configuration was zero.
RTEMS_INVALID_SIZE	The maximum message size in the configuration was zero.
RTEMS_TOO_MANY	There was no inactive message queue object available to construct a message queue.
RTEMS_TOO_MANY	In multiprocessing configurations, there was no inactive global object available to construct a global message queue.
RTEMS_INVALID_SIZE	The maximum message size in the configuration was too big and resulted in integer overflows in calculations carried out to determine the size of the message buffer area.
RTEMS_INVALID_NUMBER	The maximum number of pending messages in the configuration was too big and resulted in integer overflows in calculations carried out to determine the size of the message buffer area.
RTEMS_UNSATISFIED	The message queue storage area begin pointer in the configuration was NULL.
RTEMS_UNSATISFIED	The message queue storage area size in the configuration was not equal to the size calculated from the maximum number of pending messages and the maximum message size.

Notes

In contrast to message queues created by rtems_message_queue_create(), the message queues constructed by this directive use a user-provided message buffer storage area.

This directive is intended for applications which do not want to use the RTEMS Workspace and instead statically allocate all operating system resources. An application based solely on static allocation can avoid any runtime memory allocators. This can simplify the application architecture as well as any analysis that may be required.

The value for CONFIGURE_MESSAGE_BUFFER_MEMORY should not include memory for message queues constructed by rtems_message_queue_construct().

Constraints

The following constraints apply to this directive:

The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.
When the directive operates on a global object, the directive sends a message to remote nodes. This may preempt the calling task.
The number of message queues available to the application is configured through the CONFIGURE_MAXIMUM_MESSAGE_QUEUES application configuration option.
Where the object class corresponding to the directive is configured to use unlimited objects, the directive may allocate memory from the RTEMS Workspace.
The number of global objects available to the application is configured through the CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option.

◆ rtems_message_queue_create()

rtems_status_code rtems_message_queue_create	(	rtems_name	name,
		uint32_t	count,
		size_t	max_message_size,
		rtems_attribute	attribute_set,
		rtems_id *	id
	)

Creates a message queue.

Parameters

	name	is the object name of the message queue.
	count	is the maximum count of pending messages supported by the message queue.
	max_message_size	is the maximum size in bytes of a message supported by the message queue.
	attribute_set	is the attribute set of the message queue.
[out]	id	is the pointer to an rtems_id object. When the directive call is successful, the identifier of the created message queue will be stored in this object.

This directive creates a message queue which resides on the local node. The message queue has the user-defined object name specified in name. Memory is allocated from the RTEMS Workspace for the count of messages specified in count, each of max_message_size bytes in length. The assigned object identifier is returned in id. This identifier is used to access the message queue with other message queue related directives.

The attribute set specified in attribute_set is built through a bitwise or of the attribute constants described below. Not all combinations of attributes are allowed. Some attributes are mutually exclusive. If mutually exclusive attributes are combined, the behaviour is undefined. Attributes not mentioned below are not evaluated by this directive and have no effect. Default attributes can be selected by using the RTEMS_DEFAULT_ATTRIBUTES constant. The attribute set defines

the scope of the message queue: RTEMS_LOCAL (default) or RTEMS_GLOBAL and
the task wait queue discipline used by the message queue: RTEMS_FIFO (default) or RTEMS_PRIORITY.

The message queue has a local or global scope in a multiprocessing network (this attribute does not refer to SMP systems). The scope is selected by the mutually exclusive RTEMS_LOCAL and RTEMS_GLOBAL attributes.

A local scope is the default and can be emphasized through the use of the RTEMS_LOCAL attribute. A local message queue can be only used by the node which created it.
A global scope is established if the RTEMS_GLOBAL attribute is set. Setting the global attribute in a single node system has no effect.

The task wait queue discipline is selected by the mutually exclusive RTEMS_FIFO and RTEMS_PRIORITY attributes. The discipline defines the order in which tasks wait for a message to receive on a currently empty message queue.

The FIFO discipline is the default and can be emphasized through use of the RTEMS_FIFO attribute.
The priority discipline is selected by the RTEMS_PRIORITY attribute.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_NAME	The `name` parameter was invalid.
RTEMS_INVALID_ADDRESS	The `id` parameter was NULL.
RTEMS_INVALID_NUMBER	The `count` parameter was invalid.
RTEMS_INVALID_SIZE	The `max_message_size` parameter was invalid.
RTEMS_TOO_MANY	There was no inactive object available to create a message queue. The number of message queue available to the application is configured through the CONFIGURE_MAXIMUM_MESSAGE_QUEUES application configuration option.
RTEMS_TOO_MANY	In multiprocessing configurations, there was no inactive global object available to create a global message queue. The number of global objects available to the application is configured through the CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option.
RTEMS_INVALID_NUMBER	The product of `count` and `max_message_size` is greater than the maximum storage size.
RTEMS_UNSATISFIED	There was not enough memory available in the RTEMS Workspace to allocate the message buffers for the message queue.

Notes

For message queues with a global scope, the maximum message size is effectively limited to the longest message which the MPCI is capable of transmitting.

For control and maintenance of the message queue, RTEMS allocates a QCB from the local QCB free pool and initializes it.

The QCB for a global message queue is allocated on the local node. Message queues should not be made global unless remote tasks must interact with the message queue. This is to avoid the system overhead incurred by the creation of a global message queue. When a global message queue is created, the message queue's name and identifier must be transmitted to every node in the system for insertion in the local copy of the global object table.

Constraints

The following constraints apply to this directive:

The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.
When the directive operates on a global object, the directive sends a message to remote nodes. This may preempt the calling task.
The number of message queues available to the application is configured through the CONFIGURE_MAXIMUM_MESSAGE_QUEUES application configuration option.
Where the object class corresponding to the directive is configured to use unlimited objects, the directive may allocate memory from the RTEMS Workspace.
The number of global objects available to the application is configured through the CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option.

◆ rtems_message_queue_delete()

rtems_status_code rtems_message_queue_delete ( rtems_id id )

Deletes the message queue.

Parameters

id	is the message queue identifier.

This directive deletes the message queue specified by id. As a result of this directive, all tasks blocked waiting to receive a message from this queue will be readied and returned a status code which indicates that the message queue was deleted.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no message queue associated with the identifier specified by `id`.
RTEMS_ILLEGAL_ON_REMOTE_OBJECT	The message queue resided on a remote node.

Notes

When the message queue is deleted, any messages in the queue are returned to the free message buffer pool. Any information stored in those messages is lost. The message buffers allocated for the message queue are reclaimed.

The QCB for the deleted message queue is reclaimed by RTEMS.

When a global message queue is deleted, the message queue identifier must be transmitted to every node in the system for deletion from the local copy of the global object table.

The message queue must reside on the local node, even if the message queue was created with the RTEMS_GLOBAL attribute.

Proxies, used to represent remote tasks, are reclaimed when the message queue is deleted.

Constraints

The following constraints apply to this directive:

The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive may obtain and release the object allocator mutex. This may cause the calling task to be preempted.
When the directive operates on a global object, the directive sends a message to remote nodes. This may preempt the calling task.
The calling task does not have to be the task that created the object. Any local task that knows the object identifier can delete the object.
Where the object class corresponding to the directive is configured to use unlimited objects, the directive may free memory to the RTEMS Workspace.

◆ rtems_message_queue_flush()

rtems_status_code rtems_message_queue_flush	(	rtems_id	id,
		uint32_t *	count
	)

Flushes all messages on the queue.

Parameters

	id	is the queue identifier.
[out]	count	is the pointer to an uint32_t object. When the directive call is successful, the number of pending messages removed from the queue will be stored in this object.

This directive removes all pending messages from the queue specified by id. The number of messages removed is returned in count. If no messages are present on the queue, count is set to zero.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no queue associated with the identifier specified by `id`.
RTEMS_INVALID_ADDRESS	The `count` parameter was NULL.

Notes: The directive does not flush tasks waiting to receive a message from the wait queue of the message queue.

Constraints

The following constraints apply to this directive:

The directive may be called from within interrupt context.
The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive will not cause the calling task to be preempted.

◆ rtems_message_queue_get_number_pending()

rtems_status_code rtems_message_queue_get_number_pending	(	rtems_id	id,
		uint32_t *	count
	)

Gets the number of messages pending on the queue.

Parameters

	id	is the queue identifier.
[out]	count	is the pointer to an uint32_t object. When the directive call is successful, the number of pending messages will be stored in this object.

This directive returns the number of messages pending on the queue specified by id in count. If no messages are present on the queue, count is set to zero.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no queue associated with the identifier specified by `id`.
RTEMS_INVALID_ADDRESS	The `count` parameter was NULL.

Constraints

The following constraints apply to this directive:

The directive may be called from within task context.
The directive may be called from within interrupt context.
When the directive operates on a remote object, the directive sends a message to the remote node and waits for a reply. This will preempt the calling task.

◆ rtems_message_queue_ident()

rtems_status_code rtems_message_queue_ident	(	rtems_name	name,
		uint32_t	node,
		rtems_id *	id
	)

Identifies a message queue by the object name.

Parameters

	name	is the object name to look up.
	node	is the node or node set to search for a matching object.
[out]	id	is the pointer to an rtems_id object. When the directive call is successful, the object identifier of an object with the specified name will be stored in this object.

This directive obtains a message queue identifier associated with the message queue name specified in name.

The node to search is specified in node. It shall be

a valid node number,
the constant RTEMS_SEARCH_ALL_NODES to search in all nodes,
the constant RTEMS_SEARCH_LOCAL_NODE to search in the local node only, or
the constant RTEMS_SEARCH_OTHER_NODES to search in all nodes except the local node.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The `id` parameter was NULL.
RTEMS_INVALID_NAME	The `name` parameter was 0.
RTEMS_INVALID_NAME	There was no object with the specified name on the specified nodes.
RTEMS_INVALID_NODE	In multiprocessing configurations, the specified node was invalid.

Notes

If the message queue name is not unique, then the message queue identifier will match the first message queue with that name in the search order. However, this message queue identifier is not guaranteed to correspond to the desired message queue.

The objects are searched from lowest to the highest index. If node is RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local node being searched first. All other nodes are searched from lowest to the highest node number.

If node is a valid node number which does not represent the local node, then only the message queues exported by the designated node are searched.

This directive does not generate activity on remote nodes. It accesses only the local copy of the global object table.

The message queue identifier is used with other message related directives to access the message queue.

Constraints

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

◆ rtems_message_queue_receive()

rtems_status_code rtems_message_queue_receive	(	rtems_id	id,
		void *	buffer,
		size_t *	size,
		rtems_option	option_set,
		rtems_interval	timeout
	)

Receives a message from the queue.

Parameters

	id	is the queue identifier.
	buffer	is the begin address of the buffer to receive the message. The buffer shall be large enough to receive a message of the maximum length of the queue as defined by rtems_message_queue_create() or rtems_message_queue_construct(). The `size` parameter cannot be used to specify the size of the buffer.
[out]	size	is the pointer to a size_t object. When the directive call is successful, the size in bytes of the received messages will be stored in this object. This parameter cannot be used to specify the size of the buffer.
	option_set	is the option set.
	timeout	is the timeout in clock ticks if the RTEMS_WAIT option is set. Use RTEMS_NO_TIMEOUT to wait potentially forever.

This directive receives a message from the queue specified by id.

The option set specified in option_set is built through a bitwise or of the option constants described below. Not all combinations of options are allowed. Some options are mutually exclusive. If mutually exclusive options are combined, the behaviour is undefined. Options not mentioned below are not evaluated by this directive and have no effect. Default options can be selected by using the RTEMS_DEFAULT_OPTIONS constant.

The calling task can wait or try to receive a message from the queue according to the mutually exclusive RTEMS_WAIT and RTEMS_NO_WAIT options.

Waiting to receive a message from the queue is the default and can be emphasized through the use of the RTEMS_WAIT option. The timeout parameter defines how long the calling task is willing to wait. Use RTEMS_NO_TIMEOUT to wait potentially forever, otherwise set a timeout interval in clock ticks.
Trying to receive a message from the queue is selected by the RTEMS_NO_WAIT option. If this option is defined, then the timeout parameter is ignored. When a message from the queue cannot be immediately received, then the RTEMS_UNSATISFIED status is returned.

With either RTEMS_WAIT or RTEMS_NO_WAIT if there is at least one message in the queue, then it is copied to the buffer, the size is set to return the length of the message in bytes, and this directive returns immediately with the RTEMS_SUCCESSFUL status code. The buffer has to be big enough to receive a message of the maximum length with respect to this message queue.

If the calling task chooses to return immediately and the queue is empty, then the directive returns immediately with the RTEMS_UNSATISFIED status code. If the calling task chooses to wait at the message queue and the queue is empty, then the calling task is placed on the message wait queue and blocked. If the queue was created with the RTEMS_PRIORITY option specified, then the calling task is inserted into the wait queue according to its priority. But, if the queue was created with the RTEMS_FIFO option specified, then the calling task is placed at the rear of the wait queue.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no queue associated with the identifier specified by `id`.
RTEMS_INVALID_ADDRESS	The `buffer` parameter was NULL.
RTEMS_INVALID_ADDRESS	The `size` parameter was NULL.
RTEMS_UNSATISFIED	The queue was empty.
RTEMS_TIMEOUT	The timeout happened while the calling task was waiting to receive a message
RTEMS_OBJECT_WAS_DELETED	The queue was deleted while the calling task was waiting to receive a message.

Constraints

The following constraints apply to this directive:

When a local queue is accessed and the RTEMS_NO_WAIT option is set, the directive may be called from within interrupt context.
The directive may be called from within task context.
When the request cannot be immediately satisfied and the RTEMS_WAIT option is set, the calling task blocks at some point during the directive call.
The timeout functionality of the directive requires a clock tick.
When the directive operates on a remote object, the directive sends a message to the remote node and waits for a reply. This will preempt the calling task.

◆ rtems_message_queue_send()

rtems_status_code rtems_message_queue_send	(	rtems_id	id,
		const void *	buffer,
		size_t	size
	)

Puts the message at the rear of the queue.

Parameters

id	is the queue identifier.
buffer	is the begin address of the message buffer to send.
size	is the size in bytes of the message buffer to send.

This directive sends the message buffer of size bytes in length to the queue specified by id. If a task is waiting at the queue, then the message is copied to the waiting task's buffer and the task is unblocked. If no tasks are waiting at the queue, then the message is copied to a message buffer which is obtained from this message queue's message buffer pool. The message buffer is then placed at the rear of the queue.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no queue associated with the identifier specified by `id`.
RTEMS_INVALID_ADDRESS	The `buffer` parameter was NULL.
RTEMS_INVALID_SIZE	The size of the message exceeded the maximum message size of the queue as defined by rtems_message_queue_create() or rtems_message_queue_construct().
RTEMS_TOO_MANY	The maximum number of pending messages supported by the queue as defined by rtems_message_queue_create() or rtems_message_queue_construct() has been reached.

Constraints

The following constraints apply to this directive:

The directive may be called from within task context.
The directive may be called from within interrupt context.
The directive may unblock a task. This may cause the calling task to be preempted.
When the directive operates on a remote object, the directive sends a message to the remote node and waits for a reply. This will preempt the calling task.

◆ rtems_message_queue_urgent()

rtems_status_code rtems_message_queue_urgent	(	rtems_id	id,
		const void *	buffer,
		size_t	size
	)

Puts the message at the front of the queue.

Parameters

id	is the queue identifier.
buffer	is the begin address of the message buffer to send urgently.
size	is the size in bytes of the message buffer to send urgently.

This directive sends the message buffer of size bytes in length to the queue specified by id. If a task is waiting at the queue, then the message is copied to the waiting task's buffer and the task is unblocked. If no tasks are waiting at the queue, then the message is copied to a message buffer which is obtained from this message queue's message buffer pool. The message buffer is then placed at the front of the queue.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no queue associated with the identifier specified by `id`.
RTEMS_INVALID_ADDRESS	The `buffer` parameter was NULL.
RTEMS_INVALID_SIZE	The size of the message exceeded the maximum message size of the queue as defined by rtems_message_queue_create() or rtems_message_queue_construct().
RTEMS_TOO_MANY	The maximum number of pending messages supported by the queue as defined by rtems_message_queue_create() or rtems_message_queue_construct() has been reached.

Constraints

The following constraints apply to this directive:

The directive may be called from within task context.
The directive may be called from within interrupt context.
The directive may unblock a task. This may cause the calling task to be preempted.
When the directive operates on a remote object, the directive sends a message to the remote node and waits for a reply. This will preempt the calling task.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ RTEMS_MESSAGE_QUEUE_BUFFER

Function Documentation

◆ rtems_message_queue_broadcast()

◆ rtems_message_queue_construct()

◆ rtems_message_queue_create()

◆ rtems_message_queue_delete()

◆ rtems_message_queue_flush()

◆ rtems_message_queue_get_number_pending()

◆ rtems_message_queue_ident()

◆ rtems_message_queue_receive()

◆ rtems_message_queue_send()

◆ rtems_message_queue_urgent()