From 73a0175406f734852e7ef083a9a15726e38ce678 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 24 Jun 2020 06:34:49 +0200 Subject: rtems: Generate Change license to BSD-2-Clause according to file histories and documentation re-licensing agreement. Update #3899. Update #3993. --- cpukit/include/rtems/rtems/message.h | 903 ++++++++++++++++++++++++++++------- 1 file changed, 720 insertions(+), 183 deletions(-) (limited to 'cpukit/include/rtems/rtems/message.h') diff --git a/cpukit/include/rtems/rtems/message.h b/cpukit/include/rtems/rtems/message.h index 14083b8cd0..a8ea7c1814 100644 --- a/cpukit/include/rtems/rtems/message.h +++ b/cpukit/include/rtems/rtems/message.h @@ -1,22 +1,61 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * - * @ingroup ClassicMessageQueue - * - * @brief Classic Message Queue Manager API + * @brief This header file defines the Message Manager API. + */ + +/* + * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ -/* COPYRIGHT (c) 1989-2013. - * On-Line Applications Research Corporation (OAR). +/* + * This file is part of the RTEMS quality process and was automatically + * generated. If you find something that needs to be fixed or + * worded better please post a report or patch to an RTEMS mailing list + * or raise a bug report: * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * https://www.rtems.org/bugs.html + * + * For information on updating and regenerating please refer to the How-To + * section in the Software Requirements Engineering chapter of the + * RTEMS Software Engineering manual. The manual is provided as a part of + * a release. For development sources please refer to the online + * documentation at: + * + * https://docs.rtems.org */ +/* Generated from spec:/rtems/message/if/header */ + #ifndef _RTEMS_RTEMS_MESSAGE_H #define _RTEMS_RTEMS_MESSAGE_H +#include +#include #include #include #include @@ -27,17 +66,22 @@ extern "C" { #endif +/* Generated from spec:/rtems/message/if/group */ + /** - * @defgroup ClassicMessageQueue Message Queues + * @defgroup RTEMSAPIClassicMessage Message Manager * - * @ingroup RTEMSAPIClassic + * @ingroup RTEMSAPIClassic * - * This encapsulates functionality related to the Classic API Message Queue - * Manager. + * @brief The Message Manager provides communication and synchronization + * capabilities using RTEMS message queues. */ -/**@{*/ + +/* Generated from spec:/rtems/message/if/config */ /** + * @ingroup RTEMSAPIClassicMessage + * * @brief This structure defines the configuration of a message queue * constructed by rtems_message_queue_construct(). */ @@ -90,51 +134,173 @@ typedef struct { rtems_attribute attributes; } rtems_message_queue_config; +/* Generated from spec:/rtems/message/if/create */ + /** - * @brief Defines a structure which can be used as a message queue buffer for - * messages of the specified maximum size. + * @ingroup RTEMSAPIClassicMessage * - * Use this macro to define the message buffer storage area for - * rtems_message_queue_construct(). + * @brief Creates a message queue. * - * @param _maximum_message_size is the maximum message size in bytes. + * @param name is the object name of the message queue. + * + * @param count is the maximum count of pending messages supported by the + * message queue. + * + * @param max_message_size is the maximum size in bytes of a message supported + * by the message queue. + * + * @param attribute_set is the attribute set of the message queue. + * + * @param[out] id is the pointer to an object identifier variable. When the + * directive call is successful, the identifier of the created message queue + * will be stored in this variable. + * + * This directive creates a message queue which resides on the local node. The + * message queue has the user-defined object name specified in ``name``. + * Memory is allocated from the RTEMS Workspace for the count of messages + * specified in ``count``, each of ``max_message_size`` bytes in length. The + * assigned object identifier is returned in ``id``. This identifier is used + * to access the message queue with other message queue related directives. + * + * The **attribute set** specified in ``attribute_set`` is built through a + * *bitwise or* of the attribute constants described below. Not all + * combinations of attributes are allowed. Some attributes are mutually + * exclusive. If mutually exclusive attributes are combined, the behaviour is + * undefined. Attributes not mentioned below are not evaluated by this + * directive and have no effect. Default attributes can be selected by using + * the #RTEMS_DEFAULT_ATTRIBUTES constant. The attribute set defines + * + * * the scope of the message queue: #RTEMS_LOCAL (default) or #RTEMS_GLOBAL + * and + * + * * the task wait queue discipline used by the message queue: #RTEMS_FIFO + * (default) or #RTEMS_PRIORITY. + * + * The message queue has a local or global **scope** in a multiprocessing + * network (this attribute does not refer to SMP systems). The scope is + * selected by the mutually exclusive #RTEMS_LOCAL and #RTEMS_GLOBAL + * attributes. + * + * * A **local scope** is the default and can be emphasized through the use of + * the #RTEMS_LOCAL attribute. A local message queue can be only used by the + * node which created it. + * + * * A **global scope** is established if the #RTEMS_GLOBAL attribute is set. + * Setting the global attribute in a single node system has no effect. + * + * The **task wait queue discipline** is selected by the mutually exclusive + * #RTEMS_FIFO and #RTEMS_PRIORITY attributes. The discipline defines the order + * in which tasks wait for a message to receive on a currently empty message + * queue. + * + * * The **FIFO discipline** is the default and can be emphasized through use + * of the #RTEMS_FIFO attribute. + * + * * The **priority discipline** is selected by the #RTEMS_PRIORITY attribute. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_NUMBER The ``count`` parameter was invalid. + * + * @retval ::RTEMS_INVALID_SIZE The ``max_message_size`` parameter was invalid. + * + * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a + * message queue. The number of message queue available to the application + * is configured through the #CONFIGURE_MAXIMUM_MESSAGE_QUEUES application + * configuration option. + * + * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no + * inactive global object available to create a global message queue. The + * number of global objects available to the application is configured + * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration + * option. + * + * @retval ::RTEMS_INVALID_NUMBER The product of ``count`` and + * ``max_message_size`` is greater than the maximum storage size. + * + * @retval ::RTEMS_UNSATISFIED There was not enough memory available in the + * RTEMS Workspace to allocate the message buffers for the message queue. + * + * @par Notes + * @parblock + * For message queues with a global scope, the maximum message size is + * effectively limited to the longest message which the MPCI is capable of + * transmitting. + * + * For control and maintenance of the message queue, RTEMS allocates a QCB from + * the local QCB free pool and initializes it. + * + * The QCB for a global message queue is allocated on the local node. Message + * queues should not be made global unless remote tasks must interact with the + * 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 identifier must be transmitted to every node in + * the system for insertion in the local copy of the global object table. + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * + * * When the directive operates on a global object, the directive sends a + * message to remote nodes. This may preempt the calling task. + * + * * The number of message queues available to the application is configured + * through the #CONFIGURE_MAXIMUM_MESSAGE_QUEUES application configuration + * option. + * + * * Where the object class corresponding to the directive is configured to use + * unlimited objects, the directive may allocate memory from the RTEMS + * Workspace. + * + * * The number of global objects available to the application is configured + * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration + * option. + * @endparblock */ -#define RTEMS_MESSAGE_QUEUE_BUFFER( _maximum_message_size ) \ - struct { \ - CORE_message_queue_Buffer _buffer; \ - char _message[ _maximum_message_size ]; \ - } +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 +); + +/* Generated from spec:/rtems/message/if/construct */ /** + * @ingroup RTEMSAPIClassicMessage + * * @brief Constructs a message queue from the specified the message queue * configuration. * - * In contrast to message queues created by rtems_message_queue_create(), the - * message queues constructed by this directive use a user-provided message - * buffer storage area. - * - * This directive is intended for applications which do not want to use the - * RTEMS Workspace and instead statically allocate all operating system - * resources. An application based solely on static allocation can avoid any - * runtime memory allocators. This can simplify the application architecture - * as well as any analysis that may be required. - * - * The value for #CONFIGURE_MESSAGE_BUFFER_MEMORY should not include memory for - * message queues constructed by rtems_message_queue_construct(). - * * @param config is the message queue configuration. * - * @param[out] id is the pointer to an object identifier variable. The - * identifier of the constructed message queue object will be stored in this - * variable, in case of a successful operation. + * @param[out] id is the pointer to an object identifier variable. When the + * directive call is successful, the identifier of the constructed message + * queue will be stored in this variable. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * - * @retval ::RTEMS_INVALID_ADDRESS The id parameter was NULL. + * @retval ::RTEMS_INVALID_ADDRESS The ``config`` parameter was NULL. * * @retval ::RTEMS_INVALID_NAME The message queue name in the configuration was * invalid. * + * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. + * * @retval ::RTEMS_INVALID_NUMBER The maximum number of pending messages in the * configuration was zero. * @@ -161,101 +327,248 @@ typedef struct { * @retval ::RTEMS_UNSATISFIED The message queue storage area size in the * configuration was not equal to the size calculated from the maximum number * of pending messages and the maximum message size. + * + * @par Notes + * @parblock + * In contrast to message queues created by rtems_message_queue_create(), the + * message queues constructed by this directive use a user-provided message + * buffer storage area. + * + * This directive is intended for applications which do not want to use the + * RTEMS Workspace and instead statically allocate all operating system + * resources. An application based solely on static allocation can avoid any + * runtime memory allocators. This can simplify the application architecture + * as well as any analysis that may be required. + * + * The value for #CONFIGURE_MESSAGE_BUFFER_MEMORY should not include memory for + * message queues constructed by rtems_message_queue_construct(). + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * + * * When the directive operates on a global object, the directive sends a + * message to remote nodes. This may preempt the calling task. + * + * * The number of message queues available to the application is configured + * through the #CONFIGURE_MAXIMUM_MESSAGE_QUEUES application configuration + * option. + * + * * Where the object class corresponding to the directive is configured to use + * unlimited objects, the directive may allocate memory from the RTEMS + * Workspace. + * + * * The number of global objects available to the application is configured + * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration + * option. + * @endparblock */ rtems_status_code rtems_message_queue_construct( const rtems_message_queue_config *config, rtems_id *id ); -/** - * @brief RTEMS Create Message Queue - * - * This routine implements the rtems_message_queue_create directive. The - * message queue will have the @a name. If the @a attribute_set indicates - * that the message queue is to be limited in the number of messages - * that can be outstanding, then @a count indicates the maximum number of - * messages that will be held. It returns the id of the created - * message queue in @a id. - * - * @param[in] name is the user defined queue name - * @param[in] count is the maximum message and reserved buffer count - * @param[in] max_message_size is the maximum size of each message - * @param[in] attribute_set is the process method - * @param[in] id is the pointer to queue - * - * @retval This method returns RTEMS_SUCCESSFUL if there was not an - * error. Otherwise, a status code is returned indicating the - * source of the error. If successful, the @a id will - * be filled in with the queue id. - */ -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 -); +/* Generated from spec:/rtems/message/if/ident */ /** - * @brief RTEMS Message Queue Name to Id - * - * This routine implements the rtems_message_queue_ident directive. - * This directive returns the message queue ID associated with NAME. - * If more than one message queue is named name, then the message - * queue to which the ID belongs is arbitrary. node indicates the - * extent of the search for the ID of the message queue named name. - * The search can be limited to a particular node or allowed to - * encompass all nodes. - * - * @param[in] name is the user defined message queue name - * @param[in] node is the node(s) to be searched - * @param[in] id is the pointer to message queue id - * - * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and - * *id filled with the message queue id + * @ingroup RTEMSAPIClassicMessage + * + * @brief Identifies a message queue by the object name. + * + * @param name is the object name to look up. + * + * @param node is the node or node set to search for a matching object. + * + * @param[out] id is the pointer to an object identifier variable. When the + * directive call is successful, the object identifier of an object with the + * specified name will be stored in this variable. + * + * This directive obtains a message queue identifier associated with the + * message queue name specified in ``name``. + * + * The node to search is specified in ``node``. It shall be + * + * * a valid node number, + * + * * the constant #RTEMS_SEARCH_ALL_NODES to search in all nodes, + * + * * the constant #RTEMS_SEARCH_LOCAL_NODE to search in the local node only, or + * + * * the constant #RTEMS_SEARCH_OTHER_NODES to search in all nodes except the + * local node. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was 0. + * + * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on + * the specified nodes. + * + * @retval ::RTEMS_INVALID_NODE In multiprocessing configurations, the + * specified node was invalid. + * + * @par Notes + * @parblock + * If the message queue name is not unique, then the message queue identifier + * will match the first message queue with that name in the search order. + * However, this message queue identifier is not guaranteed to correspond to + * the desired message queue. + * + * The objects are searched from lowest to the highest index. If ``node`` is + * #RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local node being + * searched first. All other nodes are searched from lowest to the highest + * node number. + * + * 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. + * + * The message queue identifier is used with other message related directives + * to access the message queue. + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ 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 ); +/* Generated from spec:/rtems/message/if/delete */ + /** - * @brief RTEMS Delete Message Queue + * @ingroup RTEMSAPIClassicMessage * - * This routine implements the rtems_message_queue_delete directive. The - * message queue indicated by ID is deleted. + * @brief Deletes the message queue. * - * @param[in] id is the queue id + * @param id is the message queue identifier. * - * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful + * 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. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no message queue associated with the + * identifier specified by ``id``. + * + * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The message queue resided on a + * remote node. + * + * @par Notes + * @parblock + * When the message queue is deleted, any messages in the queue are returned to + * the free message buffer pool. Any information stored in those messages is + * lost. The message buffers allocated for the message queue are reclaimed. + * + * The QCB for the deleted message queue is reclaimed by RTEMS. + * + * When a global message queue is deleted, the message queue identifier must be + * transmitted to every node in the system for deletion from the local copy of + * the global object table. + * + * The message queue must reside on the local node, even if the message queue + * was created with the #RTEMS_GLOBAL attribute. + * + * Proxies, used to represent remote tasks, are reclaimed when the message + * queue is deleted. + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * + * * When the directive operates on a global object, the directive sends a + * message to remote nodes. This may preempt the calling task. + * + * * The calling task does not have to be the task that created the object. + * Any local task that knows the object identifier can delete the object. + * + * * Where the object class corresponding to the directive is configured to use + * unlimited objects, the directive may free memory to the RTEMS Workspace. + * @endparblock */ -rtems_status_code rtems_message_queue_delete( - rtems_id id -); +rtems_status_code rtems_message_queue_delete( rtems_id id ); + +/* Generated from spec:/rtems/message/if/send */ /** - * @brief Sends a message to the message queue. - * - * This directive sends the message buffer to the message queue indicated by - * ID. If one or more tasks is blocked waiting to receive a message from this - * message queue, then one will receive the message. The task selected to - * receive the message is based on the task queue discipline algorithm in use - * by this particular message queue. If no tasks are waiting, then the message - * buffer will be placed at the rear of the chain of pending messages for this - * message queue. - * - * @param id The message queue ID. - * @param buffer The message content buffer. - * @param size The size of the message. - * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_INVALID_ID Invalid message queue ID. - * @retval RTEMS_INVALID_ADDRESS The message buffer pointer is @c NULL. - * @retval RTEMS_INVALID_SIZE The message size is larger than the maximum - * message size of the message queue. - * @retval RTEMS_TOO_MANY The new message would exceed the message queue limit - * for pending messages. + * @ingroup RTEMSAPIClassicMessage + * + * @brief Puts the message at the rear of the queue. + * + * @param id is the queue identifier. + * + * @param buffer is the begin address of the message buffer to send. + * + * @param size is the size in bytes of the message buffer to send. + * + * 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. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no queue associated with the identifier + * specified by ``id``. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``buffer`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_SIZE The size of the message exceeded the maximum + * message size of the queue as defined by rtems_message_queue_create() or + * rtems_message_queue_construct(). + * + * @retval ::RTEMS_TOO_MANY The maximum number of pending messages supported by + * the queue as defined by rtems_message_queue_create() or + * rtems_message_queue_construct() has been reached. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within task context. + * + * * The directive may be called from within interrupt context. + * + * * The directive may unblock another task which may preempt the calling task. + * + * * When the directive operates on a remote object, the directive sends a + * message to the remote node and waits for a reply. This will preempt the + * calling task. + * @endparblock */ rtems_status_code rtems_message_queue_send( rtems_id id, @@ -263,20 +576,55 @@ rtems_status_code rtems_message_queue_send( size_t size ); +/* Generated from spec:/rtems/message/if/urgent */ + /** - * @brief RTEMS Urgent Message Queue + * @ingroup RTEMSAPIClassicMessage + * + * @brief Puts the message at the front of the queue. + * + * @param id is the queue identifier. + * + * @param buffer is the begin address of the message buffer to send urgently. + * + * @param size is the size in bytes of the message buffer to send urgently. + * + * 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 front of the queue. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no queue associated with the identifier + * specified by ``id``. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``buffer`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_SIZE The size of the message exceeded the maximum + * message size of the queue as defined by rtems_message_queue_create() or + * rtems_message_queue_construct(). + * + * @retval ::RTEMS_TOO_MANY The maximum number of pending messages supported by + * the queue as defined by rtems_message_queue_create() or + * rtems_message_queue_construct() has been reached. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * This routine implements the rtems_message_queue_urgent directive. - * This directive has the same behavior as rtems_message_queue_send - * except that if no tasks are waiting, the message buffer will - * be placed at the FRONT of the chain of pending messages rather - * than at the REAR. + * * The directive may be called from within task context. * - * @param[in] id is the pointer to message queue - * @param[in] buffer is the pointer to message buffer - * @param[in] size is the size of message to send urgently + * * The directive may be called from within interrupt context. * - * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful + * * The directive may unblock another task which may preempt the calling task. + * + * * When the directive operates on a remote object, the directive sends a + * message to the remote node and waits for a reply. This will preempt the + * calling task. + * @endparblock */ rtems_status_code rtems_message_queue_urgent( rtems_id id, @@ -284,21 +632,61 @@ rtems_status_code rtems_message_queue_urgent( size_t size ); +/* Generated from spec:/rtems/message/if/broadcast */ + /** - * @brief RTEMS Broadcast Message Queue + * @ingroup RTEMSAPIClassicMessage + * + * @brief Broadcasts the messages to the tasks waiting at the queue. + * + * @param id is the queue identifier. + * + * @param buffer is the begin address of the message buffer to broadcast. + * + * @param size is the size in bytes of the message buffer to broadcast. + * + * @param[out] count is the pointer to an uint32_t variable. When the + * directive call is successful, the number of unblocked tasks will be stored + * in this variable. + * + * 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``. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no queue associated with the identifier + * specified by ``id``. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``buffer`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``count`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_SIZE The size of the message exceeded the maximum + * message size of the queue as defined by rtems_message_queue_create() or + * rtems_message_queue_construct(). + * + * @par Notes + * 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(). * - * This routine implements the rtems_message_queue_broadcast directive. - * This directive sends the message buffer to all of the tasks blocked - * waiting for a message on the message queue indicated by ID. - * If no tasks are waiting, then the message buffer will not be queued. + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @param[in] id is the pointer to message queue - * @param[in] buffer is the pointer to message buffer - * @param[in] size is the size of message to broadcast - * @param[in] count pointer to area to store number of threads made ready + * * The directive may be called from within task context. * - * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and - * *count filled in with number of threads made ready + * * The directive may be called from within interrupt context. + * + * * The directive may unblock another task which may preempt the calling task. + * + * * When the directive operates on a remote object, the directive sends a + * message to the remote node and waits for a reply. This will preempt the + * calling task. + * @endparblock */ rtems_status_code rtems_message_queue_broadcast( rtems_id id, @@ -307,72 +695,221 @@ rtems_status_code rtems_message_queue_broadcast( uint32_t *count ); +/* Generated from spec:/rtems/message/if/receive */ + /** - * @brief Receives a message from the message queue - * - * This directive is invoked when the calling task wishes to receive a message - * from the message queue indicated by ID. The received message is to be placed - * in the buffer. If no messages are outstanding and the option set indicates - * that the task is willing to block, then the task will be blocked until a - * message arrives or until, optionally, timeout clock ticks have passed. - * - * @param id The message queue ID. - * @param[out] buffer The buffer for the message content. The buffer must be - * large enough to store maximum size messages of this message queue. - * @param[out] size The size of the message. - * @param option_set The option set, e.g. RTEMS_NO_WAIT or RTEMS_WAIT. - * @param timeout The number of ticks to wait if the RTEMS_WAIT is set. Use - * RTEMS_NO_TIMEOUT to wait indefinitely. - * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_INVALID_ID Invalid message queue ID. - * @retval RTEMS_INVALID_ADDRESS The message buffer pointer or the message size - * pointer is @c NULL. - * @retval RTEMS_TIMEOUT A timeout occurred and no message was received. + * @ingroup RTEMSAPIClassicMessage + * + * @brief Receives a message from the queue. + * + * @param id is the queue identifier. + * + * @param buffer is the begin address of the buffer to receive the message. + * The buffer shall be large enough to receive a message of the maximum + * length of the queue as defined by rtems_message_queue_create() or + * rtems_message_queue_construct(). The ``size`` parameter cannot be used to + * specify the size of the buffer. + * + * @param size is the pointer to a size_t variable. When the directive call is + * successful, the size in bytes of the received messages will be stored in + * this variable. This parameter cannot be used to specify the size of the + * buffer. + * + * @param option_set is the option set. + * + * @param timeout is the timeout in clock ticks if the #RTEMS_WAIT option is + * set. Use #RTEMS_NO_TIMEOUT to wait potentially forever. + * + * This directive receives a message from the queue specified by ``id``. + * + * The **option set** specified in ``option_set`` is built through a *bitwise + * or* of the option constants described below. Not all combinations of + * options are allowed. Some options are mutually exclusive. If mutually + * exclusive options are combined, the behaviour is undefined. Options not + * mentioned below are not evaluated by this directive and have no effect. + * Default options can be selected by using the #RTEMS_DEFAULT_OPTIONS + * constant. + * + * The calling task can **wait** or **try to receive** a message from the queue + * according to the mutually exclusive #RTEMS_WAIT and #RTEMS_NO_WAIT options. + * + * * **Waiting to receive** a message from the queue is the default and can be + * emphasized through the use of the #RTEMS_WAIT option. The ``timeout`` + * parameter defines how long the calling task is willing to wait. Use + * #RTEMS_NO_TIMEOUT to wait potentially forever, otherwise set a timeout + * interval in clock ticks. + * + * * **Trying to receive** a message from the queue is selected by the + * #RTEMS_NO_WAIT option. If this option is defined, then the ``timeout`` + * parameter is ignored. When a message from the queue cannot be immediately + * received, then the ::RTEMS_UNSATISFIED status is returned. + * + * With either #RTEMS_WAIT or #RTEMS_NO_WAIT if there is at least one message + * in the queue, then it is copied to the buffer, the size is set to return the + * length of the message in bytes, and this directive returns immediately with + * the ::RTEMS_SUCCESSFUL status 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 the directive returns immediately with the ::RTEMS_UNSATISFIED status + * cod. 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. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no queue associated with the identifier + * specified by ``id``. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``buffer`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``size`` parameter was NULL. + * + * @retval ::RTEMS_UNSATISFIED The queue was empty. + * + * @retval ::RTEMS_UNSATISFIED The queue was flushed while the calling task was + * waiting to receive a message. + * + * @retval ::RTEMS_TIMEOUT The timeout happened while the calling task was + * waiting to receive a message + * + * @retval ::RTEMS_OBJECT_WAS_DELETED The queue was deleted while the calling + * task was waiting to receive a message. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * When a local queue is accessed and the #RTEMS_NO_WAIT option is set, the + * directive may be called from within interrupt context. + * + * * The directive may be called from within task context. + * + * * When the request cannot be immediately satisfied and the #RTEMS_WAIT + * option is set, the calling task blocks at some point during the directive + * call. + * + * * The timeout functionality of the directive requires a clock tick. + * + * * When the directive operates on a remote object, the directive sends a + * message to the remote node and waits for a reply. This will preempt the + * calling task. + * @endparblock */ 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 ); +/* Generated from spec:/rtems/message/if/get-number-pending */ + /** - * @brief rtems_message_queue_flush + * @ingroup RTEMSAPIClassicMessage + * + * @brief Gets the number of messages pending on the queue. * - * This routine implements the rtems_message_queue_flush directive. - * This directive takes all outstanding messages for the message - * queue indicated by ID and returns them to the inactive message - * chain. The number of messages flushed is returned in COUNT. + * @param id is the queue identifier. + * + * @param[out] count is the pointer to an uint32_t variable. When the + * directive call is successful, the number of pending messages will be + * stored in this variable. + * + * This directive returns the number of messages pending on the queue specified + * by ``id`` in ``count``. If no messages are present on the queue, count is + * set to zero. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * - * Message Queue Manager + * @retval ::RTEMS_INVALID_ID There was no queue associated with the identifier + * specified by ``id``. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``count`` parameter was NULL. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within task context. + * + * * The directive may be called from within interrupt context. + * + * * When the directive operates on a remote object, the directive sends a + * message to the remote node and waits for a reply. This will preempt the + * calling task. + * @endparblock */ -rtems_status_code rtems_message_queue_flush( +rtems_status_code rtems_message_queue_get_number_pending( rtems_id id, uint32_t *count ); +/* Generated from spec:/rtems/message/if/flush */ + /** - * @brief RTEMS Message Queue Get Number Pending + * @ingroup RTEMSAPIClassicMessage * - * Message Queue Manager + * @brief Flushes all messages on the queue. * - * This routine implements the rtems_message_queue_get_number_pending - * directive. This directive returns the number of pending - * messages for the message queue indicated by ID - * chain. The number of messages pending is returned in COUNT. + * @param id is the queue identifier. + * + * @param[out] count is the pointer to an uint32_t variable. When the + * directive call is successful, the number of unblocked tasks will be stored + * in this variable. + * + * This directive removes all pending messages from the queue specified by + * ``id``. The number of messages removed is returned in ``count``. If no + * messages are present on the queue, count is set to zero. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no queue associated with the identifier + * specified by ``id``. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``count`` parameter was NULL. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within task context. + * + * * The directive may be called from within interrupt context. + * + * * When the directive operates on a remote object, the directive sends a + * message to the remote node and waits for a reply. This will preempt the + * calling task. + * @endparblock */ -rtems_status_code rtems_message_queue_get_number_pending( - rtems_id id, - uint32_t *count -); +rtems_status_code rtems_message_queue_flush( rtems_id id, uint32_t *count ); -/**@}*/ +/* Generated from spec:/rtems/message/if/buffer */ + +/** + * @ingroup RTEMSAPIClassicMessage + * + * @brief Defines a structure which can be used as a message queue buffer for + * messages of the specified maximum size. + * + * @param _maximum_message_size is the maximum message size in bytes. + * + * @par Notes + * Use this macro to define the message buffer storage area for + * rtems_message_queue_construct(). + */ +#define RTEMS_MESSAGE_QUEUE_BUFFER( _maximum_message_size ) \ + struct { \ + CORE_message_queue_Buffer _buffer; \ + char _message[ _maximum_message_size ]; \ + } #ifdef __cplusplus } #endif -#endif -/* end of include file */ +#endif /* _RTEMS_RTEMS_MESSAGE_H */ -- cgit v1.2.3