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/index.rst | 2 +- c-user/message/background.rst | 91 +++++ c-user/message/directives.rst | 559 +++++++++++++++++++++++++++++ c-user/message/index.rst | 16 + c-user/message/introduction.rst | 28 ++ c-user/message/operations.rst | 89 +++++ c-user/message_manager.rst | 764 ---------------------------------------- 7 files changed, 784 insertions(+), 765 deletions(-) create mode 100644 c-user/message/background.rst create mode 100644 c-user/message/directives.rst create mode 100644 c-user/message/index.rst create mode 100644 c-user/message/introduction.rst create mode 100644 c-user/message/operations.rst delete mode 100644 c-user/message_manager.rst diff --git a/c-user/index.rst b/c-user/index.rst index cf73c77..0febfc4 100644 --- a/c-user/index.rst +++ b/c-user/index.rst @@ -37,7 +37,7 @@ RTEMS Classic API Guide (|version|). rate_monotonic_manager semaphore/index barrier/index - message_manager + message/index event/index signal_manager partition_manager diff --git a/c-user/message/background.rst b/c-user/message/background.rst new file mode 100644 index 0000000..2ab43fe --- /dev/null +++ b/c-user/message/background.rst @@ -0,0 +1,91 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +Messages +-------- + +A message is a variable length buffer where information can be stored to +support communication. The length of the message and the information stored in +that message are user-defined and can be actual data, pointer(s), or empty. + +Message Queues +-------------- + +A message queue permits the passing of messages among tasks and ISRs. Message +queues can contain a variable number of messages. Normally messages are sent +to and received from the queue in FIFO order using the +``rtems_message_queue_send`` directive. However, the +``rtems_message_queue_urgent`` directive can be used to place messages at the +head of a queue in LIFO order. + +Synchronization can be accomplished when a task can wait for a message to +arrive at a queue. Also, a task may poll a queue for the arrival of a message. + +The maximum length message which can be sent is set on a per message queue +basis. The message content must be copied in general to/from an internal +buffer of the message queue or directly to a peer in certain cases. This copy +operation is performed with interrupts disabled. So it is advisable to keep +the messages as short as possible. + +.. index:: message queue attributes + +Building a Message Queue Attribute Set +-------------------------------------- + +In general, an attribute set is built by a bitwise OR of the desired attribute +components. The set of valid message queue attributes is provided in the +following table: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_FIFO`` + - tasks wait by FIFO (default) + * - ``RTEMS_PRIORITY`` + - tasks wait by priority + * - ``RTEMS_LOCAL`` + - local message queue (default) + * - ``RTEMS_GLOBAL`` + - global message queue + +An attribute listed as a default is not required to appear in the attribute +list, although it is a good programming practice to specify default attributes. +If all defaults are desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should +be specified on this call. + +This example demonstrates the attribute_set parameter needed to create a local +message queue with the task priority waiting queue discipline. The +attribute_set parameter to the ``rtems_message_queue_create`` directive could +be either ``RTEMS_PRIORITY`` or ``RTEMS_LOCAL | RTEMS_PRIORITY``. The +attribute_set parameter can be set to ``RTEMS_PRIORITY`` because +``RTEMS_LOCAL`` is the default for all created message queues. If a similar +message queue were to be known globally, then the attribute_set parameter would +be ``RTEMS_GLOBAL | RTEMS_PRIORITY``. + +Building a MESSAGE_QUEUE_RECEIVE Option Set +------------------------------------------- + +In general, an option is built by a bitwise OR of the desired option +components. The set of valid options for the ``rtems_message_queue_receive`` +directive are listed in the following table: + +.. list-table:: + :class: rtems-table + + * - ``RTEMS_WAIT`` + - task will wait for a message (default) + * - ``RTEMS_NO_WAIT`` + - task should not wait + +An option listed as a default is not required to appear in the option OR list, +although it is a good programming practice to specify default options. If all +defaults are desired, the option ``RTEMS_DEFAULT_OPTIONS`` should be specified +on this call. + +This example demonstrates the option parameter needed to poll for a message to +arrive. The option parameter passed to the ``rtems_message_queue_receive`` +directive should be ``RTEMS_NO_WAIT``. diff --git a/c-user/message/directives.rst b/c-user/message/directives.rst new file mode 100644 index 0000000..4d9bdc7 --- /dev/null +++ b/c-user/message/directives.rst @@ -0,0 +1,559 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Directives +========== + +This section details the message manager's directives. A subsection is +dedicated to each of this manager's directives and describes the calling +sequence, related constants, usage, and status codes. + +.. raw:: latex + + \clearpage + +.. index:: create a message queue +.. index:: rtems_message_queue_create + +.. _rtems_message_queue_create: + +MESSAGE_QUEUE_CREATE - Create a queue +------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + 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 + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - queue created successfully + * - ``RTEMS_INVALID_NAME`` + - invalid queue name + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NUMBER`` + - invalid message count + * - ``RTEMS_INVALID_SIZE`` + - invalid message size + * - ``RTEMS_TOO_MANY`` + - too many queues created + * - ``RTEMS_UNSATISFIED`` + - unable to allocate message buffers + * - ``RTEMS_TOO_MANY`` + - too many global objects + +DESCRIPTION: + This directive creates a message queue which resides on the local node with + the user-defined name specified in name. For control and maintenance of + the queue, RTEMS allocates and initializes a QCB. Memory is allocated from + the RTEMS Workspace for the specified count of messages, each of + max_message_size bytes in length. The RTEMS-assigned queue id, returned in + id, is used to access the message queue. + + Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks waiting for a + message to be serviced according to task priority. When ``RTEMS_FIFO`` is + specified, waiting tasks are serviced in First In-First Out order. + +NOTES: + This directive may cause the calling task to be preempted due to an + obtain and release of the object allocator mutex. + + The following message queue attribute constants are defined by RTEMS: + + .. list-table:: + :class: rtems-table + + * - ``RTEMS_FIFO`` + - tasks wait by FIFO (default) + * - ``RTEMS_PRIORITY`` + - tasks wait by priority + * - ``RTEMS_LOCAL`` + - local message queue (default) + * - ``RTEMS_GLOBAL`` + - global message queue + + Message queues should not be made global unless remote tasks must interact + with the created 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 id must be transmitted to + every node in the system for insertion in the local copy of the global + object table. + + For GLOBAL message queues, the maximum message size is effectively limited + to the longest message which the MPCI is capable of transmitting. + + The total number of global objects, including message queues, is limited by + the ``maximum_global_objects`` field in the configuration table. + +.. raw:: latex + + \clearpage + +.. index:: get ID of a message queue +.. index:: rtems_message_queue_ident + +.. _rtems_message_queue_ident: + +MESSAGE_QUEUE_IDENT - Get ID of a queue +--------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_message_queue_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - queue identified successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NAME`` + - queue name not found + * - ``RTEMS_INVALID_NODE`` + - invalid node id + +DESCRIPTION: + This directive obtains the queue id associated with the queue name + specified in name. If the queue name is not unique, then the queue id will + match one of the queues with that name. However, this queue id is not + guaranteed to correspond to the desired queue. The queue id is used with + other message related directives to access the message queue. + +NOTES: + This directive will not cause the running task to be preempted. + + If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the + local node being searched first. All other nodes are searched with the + lowest numbered node searched first. + + 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. + +.. raw:: latex + + \clearpage + +.. index:: delete a message queue +.. index:: rtems_message_queue_delete + +.. _rtems_message_queue_delete: + +MESSAGE_QUEUE_DELETE - Delete a queue +------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_message_queue_delete( + rtems_id id + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - queue deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid queue id + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - cannot delete remote queue + +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. If no tasks are waiting, but the queue contains + messages, then RTEMS returns these message buffers back to the system + message buffer pool. The QCB for this queue as well as the memory for the + message buffers is reclaimed by RTEMS. + +NOTES: + This directive may cause the calling task to be preempted due to an + obtain and release of the object allocator mutex. + + The calling task will be preempted if its preemption mode is enabled and + one or more local tasks with a higher priority than the calling task are + waiting on the deleted queue. The calling task will NOT be preempted if + the tasks that are waiting are remote tasks. + + The calling task does not have to be the task that created the queue, + although the task and queue must reside on the same node. + + When the queue is deleted, any messages in the queue are returned to the + free message buffer pool. Any information stored in those messages is + lost. + + When a global message queue is deleted, the message queue id must be + transmitted to every node in the system for deletion from the local copy of + the global object table. + + Proxies, used to represent remote tasks, are reclaimed when the message + queue is deleted. + +.. raw:: latex + + \clearpage + +.. index:: send message to a queue +.. index:: rtems_message_queue_send + +.. _rtems_message_queue_send: + +MESSAGE_QUEUE_SEND - Put message at rear of a queue +--------------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_message_queue_send( + rtems_id id, + const void *buffer, + size_t size + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - message sent successfully + * - ``RTEMS_INVALID_ID`` + - invalid queue id + * - ``RTEMS_INVALID_SIZE`` + - invalid message size + * - ``RTEMS_INVALID_ADDRESS`` + - ``buffer`` is NULL + * - ``RTEMS_UNSATISFIED`` + - out of message buffers + * - ``RTEMS_TOO_MANY`` + - queue's limit has been reached + +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. + +NOTES: + The calling task will be preempted if it has preemption enabled and a + higher priority task is unblocked as the result of this directive. + + Sending a message to a global message queue which does not reside on the + local node will generate a request to the remote node to post the message + on the specified message queue. + + If the task to be unblocked resides on a different node from the message + queue, then the message is forwarded to the appropriate node, the waiting + task is unblocked, and the proxy used to represent the task is reclaimed. + +.. raw:: latex + + \clearpage + +.. index:: put message at front of queue +.. index:: rtems_message_queue_urgent + +.. _rtems_message_queue_urgent: + +MESSAGE_QUEUE_URGENT - Put message at front of a queue +------------------------------------------------------ + +**CALLING SEQUENCE:** + .. code-block:: c + + rtems_status_code rtems_message_queue_urgent( + rtems_id id, + const void *buffer, + size_t size + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - message sent successfully + * - ``RTEMS_INVALID_ID`` + - invalid queue id + * - ``RTEMS_INVALID_SIZE`` + - invalid message size + * - ``RTEMS_INVALID_ADDRESS`` + - ``buffer`` is NULL + * - ``RTEMS_UNSATISFIED`` + - out of message buffers + * - ``RTEMS_TOO_MANY`` + - queue's limit has been reached + +DESCRIPTION: + This directive sends the message buffer of size bytes in length to the + queue specified by id. If a task is waiting on the queue, then the message + is copied to the task's buffer and the task is unblocked. If no tasks are + waiting on 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. + +NOTES: + The calling task will be preempted if it has preemption enabled and a + higher priority task is unblocked as the result of this directive. + + Sending a message to a global message queue which does not reside on the + local node will generate a request telling the remote node to post the + message on the specified message queue. + + If the task to be unblocked resides on a different node from the message + queue, then the message is forwarded to the appropriate node, the waiting + task is unblocked, and the proxy used to represent the task is reclaimed. + +.. raw:: latex + + \clearpage + +.. index:: broadcast message to a queue +.. index:: rtems_message_queue_broadcast + +.. _rtems_message_queue_broadcast: + +MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue +--------------------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_message_queue_broadcast( + rtems_id id, + const void *buffer, + size_t size, + uint32_t *count + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - message broadcasted successfully + * - ``RTEMS_INVALID_ID`` + - invalid queue id + * - ``RTEMS_INVALID_ADDRESS`` + - ``buffer`` is NULL + * - ``RTEMS_INVALID_ADDRESS`` + - ``count`` is NULL + * - ``RTEMS_INVALID_SIZE`` + - invalid message size + +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 byes in length is copied to that + task's message buffer. The number of tasks that were unblocked is returned + in count. + +NOTES: + The calling task will be preempted if it has preemption enabled and a + higher priority task is unblocked as the result of this directive. + + 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``. + + Broadcasting a message to a global message queue which does not reside on + the local node will generate a request telling the remote node to broadcast + the message to the specified message queue. + + When a task is unblocked which resides on a different node from the message + queue, a copy of the message is forwarded to the appropriate node, the + waiting task is unblocked, and the proxy used to represent the task is + reclaimed. + +.. raw:: latex + + \clearpage + +.. index:: receive message from a queue +.. index:: rtems_message_queue_receive + +.. _rtems_message_queue_receive: + +MESSAGE_QUEUE_RECEIVE - Receive message from a queue +---------------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_message_queue_receive( + rtems_id id, + void *buffer, + size_t *size, + rtems_option option_set, + rtems_interval timeout + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - message received successfully + * - ``RTEMS_INVALID_ID`` + - invalid queue id + * - ``RTEMS_INVALID_ADDRESS`` + - ``buffer`` is NULL + * - ``RTEMS_INVALID_ADDRESS`` + - ``size`` is NULL + * - ``RTEMS_UNSATISFIED`` + - queue is empty + * - ``RTEMS_TIMEOUT`` + - timed out waiting for message + * - ``RTEMS_OBJECT_WAS_DELETED`` + - queue deleted while waiting + +DESCRIPTION: + This directive receives a message from the message queue specified in id. + The ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` options of the options parameter + allow the calling task to specify whether to wait for a message to become + available or return immediately. For either option, if there is at least + one message in the queue, then it is copied to buffer, size is set to + return the length of the message in bytes, and this directive returns + immediately with a successful return 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 a status code indicating this condition is returned. 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. + + A task choosing to wait at the queue can optionally specify a timeout value + in the timeout parameter. The timeout parameter specifies the maximum + interval to wait before the calling task desires to be unblocked. If it is + set to ``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. + +NOTES: + The following message receive option constants are defined by RTEMS: + + .. list-table:: + :class: rtems-table + + * - ``RTEMS_WAIT`` + - task will wait for a message (default) + * - ``RTEMS_NO_WAIT`` + - task should not wait + + Receiving a message from a global message queue which does not reside on + the local node will generate a request to the remote node to obtain a + message from the specified message queue. If no message is available and + ``RTEMS_WAIT`` was specified, then the task must be blocked until a message + is posted. A proxy is allocated on the remote node to represent the task + until the message is posted. + + A clock tick is required to support the timeout functionality of this + directive. + +.. raw:: latex + + \clearpage + +.. index:: get number of pending messages +.. index:: rtems_message_queue_get_number_pending + +.. _rtems_message_queue_get_number_pending: + +MESSAGE_QUEUE_GET_NUMBER_PENDING - Get number of messages pending on a queue +---------------------------------------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_message_queue_get_number_pending( + rtems_id id, + uint32_t *count + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - number of messages pending returned successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``count`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid queue id + +DESCRIPTION: + This directive returns the number of messages pending on this message queue + in count. If no messages are present on the queue, count is set to zero. + +NOTES: + Getting the number of pending messages on a global message queue which does + not reside on the local node will generate a request to the remote node to + actually obtain the pending message count for the specified message queue. + +.. raw:: latex + + \clearpage + +.. index:: flush messages on a queue +.. index:: rtems_message_queue_flush + +.. _rtems_message_queue_flush: + +MESSAGE_QUEUE_FLUSH - Flush all messages on a queue +--------------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_message_queue_flush( + rtems_id id, + uint32_t *count + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - message queue flushed successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``count`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid queue id + +DESCRIPTION: + This directive removes all pending messages from the specified queue id. + The number of messages removed is returned in count. If no messages are + present on the queue, count is set to zero. + +NOTES: + Flushing all messages on a global message queue which does not reside on + the local node will generate a request to the remote node to actually flush + the specified message queue. diff --git a/c-user/message/index.rst b/c-user/message/index.rst new file mode 100644 index 0000000..456d177 --- /dev/null +++ b/c-user/message/index.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + +.. index:: messages +.. index:: message queues + +Message Manager +*************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/message/introduction.rst b/c-user/message/introduction.rst new file mode 100644 index 0000000..b10e06c --- /dev/null +++ b/c-user/message/introduction.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Introduction +============ + +The message manager provides communication and synchronization capabilities +using RTEMS message queues. The directives provided by the message manager +are: + +- :ref:`rtems_message_queue_create` + +- :ref:`rtems_message_queue_ident` + +- :ref:`rtems_message_queue_delete` + +- :ref:`rtems_message_queue_send` + +- :ref:`rtems_message_queue_urgent` + +- :ref:`rtems_message_queue_broadcast` + +- :ref:`rtems_message_queue_receive` + +- :ref:`rtems_message_queue_get_number_pending` + +- :ref:`rtems_message_queue_flush` 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. diff --git a/c-user/message_manager.rst b/c-user/message_manager.rst deleted file mode 100644 index 8115609..0000000 --- a/c-user/message_manager.rst +++ /dev/null @@ -1,764 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: messages -.. index:: message queues - -Message Manager -*************** - -Introduction -============ - -The message manager provides communication and synchronization capabilities -using RTEMS message queues. The directives provided by the message manager -are: - -- rtems_message_queue_create_ - Create a queue - -- rtems_message_queue_ident_ - Get ID of a queue - -- rtems_message_queue_delete_ - Delete a queue - -- rtems_message_queue_send_ - Put message at rear of a queue - -- rtems_message_queue_urgent_ - Put message at front of a queue - -- rtems_message_queue_broadcast_ - Broadcast N messages to a queue - -- rtems_message_queue_receive_ - Receive message from a queue - -- rtems_message_queue_get_number_pending_ - Get number of messages pending on a queue - -- rtems_message_queue_flush_ - Flush all messages on a queue - -Background -========== - -Messages --------- - -A message is a variable length buffer where information can be stored to -support communication. The length of the message and the information stored in -that message are user-defined and can be actual data, pointer(s), or empty. - -Message Queues --------------- - -A message queue permits the passing of messages among tasks and ISRs. Message -queues can contain a variable number of messages. Normally messages are sent -to and received from the queue in FIFO order using the -``rtems_message_queue_send`` directive. However, the -``rtems_message_queue_urgent`` directive can be used to place messages at the -head of a queue in LIFO order. - -Synchronization can be accomplished when a task can wait for a message to -arrive at a queue. Also, a task may poll a queue for the arrival of a message. - -The maximum length message which can be sent is set on a per message queue -basis. The message content must be copied in general to/from an internal -buffer of the message queue or directly to a peer in certain cases. This copy -operation is performed with interrupts disabled. So it is advisable to keep -the messages as short as possible. - -.. index:: message queue attributes - -Building a Message Queue Attribute Set --------------------------------------- - -In general, an attribute set is built by a bitwise OR of the desired attribute -components. The set of valid message queue attributes is provided in the -following table: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_FIFO`` - - tasks wait by FIFO (default) - * - ``RTEMS_PRIORITY`` - - tasks wait by priority - * - ``RTEMS_LOCAL`` - - local message queue (default) - * - ``RTEMS_GLOBAL`` - - global message queue - -An attribute listed as a default is not required to appear in the attribute -list, although it is a good programming practice to specify default attributes. -If all defaults are desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should -be specified on this call. - -This example demonstrates the attribute_set parameter needed to create a local -message queue with the task priority waiting queue discipline. The -attribute_set parameter to the ``rtems_message_queue_create`` directive could -be either ``RTEMS_PRIORITY`` or ``RTEMS_LOCAL | RTEMS_PRIORITY``. The -attribute_set parameter can be set to ``RTEMS_PRIORITY`` because -``RTEMS_LOCAL`` is the default for all created message queues. If a similar -message queue were to be known globally, then the attribute_set parameter would -be ``RTEMS_GLOBAL | RTEMS_PRIORITY``. - -Building a MESSAGE_QUEUE_RECEIVE Option Set -------------------------------------------- - -In general, an option is built by a bitwise OR of the desired option -components. The set of valid options for the ``rtems_message_queue_receive`` -directive are listed in the following table: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_WAIT`` - - task will wait for a message (default) - * - ``RTEMS_NO_WAIT`` - - task should not wait - -An option listed as a default is not required to appear in the option OR list, -although it is a good programming practice to specify default options. If all -defaults are desired, the option ``RTEMS_DEFAULT_OPTIONS`` should be specified -on this call. - -This example demonstrates the option parameter needed to poll for a message to -arrive. The option parameter passed to the ``rtems_message_queue_receive`` -directive should be ``RTEMS_NO_WAIT``. - -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. - -Directives -========== - -This section details the message manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: create a message queue -.. index:: rtems_message_queue_create - -.. _rtems_message_queue_create: - -MESSAGE_QUEUE_CREATE - Create a queue -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - 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 - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - queue created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid queue name - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NUMBER`` - - invalid message count - * - ``RTEMS_INVALID_SIZE`` - - invalid message size - * - ``RTEMS_TOO_MANY`` - - too many queues created - * - ``RTEMS_UNSATISFIED`` - - unable to allocate message buffers - * - ``RTEMS_TOO_MANY`` - - too many global objects - -DESCRIPTION: - This directive creates a message queue which resides on the local node with - the user-defined name specified in name. For control and maintenance of - the queue, RTEMS allocates and initializes a QCB. Memory is allocated from - the RTEMS Workspace for the specified count of messages, each of - max_message_size bytes in length. The RTEMS-assigned queue id, returned in - id, is used to access the message queue. - - Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks waiting for a - message to be serviced according to task priority. When ``RTEMS_FIFO`` is - specified, waiting tasks are serviced in First In-First Out order. - -NOTES: - This directive may cause the calling task to be preempted due to an - obtain and release of the object allocator mutex. - - The following message queue attribute constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_FIFO`` - - tasks wait by FIFO (default) - * - ``RTEMS_PRIORITY`` - - tasks wait by priority - * - ``RTEMS_LOCAL`` - - local message queue (default) - * - ``RTEMS_GLOBAL`` - - global message queue - - Message queues should not be made global unless remote tasks must interact - with the created 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 id must be transmitted to - every node in the system for insertion in the local copy of the global - object table. - - For GLOBAL message queues, the maximum message size is effectively limited - to the longest message which the MPCI is capable of transmitting. - - The total number of global objects, including message queues, is limited by - the ``maximum_global_objects`` field in the configuration table. - -.. raw:: latex - - \clearpage - -.. index:: get ID of a message queue -.. index:: rtems_message_queue_ident - -.. _rtems_message_queue_ident: - -MESSAGE_QUEUE_IDENT - Get ID of a queue ---------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - queue identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - queue name not found - * - ``RTEMS_INVALID_NODE`` - - invalid node id - -DESCRIPTION: - This directive obtains the queue id associated with the queue name - specified in name. If the queue name is not unique, then the queue id will - match one of the queues with that name. However, this queue id is not - guaranteed to correspond to the desired queue. The queue id is used with - other message related directives to access the message queue. - -NOTES: - This directive will not cause the running task to be preempted. - - If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the - local node being searched first. All other nodes are searched with the - lowest numbered node searched first. - - 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. - -.. raw:: latex - - \clearpage - -.. index:: delete a message queue -.. index:: rtems_message_queue_delete - -.. _rtems_message_queue_delete: - -MESSAGE_QUEUE_DELETE - Delete a queue -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_delete( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - queue deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - - cannot delete remote queue - -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. If no tasks are waiting, but the queue contains - messages, then RTEMS returns these message buffers back to the system - message buffer pool. The QCB for this queue as well as the memory for the - message buffers is reclaimed by RTEMS. - -NOTES: - This directive may cause the calling task to be preempted due to an - obtain and release of the object allocator mutex. - - The calling task will be preempted if its preemption mode is enabled and - one or more local tasks with a higher priority than the calling task are - waiting on the deleted queue. The calling task will NOT be preempted if - the tasks that are waiting are remote tasks. - - The calling task does not have to be the task that created the queue, - although the task and queue must reside on the same node. - - When the queue is deleted, any messages in the queue are returned to the - free message buffer pool. Any information stored in those messages is - lost. - - When a global message queue is deleted, the message queue id must be - transmitted to every node in the system for deletion from the local copy of - the global object table. - - Proxies, used to represent remote tasks, are reclaimed when the message - queue is deleted. - -.. raw:: latex - - \clearpage - -.. index:: send message to a queue -.. index:: rtems_message_queue_send - -.. _rtems_message_queue_send: - -MESSAGE_QUEUE_SEND - Put message at rear of a queue ---------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_send( - rtems_id id, - const void *buffer, - size_t size - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message sent successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_INVALID_SIZE`` - - invalid message size - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_UNSATISFIED`` - - out of message buffers - * - ``RTEMS_TOO_MANY`` - - queue's limit has been reached - -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. - -NOTES: - The calling task will be preempted if it has preemption enabled and a - higher priority task is unblocked as the result of this directive. - - Sending a message to a global message queue which does not reside on the - local node will generate a request to the remote node to post the message - on the specified message queue. - - If the task to be unblocked resides on a different node from the message - queue, then the message is forwarded to the appropriate node, the waiting - task is unblocked, and the proxy used to represent the task is reclaimed. - -.. raw:: latex - - \clearpage - -.. index:: put message at front of queue -.. index:: rtems_message_queue_urgent - -.. _rtems_message_queue_urgent: - -MESSAGE_QUEUE_URGENT - Put message at front of a queue ------------------------------------------------------- - -**CALLING SEQUENCE:** - .. code-block:: c - - rtems_status_code rtems_message_queue_urgent( - rtems_id id, - const void *buffer, - size_t size - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message sent successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_INVALID_SIZE`` - - invalid message size - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_UNSATISFIED`` - - out of message buffers - * - ``RTEMS_TOO_MANY`` - - queue's limit has been reached - -DESCRIPTION: - This directive sends the message buffer of size bytes in length to the - queue specified by id. If a task is waiting on the queue, then the message - is copied to the task's buffer and the task is unblocked. If no tasks are - waiting on 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. - -NOTES: - The calling task will be preempted if it has preemption enabled and a - higher priority task is unblocked as the result of this directive. - - Sending a message to a global message queue which does not reside on the - local node will generate a request telling the remote node to post the - message on the specified message queue. - - If the task to be unblocked resides on a different node from the message - queue, then the message is forwarded to the appropriate node, the waiting - task is unblocked, and the proxy used to represent the task is reclaimed. - -.. raw:: latex - - \clearpage - -.. index:: broadcast message to a queue -.. index:: rtems_message_queue_broadcast - -.. _rtems_message_queue_broadcast: - -MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue ---------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_broadcast( - rtems_id id, - const void *buffer, - size_t size, - uint32_t *count - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message broadcasted successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``count`` is NULL - * - ``RTEMS_INVALID_SIZE`` - - invalid message size - -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 byes in length is copied to that - task's message buffer. The number of tasks that were unblocked is returned - in count. - -NOTES: - The calling task will be preempted if it has preemption enabled and a - higher priority task is unblocked as the result of this directive. - - 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``. - - Broadcasting a message to a global message queue which does not reside on - the local node will generate a request telling the remote node to broadcast - the message to the specified message queue. - - When a task is unblocked which resides on a different node from the message - queue, a copy of the message is forwarded to the appropriate node, the - waiting task is unblocked, and the proxy used to represent the task is - reclaimed. - -.. raw:: latex - - \clearpage - -.. index:: receive message from a queue -.. index:: rtems_message_queue_receive - -.. _rtems_message_queue_receive: - -MESSAGE_QUEUE_RECEIVE - Receive message from a queue ----------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_receive( - rtems_id id, - void *buffer, - size_t *size, - rtems_option option_set, - rtems_interval timeout - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message received successfully - * - ``RTEMS_INVALID_ID`` - - invalid queue id - * - ``RTEMS_INVALID_ADDRESS`` - - ``buffer`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``size`` is NULL - * - ``RTEMS_UNSATISFIED`` - - queue is empty - * - ``RTEMS_TIMEOUT`` - - timed out waiting for message - * - ``RTEMS_OBJECT_WAS_DELETED`` - - queue deleted while waiting - -DESCRIPTION: - This directive receives a message from the message queue specified in id. - The ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` options of the options parameter - allow the calling task to specify whether to wait for a message to become - available or return immediately. For either option, if there is at least - one message in the queue, then it is copied to buffer, size is set to - return the length of the message in bytes, and this directive returns - immediately with a successful return 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 a status code indicating this condition is returned. 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. - - A task choosing to wait at the queue can optionally specify a timeout value - in the timeout parameter. The timeout parameter specifies the maximum - interval to wait before the calling task desires to be unblocked. If it is - set to ``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. - -NOTES: - The following message receive option constants are defined by RTEMS: - - .. list-table:: - :class: rtems-table - - * - ``RTEMS_WAIT`` - - task will wait for a message (default) - * - ``RTEMS_NO_WAIT`` - - task should not wait - - Receiving a message from a global message queue which does not reside on - the local node will generate a request to the remote node to obtain a - message from the specified message queue. If no message is available and - ``RTEMS_WAIT`` was specified, then the task must be blocked until a message - is posted. A proxy is allocated on the remote node to represent the task - until the message is posted. - - A clock tick is required to support the timeout functionality of this - directive. - -.. raw:: latex - - \clearpage - -.. index:: get number of pending messages -.. index:: rtems_message_queue_get_number_pending - -.. _rtems_message_queue_get_number_pending: - -MESSAGE_QUEUE_GET_NUMBER_PENDING - Get number of messages pending on a queue ----------------------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_get_number_pending( - rtems_id id, - uint32_t *count - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - number of messages pending returned successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``count`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid queue id - -DESCRIPTION: - This directive returns the number of messages pending on this message queue - in count. If no messages are present on the queue, count is set to zero. - -NOTES: - Getting the number of pending messages on a global message queue which does - not reside on the local node will generate a request to the remote node to - actually obtain the pending message count for the specified message queue. - -.. raw:: latex - - \clearpage - -.. index:: flush messages on a queue -.. index:: rtems_message_queue_flush - -.. _rtems_message_queue_flush: - -MESSAGE_QUEUE_FLUSH - Flush all messages on a queue ---------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_message_queue_flush( - rtems_id id, - uint32_t *count - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - message queue flushed successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``count`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid queue id - -DESCRIPTION: - This directive removes all pending messages from the specified queue id. - The number of messages removed is returned in count. If no messages are - present on the queue, count is set to zero. - -NOTES: - Flushing all messages on a global message queue which does not reside on - the local node will generate a request to the remote node to actually flush - the specified message queue. -- cgit v1.2.3