diff options
Diffstat (limited to 'c-user/config/task-stack-alloc.rst')
| -rw-r--r-- | c-user/config/task-stack-alloc.rst | 313 |
1 files changed, 227 insertions, 86 deletions
diff --git a/c-user/config/task-stack-alloc.rst b/c-user/config/task-stack-alloc.rst index 203757a..c79833f 100644 --- a/c-user/config/task-stack-alloc.rst +++ b/c-user/config/task-stack-alloc.rst @@ -1,7 +1,24 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/acfg/if/group-stackalloc Task Stack Allocator Configuration ================================== @@ -12,6 +29,12 @@ and deallocation methods for task stacks. This can be used to place task stacks in special areas of memory or to utilize a Memory Management Unit so that stack overflows are detected in hardware. +.. Generated from spec:/acfg/if/task-stack-allocator + +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TASK_STACK_ALLOCATOR .. index:: task stack allocator @@ -20,32 +43,44 @@ overflows are detected in hardware. CONFIGURE_TASK_STACK_ALLOCATOR ------------------------------ -CONSTANT: - ``CONFIGURE_TASK_STACK_ALLOCATOR`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``_Workspace_Allocate``, which indicates that task +stacks will be allocated from the RTEMS Workspace. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an initializer define. +The value of this configuration option initializes the stack allocator +allocate handler. -DEFAULT VALUE: - The default value is ``_Workspace_Allocate``, which indicates that task - stacks will be allocated from the RTEMS Workspace. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void *( *allocate )( size_t )``. +A correctly configured system shall configure the following to be consistent: -DESCRIPTION: - The value of this configuration option initializes the stack allocator - allocate handler. +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` -NOTES: - A correctly configured system shall configure the following to be consistent: +* ``CONFIGURE_TASK_STACK_ALLOCATOR`` - * :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` +* :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` - * `CONFIGURE_TASK_STACK_ALLOCATOR` +.. rubric:: CONSTRAINTS: - * :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` +The value of the configuration option shall be defined to a valid function +pointer of the type ``void *( *allocate )( size_t )``. + +.. Generated from spec:/acfg/if/task-stack-no-workspace + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE @@ -54,23 +89,99 @@ NOTES: CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE ------------------------------------------------ -CONSTANT: - ``CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE`` + +.. rubric:: OPTION TYPE: + +This configuration option is a boolean feature define. + +.. rubric:: DEFAULT CONFIGURATION: + +If this configuration option is undefined, then the described feature is not +enabled. + +.. rubric:: DESCRIPTION: + +In case this configuration option is defined, then the system is informed +that the task stack allocator does not use the RTEMS Workspace. + +.. rubric:: NOTES: + +This configuration option may be used if a custom task stack allocator is +configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. + +.. Generated from spec:/acfg/if/task-stack-allocator-for-idle + +.. raw:: latex + + \clearpage + +.. index:: CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE +.. index:: task stack allocator for IDLE tasks + +.. _CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE: + +CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE +--------------------------------------- + +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +By default, the IDLE task storage area will be allocated from the RTEMS +Workspace. + +.. rubric:: DESCRIPTION: + +The value of this configuration option is the address for the stack allocator +allocate handler used to allocate the task storage area of each +:term:`IDLE task`. -OPTION TYPE: - This configuration option is a boolean feature define. +.. rubric:: NOTES: -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +This configuration option is independent of the other thread stack allocator +configuration options. It is assumed that any memory allocated for the task +storage area of an :term:`IDLE task` will not be from the RTEMS +Workspace. -DESCRIPTION: - In case this configuration option is defined, then the system is informed - that the task stack allocator does not use the RTEMS Workspace. +The IDLE task stack allocator may increase the size of the allocated memory +area to account for the actually allocated memory area. -NOTES: - This configuration option may be used if a custom task stack allocator is - configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. +The + +* :ref:`CONFIGURE_IDLE_TASK_STORAGE_SIZE`, and + +* ``CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE`` + +configuration options are mutually exclusive. + +.. rubric:: CONSTRAINTS: + +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 + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_TASK_STACK_ALLOCATOR_INIT @@ -79,31 +190,44 @@ NOTES: CONFIGURE_TASK_STACK_ALLOCATOR_INIT ----------------------------------- -CONSTANT: - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is `NULL <https://en.cppreference.com/w/c/types/NULL>`_. + +.. rubric:: DESCRIPTION: + +The value of this configuration option initializes the stack allocator +initialization handler. -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: NOTES: -DEFAULT VALUE: - The default value is ``NULL``. +A correctly configured system shall configure the following to be consistent: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void ( *initialize )( size_t )`` or to ``NULL``. +* ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` -DESCRIPTION: - The value of this configuration option initializes the stack allocator - initialization handler. +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` -NOTES: - A correctly configured system shall configure the following to be consistent: +* :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` - * `CONFIGURE_TASK_STACK_ALLOCATOR_INIT` +.. rubric:: CONSTRAINTS: - * :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` +The value of the configuration option shall be defined to a valid function +pointer of the type ``void ( *initialize )( size_t )`` or to `NULL +<https://en.cppreference.com/w/c/types/NULL>`_. - * :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` +.. Generated from spec:/acfg/if/task-stack-deallocator + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_TASK_STACK_DEALLOCATOR .. index:: task stack deallocator @@ -113,32 +237,44 @@ NOTES: CONFIGURE_TASK_STACK_DEALLOCATOR -------------------------------- -CONSTANT: - ``CONFIGURE_TASK_STACK_DEALLOCATOR`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_DEALLOCATOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is ``_Workspace_Free``, which indicates that task stacks +will be allocated from the RTEMS Workspace. + +.. rubric:: DESCRIPTION: + +The value of this configuration option initializes the stack allocator +deallocate handler. -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: NOTES: -DEFAULT VALUE: - The default value is ``_Workspace_Free``, which indicates that task stacks - will be allocated from the RTEMS Workspace. +A correctly configured system shall configure the following to be consistent: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void ( *deallocate )( void * )``. +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` -DESCRIPTION: - The value of this configuration option initializes the stack allocator - deallocate handler. +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` -NOTES: - A correctly configured system shall configure the following to be consistent: +* ``CONFIGURE_TASK_STACK_DEALLOCATOR`` - * :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` +.. rubric:: CONSTRAINTS: - * :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` +The value of the configuration option shall be defined to a valid function +pointer of the type ``void ( *deallocate )( void * )``. - * `CONFIGURE_TASK_STACK_DEALLOCATOR` +.. Generated from spec:/acfg/if/task-stack-from-alloc + +.. raw:: latex + + \clearpage .. index:: CONFIGURE_TASK_STACK_FROM_ALLOCATOR .. index:: task stack allocator @@ -148,26 +284,31 @@ NOTES: CONFIGURE_TASK_STACK_FROM_ALLOCATOR ----------------------------------- -CONSTANT: - ``CONFIGURE_TASK_STACK_FROM_ALLOCATOR`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_FROM_ALLOCATOR`` + +.. rubric:: OPTION TYPE: + +This configuration option is an initializer define. + +.. rubric:: DEFAULT VALUE: + +The default value is a macro which supports the system heap allocator. + +.. rubric:: DESCRIPTION: -OPTION TYPE: - This configuration option is an initializer define. +The value of this configuration option is used to calculate the task stack +space size. -DEFAULT VALUE: - The default value is a macro which supports the system heap allocator. +.. rubric:: NOTES: -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a macro which - accepts exactly one parameter and returns an unsigned integer. The - parameter will be an allocation size and the macro shall return this size - plus the overhead of the allocator to manage an allocation request for this - size. +This configuration option may be used if a custom task stack allocator is +configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. -DESCRIPTION: - The value of this configuration option is used to calculate the task stack - space size. +.. rubric:: CONSTRAINTS: -NOTES: - This configuration option may be used if a custom task stack allocator is - configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. +The value of the configuration option shall be defined to a macro which accepts +exactly one parameter and returns an unsigned integer. The parameter will be +an allocation size and the macro shall return this size plus the overhead of +the allocator to manage an allocation request for this size. |