[rtems-central commit] spec: Add task entry glossary term

[Sebastian Huber]

Module:    rtems-central
Branch:    master
Commit:    b3a911efa72d6de5ef9acbdc8760039d673f2b77
Changeset: http://git.rtems.org/rtems-central/commit/?id=b3a911efa72d6de5ef9acbdc8760039d673f2b77

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Sat Jul 22 11:43:44 2023 +0200

spec: Add task entry glossary term

---

 spec-glossary/glossary/global-construction.yml        | 13 +++++++++++++
 spec-glossary/glossary/task-entry.yml                 | 18 ++++++++++++++++++
 spec/acfg/if/idle-task-init-appl.yml                  |  5 ++++-
 spec/acfg/if/posix-init-thread-table.yml              |  5 ++++-
 spec/acfg/if/rtems-init-tasks-table.yml               |  5 ++++-
 spec/doc/if/global-construction.yml                   | 19 +++++++++++++++++++
 spec/rtems/task/if/entry.yml                          |  2 +-
 spec/rtems/task/if/start.yml                          |  5 +++--
 .../req/global-construction-classic-before-entry.yml  |  5 +++--
 spec/score/thread/req/global-construction-classic.yml |  5 +++--
 .../thread/req/global-construction-constructors.yml   |  4 ++--
 .../thread/req/global-construction-preinit-array.yml  |  4 ++--
 spec/score/thread/val/thread.yml                      |  3 ++-
 13 files changed, 78 insertions(+), 15 deletions(-)

diff --git a/spec-glossary/glossary/global-construction.yml b/spec-glossary/glossary/global-construction.yml
new file mode 100644
index 00000000..f0e3a319
--- /dev/null
+++ b/spec-glossary/glossary/global-construction.yml
@@ -0,0 +1,13 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2023 embedded brains GmbH & Co. KG
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+  uid: ../glossary-general
+term: global construction
+text: |
+  In the global construction, the C++ global constructors and constructor
+  functions are invoked.  See ${/doc/if/global-construction:/name}.
+type: glossary
diff --git a/spec-glossary/glossary/task-entry.yml b/spec-glossary/glossary/task-entry.yml
new file mode 100644
index 00000000..c4778e17
--- /dev/null
+++ b/spec-glossary/glossary/task-entry.yml
@@ -0,0 +1,18 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2023 embedded brains GmbH & Co. KG
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+  uid: ../glossary-general
+term: task entry
+text: |
+  The task entry is invoked to execute the task's job.  Before the task entry
+  is invoked, the thread begin ${userextensions:/term} run in the context of
+  the task.  After the return of the task entry, the thread exitted user
+  extensions run in the context of the task.  The first user initialization
+  task performs the ${global-construction:/term} after running the thread begin
+  extensions and before the task entry is invoked.  See also
+  ${/rtems/task/if/start:/name}.
+type: glossary
diff --git a/spec/acfg/if/idle-task-init-appl.yml b/spec/acfg/if/idle-task-init-appl.yml
index ef843cce..080cd0bb 100644
--- a/spec/acfg/if/idle-task-init-appl.yml
+++ b/spec/acfg/if/idle-task-init-appl.yml
@@ -31,7 +31,7 @@ notes: |
   user IDLE task with the ${idle-task-body:/name} configuration option,
   otherwise a compile time error in the configuration file will occur.
 
-  The application shall define exactly one of the following configuration
+  The application shall define at least one of the following configuration
   options
 
   * ${rtems-init-tasks-table:/name},
@@ -41,4 +41,7 @@ notes: |
   * ``CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION``
 
   otherwise a compile time error in the configuration file will occur.
+
+  If no Classic API initialization task and no POSIX API initialization thread
+  is configured, then no ${/doc/if/global-construction:/name} is performed.
 type: interface
diff --git a/spec/acfg/if/posix-init-thread-table.yml b/spec/acfg/if/posix-init-thread-table.yml
index 26381f8b..11fc9a12 100644
--- a/spec/acfg/if/posix-init-thread-table.yml
+++ b/spec/acfg/if/posix-init-thread-table.yml
@@ -17,7 +17,7 @@ links:
   uid: ../constraint/option-not-pre-qualified
 name: CONFIGURE_POSIX_INIT_THREAD_TABLE
 notes: |
-  The application shall define exactly one of the following configuration
+  The application shall define at least one of the following configuration
   options
 
   * ${rtems-init-tasks-table:/name},
@@ -27,4 +27,7 @@ notes: |
   * ${idle-task-init-appl:/name}
 
   otherwise a compile time error in the configuration file will occur.
+
+  If no Classic API initialization task is configured, then the POSIX API
+  initialization thread performs the ${/doc/if/global-construction:/name}.
 type: interface
diff --git a/spec/acfg/if/rtems-init-tasks-table.yml b/spec/acfg/if/rtems-init-tasks-table.yml
index a8fcdf6a..6e5128d6 100644
--- a/spec/acfg/if/rtems-init-tasks-table.yml
+++ b/spec/acfg/if/rtems-init-tasks-table.yml
@@ -15,7 +15,7 @@ links:
   uid: group-classicinit
 name: CONFIGURE_RTEMS_INIT_TASKS_TABLE
 notes: |
-  The application shall define exactly one of the following configuration
+  The application shall define at least one of the following configuration
   options
 
   * ``CONFIGURE_RTEMS_INIT_TASKS_TABLE``,
@@ -25,4 +25,7 @@ notes: |
   * ${idle-task-init-appl:/name}
 
   otherwise a compile time error in the configuration file will occur.
+
+  The Classic API initialization task performs the
+  ${/doc/if/global-construction:/name}.
 type: interface
diff --git a/spec/doc/if/global-construction.yml b/spec/doc/if/global-construction.yml
new file mode 100644
index 00000000..60428326
--- /dev/null
+++ b/spec/doc/if/global-construction.yml
@@ -0,0 +1,19 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2023 embedded brains GmbH & Co. KG
+enabled-by: true
+index-entries: []
+interface-type: unspecified-group
+links:
+- role: interface-placement
+  uid: domain
+- role: interface-ingroup
+  uid: group
+name: Global Construction
+references:
+- identifier: GlobalConstruction
+  name: c-user
+  type: document
+- identifier: https://docs.rtems.org/branches/master/c-user/initialization/operations.html
+  type: url
+type: interface
diff --git a/spec/rtems/task/if/entry.yml b/spec/rtems/task/if/entry.yml
index 83836ac1..5c5e89a2 100644
--- a/spec/rtems/task/if/entry.yml
+++ b/spec/rtems/task/if/entry.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  This type defines the entry point of an RTEMS task.
+  This type defines the ${/glossary/task-entry:/term} point of an RTEMS task.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH & Co. KG
 - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR)
diff --git a/spec/rtems/task/if/start.yml b/spec/rtems/task/if/start.yml
index 07603648..09f1fc49 100644
--- a/spec/rtems/task/if/start.yml
+++ b/spec/rtems/task/if/start.yml
@@ -17,8 +17,9 @@ definition:
 description: |
   This directive readies the task, specified by ${.:/params[0]/name}, for
   execution based on the priority and execution mode specified when the task
-  was created.  The entry point of the task is given in ${.:/params[1]/name}.
-  The task's entry point argument is contained in ${.:/params[2]/name}.
+  was created.  The ${/glossary/task-entry:/term} point of the task is given in
+  ${.:/params[1]/name}.  The task's entry point argument is contained in
+  ${.:/params[2]/name}.
 enabled-by: true
 index-entries:
 - starting a task
diff --git a/spec/score/thread/req/global-construction-classic-before-entry.yml b/spec/score/thread/req/global-construction-classic-before-entry.yml
index 03fcdf99..2a4cad42 100644
--- a/spec/score/thread/req/global-construction-classic-before-entry.yml
+++ b/spec/score/thread/req/global-construction-classic-before-entry.yml
@@ -10,6 +10,7 @@ rationale: null
 references: []
 requirement-type: functional
 text: |
-  Where the global construction is done by the Classic API user initialization
-  task, the global construction shall be done before the task entry is called.
+  Where the ${/glossary/global-construction:/term} is done by the Classic API
+  user initialization task, the global construction shall be done before the
+  task entry is called.
 type: requirement
diff --git a/spec/score/thread/req/global-construction-classic.yml b/spec/score/thread/req/global-construction-classic.yml
index e4b9b00d..d282c09e 100644
--- a/spec/score/thread/req/global-construction-classic.yml
+++ b/spec/score/thread/req/global-construction-classic.yml
@@ -10,6 +10,7 @@ rationale: null
 references: []
 requirement-type: functional
 text: |
-  Where the Classic API user initialization task is configured, the global
-  construction shall be done by the Classic API user initialization task.
+  Where the Classic API user initialization task is configured, the
+  ${/glossary/global-construction:/term} shall be done by the Classic API user
+  initialization task.
 type: requirement
diff --git a/spec/score/thread/req/global-construction-constructors.yml b/spec/score/thread/req/global-construction-constructors.yml
index 9f43c77f..7540d471 100644
--- a/spec/score/thread/req/global-construction-constructors.yml
+++ b/spec/score/thread/req/global-construction-constructors.yml
@@ -10,6 +10,6 @@ rationale: null
 references: []
 requirement-type: functional
 text: |
-  When the global construction is done, the global constructors shall be
-  called.
+  When the ${/glossary/global-construction:/term} is done, the global
+  constructors shall be called.
 type: requirement
diff --git a/spec/score/thread/req/global-construction-preinit-array.yml b/spec/score/thread/req/global-construction-preinit-array.yml
index 50ff51ec..88e7b851 100644
--- a/spec/score/thread/req/global-construction-preinit-array.yml
+++ b/spec/score/thread/req/global-construction-preinit-array.yml
@@ -12,6 +12,6 @@ rationale: null
 references: []
 requirement-type: functional
 text: |
-  When the global construction is done, the handlers registered in the
-  ``.preinit_array`` table shall be called.
+  When the ${/glossary/global-construction:/term} is done, the handlers
+  registered in the ``.preinit_array`` table shall be called.
 type: requirement
diff --git a/spec/score/thread/val/thread.yml b/spec/score/thread/val/thread.yml
index aec9490b..23ecf414 100644
--- a/spec/score/thread/val/thread.yml
+++ b/spec/score/thread/val/thread.yml
@@ -116,7 +116,8 @@ test-actions:
     links: []
   links: []
 - action-brief: |
-    Validate the global construction.  Mark that the test case executed.
+    Validate the ${/glossary/global-construction:/term}.  Mark that the test
+    case executed.
   action-code: |
     test_case_executed = true;
   checks: