diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-09-23 16:47:58 +0200 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-09-28 07:16:01 +0200 |
commit | 4a4f41ed642cd5d9f4056b12d86bbf80e8da983a (patch) | |
tree | 40a7ff0913194c8aa9603dd47625816ae332ce01 /cpukit/include/rtems | |
parent | rtems: Remove Message_queue_Control::attribute_set (diff) | |
download | rtems-4a4f41ed642cd5d9f4056b12d86bbf80e8da983a.tar.bz2 |
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.
Diffstat (limited to '')
-rw-r--r-- | cpukit/include/rtems/rtems/message.h | 131 | ||||
-rw-r--r-- | cpukit/include/rtems/rtems/messageimpl.h | 17 | ||||
-rw-r--r-- | cpukit/include/rtems/score/coremsg.h | 10 | ||||
-rw-r--r-- | cpukit/include/rtems/score/coremsgimpl.h | 67 |
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 ); /** |