/** * @file * * @ingroup ClassicMessageQueue * * @brief Classic Message Queue Manager API */ /* COPYRIGHT (c) 1989-2013. * On-Line Applications Research Corporation (OAR). * * 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. */ #ifndef _RTEMS_RTEMS_MESSAGE_H #define _RTEMS_RTEMS_MESSAGE_H #include #include #include #include #include #ifdef __cplusplus extern "C" { #endif /** * @defgroup ClassicMessageQueue Message Queues * * @ingroup RTEMSAPIClassic * * This encapsulates functionality related to the Classic API Message Queue * Manager. */ /**@{*/ /** * @brief This structure defines the configuration of a message queue * constructed by rtems_message_queue_construct(). */ typedef struct { /** * @brief This member defines the name of the message queue. */ rtems_name name; /** * @brief This member defines the maximum number of pending messages supported * by the message queue. */ uint32_t maximum_pending_messages; /** * @brief This member defines the maximum message size supported by the message * queue. */ size_t maximum_message_size; /** * @brief This member shall point to the message buffer storage area begin. * * The message buffer storage area for the message queue shall be an array of * the type defined by RTEMS_MESSAGE_QUEUE_BUFFER() with a maximum message size * equal to the maximum message size of this configuration. */ void *storage_area; /** * @brief This member defines size of the message buffer storage area in bytes. */ size_t storage_size; /** * @brief This member defines the optional handler to free the message buffer * storage area. * * It is called when the message queue is deleted. It is called from task * context under protection of the object allocator lock. It is allowed to * call free() in this handler. If handler is NULL, then no action will be * performed. */ void ( *storage_free )( void * ); /** * @brief This member defines the attributes of the message queue. */ rtems_attribute attributes; } rtems_message_queue_config; /** * @brief Defines a structure which can be used as a message queue buffer for * messages of the specified maximum size. * * Use this macro to define the message buffer storage area for * rtems_message_queue_construct(). * * @param _maximum_message_size is the maximum message size in bytes. */ #define RTEMS_MESSAGE_QUEUE_BUFFER( _maximum_message_size ) \ struct { \ CORE_message_queue_Buffer _buffer; \ char _message[ _maximum_message_size ]; \ } /** * @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. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * * @retval ::RTEMS_INVALID_ADDRESS The id parameter was NULL. * * @retval ::RTEMS_INVALID_NAME The message queue name in the configuration was * invalid. * * @retval ::RTEMS_INVALID_NUMBER The maximum number of pending messages in the * configuration was zero. * * @retval ::RTEMS_INVALID_SIZE The maximum message size in the configuration * was zero. * * @retval ::RTEMS_TOO_MANY There was no inactive message queue object * available to construct a message queue. * * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no * inactive global object available to construct a global message queue. * * @retval ::RTEMS_INVALID_SIZE The maximum message size in the configuration * was too big and resulted in integer overflows in calculations carried out * to determine the size of the message buffer area. * * @retval ::RTEMS_INVALID_NUMBER The maximum number of pending messages in the * configuration was too big and resulted in integer overflows in * calculations carried out to determine the size of the message buffer area. * * @retval ::RTEMS_UNSATISFIED The message queue storage area begin pointer in * the configuration was NULL. * * @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. */ 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 ); /** * @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 */ rtems_status_code rtems_message_queue_ident( rtems_name name, uint32_t node, rtems_id *id ); /** * @brief RTEMS Delete Message Queue * * This routine implements the rtems_message_queue_delete directive. The * message queue indicated by ID is deleted. * * @param[in] id is the queue id * * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful */ rtems_status_code rtems_message_queue_delete( rtems_id id ); /** * @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. */ rtems_status_code rtems_message_queue_send( rtems_id id, const void *buffer, size_t size ); /** * @brief RTEMS Urgent Message Queue * * 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. * * @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 * * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful */ rtems_status_code rtems_message_queue_urgent( rtems_id id, const void *buffer, size_t size ); /** * @brief RTEMS Broadcast Message Queue * * 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. * * @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 * * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and * *count filled in with number of threads made ready */ rtems_status_code rtems_message_queue_broadcast( rtems_id id, const void *buffer, size_t size, uint32_t *count ); /** * @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. */ rtems_status_code rtems_message_queue_receive( rtems_id id, void *buffer, size_t *size, rtems_option option_set, rtems_interval timeout ); /** * @brief rtems_message_queue_flush * * 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. * * Message Queue Manager */ rtems_status_code rtems_message_queue_flush( rtems_id id, uint32_t *count ); /** * @brief RTEMS Message Queue Get Number Pending * * Message Queue Manager * * 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. */ rtems_status_code rtems_message_queue_get_number_pending( rtems_id id, uint32_t *count ); /**@}*/ #ifdef __cplusplus } #endif #endif /* end of include file */