rtems: Add rtems_message_queue_construct()

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.

Add RTEMS_MESSAGE_QUEUE_BUFFER() to define a message buffer type for message
buffer storage areas.

Update #4007.

4 files changed, 219 insertions, 6 deletions

diff --git a/cpukit/include/rtems/rtems/message.h b/cpukit/include/rtems/rtems/message.h
index 675cd98acc..14083b8cd0 100644
--- a/cpukit/include/rtems/rtems/message.h
+++ b/cpukit/include/rtems/rtems/message.h
@@ -21,6 +21,7 @@
 #include <rtems/rtems/options.h>
 #include <rtems/rtems/status.h>
 #include <rtems/rtems/types.h>
+#include <rtems/score/coremsgbuffer.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -37,6 +38,136 @@ extern "C" {
 /**@{*/
 
 /**
+ * @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
diff --git a/cpukit/include/rtems/rtems/messageimpl.h b/cpukit/include/rtems/rtems/messageimpl.h
index e317244025..c90ac97da9 100644
--- a/cpukit/include/rtems/rtems/messageimpl.h
+++ b/cpukit/include/rtems/rtems/messageimpl.h
@@ -101,6 +101,23 @@ RTEMS_INLINE_ROUTINE Message_queue_Control *_Message_queue_Allocate( void )
     _Objects_Allocate( &_Message_queue_Information );
 }
 
+/**
+ * @brief Creates a message queue.
+ *
+ * @param config is the message queue configuration.
+ *
+ * @param[out] id contains the object identifier if the operation was
+ *   successful.
+ *
+ * @param allocate_buffers is the message buffer storage area allocation
+ *   handler.
+ */
+rtems_status_code _Message_queue_Create(
+  const rtems_message_queue_config    *config,
+  rtems_id                            *id,
+  CORE_message_queue_Allocate_buffers  allocate_buffers
+);
+
 /**@}*/
 
 #ifdef __cplusplus
diff --git a/cpukit/include/rtems/score/coremsg.h b/cpukit/include/rtems/score/coremsg.h
index 220c9839a5..51c638bcc3 100644
--- a/cpukit/include/rtems/score/coremsg.h
+++ b/cpukit/include/rtems/score/coremsg.h
@@ -124,6 +124,16 @@ struct CORE_message_queue_Control {
    *  as part of destroying it.
    */
   CORE_message_queue_Buffer         *message_buffers;
+
+  /**
+   * @brief This member contains the optional message buffer storage area free
+   * handler.
+   *
+   * It may be NULL.  In this case no action is performed to free the message
+   * buffer storage area.
+   */
+  void                            ( *free_message_buffers )( void * );
+
   #if defined(RTEMS_SCORE_COREMSG_ENABLE_NOTIFICATION)
     /** This is the routine invoked when the message queue transitions
      *  from zero (0) messages pending to one (1) message pending.
diff --git a/cpukit/include/rtems/score/coremsgimpl.h b/cpukit/include/rtems/score/coremsgimpl.h
index cb84bfb207..0bf5fa52d0 100644
--- a/cpukit/include/rtems/score/coremsgimpl.h
+++ b/cpukit/include/rtems/score/coremsgimpl.h
@@ -69,6 +69,54 @@ extern "C" {
 typedef int CORE_message_queue_Submit_types;
 
 /**
+ * @brief This handler shall allocate the message buffer storage area for a
+ *   message queue.
+ *
+ * The handler shall set the CORE_message_queue_Control::free_message_buffers
+ * member.
+ *
+ * @param[out] the_message_queue is the message queue control.
+ *
+ * @param size is the message buffer storage area size to allocate.
+ *
+ * @param arg is the handler argument.
+ *
+ * @retval NULL The allocation failed.
+ *
+ * @return Otherwise the pointer to the allocated message buffer storage area
+ *   begin shall be returned.
+ */
+typedef void *( *CORE_message_queue_Allocate_buffers )(
+  CORE_message_queue_Control *the_message_queue,
+  size_t                      size,
+  const void                 *arg
+);
+
+/**
+ * @brief This handler allocates the message buffer storage area for a message
+ *   queue from the RTEMS Workspace.
+ *
+ * The handler sets the CORE_message_queue_Control::free_message_buffers
+ * to _Workspace_Free().
+ *
+ * @param[out] the_message_queue is the message queue control.
+ *
+ * @param size is the message buffer storage area size to allocate.
+ *
+ * @param arg is the unused handler argument.
+ *
+ * @retval NULL The allocation failed.
+ *
+ * @return Otherwise the pointer to the allocated message buffer storage area
+ *   begin is returned.
+ */
+void *_CORE_message_queue_Workspace_allocate(
+  CORE_message_queue_Control *the_message_queue,
+  size_t                      size,
+  const void                 *arg
+);
+
+/**
  * @brief Initializes a message queue.
  *
  * @param[out] the_message_queue is the message queue to initialize.
@@ -81,19 +129,26 @@ typedef int CORE_message_queue_Submit_types;
  * @param maximum_message_size is the size of the largest message that may be
  *   sent to this message queue instance.
  *
+ * @param allocate_buffers is the message buffer storage area allocation
+ *   handler.
+ *
+ * @param arg is the message buffer storage area allocation handler argument.
+ *
  * @retval STATUS_SUCCESSFUL The message queue was initialized.
  *
  * @retval STATUS_MESSAGE_QUEUE_INVALID_SIZE Calculations with the maximum
  *   pending messages or maximum message size produced an integer overflow.
  *
- * @retval STATUS_MESSAGE_QUEUE_NO_MEMORY There was not enough memory to
- *   allocate the message buffers.
+ * @retval STATUS_MESSAGE_QUEUE_NO_MEMORY The message buffer storage area
+ *   allocation failed.
  */
 Status_Control _CORE_message_queue_Initialize(
-  CORE_message_queue_Control     *the_message_queue,
-  CORE_message_queue_Disciplines  discipline,
-  uint32_t                        maximum_pending_messages,
-  size_t                          maximum_message_size
+  CORE_message_queue_Control          *the_message_queue,
+  CORE_message_queue_Disciplines       discipline,
+  uint32_t                             maximum_pending_messages,
+  size_t                               maximum_message_size,
+  CORE_message_queue_Allocate_buffers  allocate_buffers,
+  const void                          *arg
 );
 
 /**