spec: Document the user extension manager

29 files changed, 468 insertions, 73 deletions

diff --git a/spec/c/if/pthread-create.yml b/spec/c/if/pthread-create.yml
new file mode 100644
index 00000000..1841be3a
--- /dev/null
+++ b/spec/c/if/pthread-create.yml
@@ -0,0 +1,13 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: pthread
+name: pthread_create
+references:
+  url: https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_create.html
+type: interface
diff --git a/spec/constraint/interrupts-disabled-smp.yml b/spec/constraint/interrupts-disabled-smp.yml
new file mode 100644
index 00000000..7d926fa4
--- /dev/null
+++ b/spec/constraint/interrupts-disabled-smp.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  Where the system was built with SMP support enabled, maskable interrupts are
+  disabled for the executing thread.
+type: constraint
diff --git a/spec/constraint/object-allocator-not-owner.yml b/spec/constraint/object-allocator-not-owner.yml
new file mode 100644
index 00000000..0d2caba2
--- /dev/null
+++ b/spec/constraint/object-allocator-not-owner.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  The executing thread is not the owner of the object allocator mutex.
+type: constraint
diff --git a/spec/constraint/object-allocator-owner.yml b/spec/constraint/object-allocator-owner.yml
new file mode 100644
index 00000000..88311fab
--- /dev/null
+++ b/spec/constraint/object-allocator-owner.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  The executing thread is the owner of the object allocator mutex.
+type: constraint
diff --git a/spec/constraint/thread-dispatching-disabled-init.yml b/spec/constraint/thread-dispatching-disabled-init.yml
new file mode 100644
index 00000000..0ee90b3d
--- /dev/null
+++ b/spec/constraint/thread-dispatching-disabled-init.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  While the system is initialized, thread dispatching is disabled.
+type: constraint
diff --git a/spec/constraint/thread-dispatching-disabled.yml b/spec/constraint/thread-dispatching-disabled.yml
new file mode 100644
index 00000000..43959fba
--- /dev/null
+++ b/spec/constraint/thread-dispatching-disabled.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  Thread dispatching is disabled.
+type: constraint
diff --git a/spec/constraint/thread-dispatching-enabled-multitasking.yml b/spec/constraint/thread-dispatching-enabled-multitasking.yml
new file mode 100644
index 00000000..015d91f3
--- /dev/null
+++ b/spec/constraint/thread-dispatching-enabled-multitasking.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  While the system is in the multitasking state, thread dispatching is enabled.
+type: constraint
diff --git a/spec/constraint/thread-dispatching-enabled.yml b/spec/constraint/thread-dispatching-enabled.yml
new file mode 100644
index 00000000..89b19b51
--- /dev/null
+++ b/spec/constraint/thread-dispatching-enabled.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  Thread dispatching is enabled.
+type: constraint
diff --git a/spec/constraint/thread-life-protected.yml b/spec/constraint/thread-life-protected.yml
new file mode 100644
index 00000000..4e96a420
--- /dev/null
+++ b/spec/constraint/thread-life-protected.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  Thread life is protected.
+type: constraint
diff --git a/spec/rtems/userext/constraint/object-allocator-pthread-create.yml b/spec/rtems/userext/constraint/object-allocator-pthread-create.yml
new file mode 100644
index 00000000..606ec483
--- /dev/null
+++ b/spec/rtems/userext/constraint/object-allocator-pthread-create.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  While a task is created by ${/c/if/pthread-create:/name}, the executing
+  thread is the owner of the object allocator mutex.
+type: constraint
diff --git a/spec/rtems/userext/constraint/object-allocator-system.yml b/spec/rtems/userext/constraint/object-allocator-system.yml
new file mode 100644
index 00000000..1618219a
--- /dev/null
+++ b/spec/rtems/userext/constraint/object-allocator-system.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  While an idle thread or another internal system thread is created, the object
+  allocator mutex has no owner.
+type: constraint
diff --git a/spec/rtems/userext/constraint/object-allocator-task-construct.yml b/spec/rtems/userext/constraint/object-allocator-task-construct.yml
new file mode 100644
index 00000000..bffc999a
--- /dev/null
+++ b/spec/rtems/userext/constraint/object-allocator-task-construct.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  While a task is constructed by ${../../task/if/construct:/name}, the
+  executing thread is the owner of the object allocator mutex.
+type: constraint
diff --git a/spec/rtems/userext/constraint/object-allocator-task-create.yml b/spec/rtems/userext/constraint/object-allocator-task-create.yml
new file mode 100644
index 00000000..26896dfe
--- /dev/null
+++ b/spec/rtems/userext/constraint/object-allocator-task-create.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  While a task is created by ${../../task/if/create:/name}, the executing
+  thread is the owner of the object allocator mutex.
+type: constraint
diff --git a/spec/rtems/userext/if/create.yml b/spec/rtems/userext/if/create.yml
index f4f25323..291a43fa 100644
--- a/spec/rtems/userext/if/create.yml
+++ b/spec/rtems/userext/if/create.yml
@@ -42,11 +42,15 @@ links:
   uid: ../constraint/max
 name: rtems_extension_create
 notes: |
-  The user-provided extension set table is not used after the return of the
+  The user-provided extension table is not used after the return of the
   directive.
 
-  Newly created extension sets are immediately installed and are invoked upon
-  the next system event supporting an extension.
+  Each extension of the extension table is optional and may be
+  ${/c/if/null:/name}.  All extensions except the task switch extension of the
+  extension table are atomically and immediately installed.  A task switch
+  extension is separately installed after the other extensions.  The extensions
+  of the extension table are invoked upon the next system event supporting an
+  extension.
 
   An alternative to dynamically created extension sets are initial extensions,
   see ${/acfg/if/initial-extensions:/name}.  Initial extensions are recommended
diff --git a/spec/rtems/userext/if/fatal-code.yml b/spec/rtems/userext/if/fatal-code.yml
index 811f5d07..9b36757c 100644
--- a/spec/rtems/userext/if/fatal-code.yml
+++ b/spec/rtems/userext/if/fatal-code.yml
@@ -1,12 +1,13 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This integer type represents system termination codes.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default: ${/score/interr/if/code:/name} ${.:/name}
   variants: []
-description: null
+description: |
+  This integer type is large enough to store a 32-bit integer or a pointer.
 enabled-by: true
 index-entries: []
 interface-type: typedef
@@ -16,7 +17,9 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_fatal_code
-notes: null
+notes: |
+  The interpretation of a system termination code depends on the system
+  termination source, see ${fatal-source:/name}.
 params: []
 return: null
 type: interface
diff --git a/spec/rtems/userext/if/fatal-source.yml b/spec/rtems/userext/if/fatal-source.yml
index a2005366..de189663 100644
--- a/spec/rtems/userext/if/fatal-source.yml
+++ b/spec/rtems/userext/if/fatal-source.yml
@@ -1,8 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This enumeration represents system termination sources.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default: ${/score/interr/if/source:/name} ${.:/name}
   variants: []
@@ -16,7 +16,9 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_fatal_source
-notes: null
+notes: |
+  The system termination code may provide additional information depending on
+  the system termination source, see ${fatal-code:/name}.
 params: []
 return: null
 type: interface
diff --git a/spec/rtems/userext/if/fatal.yml b/spec/rtems/userext/if/fatal.yml
index 1ab0bf37..62f09387 100644
--- a/spec/rtems/userext/if/fatal.yml
+++ b/spec/rtems/userext/if/fatal.yml
@@ -1,8 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Fatal extensions are invoked when the system should terminate.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default: ${/score/userext/if/fatal:/name} ${.:/name}
   variants: []
@@ -16,7 +16,33 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_fatal_extension
-notes: null
-params: []
+notes: |
+  The fatal extensions are invoked in
+  ${/glossary/extension-forward-order:/term}.
+
+  The fatal extension should be extremely careful with respect to the RTEMS
+  directives it calls.  Depending on the system termination source, the system
+  may be in an undefined and corrupt state.
+  
+  It is recommended to register fatal extensions through
+  ${/glossary/initial-extension-sets:/term}, see
+  ${/acfg/if/initial-extensions:/name}.
+params:
+- description: |
+    is the system termination source.  The source indicates the component which
+    caused the system termination request, see ${fatal-source:/name}.  The
+    system termination code may provide additional information related to the
+    system termination request.
+  dir: null
+  name: source
+- description: |
+    is a value equal to ${/c/if/false:/name}.
+  dir: null
+  name: always_set_to_false
+- description: |
+    is the system termination code.  This value must be interpreted with
+    respect to the source.
+  dir: null
+  name: code
 return: null
 type: interface
diff --git a/spec/rtems/userext/if/group.yml b/spec/rtems/userext/if/group.yml
index 8f4ada2d..56585442 100644
--- a/spec/rtems/userext/if/group.yml
+++ b/spec/rtems/userext/if/group.yml
@@ -8,7 +8,7 @@ copyrights:
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 description: null
 enabled-by: true
-identifier: RTEMSAPIClassicUserext
+identifier: RTEMSAPIClassicUserExt
 index-entries: []
 interface-type: group
 links:
diff --git a/spec/rtems/userext/if/header.yml b/spec/rtems/userext/if/header.yml
index 477e67e7..aeb785c0 100644
--- a/spec/rtems/userext/if/header.yml
+++ b/spec/rtems/userext/if/header.yml
@@ -8,6 +8,8 @@ interface-type: header-file
 links:
 - role: interface-placement
   uid: /if/domain
+- role: interface-ingroup
+  uid: ../req/group
 path: rtems/extension.h
 prefix: cpukit/include
 type: interface
diff --git a/spec/rtems/userext/if/table.yml b/spec/rtems/userext/if/table.yml
index 472b9f1b..4e085e0d 100644
--- a/spec/rtems/userext/if/table.yml
+++ b/spec/rtems/userext/if/table.yml
@@ -1,8 +1,10 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  The extensions table contains a set of extensions which may be registered in
+  the system through the ${/acfg/if/initial-extensions:/name} application
+  configuration option or the ${../if/create:/name} directive.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default: ${/score/userext/if/table:/name} ${.:/name}
   variants: []
diff --git a/spec/rtems/userext/if/task-begin.yml b/spec/rtems/userext/if/task-begin.yml
index 56a2dde8..d5e22426 100644
--- a/spec/rtems/userext/if/task-begin.yml
+++ b/spec/rtems/userext/if/task-begin.yml
@@ -1,8 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Task begin extensions are invoked when a task begins execution.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default: ${/score/userext/if/thread-begin:/name} ${.:/name}
   variants: []
@@ -15,8 +15,28 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/thread-dispatching-enabled
+- role: constraint
+  uid: /constraint/object-allocator-not-owner
 name: rtems_task_begin_extension
-notes: null
-params: []
+notes: |
+  The task begin extensions are invoked in
+  ${/glossary/extension-forward-order:/term}.
+
+  Task begin extensions are invoked with thread dispatching enabled.  This
+  allows the use of dynamic memory allocation, creation of POSIX keys, and use
+  of C++ thread-local storage.  Blocking synchronization primitives are allowed
+  also.
+
+  The task begin extensions are invoked before the global construction.
+
+  The task begin extensions may be called as a result of a task restart through
+  ${../../task/if/restart:/name}.
+params:
+- description: |
+    is the ${/glossary/tcb:/term} of the executing thread.
+  dir: null
+  name: executing
 return: null
 type: interface
diff --git a/spec/rtems/userext/if/task-create.yml b/spec/rtems/userext/if/task-create.yml
index 8bf2d20c..20ba5e97 100644
--- a/spec/rtems/userext/if/task-create.yml
+++ b/spec/rtems/userext/if/task-create.yml
@@ -1,8 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Task create extensions are invoked when a task is created.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default: ${/score/userext/if/thread-create:/name} ${.:/name}
   variants: []
@@ -15,8 +15,47 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/thread-dispatching-disabled-init
+- role: constraint
+  uid: /constraint/thread-dispatching-enabled-multitasking
+- role: constraint
+  uid: ../constraint/object-allocator-system
+- role: constraint
+  uid: ../constraint/object-allocator-task-create
+- role: constraint
+  uid: ../constraint/object-allocator-task-construct
+- role: constraint
+  uid: ../constraint/object-allocator-pthread-create
 name: rtems_task_create_extension
-notes: null
-params: []
-return: null
+notes: |
+  The task create extensions are invoked in
+  ${/glossary/extension-forward-order:/term}.
+
+  The task create extensions are invoked after a new task has been completely
+  initialized, but before it is started.
+
+  While normal tasks are created, the executing thread is the owner of the
+  object allocator mutex.  The object allocator mutex allows nesting, so the
+  normal memory allocation routines can be used allocate memory for the created
+  thread.
+
+  If the task create extension returns ${/c/if/false:/name}, then the task
+  create operation stops immediately and the entire task create operation will
+  fail.  In this case, all task delete extensions are invoked, see
+  ${task-delete:/name}.
+params:
+- description: |
+    is the ${/glossary/tcb:/term} of the executing thread.  When the idle
+    thread is created, the executing thread is equal to ${/c/if/null:/name}.
+  dir: null
+  name: executing
+- description: |
+    is the ${/glossary/tcb:/term} of the created thread.
+  dir: null
+  name: created
+return:
+  return: |
+    Returns true, if the task create extension was successful, otherwise false.
+  return-values: []
 type: interface
diff --git a/spec/rtems/userext/if/task-delete.yml b/spec/rtems/userext/if/task-delete.yml
index 62e10b16..24822625 100644
--- a/spec/rtems/userext/if/task-delete.yml
+++ b/spec/rtems/userext/if/task-delete.yml
@@ -1,8 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Task delete extensions are invoked when a task is deleted.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default: ${/score/userext/if/thread-delete:/name} ${.:/name}
   variants: []
@@ -15,8 +15,40 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/thread-dispatching-disabled-init
+- role: constraint
+  uid: /constraint/thread-dispatching-enabled-multitasking
+- role: constraint
+  uid: ../constraint/object-allocator-system
+- role: constraint
+  uid: ../constraint/object-allocator-task-create
+- role: constraint
+  uid: ../constraint/object-allocator-task-construct
+- role: constraint
+  uid: ../constraint/object-allocator-pthread-create
 name: rtems_task_delete_extension
-notes: null
-params: []
+notes: |
+  The task delete extensions are invoked in
+  ${/glossary/extension-reverse-order:/term}.
+
+  The task delete extensions are invoked by task create directives before an
+  attempt to allocate a ${/glossary/tcb:/term} is made.
+
+  If a task create extension failed, then a task delete extension may be
+  invoked without a previous invocation of the corresponding task create
+  extension of the extension set.
+params:
+- description: |
+    is the ${/glossary/tcb:/term} of the executing thread.  If the idle thread
+    is created and one of the initial task create extension fails, then the
+    executing thread is equal to ${/c/if/null:/name}.
+  dir: null
+  name: executing
+- description: |
+    is the ${/glossary/tcb:/term} of the deleted thread.  The executing and
+    deleted arguments are never equal.
+  dir: null
+  name: created
 return: null
 type: interface
diff --git a/spec/rtems/userext/if/task-exitted.yml b/spec/rtems/userext/if/task-exitted.yml
index 241bcab1..80c631a3 100644
--- a/spec/rtems/userext/if/task-exitted.yml
+++ b/spec/rtems/userext/if/task-exitted.yml
@@ -1,8 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Task exitted extensions are invoked when a task entry returns.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default: ${/score/userext/if/thread-exitted:/name} ${.:/name}
   variants: []
@@ -15,8 +15,16 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/thread-dispatching-enabled
 name: rtems_task_exitted_extension
-notes: null
-params: []
+notes: |
+  The task exitted extensions are invoked in
+  ${/glossary/extension-forward-order:/term}.
+params:
+- description: |
+    is the ${/glossary/tcb:/term} of the executing thread.
+  dir: null
+  name: executing
 return: null
 type: interface
diff --git a/spec/rtems/userext/if/task-restart.yml b/spec/rtems/userext/if/task-restart.yml
index fa01e689..a8793259 100644
--- a/spec/rtems/userext/if/task-restart.yml
+++ b/spec/rtems/userext/if/task-restart.yml
@@ -1,8 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Task restart extensions are invoked when a task restarts.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default: ${/score/userext/if/thread-restart:/name} ${.:/name}
   variants: []
@@ -15,8 +15,32 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/thread-dispatching-enabled
+- role: constraint
+  uid: /constraint/thread-life-protected
+- role: constraint
+  uid: /constraint/object-allocator-not-owner
 name: rtems_task_restart_extension
-notes: null
-params: []
+notes: |
+  The task restart extensions are invoked in
+  ${/glossary/extension-forward-order:/term}.
+
+  The task restart extensions are invoked in the context of the restarted
+  thread right before the execution context is reloaded.  The thread stack
+  reflects the previous execution context.
+
+  Thread restart and delete requests issued by restart extensions lead to
+  recursion.
+params:
+- description: |
+    is the ${/glossary/tcb:/term} of the executing thread.
+  dir: null
+  name: executing
+- description: |
+    is the ${/glossary/tcb:/term} of the executing thread.  Yes, the executing
+    thread.
+  dir: null
+  name: restarted
 return: null
 type: interface
diff --git a/spec/rtems/userext/if/task-start.yml b/spec/rtems/userext/if/task-start.yml
index ffbbbef8..dd775b53 100644
--- a/spec/rtems/userext/if/task-start.yml
+++ b/spec/rtems/userext/if/task-start.yml
@@ -1,8 +1,9 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Task start extensions are invoked when a task was made ready for the first
+  time.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default: ${/score/userext/if/thread-start:/name} ${.:/name}
   variants: []
@@ -15,8 +16,25 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/thread-dispatching-disabled
 name: rtems_task_start_extension
-notes: null
-params: []
+notes: |
+  The task start extensions are invoked in
+  ${/glossary/extension-forward-order:/term}.
+
+  In SMP configurations, the thread may already run on another processor before
+  the task start extensions are actually invoked.  Task switch and task begin
+  extensions may run before or in parallel with the thread start extension in
+  SMP configurations, see ${task-switch:/name} and ${task-begin:/name}.
+params:
+- description: |
+    is the ${/glossary/tcb:/term} of the executing thread.
+  dir: null
+  name: executing
+- description: |
+    is the ${/glossary/tcb:/term} of the started thread.
+  dir: null
+  name: started
 return: null
 type: interface
diff --git a/spec/rtems/userext/if/task-switch.yml b/spec/rtems/userext/if/task-switch.yml
index c167747e..ed0a184f 100644
--- a/spec/rtems/userext/if/task-switch.yml
+++ b/spec/rtems/userext/if/task-switch.yml
@@ -1,8 +1,9 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Task switch extensions are invoked when a thread switch from an executing
+  thread to a heir thread takes place.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default: ${/score/userext/if/thread-switch:/name} ${.:/name}
   variants: []
@@ -15,8 +16,53 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/thread-dispatching-disabled
+- role: constraint
+  uid: /constraint/interrupts-disabled-smp
 name: rtems_task_switch_extension
-notes: null
-params: []
+notes: |
+  The task switch extensions are invoked in
+  ${/glossary/extension-forward-order:/term}.
+
+  The invocation conditions of the task switch extensions depend on whether
+  RTEMS was built with SMP support enabled or disabled.  A user must pay
+  attention to the differences to correctly implement a task switch extension.
+
+  Where the system was built with SMP support disabled, the task switch
+  extensions are invoked before the context switch from the currently executing
+  thread to the heir thread.  The ${.:/params[0]/name} is a pointer to the
+  ${/glossary/tcb:/term} of the currently executing thread. The
+  ${.:/params[1]/name} is a pointer to the TCB of the heir thread.  The context
+  switch initiated through the multitasking start is not covered by the task
+  switch extensions.
+
+  Where the system was built with SMP support enabled, the task switch
+  extensions are invoked after the context switch to the heir thread.  The
+  ${.:/params[0]/name} is a pointer to the TCB of the previously executing
+  thread. Despite the name, this is not the currently executing thread. The
+  ${.:/params[1]/name} is a pointer to the TCB of the newly executing thread.
+  This is the currently executing thread. The context switches initiated
+  through the multitasking start are covered by the task switch extensions.
+  The reason for the differences to uniprocessor configurations is that the
+  context switch may update the heir thread of the processor.  The task switch
+  extensions are invoked with maskable interrupts disabled and with ownership
+  of a processor-specific SMP lock.  Task switch extensions may run in parallel
+  on multiple processors.  It is recommended to use thread-local or
+  processor-specific data structures for task switch extensions.  A global SMP
+  lock should be avoided for performance reasons, see
+  ${../../intr/if/lock-initialize:/name}.
+params:
+- description: |
+    is the ${/glossary/tcb:/term} of the executing thread.  In SMP
+    configurations, this is the previously executing thread also known as the
+    ancestor thread.
+  dir: null
+  name: executing
+- description: |
+    is the ${/glossary/tcb:/term} of the heir thread.  In SMP configurations,
+    this is the executing thread.
+  dir: null
+  name: heir
 return: null
 type: interface
diff --git a/spec/rtems/userext/if/task-terminate.yml b/spec/rtems/userext/if/task-terminate.yml
index 6d3a9808..c92109a3 100644
--- a/spec/rtems/userext/if/task-terminate.yml
+++ b/spec/rtems/userext/if/task-terminate.yml
@@ -1,8 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Task terminate extensions are invoked when a task terminates.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default: ${/score/userext/if/thread-terminate:/name} ${.:/name}
   variants: []
@@ -15,8 +15,29 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/thread-dispatching-enabled
+- role: constraint
+  uid: /constraint/thread-life-protected
+- role: constraint
+  uid: /constraint/object-allocator-not-owner
 name: rtems_task_terminate_extension
-notes: null
-params: []
+notes: |
+  The task terminate extensions are invoked in
+  ${/glossary/extension-reverse-order:/term}.
+
+  The task terminate extensions are invoked in the context of the terminating
+  thread right before the thread dispatch to the heir thread should take place.
+  The thread stack reflects the previous execution context.  The POSIX cleanup
+  and key destructors execute in this context.
+
+  Thread restart and delete requests issued by terminate extensions lead to
+  recursion.
+params:
+- description: |
+    is the ${/glossary/tcb:/term} of the executing thread.  This is the
+    terminating thread.
+  dir: null
+  name: executing
 return: null
 type: interface
diff --git a/spec/rtems/userext/req/group.yml b/spec/rtems/userext/req/group.yml
index 75cf4efb..0c76e947 100644
--- a/spec/rtems/userext/req/group.yml
+++ b/spec/rtems/userext/req/group.yml
@@ -1,18 +1,16 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: |
-  This group contains the User Extension Manager implementation.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-description: null
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 enabled-by: true
-identifier: ClassicUserExtensionsImpl
-index-entries: []
-interface-type: group
+identifier: RTEMSImplClassicUserExt
 links:
 - role: interface-ingroup
-  uid: ../../if/group
-name: User Extension Manager
+  uid: /req/impl
+non-functional-type: design-group
+rationale: null
+references: []
+requirement-type: non-functional
 text: |
   The software architecture shall have a component containing the User
-  Extension Manager implementation.
-type: interface
+  Extensions Manager implementation.
+type: requirement