8 files changed, 116 insertions, 36 deletions
diff --git a/spec/if/acfg/max-thread-local-storage-size.yml b/spec/if/acfg/max-thread-local-storage-size.yml
index 1479bddc..b07b57af 100644
--- a/spec/if/acfg/max-thread-local-storage-size.yml
+++ b/spec/if/acfg/max-thread-local-storage-size.yml
@@ -26,5 +26,9 @@ notes: |
   objects used by the application in the statically-linked executable is greater
   than a non-zero value of this configuration option, then a fatal error will
   occur during system initialization.
+
+  Use ${../rtems/basedefs/align-up:/name} and
+  ${../rtems/tasks/storage-alignment:/name} to adjust the size to meet the
+  minimum alignment requirement of a thread-local storage area.
 text: ''
 type: interface
diff --git a/spec/if/acfg/tasks-created-from-config.yml b/spec/if/acfg/min-tasks-with-user-provided-storage.yml
index e8863ac8..2001c01b 100644
--- a/spec/if/acfg/tasks-created-from-config.yml
+++ b/spec/if/acfg/min-tasks-with-user-provided-storage.yml
@@ -7,21 +7,21 @@ copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 default-value: 0
 description: |
-  The value of this configuration option defines the count of Classic API Tasks
-  which are created by ${../rtems/tasks/create-from-config:/name}.
+  The value of this configuration option defines the minimum count of Classic
+  API Tasks which are constructed by ${../rtems/tasks/construct:/name}.
 enabled-by: true
 index-entries: []
 interface-type: appl-config-option
 links:
 - role: appl-config-group-member
   uid: group-classic
-name: CONFIGURE_TASKS_CREATED_FROM_CONFIG
+name: CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE
 notes: |
-  By default, the calculation for the required memory in the RTEMS Workspace for
-  tasks assumes that all Classic API Tasks are created by
+  By default, the calculation for the required memory in the RTEMS Workspace
+  for tasks assumes that all Classic API Tasks are created by
   ${../rtems/tasks/create:/name}.  This configuration option can be used to
-  reduce the required memory for the system-provided task storage
-  areas since tasks created by ${../rtems/tasks/create-from-config:/name} use a
-  user-provided task storage area.
+  reduce the required memory for the system-provided task storage areas since
+  tasks constructed by ${../rtems/tasks/construct:/name} use a user-provided
+  task storage area.
 text: ''
 type: interface
diff --git a/spec/if/impl/cpu/stack-alignment.yml b/spec/if/impl/cpu/heap-alignment.yml
index ae6b754c..2f09e1d4 100644
--- a/spec/if/impl/cpu/stack-alignment.yml
+++ b/spec/if/impl/cpu/heap-alignment.yml
@@ -6,6 +6,6 @@ interface-type: unspecified-define
 links:
 - role: interface-placement
   uid: header
-name: CPU_STACK_ALIGNMENT
+name: CPU_HEAP_ALIGNMENT
 reference: null
 type: interface
diff --git a/spec/if/rtems/basedefs/align-down.yml b/spec/if/rtems/basedefs/align-down.yml
new file mode 100644
index 00000000..a309b03f
--- /dev/null
+++ b/spec/if/rtems/basedefs/align-down.yml
@@ -0,0 +1,35 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Returns the specified value aligned down to the specified alignment.
+copyrights:
+- Copyright (C) 2016 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default: |
+    ( ( ${.:/params[0]/name} ) & ~( ( ${.:/params[1]/name} ) - 1 ) )
+  variants: []
+description: null
+enabled-by: true
+interface-type: macro
+links:
+- role: interface-placement
+  uid: header
+- role: interface-ingroup
+  uid: group
+name: RTEMS_ALIGN_DOWN
+notes: null
+params:
+- description: |
+    is the value to align down.
+  dir: null
+  name: _value
+- description: |
+    is the desired alignment in bytes.  The alignment shall be a power of two,
+    otherwise the returned value is undefined.  The alignment parameter is
+    evaluated twice.
+  dir: null
+  name: _alignment
+return:
+  return: |
+    The specified value aligned down to the specified alignment is returned.
+  return-values: []
+type: interface
diff --git a/spec/if/rtems/basedefs/align-up.yml b/spec/if/rtems/basedefs/align-up.yml
new file mode 100644
index 00000000..cb3a46dd
--- /dev/null
+++ b/spec/if/rtems/basedefs/align-up.yml
@@ -0,0 +1,35 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Returns the specified value aligned up to the specified alignment.
+copyrights:
+- Copyright (C) 2016 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default: |
+    ( ( ( ${.:/params[0]/name} ) + ( ${.:/params[1]/name} ) - 1 ) & ~( ( ${.:/params[1]/name} ) - 1 ) )
+  variants: []
+description: null
+enabled-by: true
+interface-type: macro
+links:
+- role: interface-placement
+  uid: header
+- role: interface-ingroup
+  uid: group
+name: RTEMS_ALIGN_UP
+notes: null
+params:
+- description: |
+    is the value to align up.
+  dir: null
+  name: _value
+- description: |
+    is the desired alignment in bytes.  The alignment shall be a power of two,
+    otherwise the returned value is undefined.  The alignment parameter is
+    evaluated twice.
+  dir: null
+  name: _alignment
+return:
+  return: |
+    The specified value aligned up to the specified alignment is returned.
+  return-values: []
+type: interface
diff --git a/spec/if/rtems/tasks/config.yml b/spec/if/rtems/tasks/config.yml
index 91943ff1..f09fc1a1 100644
--- a/spec/if/rtems/tasks/config.yml
+++ b/spec/if/rtems/tasks/config.yml
@@ -1,8 +1,7 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  This structure defines a task configuration used to build a task.  This
-  structure defines the configuration of a task created by
-  ${create-from-config:/name}.
+  This structure defines the configuration of a task constructed by
+  ${construct:/name}.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
@@ -31,9 +30,10 @@ definition:
       storage, and the floating-point context on architectures with a separate
       floating-point context.
 
-      There are no alignment requirements for the task storage area.  To avoid
-      memory waste, use the ${storage-alignment:/name} variable attribute to
-      enforce the recommended alignment of the task storage area.
+      The task storage area begin address and size should be aligned by
+      ${storage-alignment:/name}.  To avoid memory waste, use
+      ${../basedefs/aligned:/name} and ${storage-alignment:/name} to enforce
+      the recommended alignment of a statically allocated task storage area.
     kind: member
     name: storage_area
   variants: []
@@ -53,11 +53,15 @@ definition:
       task storage area.
     definition: ${../../c/size_t:/name} ${.:name}
     description: |
+      Use ${../basedefs/align-up:/name} and ${storage-alignment:/name} to
+      adjust the size to meet the minimum alignment requirement of a
+      thread-local storage area used to construct a task.
+
       If the value is less than the actual thread-local storage size, then the
-      task creation by ${create-from-config:/name} fails.
+      task construction by ${construct:/name} fails.
 
-      If the is less than the task storage area size, then the task creation by
-      ${create-from-config:/name} fails.
+      If the is less than the task storage area size, then the task
+      construction by ${construct:/name} fails.
     kind: member
     name: maximum_thread_local_storage_size
   variants: []
@@ -66,10 +70,12 @@ definition:
       This member defines the optional handler to free the task storage area.
     definition: void ( *${.:name} )( void * )
     description: |
-      It is called when the task creation aborts due to a failed task create
-      extension or the task is deleted.  It is called from task context under
+      It is called on exactly two mutually exclusive occasions.  Firstly, when
+      the task construction aborts due to a failed task create extension, or
+      secondly, when the task is deleted.  It is called from task context under
       protection of the object allocator lock.  It is allowed to call free() in
-      this handler.  The handler may be ${../../c/null:/name}.
+      this handler.  If handler is ${../../c/null:/name}, then no action will
+      be performed.
     kind: member
     name: storage_free
   variants: []
diff --git a/spec/if/rtems/tasks/create-from-config.yml b/spec/if/rtems/tasks/construct.yml
index f592686e..329b4b83 100644
--- a/spec/if/rtems/tasks/create-from-config.yml
+++ b/spec/if/rtems/tasks/construct.yml
@@ -19,10 +19,10 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
-name: rtems_task_create_from_config
+name: rtems_task_construct
 notes: |
-  In contrast to tasks created by ${create:/name}, the tasks created by this
-  directive use a user-provided task storage area.  The task storage area
+  In contrast to tasks created by ${create:/name}, the tasks constructed by
+  this directive use a user-provided task storage area.  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.
 
@@ -32,16 +32,15 @@ notes: |
   system resources.  The stack space estimate done by <rtems/confdefs.h>
   assumes that all tasks are created by ${create:/name}.  The estimate can be
   adjusted to take user-provided task storage areas into account through the
-  ${../../acfg/tasks-created-from-config:/name} application configuration
-  option or a custom task stack allocator, see
-  ${../../acfg/task-stack-allocator:/name}.
+  ${../../acfg/min-tasks-with-user-provided-storage:/name} application
+  configuration option.
 params:
 - description: is the task configuration.
   dir: null
   name: config
 - description: |
     is the pointer to an object identifier variable.  The identifier of the
-    created task object will be stored in this variable, in case of a
+    constructed task object will be stored in this variable, in case of a
     successful operation.
   dir: out
   name: id
@@ -74,14 +73,14 @@ return:
       floating-point context.
     value: ${../status/invalid-size:/name}
   - description: |
-      There was no inactive task object available to create a task.
+      There was no inactive task object available to construct a task.
     value: ${../status/too-many:/name}
   - description: |
       In multiprocessing configurations, there was no inactive global object
-      available to create a global task.
+      available to construct a global task.
     value: ${../status/too-many:/name}
   - description: |
-      One of the task create extensions failed during the task creation.
+      One of the task create extensions failed during the task construction.
     value: ${../status/unsatisfied:/name}
   - description: |
       In SMP configurations, the non-preemption mode was not supported.
diff --git a/spec/if/rtems/tasks/storage-alignment.yml b/spec/if/rtems/tasks/storage-alignment.yml
index 50b64991..6a8f677c 100644
--- a/spec/if/rtems/tasks/storage-alignment.yml
+++ b/spec/if/rtems/tasks/storage-alignment.yml
@@ -1,12 +1,11 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  This variable attribute defines the recommended alignment of a task storage
-  area.
+  This constant defines the recommended alignment of a task storage area in
+  bytes.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
-  default: |
-    ${../basedefs/aligned:/name}( ${../../impl/cpu/stack-alignment:/name} )
+  default: ${../../impl/cpu/heap-alignment:/name}
   variants: []
 description: null
 enabled-by: true
@@ -17,5 +16,7 @@ links:
 - role: interface-ingroup
   uid: group
 name: RTEMS_TASK_STORAGE_ALIGNMENT
-notes: null
+notes: |
+  Use it with ${../basedefs/aligned:/name} to define the alignment of a
+  statically allocated task storage area.
 type: interface