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

@@ -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

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``.

c-user/message/directives.rst

@@ -2,211 +2,6 @@
 
 .. 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
 ==========
 

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

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`

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.