spec: Add CONFIGURE_IDLE_TASK_STORAGE_SIZE

8 files changed, 136 insertions, 12 deletions

diff --git a/spec/acfg/constraint/idle-task-min-stack-size.yml b/spec/acfg/constraint/idle-task-min-stack-size.yml
new file mode 100644
index 00000000..bf2ee7d9
--- /dev/null
+++ b/spec/acfg/constraint/idle-task-min-stack-size.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2022 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  The value of the application configuration option shall be greater than or
+  equal to ${../if/idle-task-stack-size:/name}.
+type: constraint
diff --git a/spec/acfg/constraint/init-task-stack-allocator-for-idle.yml b/spec/acfg/constraint/init-task-stack-allocator-for-idle.yml
index 7f2586e9..2787fd7f 100644
--- a/spec/acfg/constraint/init-task-stack-allocator-for-idle.yml
+++ b/spec/acfg/constraint/init-task-stack-allocator-for-idle.yml
@@ -8,5 +8,5 @@ links:
 rationale: null
 text: |
   The value of the application configuration option shall be defined to a valid
-  function pointer of the type ``void *( *allocate )( uint32_t, size_t )``.
+  function pointer of the type ``void *( *allocate )( uint32_t, size_t * )``.
 type: constraint
diff --git a/spec/acfg/constraint/task-stack-allocator-for-idle-do-or-die.yml b/spec/acfg/constraint/task-stack-allocator-for-idle-do-or-die.yml
new file mode 100644
index 00000000..c20cbdc7
--- /dev/null
+++ b/spec/acfg/constraint/task-stack-allocator-for-idle-do-or-die.yml
@@ -0,0 +1,13 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2022 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  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.
+type: constraint
diff --git a/spec/acfg/constraint/task-stack-allocator-for-idle-increase-size.yml b/spec/acfg/constraint/task-stack-allocator-for-idle-increase-size.yml
new file mode 100644
index 00000000..0face249
--- /dev/null
+++ b/spec/acfg/constraint/task-stack-allocator-for-idle-increase-size.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2022 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  The IDLE task stack allocator may increase the size of the allocated memory
+  area.
+type: constraint
diff --git a/spec/acfg/if/idle-task-storage-size.yml b/spec/acfg/if/idle-task-storage-size.yml
new file mode 100644
index 00000000..66353a4a
--- /dev/null
+++ b/spec/acfg/if/idle-task-storage-size.yml
@@ -0,0 +1,55 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+appl-config-option-type: integer
+copyrights:
+- Copyright (C) 2022 embedded brains GmbH (http://www.embedded-brains.de)
+default-value: |
+  This configuration option has no default value.  If it is not specified, then
+  the task storage area for each ${/glossary/idletask:/term} will allocated
+  from the RTEMS Workspace or through a custom IDLE task stack allocator.
+description: |
+  If this configuration option is specified, then the task storage areas for
+  the ${/glossary/idletask:/plural} are statically allocated by
+  <rtems/confdefs.h>.  The value of this configuration option defines the size
+  in bytes of the task storage area of each IDLE task in the system.
+enabled-by: true
+index-entries:
+- IDLE task storage size
+interface-type: appl-config-option
+links:
+- role: interface-placement
+  uid: domain
+- role: interface-ingroup
+  uid: group-idle
+- role: constraint
+  uid: ../constraint/idle-task-min-stack-size
+name: CONFIGURE_IDLE_TASK_STORAGE_SIZE
+notes: |
+  By default, the IDLE task storage areas are allocated from the RTEMS
+  Workspace.  Applications which do not want to use a heap allocator can use
+  this configuration option to use statically allocated memory for the IDLE
+  task storage areas.  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 ${max-thread-local-storage-size:/name}
+  configuration option.  You have to estimate the actual thread-local storage
+  size if you want to use this configuration option.  If the IDLE task stack
+  size would be less than the value defined by the
+  ${idle-task-stack-size:/name} configuration option, for example because the
+  thread-local storage size is larger than expected, then the system terminates
+  with the ${/score/interr/if/internal-error-core:/name} fatal source and the
+  ${/score/interr/if/idle-thread-stack-too-small:/name} fatal code during
+  system initialization.
+
+  The value of this configuration option is passed to
+  ${/rtems/task/if/storage-size:/name} by <rtems/confdefs.h> to determine the
+  actual size of the statically allocated area to take architecture-specific
+  overheads into account.
+
+  The
+
+  * ``CONFIGURE_IDLE_TASK_STORAGE_SIZE``, and
+
+  * ${task-stack-allocator-for-idle:/name}
+
+  configuration options are mutually exclusive.
+type: interface
diff --git a/spec/acfg/if/task-stack-allocator-for-idle.yml b/spec/acfg/if/task-stack-allocator-for-idle.yml
index 26502816..3ecb8bb0 100644
--- a/spec/acfg/if/task-stack-allocator-for-idle.yml
+++ b/spec/acfg/if/task-stack-allocator-for-idle.yml
@@ -1,14 +1,14 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 appl-config-option-type: initializer
 copyrights:
+- Copyright (C) 2022 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 2021 On-Line Applications Research Corporation (OAR)
 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>``.
+  By default, the IDLE task storage area will be allocated from the RTEMS
+  Workspace.
 description: |
   The value of this configuration option is the address for the stack allocator
-  allocate handler used to allocate the task stack of each
+  allocate handler used to allocate the task storage area of each
   ${/glossary/idletask:/term}.
 enabled-by: true
 index-entries:
@@ -21,10 +21,25 @@ links:
   uid: group-stackalloc
 - role: constraint
   uid: ../constraint/init-task-stack-allocator-for-idle
+- role: constraint
+  uid: ../constraint/task-stack-allocator-for-idle-do-or-die
+- role: constraint
+  uid: ../constraint/task-stack-allocator-for-idle-increase-size
 name: CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE
 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 ${/glossary/idletask:/term} will not be from the RTEMS Workspace or the
-  memory statically allocated by default.
+  configuration options.  It is assumed that any memory allocated for the task
+  storage area of an ${/glossary/idletask:/term} 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
+
+  * ${idle-task-storage-size:/name}, and
+
+  * ``CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE``
+
+  configuration options are mutually exclusive.
 type: interface
diff --git a/spec/acfg/req/idle-task-storage-size.yml b/spec/acfg/req/idle-task-storage-size.yml
new file mode 100644
index 00000000..53d4fdf0
--- /dev/null
+++ b/spec/acfg/req/idle-task-storage-size.yml
@@ -0,0 +1,17 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2022 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+functional-type: function
+links:
+- role: interface-function
+  uid: ../if/idle-task-storage-size
+- role: requirement-refinement
+  uid: group
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  The application configuration option shall define the task storage area size
+  for an ${/glossary/idletask:/term}.
+type: requirement
diff --git a/spec/acfg/val/default.yml b/spec/acfg/val/default.yml
index 3cf7f91b..50323cc6 100644
--- a/spec/acfg/val/default.yml
+++ b/spec/acfg/val/default.yml
@@ -20,8 +20,8 @@ test-actions:
     - role: validation
       uid: /rtems/config/req/get-idle-task
   - brief: |
-      Check the default value ${/acfg/if/idle-task-stack-size:/name} where the
-      optional BSP-provided default value is enabled.
+      Check the default value of ${/acfg/if/idle-task-stack-size:/name} where
+      the optional BSP-provided default value is enabled.
     code: |
       T_step_eq_sz(
         ${step},
@@ -38,8 +38,8 @@ test-actions:
     - role: validation
       uid: ../if/disable-bsp-settings
   - brief: |
-      Check the default value ${/acfg/if/interrupt-stack-size:/name} where the
-      optional BSP-provided default value is enabled.
+      Check the default value of ${/acfg/if/interrupt-stack-size:/name} where
+      the optional BSP-provided default value is enabled.
     code: |
       T_step_eq_sz(
         ${step},