From c75ded25eae1c64c1b4dba796acdda741710519e Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Thu, 20 Aug 2020 09:55:50 +0200 Subject: c-user: Split up message manager This makes it easier to automatically generate parts of the manager documentation in the future. Update #3993. --- c-user/message/operations.rst | 89 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 c-user/message/operations.rst (limited to 'c-user/message/operations.rst') diff --git a/c-user/message/operations.rst b/c-user/message/operations.rst new file mode 100644 index 0000000..4d34661 --- /dev/null +++ b/c-user/message/operations.rst @@ -0,0 +1,89 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Creating a Message Queue +------------------------ + +The ``rtems_message_queue_create`` directive creates a message queue with the +user-defined name. The user specifies the maximum message size and maximum +number of messages which can be placed in the message queue at one time. The +user may select FIFO or task priority as the method for placing waiting tasks +in the task wait queue. RTEMS allocates a Queue Control Block (QCB) from the +QCB free list to maintain the newly created queue as well as memory for the +message buffer pool associated with this message queue. RTEMS also generates a +message queue ID which is returned to the calling task. + +For GLOBAL message queues, the maximum message size is effectively limited to +the longest message which the MPCI is capable of transmitting. + +Obtaining Message Queue IDs +--------------------------- + +When a message queue is created, RTEMS generates a unique message queue ID. +The message queue ID may be obtained by either of two methods. First, as the +result of an invocation of the ``rtems_message_queue_create`` directive, the +queue ID is stored in a user provided location. Second, the queue ID may be +obtained later using the ``rtems_message_queue_ident`` directive. The queue ID +is used by other message manager directives to access this message queue. + +Receiving a Message +------------------- + +The ``rtems_message_queue_receive`` directive attempts to retrieve a message +from the specified message queue. If at least one message is in the queue, +then the message is removed from the queue, copied to the caller's message +buffer, and returned immediately along with the length of the message. When +messages are unavailable, one of the following situations applies: + +- By default, the calling task will wait forever for the message to arrive. + +- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return with an + error status code. + +- Specifying a timeout limits the period the task will wait before returning + with an error status. + +If the task waits for a message, then it is placed in the message queue's task +wait queue in either FIFO or task priority order. All tasks waiting on a +message queue are returned an error code when the message queue is deleted. + +Sending a Message +----------------- + +Messages can be sent to a queue with the ``rtems_message_queue_send`` and +``rtems_message_queue_urgent`` directives. These directives work identically +when tasks are waiting to receive a message. A task is removed from the task +waiting queue, unblocked, and the message is copied to a waiting task's message +buffer. + +When no tasks are waiting at the queue, ``rtems_message_queue_send`` places the +message at the rear of the message queue, while ``rtems_message_queue_urgent`` +places the message at the front of the queue. The message is copied to a +message buffer from this message queue's buffer pool and then placed in the +message queue. Neither directive can successfully send a message to a message +queue which has a full queue of pending messages. + +Broadcasting a Message +---------------------- + +The ``rtems_message_queue_broadcast`` directive sends the same message to every +task waiting on the specified message queue as an atomic operation. The +message is copied to each waiting task's message buffer and each task is +unblocked. The number of tasks which were unblocked is returned to the caller. + +Deleting a Message Queue +------------------------ + +The ``rtems_message_queue_delete`` directive removes a message queue from the +system and frees its control block as well as the memory associated with this +message queue's message buffer pool. A message queue can be deleted by any +local task that knows the message queue's ID. As a result of this directive, +all tasks blocked waiting to receive a message from the message queue will be +readied and returned a status code which indicates that the message queue was +deleted. Any subsequent references to the message queue's name and ID are +invalid. Any messages waiting at the message queue are also deleted and +deallocated. -- cgit v1.2.3