[rtems-docs commit] c-user: Document global construction

[Sebastian Huber]

Module:    rtems-docs
Branch:    master
Commit:    674b71470bf666cde68656b0d602d0d3dc8443f3
Changeset: http://git.rtems.org/rtems-docs/commit/?id=674b71470bf666cde68656b0d602d0d3dc8443f3

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Wed Nov 22 13:42:18 2017 +0100

c-user: Document global construction

Close #3243.

---

 c-user/fatal_error.rst    |  5 ----
 c-user/initialization.rst | 74 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+), 5 deletions(-)

diff --git a/c-user/fatal_error.rst b/c-user/fatal_error.rst
index b2fe4e1..d8566f0 100644
--- a/c-user/fatal_error.rst
+++ b/c-user/fatal_error.rst
@@ -244,11 +244,6 @@ INTERNAL_ERROR_RTEMS_INIT_TASK_ENTRY_IS_NULL (26)
     occur during system initialization.  It is an application configuration
     error.
 
-INTERNAL_ERROR_POSIX_INIT_THREAD_ENTRY_IS_NULL (27)
-    A POSIX initialization thread entry function is NULL.  This fatal error may
-    occur during system initialization.  It is an application configuration
-    error.
-
 INTERNAL_ERROR_THREAD_QUEUE_DEADLOCK (28)
     A deadlock was detected during a thread queue enqueue operation.
 
diff --git a/c-user/initialization.rst b/c-user/initialization.rst
index 2bbd166..def5480 100644
--- a/c-user/initialization.rst
+++ b/c-user/initialization.rst
@@ -278,6 +278,80 @@ 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`.
 
+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
+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
+values created during global construction are accessible by the main thread.
+If other initialization tasks are configured, and one of them has a higher
+priority than the main thread and the main thread is preemptible, this task
+executes before the global construction.  In case the main thread blocks during
+global construction, then other tasks may run.  In SMP configurations, other
+initialization tasks may run in parallel with global construction.  Tasks
+created during global construction may preempt the main thread or run in
+parallel in SMP configurations.  All RTEMS services allowed in task context are
+allowed during global construction.
+
+Global constructors are C++ global object constructors or functions with the
+constructor attribute.  For example, the following test program
+
+.. code-block:: c
+
+    #include <stdio.h>
+    #include <assert.h>
+
+    class A {
+      public:
+        A()
+        {
+          puts( "A:A()" );
+        }
+    };
+
+    static A a;
+
+    static thread_local int i;
+
+    static thread_local int j;
+
+    static __attribute__(( __constructor__ )) void b( void )
+    {
+      i = 1;
+      puts( "b()" );
+    }
+
+    static __attribute__(( __constructor__( 1000 ) )) void c( void )
+    {
+      puts( "c()" );
+    }
+
+    int main( void )
+    {
+      assert( i == 1 );
+      assert( j == 0 );
+      return 0;
+    }
+
+should output:
+
+.. code-block:: shell
+
+    c()
+    b()
+    A:A()
+
 Directives
 ==========