path: root/cpukit/include/rtems/rtems/message.h

/**
 * @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 <rtems/rtems/attr.h>
#include <rtems/rtems/options.h>
#include <rtems/rtems/status.h>
#include <rtems/rtems/types.h>
#include <rtems/score/coremsgbuffer.h>

#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 */