[docs 1/5] c-user: Add CONFIGURE_IDLE_TASK_MINIMUM_STACK_SIZE
Sebastian Huber
sebastian.huber at embedded-brains.de
Fri Sep 30 09:15:30 UTC 2022
---
c-user/config/idle-task.rst | 95 ++++++++++++++++++++++++++++--
c-user/config/task-stack-alloc.rst | 39 ++++++++++--
2 files changed, 124 insertions(+), 10 deletions(-)
diff --git a/c-user/config/idle-task.rst b/c-user/config/idle-task.rst
index 359f862..d7b43ae 100644
--- a/c-user/config/idle-task.rst
+++ b/c-user/config/idle-task.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2022 embedded brains GmbH (http://www.embedded-brains.de)
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
.. This file is part of the RTEMS quality process and was automatically
@@ -134,6 +134,74 @@ options
otherwise a compile time error in the configuration file will occur.
+.. Generated from spec:/acfg/if/idle-task-min-stack-size
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: CONFIGURE_IDLE_TASK_MINIMUM_STACK_SIZE
+.. index:: minimum task stack size
+
+.. _CONFIGURE_IDLE_TASK_MINIMUM_STACK_SIZE:
+
+CONFIGURE_IDLE_TASK_MINIMUM_STACK_SIZE
+--------------------------------------
+
+.. rubric:: CONSTANT:
+
+``CONFIGURE_IDLE_TASK_MINIMUM_STACK_SIZE``
+
+.. rubric:: OPTION TYPE:
+
+This configuration option is an integer define.
+
+.. rubric:: DEFAULT VALUE:
+
+:c:macro:`CPU_STACK_MINIMUM_SIZE` / 4
+
+.. rubric:: DESCRIPTION:
+
+The value of this configuration option defines the minimum stack size in
+bytes for every :term:`IDLE task` in the system.
+
+.. rubric:: NOTES:
+
+Adjusting this parameter should be done with caution. Examining the actual
+stack usage using the stack checker usage reporting facility is recommended
+(see also :ref:`CONFIGURE_STACK_CHECKER_ENABLED`).
+
+This parameter can be used to increase the minimum from that
+recommended. This can be used in higher memory systems to reduce the risk
+of stack overflow without performing analysis on actual consumption.
+
+By default, the IDLE task storage areas are statically allocated. The size
+of the task storage area is defined by the :ref:`CONFIGURE_IDLE_TASK_STACK_SIZE`
+configuration option. The task storage area contains the task stack, the
+thread-local storage, and the floating-point context on architectures with a
+separate floating-point context. The size of the thread-local storage area
+is defined at link time or by the :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE`
+configuration option. This configuration option is used to ensure that the
+IDLE task stack size has at least the configured minimum size. If the IDLE
+task stack size is too small, for example because the thread-local storage
+size is too large, then the system terminates with the
+:ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` fatal source and the
+:ref:`INTERNAL_ERROR_IDLE_THREAD_STACK_TOO_SMALL <internal_errors>` fatal code during
+system initialization.
+
+.. rubric:: CONSTRAINTS:
+
+The value of the configuration option shall be large enough so that
+
+* the thread handler can call the thread switch extensions for the IDLE task,
+
+* the thread handler can call the thread begin extensions for the IDLE task,
+
+* the thread handler can call the IDLE task body (see
+ :ref:`CONFIGURE_IDLE_TASK_BODY`), and
+
+* the IDLE task can be interrupted by interrupt services.
+
.. Generated from spec:/acfg/if/idle-task-stack-size
.. raw:: latex
@@ -165,13 +233,30 @@ defined by the :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` configuration option.
.. rubric:: DESCRIPTION:
-The value of this configuration option defines the task stack size for an
-IDLE task.
+The value of this configuration option defines the task storage area size for
+an IDLE task.
.. rubric:: NOTES:
-In SMP configurations, there is one IDLE task per configured processor, see
-:ref:`CONFIGURE_MAXIMUM_PROCESSORS`.
+Where the system was built with SMP support enabled, there is one IDLE task
+for each configured processor, see :ref:`CONFIGURE_MAXIMUM_PROCESSORS`.
+
+By default, the IDLE task storage areas are statically allocated. The size
+of the task storage area for each IDLE task is defined by this configuration
+option. The task storage area contains the task stack, the thread-local
+storage, and the floating-point context on architectures with a separate
+floating-point context. The size of the thread-local storage area is defined
+at link time or by the :ref:`CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE` configuration
+option. The :ref:`CONFIGURE_IDLE_TASK_MINIMUM_STACK_SIZE` configuration option is used
+to ensure that the IDLE task stack size has at least the configured minimum
+size. If the IDLE task stack size is too small, for example because the
+thread-local storage size is too large, then the system terminates with the
+:ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` fatal source and the
+:ref:`INTERNAL_ERROR_IDLE_THREAD_STACK_TOO_SMALL <internal_errors>` fatal code during
+system initialization.
+
+You can use the :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE` configuration option
+to change the task stack allocator for IDLE tasks.
.. rubric:: CONSTRAINTS:
diff --git a/c-user/config/task-stack-alloc.rst b/c-user/config/task-stack-alloc.rst
index 187bff5..b23edce 100644
--- a/c-user/config/task-stack-alloc.rst
+++ b/c-user/config/task-stack-alloc.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2022 embedded brains GmbH (http://www.embedded-brains.de)
.. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR)
.. This file is part of the RTEMS quality process and was automatically
@@ -136,8 +136,7 @@ This configuration option is an initializer define.
.. rubric:: DEFAULT VALUE:
-The default value is ``_Stack_Allocator_allocate_for_idle_default``, which
-indicates that IDLE task stacks will be allocated from an area statically
+By default, the IDLE task stacks will be allocated from an area statically
allocated by ``<rtems/confdefs.h>``.
.. rubric:: DESCRIPTION:
@@ -153,10 +152,40 @@ configuration options. It is assumed that any memory allocated for the stack
of an :term:`IDLE task` will not be from the RTEMS Workspace or the
memory statically allocated by default.
+The IDLE task stack allocator may increase the size of the allocated memory
+area to account for the actual thread-local storage size which is defined at
+link time.
+
+The size of the statically allocated memory area used by the default
+allocator is defined by the :ref:`CONFIGURE_IDLE_TASK_STACK_SIZE` configuration
+option. The :ref:`CONFIGURE_IDLE_TASK_MINIMUM_STACK_SIZE` configuration option ensures
+that the IDLE task stack size has at least the configured minimum size.
+
+For applications with a thread-local storage size which is completely unknown
+at the time the application configuration is defined, RTEMS provides an IDLE
+task stack allocator which uses :c:func:`rtems_malloc`. The size
+of the allocated thread storage area is the sum of stack size defined by the
+:ref:`CONFIGURE_IDLE_TASK_STACK_SIZE` configuration option and the actual
+thread-local storage size of the application. If the memory allocation
+fails, then the system terminates with the
+:ref:`INTERNAL_ERROR_CORE <FatalErrorSources>` fatal source and the
+:ref:`INTERNAL_ERROR_NO_MEMORY_FOR_IDLE_TASK_STACK <internal_errors>` fatal code during
+system initialization. Define this configuration option to
+``rtems_malloc_task_stack_for_idle`` to use this allocator.
+
.. rubric:: CONSTRAINTS:
-The value of the configuration option shall be defined to a valid function
-pointer of the type ``void *( *allocate )( uint32_t, size_t )``.
+The following constraints apply to this configuration option:
+
+* The value of the configuration option shall be defined to a valid function
+ pointer of the type ``void *( *allocate )( uint32_t, size_t * )``.
+
+* The IDLE task stack allocator shall return a pointer to the allocated memory
+ area or terminate the system with a fatal error if the allocation request
+ cannot be satisfied.
+
+* The IDLE task stack allocator may increase the size of the allocated memory
+ area.
.. Generated from spec:/acfg/if/task-stack-allocator-init
--
2.35.3
More information about the devel
mailing list