c-user: Split up message manager

This makes it easier to automatically generate parts of the manager
documentation in the future.

Update #3993.

1 files changed, 0 insertions, 205 deletions

diff --git a/c-user/message_manager.rst b/c-user/message/directives.rst
index 8115609..4d9bdc7 100644
--- a/c-user/message_manager.rst
+++ b/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
 ==========