diff options
Diffstat (limited to 'c-user/config/task-stack-alloc.rst')
-rw-r--r-- | c-user/config/task-stack-alloc.rst | 289 |
1 files changed, 183 insertions, 106 deletions
diff --git a/c-user/config/task-stack-alloc.rst b/c-user/config/task-stack-alloc.rst index 792c4b8..c79833f 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 & Co. KG .. Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) .. This file is part of the RTEMS quality process and was automatically @@ -31,6 +31,10 @@ 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 @@ -39,35 +43,45 @@ 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. -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: DESCRIPTION: -DEFAULT VALUE: - The default value is ``_Workspace_Allocate``, which indicates that task - stacks will be allocated from the RTEMS Workspace. +The value of this configuration option initializes the stack allocator +allocate handler. -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void *( *allocate )( size_t )``. +.. rubric:: NOTES: -DESCRIPTION: - The value of this configuration option initializes the stack allocator - allocate handler. +A correctly configured system shall configure the following to be consistent: -NOTES: - A correctly configured system shall configure the following to be consistent: +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` - * :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` +* ``CONFIGURE_TASK_STACK_ALLOCATOR`` - * ``CONFIGURE_TASK_STACK_ALLOCATOR`` +* :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` - * :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` +.. rubric:: CONSTRAINTS: + +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 .. _CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE: @@ -75,26 +89,35 @@ 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: -OPTION TYPE: - This configuration option is a boolean feature define. +If this configuration option is undefined, then the described feature is not +enabled. -DEFAULT CONFIGURATION: - If this configuration option is undefined, then the described feature is not - enabled. +.. rubric:: DESCRIPTION: -DESCRIPTION: - In case this configuration option is defined, then the system is informed - that the task stack allocator does not use the RTEMS Workspace. +In case this configuration option is defined, then the system is informed +that the task stack allocator does not use the RTEMS Workspace. -NOTES: - This configuration option may be used if a custom task stack allocator is - configured, see :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`. +.. 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 @@ -103,34 +126,63 @@ NOTES: CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE --------------------------------------- -CONSTANT: - ``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`. + +.. rubric:: NOTES: + +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. + +The IDLE task stack allocator may increase the size of the allocated memory +area to account for the actually allocated memory area. + +The -OPTION TYPE: - This configuration option is an initializer define. +* :ref:`CONFIGURE_IDLE_TASK_STORAGE_SIZE`, and -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 - allocated by ``<rtems/confdefs.h>``. +* ``CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE`` -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void *( *allocate )( uint32_t, size_t )``. +configuration options are mutually exclusive. -DESCRIPTION: - The value of this configuration option is the address for the stack allocator - allocate handler used to allocate the task stack of each - :term:`IDLE task`. +.. rubric:: CONSTRAINTS: -NOTES: - This configuration option is independent of the other thread stack allocator - 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 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 .. _CONFIGURE_TASK_STACK_ALLOCATOR_INIT: @@ -138,35 +190,45 @@ NOTES: CONFIGURE_TASK_STACK_ALLOCATOR_INIT ----------------------------------- -CONSTANT: - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` + +.. rubric:: OPTION TYPE: -OPTION TYPE: - This configuration option is an initializer define. +This configuration option is an initializer define. -DEFAULT VALUE: - The default value is `NULL <https://en.cppreference.com/w/c/types/NULL>`_. +.. rubric:: DEFAULT VALUE: -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 - <https://en.cppreference.com/w/c/types/NULL>`_. +The default value is `NULL <https://en.cppreference.com/w/c/types/NULL>`_. -DESCRIPTION: - The value of this configuration option initializes the stack allocator - initialization handler. +.. rubric:: DESCRIPTION: -NOTES: - A correctly configured system shall configure the following to be consistent: +The value of this configuration option initializes the stack allocator +initialization handler. - * ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` +.. rubric:: NOTES: - * :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` +A correctly configured system shall configure the following to be consistent: - * :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` +* ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` + +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` + +* :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR` + +.. rubric:: CONSTRAINTS: + +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>`_. .. Generated from spec:/acfg/if/task-stack-deallocator +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TASK_STACK_DEALLOCATOR .. index:: task stack deallocator @@ -175,35 +237,45 @@ NOTES: CONFIGURE_TASK_STACK_DEALLOCATOR -------------------------------- -CONSTANT: - ``CONFIGURE_TASK_STACK_DEALLOCATOR`` +.. rubric:: CONSTANT: + +``CONFIGURE_TASK_STACK_DEALLOCATOR`` -OPTION TYPE: - This configuration option is an initializer define. +.. rubric:: OPTION TYPE: -DEFAULT VALUE: - The default value is ``_Workspace_Free``, which indicates that task stacks - will be allocated from the RTEMS Workspace. +This configuration option is an initializer define. -VALUE CONSTRAINTS: - The value of this configuration option shall be defined to a valid function - pointer of the type ``void ( *deallocate )( void * )``. +.. rubric:: DEFAULT VALUE: -DESCRIPTION: - The value of this configuration option initializes the stack allocator - deallocate handler. +The default value is ``_Workspace_Free``, which indicates that task stacks +will be allocated from the RTEMS Workspace. -NOTES: - A correctly configured system shall configure the following to be consistent: +.. rubric:: DESCRIPTION: - * :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` +The value of this configuration option initializes the stack allocator +deallocate handler. - * :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` +.. rubric:: NOTES: - * ``CONFIGURE_TASK_STACK_DEALLOCATOR`` +A correctly configured system shall configure the following to be consistent: + +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT` + +* :ref:`CONFIGURE_TASK_STACK_ALLOCATOR` + +* ``CONFIGURE_TASK_STACK_DEALLOCATOR`` + +.. rubric:: CONSTRAINTS: + +The value of the configuration option shall be defined to a valid function +pointer of the type ``void ( *deallocate )( void * )``. .. Generated from spec:/acfg/if/task-stack-from-alloc +.. raw:: latex + + \clearpage + .. index:: CONFIGURE_TASK_STACK_FROM_ALLOCATOR .. index:: task stack allocator @@ -212,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. |