[docs 1/5] c-user: Add CONFIGURE_IDLE_TASK_MINIMUM_STACK_SIZE

Tue Oct 4 22:26:40 UTC 2022

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 <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
>  