mirror of
https://git.rtems.org/rtems-docs/
synced 2025-07-22 18:25:34 +08:00
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.
This commit is contained in:
Sebastian Huber
parent
a7991aebae
commit
03a735f896
@ -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
|
||||
|
||||
|
||||
@ -17,7 +17,6 @@ Configuring a System
|
||||
posix-api
|
||||
posix-init-thread
|
||||
task-stack-alloc
|
||||
msg-queue-buffer
|
||||
filesystem
|
||||
bdbuf
|
||||
bsp-related
|
||||
|
||||
@ -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`.
|
||||
Loading…
x
Reference in New Issue
Block a user