From 4a4f41ed642cd5d9f4056b12d86bbf80e8da983a Mon Sep 17 00:00:00 2001
From: Sebastian Huber <sebastian.huber@embedded-brains.de>
Date: Wed, 23 Sep 2020 16:47:58 +0200
Subject: 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.
---
 cpukit/include/rtems/score/coremsgimpl.h | 67 +++++++++++++++++++++++++++++---
 1 file changed, 61 insertions(+), 6 deletions(-)

(limited to 'cpukit/include/rtems/score/coremsgimpl.h')

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
@@ -68,6 +68,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.
  *
@@ -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
 );
 
 /**
-- 
cgit v1.2.3