diff options
Diffstat (limited to 'c-user/message/background.rst')
-rw-r--r-- | c-user/message/background.rst | 91 |
1 files changed, 91 insertions, 0 deletions
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``. |