diff options
Diffstat (limited to 'c_user/message_manager.rst')
| -rw-r--r-- | c_user/message_manager.rst | 851 |
1 files changed, 450 insertions, 401 deletions
diff --git a/c_user/message_manager.rst b/c_user/message_manager.rst index 57401bc..80baf65 100644 --- a/c_user/message_manager.rst +++ b/c_user/message_manager.rst @@ -1,3 +1,7 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Message Manager ############### @@ -7,27 +11,27 @@ Message Manager Introduction ============ -The message manager provides communication and -synchronization capabilities using RTEMS message queues. The -directives provided by the message manager are: +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_create_ - Create a queue -- ``rtems_message_queue_ident`` - Get ID of a queue +- rtems_message_queue_ident_ - Get ID of a queue -- ``rtems_message_queue_delete`` - Delete a queue +- rtems_message_queue_delete_ - Delete a queue -- ``rtems_message_queue_send`` - Put message at rear of 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_urgent_ - Put message at front of a queue -- ``rtems_message_queue_broadcast`` - Broadcast N messages to a queue +- rtems_message_queue_broadcast_ - Broadcast N messages to a queue -- ``rtems_message_queue_receive`` - Receive message from 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_get_number_pending_ - Get number of messages pending on a queue -- ``rtems_message_queue_flush`` - Flush all messages on a queue +- rtems_message_queue_flush_ - Flush all messages on a queue Background ========== @@ -35,83 +39,86 @@ 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. +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. +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. +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. +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. Building a Message Queue Attribute Set -------------------------------------- .. index:: message queue attributes -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: - -- ``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. +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``. +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: +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: -- ``RTEMS_WAIT`` - task will wait for a message (default) +.. list-table:: + :class: rtems-table -- ``RTEMS_NO_WAIT`` - task should not wait + * - ``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. +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``. +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 ========== @@ -119,105 +126,94 @@ 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. +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. +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: +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. +- 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 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. +- 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. +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. +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. +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. +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. +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 ========== -This section details the message manager's -directives. A subsection is dedicated to each of this manager's -directives and describes the calling sequence, related -constants, usage, and status codes. +This section details the message manager's directives. A subsection is +dedicated to each of this manager's directives and describes the calling +sequence, related constants, usage, and status codes. + +.. _rtems_message_queue_create: MESSAGE_QUEUE_CREATE - Create a queue ------------------------------------- @@ -230,71 +226,81 @@ MESSAGE_QUEUE_CREATE - Create a queue .. code:: c rtems_status_code rtems_message_queue_create( - rtems_name name, - uint32_t count, - size_t max_message_size, - rtems_attribute attribute_set, - rtems_id \*id + rtems_name name, + uint32_t count, + size_t max_message_size, + rtems_attribute attribute_set, + rtems_id *id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - queue created successfully -``RTEMS_INVALID_NAME`` - invalid queue name -``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL -``RTEMS_INVALID_NUMBER`` - invalid message count -``RTEMS_INVALID_SIZE`` - invalid message size -``RTEMS_TOO_MANY`` - too many queues created -``RTEMS_UNSATISFIED`` - unable to allocate message buffers -``RTEMS_MP_NOT_CONFIGURED`` - multiprocessing not configured -``RTEMS_TOO_MANY`` - too many global objects +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - queue created successfully + * - ``RTEMS_INVALID_NAME`` + - invalid queue name + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NUMBER`` + - invalid message count + * - ``RTEMS_INVALID_SIZE`` + - invalid message size + * - ``RTEMS_TOO_MANY`` + - too many queues created + * - ``RTEMS_UNSATISFIED`` + - unable to allocate message buffers + * - ``RTEMS_MP_NOT_CONFIGURED`` + - multiprocessing not configured + * - ``RTEMS_TOO_MANY`` + - too many global objects **DESCRIPTION:** -This directive creates a message queue which resides -on the local node with the user-defined name specified in name. -For control and maintenance of the queue, RTEMS allocates and -initializes a QCB. Memory is allocated from the RTEMS Workspace -for the specified count of messages, each of max_message_size -bytes in length. The RTEMS-assigned queue id, returned in id, -is used to access the message queue. +This directive creates a message queue which resides on the local node with the +user-defined name specified in name. For control and maintenance of the queue, +RTEMS allocates and initializes a QCB. Memory is allocated from the RTEMS +Workspace for the specified count of messages, each of max_message_size bytes +in length. The RTEMS-assigned queue id, returned in id, is used to access the +message queue. -Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks -waiting for a message to be serviced according to task priority. -When ``RTEMS_FIFO`` is specified, waiting tasks are serviced -in First In-First Out order. +Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks waiting for a +message to be serviced according to task priority. When ``RTEMS_FIFO`` is +specified, waiting tasks are serviced in First In-First Out order. **NOTES:** -This directive will not cause the calling task to be -preempted. +This directive will not cause the calling task to be preempted. -The following message queue attribute constants are -defined by RTEMS: +The following message queue attribute constants are defined by RTEMS: -- ``RTEMS_FIFO`` - tasks wait by FIFO (default) +.. list-table:: + :class: rtems-table -- ``RTEMS_PRIORITY`` - tasks wait by priority + * - ``RTEMS_FIFO`` + - tasks wait by FIFO (default) + * - ``RTEMS_PRIORITY`` + - tasks wait by priority + * - ``RTEMS_LOCAL`` + - local message queue (default) + * - ``RTEMS_GLOBAL`` + - global message queue -- ``RTEMS_LOCAL`` - local message queue (default) +Message queues should not be made global unless remote tasks must interact with +the created message queue. This is to avoid the system overhead incurred by +the creation of a global message queue. When a global message queue is +created, the message queue's name and id must be transmitted to every node in +the system for insertion in the local copy of the global object table. -- ``RTEMS_GLOBAL`` - global message queue +For GLOBAL message queues, the maximum message size is effectively limited to +the longest message which the MPCI is capable of transmitting. -Message queues should not be made global unless -remote tasks must interact with the created message queue. This -is to avoid the system overhead incurred by the creation of a -global message queue. When a global message queue is created, -the message queue's name and id must be transmitted to every -node in the system for insertion in the local copy of the global -object table. +The total number of global objects, including message queues, is limited by the +``maximum_global_objects`` field in the configuration table. -For GLOBAL message queues, the maximum message size -is effectively limited to the longest message which the MPCI is -capable of transmitting. - -The total number of global objects, including message -queues, is limited by the maximum_global_objects field in the -configuration table. +.. _rtems_message_queue_ident: MESSAGE_QUEUE_IDENT - Get ID of a queue --------------------------------------- @@ -307,43 +313,48 @@ MESSAGE_QUEUE_IDENT - Get ID of a queue .. code:: c rtems_status_code rtems_message_queue_ident( - rtems_name name, - uint32_t node, - rtems_id \*id + rtems_name name, + uint32_t node, + rtems_id *id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - queue identified successfully -``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL -``RTEMS_INVALID_NAME`` - queue name not found -``RTEMS_INVALID_NODE`` - invalid node id +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - queue identified successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NAME`` + - queue name not found + * - ``RTEMS_INVALID_NODE`` + - invalid node id **DESCRIPTION:** -This directive obtains the queue id associated with -the queue name specified in name. If the queue name is not -unique, then the queue id will match one of the queues with that -name. However, this queue id is not guaranteed to correspond to -the desired queue. The queue id is used with other message -related directives to access the message queue. +This directive obtains the queue id associated with the queue name specified in +name. If the queue name is not unique, then the queue id will match one of the +queues with that name. However, this queue id is not guaranteed to correspond +to the desired queue. The queue id is used with other message related +directives to access the message queue. **NOTES:** -This directive will not cause the running task to be -preempted. +This directive will not cause the running task to be preempted. -If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched -with the local node being searched first. All other nodes are -searched with the lowest numbered node searched first. +If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the local +node being searched first. All other nodes are searched with the lowest +numbered node searched first. -If node is a valid node number which does not -represent the local node, then only the message queues exported -by the designated node are searched. +If node is a valid node number which does not represent the local node, then +only the message queues exported by the designated node are searched. -This directive does not generate activity on remote -nodes. It accesses only the local copy of the global object -table. +This directive does not generate activity on remote nodes. It accesses only +the local copy of the global object table. + +.. _rtems_message_queue_delete: MESSAGE_QUEUE_DELETE - Delete a queue ------------------------------------- @@ -356,48 +367,52 @@ MESSAGE_QUEUE_DELETE - Delete a queue .. code:: c rtems_status_code rtems_message_queue_delete( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - queue deleted successfully -``RTEMS_INVALID_ID`` - invalid queue id -``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - cannot delete remote queue +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - queue deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid queue id + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - cannot delete remote queue **DESCRIPTION:** -This directive deletes the message queue specified by -id. As a result of this directive, all tasks blocked waiting to -receive a message from this queue will be readied and returned a -status code which indicates that the message queue was deleted. -If no tasks are waiting, but the queue contains messages, then -RTEMS returns these message buffers back to the system message -buffer pool. The QCB for this queue as well as the memory for -the message buffers is reclaimed by RTEMS. +This directive deletes the message queue specified by ``id``. As a result of +this directive, all tasks blocked waiting to receive a message from this queue +will be readied and returned a status code which indicates that the message +queue was deleted. If no tasks are waiting, but the queue contains messages, +then RTEMS returns these message buffers back to the system message buffer +pool. The QCB for this queue as well as the memory for the message buffers is +reclaimed by RTEMS. **NOTES:** -The calling task will be preempted if its preemption -mode is enabled and one or more local tasks with a higher -priority than the calling task are waiting on the deleted queue. -The calling task will NOT be preempted if the tasks that are -waiting are remote tasks. +The calling task will be preempted if its preemption mode is enabled and one or +more local tasks with a higher priority than the calling task are waiting on +the deleted queue. The calling task will NOT be preempted if the tasks that +are waiting are remote tasks. -The calling task does not have to be the task that -created the queue, although the task and queue must reside on -the same node. +The calling task does not have to be the task that created the queue, although +the task and queue must reside on the same node. -When the queue is deleted, any messages in the queue -are returned to the free message buffer pool. Any information -stored in those messages is lost. +When the queue is deleted, any messages in the queue are returned to the free +message buffer pool. Any information stored in those messages is lost. -When a global message queue is deleted, the message -queue id must be transmitted to every node in the system for -deletion from the local copy of the global object table. +When a global message queue is deleted, the message queue id must be +transmitted to every node in the system for deletion from the local copy of the +global object table. -Proxies, used to represent remote tasks, are -reclaimed when the message queue is deleted. +Proxies, used to represent remote tasks, are reclaimed when the message queue +is deleted. + +.. _rtems_message_queue_send: MESSAGE_QUEUE_SEND - Put message at rear of a queue --------------------------------------------------- @@ -410,44 +425,52 @@ MESSAGE_QUEUE_SEND - Put message at rear of a queue .. code:: c rtems_status_code rtems_message_queue_send( - rtems_id id, - cons void \*buffer, - size_t size + rtems_id id, + cons void *buffer, + size_t size ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - message sent successfully -``RTEMS_INVALID_ID`` - invalid queue id -``RTEMS_INVALID_SIZE`` - invalid message size -``RTEMS_INVALID_ADDRESS`` - ``buffer`` is NULL -``RTEMS_UNSATISFIED`` - out of message buffers -``RTEMS_TOO_MANY`` - queue's limit has been reached +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - message sent successfully + * - ``RTEMS_INVALID_ID`` + - invalid queue id + * - ``RTEMS_INVALID_SIZE`` + - invalid message size + * - ``RTEMS_INVALID_ADDRESS`` + - ``buffer`` is NULL + * - ``RTEMS_UNSATISFIED`` + - out of message buffers + * - ``RTEMS_TOO_MANY`` + - queue's limit has been reached **DESCRIPTION:** -This directive sends the message buffer of size bytes -in length to the queue specified by id. If a task is waiting at -the queue, then the message is copied to the waiting task's -buffer and the task is unblocked. If no tasks are waiting at the -queue, then the message is copied to a message buffer which is -obtained from this message queue's message buffer pool. The -message buffer is then placed at the rear of the queue. +This directive sends the message buffer of size bytes in length to the queue +specified by id. If a task is waiting at the queue, then the message is copied +to the waiting task's buffer and the task is unblocked. If no tasks are waiting +at the queue, then the message is copied to a message buffer which is obtained +from this message queue's message buffer pool. The message buffer is then +placed at the rear of the queue. **NOTES:** -The calling task will be preempted if it has -preemption enabled and a higher priority task is unblocked as -the result of this directive. +The calling task will be preempted if it has preemption enabled and a higher +priority task is unblocked as the result of this directive. -Sending a message to a global message queue which -does not reside on the local node will generate a request to the -remote node to post the message on the specified message queue. +Sending a message to a global message queue which does not reside on the local +node will generate a request to the remote node to post the message on the +specified message queue. -If the task to be unblocked resides on a different -node from the message queue, then the message is forwarded to -the appropriate node, the waiting task is unblocked, and the -proxy used to represent the task is reclaimed. +If the task to be unblocked resides on a different node from the message queue, +then the message is forwarded to the appropriate node, the waiting task is +unblocked, and the proxy used to represent the task is reclaimed. + +.. _rtems_message_queue_urgent: MESSAGE_QUEUE_URGENT - Put message at front of a queue ------------------------------------------------------ @@ -460,45 +483,52 @@ MESSAGE_QUEUE_URGENT - Put message at front of a queue .. code:: c rtems_status_code rtems_message_queue_urgent( - rtems_id id, - const void \*buffer, - size_t size + rtems_id id, + const void *buffer, + size_t size ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - message sent successfully -``RTEMS_INVALID_ID`` - invalid queue id -``RTEMS_INVALID_SIZE`` - invalid message size -``RTEMS_INVALID_ADDRESS`` - ``buffer`` is NULL -``RTEMS_UNSATISFIED`` - out of message buffers -``RTEMS_TOO_MANY`` - queue's limit has been reached +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - message sent successfully + * - ``RTEMS_INVALID_ID`` + - invalid queue id + * - ``RTEMS_INVALID_SIZE`` + - invalid message size + * - ``RTEMS_INVALID_ADDRESS`` + - ``buffer`` is NULL + * - ``RTEMS_UNSATISFIED`` + - out of message buffers + * - ``RTEMS_TOO_MANY`` + - queue's limit has been reached **DESCRIPTION:** -This directive sends the message buffer of size bytes -in length to the queue specified by id. If a task is waiting on -the queue, then the message is copied to the task's buffer and -the task is unblocked. If no tasks are waiting on the queue, -then the message is copied to a message buffer which is obtained -from this message queue's message buffer pool. The message -buffer is then placed at the front of the queue. +This directive sends the message buffer of size bytes in length to the queue +specified by id. If a task is waiting on the queue, then the message is copied +to the task's buffer and the task is unblocked. If no tasks are waiting on the +queue, then the message is copied to a message buffer which is obtained from +this message queue's message buffer pool. The message buffer is then placed at +the front of the queue. **NOTES:** -The calling task will be preempted if it has -preemption enabled and a higher priority task is unblocked as -the result of this directive. +The calling task will be preempted if it has preemption enabled and a higher +priority task is unblocked as the result of this directive. -Sending a message to a global message queue which -does not reside on the local node will generate a request -telling the remote node to post the message on the specified -message queue. +Sending a message to a global message queue which does not reside on the local +node will generate a request telling the remote node to post the message on the +specified message queue. -If the task to be unblocked resides on a different -node from the message queue, then the message is forwarded to -the appropriate node, the waiting task is unblocked, and the -proxy used to represent the task is reclaimed. +If the task to be unblocked resides on a different node from the message queue, +then the message is forwarded to the appropriate node, the waiting task is +unblocked, and the proxy used to represent the task is reclaimed. + +.. _rtems_message_queue_broadcast: MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue --------------------------------------------------------- @@ -511,49 +541,53 @@ MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue .. code:: c rtems_status_code rtems_message_queue_broadcast( - rtems_id id, - const void \*buffer, - size_t size, - uint32_t \*count + rtems_id id, + const void *buffer, + size_t size, + uint32_t *count ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - message broadcasted successfully -``RTEMS_INVALID_ID`` - invalid queue id -``RTEMS_INVALID_ADDRESS`` - ``buffer`` is NULL -``RTEMS_INVALID_ADDRESS`` - ``count`` is NULL -``RTEMS_INVALID_SIZE`` - invalid message size +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - message broadcasted successfully + * - ``RTEMS_INVALID_ID`` + - invalid queue id + * - ``RTEMS_INVALID_ADDRESS`` + - ``buffer`` is NULL + * - ``RTEMS_INVALID_ADDRESS`` + - ``count`` is NULL + * - ``RTEMS_INVALID_SIZE`` + - invalid message size **DESCRIPTION:** -This directive causes all tasks that are waiting at -the queue specified by id to be unblocked and sent the message -contained in buffer. Before a task is unblocked, the message -buffer of size byes in length is copied to that task's message -buffer. The number of tasks that were unblocked is returned in -count. +This directive causes all tasks that are waiting at the queue specified by id +to be unblocked and sent the message contained in buffer. Before a task is +unblocked, the message buffer of size byes in length is copied to that task's +message buffer. The number of tasks that were unblocked is returned in count. **NOTES:** -The calling task will be preempted if it has -preemption enabled and a higher priority task is unblocked as -the result of this directive. +The calling task will be preempted if it has preemption enabled and a higher +priority task is unblocked as the result of this directive. -The execution time of this directive is directly -related to the number of tasks waiting on the message queue, -although it is more efficient than the equivalent number of -invocations of ``rtems_message_queue_send``. +The execution time of this directive is directly related to the number of tasks +waiting on the message queue, although it is more efficient than the equivalent +number of invocations of ``rtems_message_queue_send``. -Broadcasting a message to a global message queue -which does not reside on the local node will generate a request -telling the remote node to broadcast the message to the -specified message queue. +Broadcasting a message to a global message queue which does not reside on the +local node will generate a request telling the remote node to broadcast the +message to the specified message queue. + +When a task is unblocked which resides on a different node from the message +queue, a copy of the message is forwarded to the appropriate node, the waiting +task is unblocked, and the proxy used to represent the task is reclaimed. -When a task is unblocked which resides on a different -node from the message queue, a copy of the message is forwarded -to the appropriate node, the waiting task is unblocked, and the -proxy used to represent the task is reclaimed. +.. _rtems_message_queue_receive: MESSAGE_QUEUE_RECEIVE - Receive message from a queue ---------------------------------------------------- @@ -566,69 +600,80 @@ MESSAGE_QUEUE_RECEIVE - Receive message from a queue .. code:: c rtems_status_code rtems_message_queue_receive( - rtems_id id, - void \*buffer, - size_t \*size, - rtems_option option_set, - rtems_interval timeout + rtems_id id, + void *buffer, + size_t *size, + rtems_option option_set, + rtems_interval timeout ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - message received successfully -``RTEMS_INVALID_ID`` - invalid queue id -``RTEMS_INVALID_ADDRESS`` - ``buffer`` is NULL -``RTEMS_INVALID_ADDRESS`` - ``size`` is NULL -``RTEMS_UNSATISFIED`` - queue is empty -``RTEMS_TIMEOUT`` - timed out waiting for message -``RTEMS_OBJECT_WAS_DELETED`` - queue deleted while waiting +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - message received successfully + * - ``RTEMS_INVALID_ID`` + - invalid queue id + * - ``RTEMS_INVALID_ADDRESS`` + - ``buffer`` is NULL + * - ``RTEMS_INVALID_ADDRESS`` + - ``size`` is NULL + * - ``RTEMS_UNSATISFIED`` + - queue is empty + * - ``RTEMS_TIMEOUT`` + - timed out waiting for message + * - ``RTEMS_OBJECT_WAS_DELETED`` + - queue deleted while waiting **DESCRIPTION:** -This directive receives a message from the message -queue specified in id. The ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` options of the -options parameter allow the calling task to specify whether to -wait for a message to become available or return immediately. -For either option, if there is at least one message in the -queue, then it is copied to buffer, size is set to return the -length of the message in bytes, and this directive returns -immediately with a successful return code. The buffer has to be big enough to -receive a message of the maximum length with respect to this message queue. - -If the calling task chooses to return immediately and -the queue is empty, then a status code indicating this condition -is returned. If the calling task chooses to wait at the message -queue and the queue is empty, then the calling task is placed on -the message wait queue and blocked. If the queue was created -with the ``RTEMS_PRIORITY`` option specified, then -the calling task is inserted into the wait queue according to -its priority. But, if the queue was created with the``RTEMS_FIFO`` option specified, then the -calling task is placed at the rear of the wait queue. - -A task choosing to wait at the queue can optionally -specify a timeout value in the timeout parameter. The timeout -parameter specifies the maximum interval to wait before the -calling task desires to be unblocked. If it is set to``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. +This directive receives a message from the message queue specified in id. The +``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` options of the options parameter allow the +calling task to specify whether to wait for a message to become available or +return immediately. For either option, if there is at least one message in the +queue, then it is copied to buffer, size is set to return the length of the +message in bytes, and this directive returns immediately with a successful +return code. The buffer has to be big enough to receive a message of the +maximum length with respect to this message queue. + +If the calling task chooses to return immediately and the queue is empty, then +a status code indicating this condition is returned. If the calling task +chooses to wait at the message queue and the queue is empty, then the calling +task is placed on the message wait queue and blocked. If the queue was created +with the ``RTEMS_PRIORITY`` option specified, then the calling task is inserted +into the wait queue according to its priority. But, if the queue was created +with the ``RTEMS_FIFO`` option specified, then the calling task is placed at +the rear of the wait queue. + +A task choosing to wait at the queue can optionally specify a timeout value in +the timeout parameter. The timeout parameter specifies the maximum interval to +wait before the calling task desires to be unblocked. If it is set to +``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. **NOTES:** -The following message receive option constants are -defined by RTEMS: +The following message receive option constants are defined by RTEMS: -- ``RTEMS_WAIT`` - task will wait for a message (default) +.. list-table:: + :class: rtems-table -- ``RTEMS_NO_WAIT`` - task should not wait + * - ``RTEMS_WAIT`` + - task will wait for a message (default) + * - ``RTEMS_NO_WAIT`` + - task should not wait -Receiving a message from a global message queue which -does not reside on the local node will generate a request to the -remote node to obtain a message from the specified message -queue. If no message is available and ``RTEMS_WAIT`` was specified, then -the task must be blocked until a message is posted. A proxy is -allocated on the remote node to represent the task until the -message is posted. +Receiving a message from a global message queue which does not reside on the +local node will generate a request to the remote node to obtain a message from +the specified message queue. If no message is available and ``RTEMS_WAIT`` was +specified, then the task must be blocked until a message is posted. A proxy is +allocated on the remote node to represent the task until the message is posted. -A clock tick is required to support the timeout functionality of -this directive. +A clock tick is required to support the timeout functionality of this +directive. + +.. _rtems_message_queue_get_number_pending: MESSAGE_QUEUE_GET_NUMBER_PENDING - Get number of messages pending on a queue ---------------------------------------------------------------------------- @@ -641,28 +686,34 @@ MESSAGE_QUEUE_GET_NUMBER_PENDING - Get number of messages pending on a queue .. code:: c rtems_status_code rtems_message_queue_get_number_pending( - rtems_id id, - uint32_t \*count + rtems_id id, + uint32_t *count ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - number of messages pending returned successfully -``RTEMS_INVALID_ADDRESS`` - ``count`` is NULL -``RTEMS_INVALID_ID`` - invalid queue id +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - number of messages pending returned successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``count`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid queue id **DESCRIPTION:** -This directive returns the number of messages pending on this -message queue in count. If no messages are present -on the queue, count is set to zero. +This directive returns the number of messages pending on this message queue in +count. If no messages are present on the queue, count is set to zero. **NOTES:** -Getting the number of pending messages on a global message queue which -does not reside on the local node will generate a request to the -remote node to actually obtain the pending message count for -the specified message queue. +Getting the number of pending messages on a global message queue which does not +reside on the local node will generate a request to the remote node to actually +obtain the pending message count for the specified message queue. + +.. _rtems_message_queue_flush: MESSAGE_QUEUE_FLUSH - Flush all messages on a queue --------------------------------------------------- @@ -675,32 +726,30 @@ MESSAGE_QUEUE_FLUSH - Flush all messages on a queue .. code:: c rtems_status_code rtems_message_queue_flush( - rtems_id id, - uint32_t \*count + rtems_id id, + uint32_t *count ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - message queue flushed successfully -``RTEMS_INVALID_ADDRESS`` - ``count`` is NULL -``RTEMS_INVALID_ID`` - invalid queue id +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - message queue flushed successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``count`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid queue id **DESCRIPTION:** -This directive removes all pending messages from the -specified queue id. The number of messages removed is returned -in count. If no messages are present on the queue, count is set -to zero. +This directive removes all pending messages from the specified queue id. The +number of messages removed is returned in count. If no messages are present on +the queue, count is set to zero. **NOTES:** -Flushing all messages on a global message queue which -does not reside on the local node will generate a request to the -remote node to actually flush the specified message queue. - -.. COMMENT: COPYRIGHT (c) 1988-2002. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - +Flushing all messages on a global message queue which does not reside on the +local node will generate a request to the remote node to actually flush the +specified message queue. |