[PATCH v2 08/16] c-user: Split up message manager
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Sep 2 16:01:02 UTC 2020
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 ++++++++
.../directives.rst} | 205 ------------------
c-user/message/index.rst | 16 ++
c-user/message/introduction.rst | 28 +++
c-user/message/operations.rst | 89 ++++++++
6 files changed, 225 insertions(+), 206 deletions(-)
create mode 100644 c-user/message/background.rst
rename c-user/{message_manager.rst => message/directives.rst} (69%)
create mode 100644 c-user/message/index.rst
create mode 100644 c-user/message/introduction.rst
create mode 100644 c-user/message/operations.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_manager.rst b/c-user/message/directives.rst
similarity index 69%
rename from c-user/message_manager.rst
rename to 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
==========
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.
--
2.26.2
More information about the devel
mailing list