From 03a735f89611d7fc031190b0e460f062a25a42d4 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Thu, 12 Mar 2020 13:40:45 +0100 Subject: c-user: Clarify message buffer configuration The help macro CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE() is not a configuration option. Move it into the documentatation of the CONFIGURE_MESSAGE_BUFFER_MEMORY configuration option. Move this option to the general system configuration group. Update #3836. --- c-user/config/general.rst | 73 ++++++++++++++++++++++++++++++ c-user/config/index.rst | 1 - c-user/config/msg-queue-buffer.rst | 93 -------------------------------------- 3 files changed, 73 insertions(+), 94 deletions(-) delete mode 100644 c-user/config/msg-queue-buffer.rst diff --git a/c-user/config/general.rst b/c-user/config/general.rst index f6d7531..f5f44d3 100644 --- a/c-user/config/general.rst +++ b/c-user/config/general.rst @@ -324,6 +324,79 @@ NOTES: Typically the memory allocation will be too low when an application does not account for all message queue buffers or task stacks. +.. index:: CONFIGURE_MESSAGE_BUFFER_MEMORY +.. index:: configure message queue buffer memory +.. index:: CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE +.. index:: memory for a single message queue's buffers + +.. _CONFIGURE_MESSAGE_BUFFER_MEMORY: + +CONFIGURE_MESSAGE_BUFFER_MEMORY +------------------------------- + +CONSTANT: + ``CONFIGURE_MESSAGE_BUFFER_MEMORY`` + +DATA TYPE: + integer summation macro + +RANGE: + undefined (zero) or calculation resulting in a positive integer + +DEFAULT VALUE: + The default value is zero. + +DESCRIPTION: + The value of this configuration option defines the number of bytes + resereved for message queue buffers in the RTEMS Workspace. + +NOTES: + The configuration options :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` and + :ref:`CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES` define only how many message + queues can be created by the application. The memory for the message + buffers is configured by this option. For each message queue you have to + reserve some memory for the message buffers. The size dependes on the + maximum number of pending messages and the maximum size of the messages of + a message queue. Use the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` macro + to specify the message buffer memory for each message queue and sum them up + to define the value for ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``. + + The interface for the ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()`` help + macro is as follows: + + .. code-block:: c + + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( max_messages, max_msg_size ) + + Where ``max_messages`` is the maximum number of pending messages and + ``max_msg_size`` is the maximum size in bytes of the messages of the + corresponding message queue. Both parameters shall be compile time + constants. Not using this help macro (e.g. just using + ``max_messages * max_msg_size``) may result in an underestimate of the + RTEMS Workspace size. + + The following example illustrates how the + `CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE()` help macro can be used to assist in + calculating the message buffer memory required. In this example, there are + two message queues used in this application. The first message queue has a + maximum of 24 pending messages with the message structure defined by the + type ``one_message_type``. The other message queue has a maximum of 500 + pending messages with the message structure defined by the type + ``other_message_type``. + + .. code-block:: c + + #define CONFIGURE_MESSAGE_BUFFER_MEMORY ( \ + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ + 24, \ + sizeof( one_message_type ) \ + ) \ + + CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ + 500, \ + sizeof( other_message_type ) \ + ) \ + ) + .. index:: CONFIGURE_MICROSECONDS_PER_TICK .. index:: tick quantum diff --git a/c-user/config/index.rst b/c-user/config/index.rst index 0d6c0dd..2318042 100644 --- a/c-user/config/index.rst +++ b/c-user/config/index.rst @@ -17,7 +17,6 @@ Configuring a System posix-api posix-init-thread task-stack-alloc - msg-queue-buffer filesystem bdbuf bsp-related diff --git a/c-user/config/msg-queue-buffer.rst b/c-user/config/msg-queue-buffer.rst deleted file mode 100644 index 8d40149..0000000 --- a/c-user/config/msg-queue-buffer.rst +++ /dev/null @@ -1,93 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -Message Queue Buffer Configuration -================================== - -This section describes the configuration parameters related to specifying the -amount of memory reserved for message queue message buffers. See -:ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES` and -:ref:`CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`. - -.. index:: CONFIGURE_MESSAGE_BUFFER_MEMORY -.. index:: configure message queue buffer memory - -.. _CONFIGURE_MESSAGE_BUFFER_MEMORY: - -CONFIGURE_MESSAGE_BUFFER_MEMORY -------------------------------- - -CONSTANT: - ``CONFIGURE_MESSAGE_BUFFER_MEMORY`` - -DATA TYPE: - integer summation macro - -RANGE: - undefined (zero) or calculation resulting in a positive integer - -DEFAULT VALUE: - This is not defined by default, and zero (0) memory is reserved. - -DESCRIPTION: - This macro is set to the number of bytes the application requires to be - reserved for pending Classic API Message Queue buffers. - -NOTES: - The following illustrates how the help macro - :ref:`CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE` can be used to assist in - calculating the message buffer memory required. In this example, there are - two message queues used in this application. The first message queue has - maximum of 24 pending messages with the message structure defined by the - type ``one_message_type``. The other message queue has maximum of 500 - pending messages with the message structure defined by the type - ``other_message_type``. - - .. code-block:: c - - #define CONFIGURE_MESSAGE_BUFFER_MEMORY \ - (CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ - 24, sizeof(one_message_type) \ - ) + \ - CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE( \ - 500, sizeof(other_message_type) \ - ) - -.. index:: CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE -.. index:: memory for a single message queue's buffers - -.. _CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE: - -CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE ------------------------------------ - -CONSTANT: - ``CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per)`` - -DATA TYPE: - Unsigned integer (``size_t``). - -RANGE: - Positive. - -DEFAULT VALUE: - The default value is None. - -DESCRIPTION: - This is a helper macro which is used to assist in computing the total - amount of memory required for message buffers. Each message queue will - have its own configuration with maximum message size and maximum number of - pending messages. - - The interface for this macro is as follows: - - .. code-block:: c - - CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(max_messages, size_per) - - Where ``max_messages`` is the maximum number of pending messages and - ``size_per`` is the size in bytes of the user message. - -NOTES: - This macro is only used in support of :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. -- cgit v1.2.3