mirror of
https://git.rtems.org/rtems-docs/
synced 2025-05-14 23:19:35 +08:00
c-user: Split up message manager
This makes it easier to automatically generate parts of the manager documentation in the future. Update #3993.
This commit is contained in:
Sebastian Huber
parent
980734f1cd
commit
c75ded25ea
@ -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
91
c-user/message/background.rst
Normal 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``.
|
||||
@ -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
16
c-user/message/index.rst
Normal 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
28
c-user/message/introduction.rst
Normal 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
89
c-user/message/operations.rst
Normal 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.
|
||||
Loading…
x
Reference in New Issue
Block a user