[rtems-central commit] spec: Document the user extension manager
Sebastian Huber
sebh at rtems.org
Wed Sep 15 06:02:35 UTC 2021
Module: rtems-central
Branch: master
Commit: 94d88e4cdeb4527ca32efc2c22aecaf374cc0bf0
Changeset: http://git.rtems.org/rtems-central/commit/?id=94d88e4cdeb4527ca32efc2c22aecaf374cc0bf0
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Thu Sep 9 15:29:54 2021 +0200
spec: Document the user extension manager
---
spec/c/if/pthread-create.yml | 13 +++++
spec/constraint/interrupts-disabled-smp.yml | 12 +++++
spec/constraint/object-allocator-not-owner.yml | 11 +++++
spec/constraint/object-allocator-owner.yml | 11 +++++
.../thread-dispatching-disabled-init.yml | 11 +++++
spec/constraint/thread-dispatching-disabled.yml | 11 +++++
.../thread-dispatching-enabled-multitasking.yml | 11 +++++
spec/constraint/thread-dispatching-enabled.yml | 11 +++++
spec/constraint/thread-life-protected.yml | 11 +++++
.../constraint/object-allocator-pthread-create.yml | 12 +++++
.../userext/constraint/object-allocator-system.yml | 12 +++++
.../constraint/object-allocator-task-construct.yml | 12 +++++
.../constraint/object-allocator-task-create.yml | 12 +++++
spec/rtems/userext/if/create.yml | 10 ++--
spec/rtems/userext/if/fatal-code.yml | 13 +++--
spec/rtems/userext/if/fatal-source.yml | 10 ++--
spec/rtems/userext/if/fatal.yml | 36 ++++++++++++--
spec/rtems/userext/if/group.yml | 2 +-
spec/rtems/userext/if/header.yml | 2 +
spec/rtems/userext/if/table.yml | 8 ++--
spec/rtems/userext/if/task-begin.yml | 30 ++++++++++--
spec/rtems/userext/if/task-create.yml | 51 +++++++++++++++++---
spec/rtems/userext/if/task-delete.yml | 42 ++++++++++++++--
spec/rtems/userext/if/task-exitted.yml | 18 +++++--
spec/rtems/userext/if/task-restart.yml | 34 +++++++++++--
spec/rtems/userext/if/task-start.yml | 28 +++++++++--
spec/rtems/userext/if/task-switch.yml | 56 ++++++++++++++++++++--
spec/rtems/userext/if/task-terminate.yml | 31 ++++++++++--
spec/rtems/userext/req/group.yml | 20 ++++----
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 0000000..1841be3
--- /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 0000000..7d926fa
--- /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 0000000..0d2caba
--- /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 0000000..88311fa
--- /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 0000000..0ee90b3
--- /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 0000000..43959fb
--- /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 0000000..015d91f
--- /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 0000000..89b19b5
--- /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 0000000..4e96a42
--- /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 0000000..606ec48
--- /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 0000000..1618219
--- /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 0000000..bffc999
--- /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 0000000..26896df
--- /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 f4f2532..291a43f 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 811f5d0..9b36757 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 a200536..de18966 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 1ab0bf3..62f0938 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 8f4ada2..5658544 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 477e67e..aeb785c 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 472b9f1..4e085e0 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 56a2dde..d5e2242 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 8bf2d20..20ba5e9 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 62e10b1..2482262 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 241bcab..80c631a 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 fa01e68..a879325 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 ffbbbef..dd775b5 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 c167747..ed0a184 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 6d3a980..c92109a 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 75cf4ef..0c76e94 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
More information about the vc
mailing list