rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-14 23:09:16 +08:00
Code Issues Packages Projects Releases Wiki Activity

c-user: Split up message manager

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

Update #3993.
This commit is contained in:
Sebastian Huber 2020-08-20 09:55:50 +02:00
parent 980734f1cd
commit c75ded25ea
6 changed files with 225 additions and 206 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
c-user/index.rst
View File

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

91
c-user/message/background.rst Normal file
View File

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

205
c-user/message_manager.rst → c-user/message/directives.rst
View File

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

16
c-user/message/index.rst Normal file
View File

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

28
c-user/message/introduction.rst Normal file
View File

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

89
c-user/message/operations.rst Normal file
View File

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