14.4. Directives¶

This section details the directives of the Message Manager. A subsection is dedicated to each of this manager’s directives and lists the calling sequence, parameters, description, return values, and notes of the directive.

14.4.1. rtems_message_queue_create()¶

Creates a message queue.

CALLING SEQUENCE:

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
);

PARAMETERS:

name: This parameter is the object name of the message queue.
count: This parameter is the maximum count of pending messages supported by the message queue.
max_message_size: This parameter is the maximum size in bytes of a message supported by the message queue.
attribute_set: This parameter is the attribute set of the message queue.
id: This parameter 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.

DESCRIPTION:

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.

14.4.2. rtems_message_queue_construct()¶

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

CALLING SEQUENCE:

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

PARAMETERS:

config: This parameter is the pointer to an rtems_message_queue_config object. It configures the message queue.
id: This parameter 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.

14.4.3. rtems_message_queue_ident()¶

Identifies a message queue by the object name.

CALLING SEQUENCE:

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

PARAMETERS:

name: This parameter is the object name to look up.
node: This parameter is the node or node set to search for a matching object.
id: This parameter 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.

DESCRIPTION:

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.

14.4.4. rtems_message_queue_delete()¶

Deletes the message queue.

CALLING SEQUENCE:

rtems_status_code rtems_message_queue_delete( rtems_id id );

PARAMETERS:

id: This parameter is the message queue identifier.

DESCRIPTION:

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.

14.4.5. rtems_message_queue_send()¶

Puts the message at the rear of the queue.

CALLING SEQUENCE:

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

PARAMETERS:

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

DESCRIPTION:

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.

14.4.6. rtems_message_queue_urgent()¶

Puts the message at the front of the queue.

CALLING SEQUENCE:

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

PARAMETERS:

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

DESCRIPTION:

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.

14.4.7. rtems_message_queue_broadcast()¶

Broadcasts the messages to the tasks waiting at the queue.

CALLING SEQUENCE:

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

PARAMETERS:

id: This parameter is the queue identifier.
buffer: This parameter is the begin address of the message buffer to broadcast.
size: This parameter is the size in bytes of the message buffer to broadcast.
count: This parameter 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.

DESCRIPTION:

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.

14.4.8. rtems_message_queue_receive()¶

Receives a message from the queue.

CALLING SEQUENCE:

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

PARAMETERS:

id: This parameter is the queue identifier.
buffer: This parameter 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.
size: This parameter 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: This parameter is the option set.
timeout: This parameter is the timeout in clock ticks if the RTEMS_WAIT option is set. Use RTEMS_NO_TIMEOUT to wait potentially forever.

DESCRIPTION:

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.

14.4.9. rtems_message_queue_get_number_pending()¶

Gets the number of messages pending on the queue.

CALLING SEQUENCE:

rtems_status_code rtems_message_queue_get_number_pending(
  rtems_id  id,
  uint32_t *count
);

PARAMETERS:

id: This parameter is the queue identifier.
count: This parameter 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.

DESCRIPTION:

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.

14.4.10. rtems_message_queue_flush()¶

Flushes all messages on the queue.

CALLING SEQUENCE:

rtems_status_code rtems_message_queue_flush( rtems_id id, uint32_t *count );

PARAMETERS:

id: This parameter is the queue identifier.
count: This parameter 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.

DESCRIPTION:

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.

14.4.11. RTEMS_MESSAGE_QUEUE_BUFFER()¶

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

CALLING SEQUENCE:

RTEMS_MESSAGE_QUEUE_BUFFER( size_t maximum_message_size );

PARAMETERS:

maximum_message_size: This parameter is the maximum message size in bytes.

NOTES:

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