Re: [docs 1/5] c-user: Add CONFIGURE_IDLE_TASK_MINIMUM_STACK_SIZE
Hi, Can we please wait until the patches are sorted before this is merged? Thanks Chris On 30/9/2022 7:15 pm, Sebastian Huber wrote: > --- > 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 ` fatal source and the > +:ref:`INTERNAL_ERROR_IDLE_THREAD_STACK_TOO_SMALL ` 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.
[docs 1/5] c-user: Add CONFIGURE_IDLE_TASK_MINIMUM_STACK_SIZE
--- 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 ` fatal source and the +:ref:`INTERNAL_ERROR_IDLE_THREAD_STACK_TOO_SMALL ` 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 ` fatal source and the +:ref:`INTERNAL_ERROR_IDLE_THREAD_STACK_TOO_SMALL ` fatal code during +system initialization. + +You can use the :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE` configuration option +to
