[PATCH v2] c-user: Link task entry and global construction

[Sebastian Huber]

---
v2: Mention global construction in application configuration options.

 c-user/config/classic-init-task.rst  |  5 ++++-
 c-user/config/idle-task.rst          |  5 ++++-
 c-user/config/posix-init-thread.rst  |  5 ++++-
 c-user/glossary.rst                  | 13 +++++++++++++
 c-user/initialization/operations.rst | 25 +++++++++++++++----------
 c-user/rtems_data_types.rst          |  2 +-
 c-user/task/directives.rst           |  6 +++---
 7 files changed, 44 insertions(+), 17 deletions(-)

diff --git a/c-user/config/classic-init-task.rst b/c-user/config/classic-init-task.rst
index 43ab95c..2f1baad 100644
--- a/c-user/config/classic-init-task.rst
+++ b/c-user/config/classic-init-task.rst
@@ -405,7 +405,7 @@ initialization task is configured.
 
 .. rubric:: 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``,
@@ -415,3 +415,6 @@ options
 * :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`
 
 otherwise a compile time error in the configuration file will occur.
+
+The Classic API initialization task performs the
+:ref:`GlobalConstruction`.
diff --git a/c-user/config/idle-task.rst b/c-user/config/idle-task.rst
index e98ad83..793fb5c 100644
--- a/c-user/config/idle-task.rst
+++ b/c-user/config/idle-task.rst
@@ -123,7 +123,7 @@ If this configuration option is defined, then it is mandatory to configure a
 user IDLE task with the :ref:`CONFIGURE_IDLE_TASK_BODY` 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
 
 * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`,
@@ -134,6 +134,9 @@ options
 
 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 :ref:`GlobalConstruction` is performed.
+
 .. Generated from spec:/acfg/if/idle-task-stack-size
 
 .. raw:: latex
diff --git a/c-user/config/posix-init-thread.rst b/c-user/config/posix-init-thread.rst
index 8a8b9b5..d4439a6 100644
--- a/c-user/config/posix-init-thread.rst
+++ b/c-user/config/posix-init-thread.rst
@@ -151,7 +151,7 @@ initialization thread is configured.
 
 .. rubric:: NOTES:
 
-The application shall define exactly one of the following configuration
+The application shall define at least one of the following configuration
 options
 
 * :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`,
@@ -162,6 +162,9 @@ options
 
 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 :ref:`GlobalConstruction`.
+
 .. rubric:: CONSTRAINTS:
 
 The configuration option is not included in the pre-qualified feature set of
diff --git a/c-user/glossary.rst b/c-user/glossary.rst
index 0962f44..8d86691 100644
--- a/c-user/glossary.rst
+++ b/c-user/glossary.rst
@@ -476,6 +476,10 @@ Glossary
         An object that has been created with the GLOBAL attribute and exported to
         all nodes in a multiprocessor system.
 
+    global construction
+        In the global construction, the C++ global constructors and constructor
+        functions are invoked.  See :ref:`GlobalConstruction`.
+
     GNAT
         *GNAT* is the :term:`GNU` compiler for Ada, integrated into the
         :term:`GCC`.
@@ -1379,6 +1383,15 @@ Glossary
         A data structure associated with each task used by RTEMS to manage that
         task.
 
+    task entry
+        The task entry is invoked to execute the task's job.  Before the task entry
+        is invoked, the thread begin :term:`user extensions` 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 :term:`global construction` after running the thread begin
+        extensions and before the task entry is invoked.  See also
+        :ref:`InterfaceRtemsTaskStart`.
+
     task migration
         Task migration happens in case a task stops execution on one processor
         and resumes execution on another processor.
diff --git a/c-user/initialization/operations.rst b/c-user/initialization/operations.rst
index db5c94b..e7d310c 100644
--- a/c-user/initialization/operations.rst
+++ b/c-user/initialization/operations.rst
@@ -285,19 +285,24 @@ Many of RTEMS actions during initialization are based upon the contents of the
 Configuration Table.  For more information regarding the format and contents of
 this table, please refer to the chapter :ref:`Configuring a System`.
 
+.. index:: global construction
+
+.. _GlobalConstruction:
+
 Global Construction
 -------------------
 
-The global construction is carried out by the first Classic API initialization
-task (first is defined by index zero in the Classic API initialization task
-configuration table).  If no Classic API initialization task exists, then it is
-carried out by the first POSIX API initialization thread.  If no initialization
-task or thread exists, then no global construction is performed, see for
-example :ref:`Specify Idle Task Performs Application Initialization`.  The
-Classic API task or POSIX API thread which carries out global construction is
-called the main thread.
-
-Global construction runs before the entry function of the main thread.  The
+The :term:`global construction` is carried out by the Classic API
+initialization task.  If no Classic API initialization task exists, then it is
+carried out by the POSIX API initialization thread.  If no initialization task
+or thread exists, then no global construction is performed.  The Classic API
+task or POSIX API thread which carries out global construction is called the
+main thread.  For configuration options related to initialization tasks, see
+:ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE`,
+:ref:`CONFIGURE_POSIX_INIT_THREAD_TABLE`, and
+:ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`.
+
+Global construction runs before the :term:`task entry` of the main thread.  The
 configuration of the main thread must take the global construction into
 account.  In particular, the main thread stack size, priority, attributes and
 initial modes must be set accordingly.  Thread-local objects and POSIX key
diff --git a/c-user/rtems_data_types.rst b/c-user/rtems_data_types.rst
index a311509..8e4274b 100644
--- a/c-user/rtems_data_types.rst
+++ b/c-user/rtems_data_types.rst
@@ -1523,7 +1523,7 @@ extension set.
 rtems_task_entry
 ----------------
 
-This type defines the entry point of an RTEMS task.
+This type defines the :term:`task entry` point of an RTEMS task.
 
 .. Generated from spec:/rtems/userext/if/task-exitted
 
diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst
index f4b65f5..d976905 100644
--- a/c-user/task/directives.rst
+++ b/c-user/task/directives.rst
@@ -624,9 +624,9 @@ Starts the task.
 .. rubric:: DESCRIPTION:
 
 This directive readies the task, specified by ``id``, for execution based on
-the priority and execution mode specified when the task was created.  The entry
-point of the task is given in ``entry_point``. The task's entry point argument
-is contained in ``argument``.
+the priority and execution mode specified when the task was created.  The
+:term:`task entry` point of the task is given in ``entry_point``.  The task's
+entry point argument is contained in ``argument``.
 
 .. rubric:: RETURN VALUES:
 
-- 
2.35.3