11 files changed, 301 insertions, 90 deletions
diff --git a/spec/if/acfg/max-thread-local-storage-size.yml b/spec/if/acfg/max-thread-local-storage-size.yml
new file mode 100644
index 00000000..1479bddc
--- /dev/null
+++ b/spec/if/acfg/max-thread-local-storage-size.yml
@@ -0,0 +1,30 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+appl-config-option-type: integer
+constraints:
+  max: ${../c/size_max:/name}
+  min: 0
+copyrights:
+- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+default-value: 0
+description: |
+  If the value of this configuration option is greater than zero, then it
+  defines the maximum thread-local storage size, otherwise the thread-local
+  storage size is defined by the linker depending on the thread-local storage
+  objects used by the application in the statically-linked executable.
+enabled-by: true
+index-entries: []
+interface-type: appl-config-option
+links:
+- role: appl-config-group-member
+  uid: group-classic
+name: CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE
+notes: |
+  This configuration option can be used to reserve space for the dynamic linking
+  of modules with thread-local storage objects.
+
+  If the thread-local storage size defined by the thread-local storage
+  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.
+text: ''
+type: interface
diff --git a/spec/if/acfg/tasks-created-from-config.yml b/spec/if/acfg/tasks-created-from-config.yml
new file mode 100644
index 00000000..e8863ac8
--- /dev/null
+++ b/spec/if/acfg/tasks-created-from-config.yml
@@ -0,0 +1,27 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+appl-config-option-type: integer
+constraints:
+  max: ${max-tasks:/name}
+  min: 0
+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}.
+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
+notes: |
+  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.
+text: ''
+type: interface
diff --git a/spec/if/impl/context/fp-size.yml b/spec/if/impl/context/fp-size.yml
new file mode 100644
index 00000000..04a897f4
--- /dev/null
+++ b/spec/if/impl/context/fp-size.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+interface-type: unspecified-define
+links:
+- role: interface-placement
+  uid: header
+name: CONTEXT_FP_SIZE
+reference: null
+type: interface
diff --git a/spec/if/impl/context/header.yml b/spec/if/impl/context/header.yml
new file mode 100644
index 00000000..aeca1f95
--- /dev/null
+++ b/spec/if/impl/context/header.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: This header file defines interfaces of the Stack Handler.
+copyrights:
+- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+interface-type: header-file
+links:
+- role: interface-placement
+  uid: /if/domains/implementation
+path: rtems/score/context.h
+prefix: cpukit/include
+type: interface
diff --git a/spec/if/impl/cpu/all-tasks-are-fp.yml b/spec/if/impl/cpu/all-tasks-are-fp.yml
new file mode 100644
index 00000000..77a9ce1c
--- /dev/null
+++ b/spec/if/impl/cpu/all-tasks-are-fp.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+interface-type: unspecified-define
+links:
+- role: interface-placement
+  uid: header
+name: CPU_ALL_TASKS_ARE_FP
+reference: null
+type: interface
diff --git a/spec/if/impl/cpu/stack-alignment.yml b/spec/if/impl/cpu/stack-alignment.yml
new file mode 100644
index 00000000..ae6b754c
--- /dev/null
+++ b/spec/if/impl/cpu/stack-alignment.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+interface-type: unspecified-define
+links:
+- role: interface-placement
+  uid: header
+name: CPU_STACK_ALIGNMENT
+reference: null
+type: interface
diff --git a/spec/if/rtems/tasks/build.yml b/spec/if/rtems/tasks/build.yml
deleted file mode 100644
index 8d06585f..00000000
--- a/spec/if/rtems/tasks/build.yml
+++ /dev/null
@@ -1,73 +0,0 @@
-SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: |
-  Builds a task according to the task configuration.
-copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-definition:
-  default:
-    body: null
-    params:
-    - const ${config:/name} *${.:/params[0]/name}
-    - ${../types/id:/name} *${.:/params[1]/name}
-    return: ${../status/code:/name}
-  variants: []
-description: null
-enabled-by: true
-interface-type: function
-links:
-- role: interface-placement
-  uid: header
-- role: interface-ingroup
-  uid: group
-name: rtems_task_build
-notes: null
-params:
-- description: is the task configuration.
-  dir: null
-  name: config
-- description: |
-    is the pointer to an object identifier variable.  The identifier of the new
-    task object will be stored in this variable, in case of a successful
-    operation.
-  dir: out
-  name: id
-return:
-  return: null
-  return-values:
-  - description: |
-      The requested operation was successful.
-    value: ${../status/successful:/name}
-  - description: |
-      The ${.:/params[1]/name} parameter was ${/if/c/null:/name}.
-    value: ${../status/invalid-address:/name}
-  - description: |
-      The task name was invalid.
-    value: ${../status/invalid-name:/name}
-  - description: |
-      The initial task priority was invalid.
-    value: ${../status/invalid-priority:/name}
-  - description: |
-      The multiprocessing support was not configured.
-    value: ${../status/mp-not-configured:/name}
-  - description: |
-      There was no inactive task object available to build a new task.
-    value: ${../status/too-many:/name}
-  - description: |
-      In multiprocessing configurations, there was no inactive global object
-      available to build a new task.
-    value: ${../status/too-many:/name}
-  - description: |
-      The provided task storage area was too small.  The task storage area
-      includes the task stack, the thread-local storage, and the floating point
-      context.
-    value: ${../status/unsatisfied:/name}
-  - description: |
-      One of the task create extensions failed to create the new task.
-    value: ${../status/unsatisfied:/name}
-  - description: |
-      In SMP configurations, the non-preemption mode was not supported.
-    value: ${../status/unsatisfied:/name}
-  - description: |
-      In SMP configurations, the interrupt level mode was not supported.
-    value: ${../status/unsatisfied:/name}
-type: interface
diff --git a/spec/if/rtems/tasks/config.yml b/spec/if/rtems/tasks/config.yml
index a1d4480f..91943ff1 100644
--- a/spec/if/rtems/tasks/config.yml
+++ b/spec/if/rtems/tasks/config.yml
@@ -1,12 +1,14 @@
 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 a task configuration used to build a task.  This
+  structure defines the configuration of a task created by
+  ${create-from-config:/name}.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
 - default:
     brief: |
-      This member is the name of the task.
+      This member defines the name of the task.
     definition: ${../types/name:/name} ${.:name}
     description: null
     kind: member
@@ -14,7 +16,7 @@ definition:
   variants: []
 - default:
     brief: |
-      This member is the initial priority of the task.
+      This member defines the initial priority of the task.
     definition: ${priority:/name} ${.:name}
     description: null
     kind: member
@@ -22,32 +24,58 @@ definition:
   variants: []
 - default:
     brief: |
-      This member is task stack area begin address for the task.
+      This member shall point to the task storage area begin.
     definition: void *${.:name}
-    description: null
+    description: |
+      The task storage area will contain the task stack, the thread-local
+      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.
     kind: member
-    name: stack_area
+    name: storage_area
   variants: []
 - default:
     brief: |
-      This member is task stack area size in bytes for the task.
-    definition: ${/if/c/size_t:/name} ${.:name}
-    description: null
+      This member defines size of the task storage area in bytes.
+    definition: ${../../c/size_t:/name} ${.:name}
+    description: |
+      Use the ${storage-size:/name} macro to determine the recommended task
+      storage area size.
     kind: member
-    name: stack_size
+    name: storage_size
   variants: []
 - default:
     brief: |
-      This member is the function to free the task stack area if the task gets
-      deleted.
+      This member defines the maximum thread-local storage size supported by the
+      task storage area.
+    definition: ${../../c/size_t:/name} ${.:name}
+    description: |
+      If the value is less than the actual thread-local storage size, then the
+      task creation by ${create-from-config:/name} fails.
+
+      If the is less than the task storage area size, then the task creation by
+      ${create-from-config:/name} fails.
+    kind: member
+    name: maximum_thread_local_storage_size
+  variants: []
+- default:
+    brief: |
+      This member defines the optional handler to free the task storage area.
     definition: void ( *${.:name} )( void * )
-    description: null
+    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
+      protection of the object allocator lock.  It is allowed to call free() in
+      this handler.  The handler may be ${../../c/null:/name}.
     kind: member
-    name: stack_free
+    name: storage_free
   variants: []
 - default:
     brief: |
-      This member is set of initial modes of the task.
+      This member defines the initial modes of the task.
     definition: ${../modes/mode:/name} ${.:name}
     description: null
     kind: member
@@ -55,11 +83,11 @@ definition:
   variants: []
 - default:
     brief: |
-      This member is set of attributes of the task.
+      This member defines the attributes of the task.
     definition: ${../attr/attribute:/name} ${.:name}
     description: null
     kind: member
-    name: attribute_set
+    name: attributes
   variants: []
 definition-kind: typedef-only
 description: null
diff --git a/spec/if/rtems/tasks/create-from-config.yml b/spec/if/rtems/tasks/create-from-config.yml
new file mode 100644
index 00000000..f592686e
--- /dev/null
+++ b/spec/if/rtems/tasks/create-from-config.yml
@@ -0,0 +1,92 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Creates a task from the specified the task configuration.
+copyrights:
+- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default:
+    body: null
+    params:
+    - const ${config:/name} *${.:/params[0]/name}
+    - ${../types/id:/name} *${.:/params[1]/name}
+    return: ${../status/code:/name}
+  variants: []
+description: null
+enabled-by: true
+interface-type: function
+links:
+- role: interface-placement
+  uid: header
+- role: interface-ingroup
+  uid: group
+name: rtems_task_create_from_config
+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
+  contains the task stack, the thread-local storage, and the floating-point
+  context on architectures with a separate floating-point context.
+
+  It is not recommended to mix ${create:/name} and ${.:/name} in an
+  application.  This directive is intended for applications which do not want
+  to use the RTEMS Workspace and instead statically allocate all operating
+  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}.
+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
+    successful operation.
+  dir: out
+  name: id
+return:
+  return: null
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../status/successful:/name}
+  - description: |
+      The ${.:/params[1]/name} parameter was ${/if/c/null:/name}.
+    value: ${../status/invalid-address:/name}
+  - description: |
+      The task name was invalid.
+    value: ${../status/invalid-name:/name}
+  - description: |
+      The initial task priority was invalid.
+    value: ${../status/invalid-priority:/name}
+  - description: |
+      The thread-local storage size is greater than the maximum thread-local
+      storage size specified in the task configuration.  The thread-local
+      storage size is determined by the thread-local variables used by the
+      application and ${../../acfg/max-thread-local-storage-size:/name}.
+    value: ${../status/invalid-size:/name}
+  - description: |
+      The task storage area was too small to provide a task stack of the
+      configured minimum size, see ${../../acfg/min-task-stack-size:/name}.
+      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.
+    value: ${../status/invalid-size:/name}
+  - description: |
+      There was no inactive task object available to create a task.
+    value: ${../status/too-many:/name}
+  - description: |
+      In multiprocessing configurations, there was no inactive global object
+      available to create a global task.
+    value: ${../status/too-many:/name}
+  - description: |
+      One of the task create extensions failed during the task creation.
+    value: ${../status/unsatisfied:/name}
+  - description: |
+      In SMP configurations, the non-preemption mode was not supported.
+    value: ${../status/unsatisfied:/name}
+  - description: |
+      In SMP configurations, the interrupt level mode was not supported.
+    value: ${../status/unsatisfied:/name}
+type: interface
diff --git a/spec/if/rtems/tasks/storage-alignment.yml b/spec/if/rtems/tasks/storage-alignment.yml
new file mode 100644
index 00000000..50b64991
--- /dev/null
+++ b/spec/if/rtems/tasks/storage-alignment.yml
@@ -0,0 +1,21 @@
+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.
+copyrights:
+- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default: |
+    ${../basedefs/aligned:/name}( ${../../impl/cpu/stack-alignment:/name} )
+  variants: []
+description: null
+enabled-by: true
+interface-type: define
+links:
+- role: interface-placement
+  uid: header
+- role: interface-ingroup
+  uid: group
+name: RTEMS_TASK_STORAGE_ALIGNMENT
+notes: null
+type: interface
diff --git a/spec/if/rtems/tasks/storage-size.yml b/spec/if/rtems/tasks/storage-size.yml
new file mode 100644
index 00000000..3ae85838
--- /dev/null
+++ b/spec/if/rtems/tasks/storage-size.yml
@@ -0,0 +1,41 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Returns the recommended task storage area size for the specified size and task
+  attributes.
+copyrights:
+- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default: |
+    ( ( ${.:/params[0]/name} ) +
+      ( ( ( ${.:/params[1]/name} ) & ${../attr/floating-point:/name} ) != 0 ?
+        ${../../impl/context/fp-size:/name} : 0 ) )
+  variants:
+  - definition: |
+      ( ( ${.:/params[0]/name} ) + ${../../impl/context/fp-size:/name} )
+    enabled-by:
+    - ${../../impl/cpu/all-tasks-are-fp:/name} == ${../basedefs/true:/name}
+description: null
+enabled-by: true
+interface-type: macro
+links:
+- role: interface-placement
+  uid: header
+- role: interface-ingroup
+  uid: group
+name: RTEMS_TASK_STORAGE_SIZE
+notes: null
+params:
+- description: |
+    is the size dedicated to the task stack and thread-local storage in bytes.
+  dir: null
+  name: _size
+- description: |
+    is the attribute set of the task using the storage area.
+  dir: null
+  name: _attributes
+return:
+  return: |
+    The recommended task storage area size calculated from the input parameters
+    is returned.
+  return-values: []
+type: interface