source: rtems-docs/c-user/initialization.rst @ 464d541

5
Last change on this file since 464d541 was 674b714, checked in by Sebastian Huber <sebastian.huber@…>, on 11/22/17 at 12:42:18

c-user: Document global construction

Close #3243.

  • Property mode set to 100644
File size: 14.2 KB
Line 
1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. COMMENT: COPYRIGHT (c) 1988-2008.
4.. COMMENT: On-Line Applications Research Corporation (OAR).
5.. COMMENT: All rights reserved.
6
7Initialization Manager
8**********************
9
10Introduction
11============
12
13The Initialization Manager is responsible for initializing the Board Support
14Package, RTEMS, device drivers, the root filesystem and the application.  The
15:ref:`Fatal Error Manager <fatal_error_manager>` is responsible for the system
16shutdown.
17
18The Initialization Manager provides only one directive:
19
20- rtems_initialize_executive_ - Initialize RTEMS
21
22Background
23==========
24
25.. index:: initialization tasks
26
27Initialization Tasks
28--------------------
29
30Initialization task(s) are the mechanism by which RTEMS transfers initial
31control to the user's application.  Initialization tasks differ from other
32application tasks in that they are defined in the User Initialization Tasks
33Table and automatically created and started by RTEMS as part of its
34initialization sequence.  Since the initialization tasks are scheduled using
35the same algorithm as all other RTEMS tasks, they must be configured at a
36priority and mode which will ensure that they will complete execution before
37other application tasks execute.  Although there is no upper limit on the
38number of initialization tasks, an application is required to define at least
39one.
40
41A typical initialization task will create and start the static set of
42application tasks.  It may also create any other objects used by the
43application.  Initialization tasks which only perform initialization should
44delete themselves upon completion to free resources for other tasks.
45Initialization tasks may transform themselves into a "normal" application task.
46This transformation typically involves changing priority and execution mode.
47RTEMS does not automatically delete the initialization tasks.
48
49The Idle Task
50-------------
51
52The Idle Task is the lowest priority task in a system and executes only when no
53other task is ready to execute.  The default implementation of this task
54consists of an infinite loop. RTEMS allows the Idle Task body to be replaced by
55a CPU specific implementation, a BSP specific implementation or an application
56specific implementation.
57
58The Idle Task is preemptible and *WILL* be preempted when any other task is
59made ready to execute.  This characteristic is critical to the overall behavior
60of any application.
61
62Initialization Manager Failure
63------------------------------
64
65System initialization errors are fatal.  See :ref:`internal_errors`.
66
67Operations
68==========
69
70Initializing RTEMS
71------------------
72
73The Initialization Manager :c:func:`rtems_initialize_executive()` directives is
74called by the :c:func:`boot_card()` routine which is invoked by the Board
75Support Package once a basic C run-time environment is set up.  This consists
76of
77
78- a valid and accessible text section, read-only data, read-write data and
79  zero-initialized data,
80
81- an initialization stack large enough to initialize the rest of the Board
82  Support Package, RTEMS and the device drivers,
83
84- all registers and components mandated by Application Binary Interface, and
85
86- disabled interrupts.
87
88The :c:func:`rtems_initialize_executive()` directive uses a system
89initialization :ref:`linker set <linker_sets>` to initialize only those parts
90of the overall RTEMS feature set that is necessary for a particular
91application.  Each RTEMS feature used the application may optionally register
92an initialization handler.  The system initialization API is available via
93:samp:`#included <rtems/sysinit.h>`.
94
95A list of all initialization steps follows.  Some steps are optional depending
96on the requested feature set of the application.  The initialization steps are
97execute in the order presented here.
98
99RTEMS_SYSINIT_BSP_WORK_AREAS
100    The work areas consisting of C Program Heap and the RTEMS Workspace are
101    initialized by the Board Support Package.  This step is mandatory.
102
103RTEMS_SYSINIT_BSP_START
104    Basic initialization step provided by the Board Support Package.  This step
105    is mandatory.
106
107RTEMS_SYSINIT_INITIAL_EXTENSIONS
108    Registers the initial extensions.  This step is optional and depends on the
109    application configuration.
110
111RTEMS_SYSINIT_MP_EARLY
112    Early MPCI initialization.  This step is mandatory on MPCI configurations.
113
114RTEMS_SYSINIT_DATA_STRUCTURES
115    This directive is called when the Board Support Package has completed its
116    basic initialization and allows RTEMS to initialize the application
117    environment based upon the information in the Configuration Table, User
118    Initialization Tasks Table, Device Driver Table, User Extension Table,
119    Multiprocessor Configuration Table, and the Multiprocessor Communications
120    Interface (MPCI) Table.
121
122RTEMS_SYSINIT_CPU_SET
123    Initialization of system CPU set.  This step is optional and depends on the
124    application configuration.
125
126RTEMS_SYSINIT_MP
127    MPCI initialization.  This step is mandatory on MPCI configurations.
128
129RTEMS_SYSINIT_USER_EXTENSIONS
130    Initialization of the User Extensions object class.  This step is optional
131    and depends on the application configuration.
132
133RTEMS_SYSINIT_CLASSIC_TASKS
134    Initialization of the Classic Tasks object class.  This step is optional
135    and depends on the application configuration.
136
137RTEMS_SYSINIT_CLASSIC_TIMER
138    Initialization of the Classic Timer object class.  This step is optional
139    and depends on the application configuration.
140
141RTEMS_SYSINIT_CLASSIC_SIGNAL
142    Initialization of the Classic Signal support.  This step is optional and
143    depends on the application configuration.
144
145RTEMS_SYSINIT_CLASSIC_EVENT
146    Initialization of the Classic Event support.  This step is optional and
147    depends on the application configuration.  This step is only used on MPCI
148    configurations.
149
150RTEMS_SYSINIT_CLASSIC_MESSAGE_QUEUE
151    Initialization of the Classic Message Queue object class.  This step is
152    optional and depends on the application configuration.
153
154RTEMS_SYSINIT_CLASSIC_SEMAPHORE
155    Initialization of the Classic Semaphore object class.  This step is
156    optional and depends on the application configuration.
157
158RTEMS_SYSINIT_CLASSIC_PARTITION
159    Initialization of the Classic Partition object class.  This step is
160    optional and depends on the application configuration.
161
162RTEMS_SYSINIT_CLASSIC_REGION
163    Initialization of the Classic Region object class.  This step is optional
164    and depends on the application configuration.
165
166RTEMS_SYSINIT_CLASSIC_DUAL_PORTED_MEMORY
167    Initialization of the Classic Dual-Ported Memory object class.  This step
168    is optional and depends on the application configuration.
169
170RTEMS_SYSINIT_CLASSIC_RATE_MONOTONIC
171    Initialization of the Classic Rate-Monotonic object class.  This step is
172    optional and depends on the application configuration.
173
174RTEMS_SYSINIT_CLASSIC_BARRIER
175    Initialization of the Classic Barrier object class.  This step is optional
176    and depends on the application configuration.
177
178RTEMS_SYSINIT_POSIX_SIGNALS
179    Initialization of the POSIX Signals support.  This step is optional and
180    depends on the application configuration.
181
182RTEMS_SYSINIT_POSIX_THREADS
183    Initialization of the POSIX Threads object class.  This step is optional
184    and depends on the application configuration.
185
186RTEMS_SYSINIT_POSIX_MESSAGE_QUEUE
187    Initialization of the POSIX Message Queue object class.  This step is
188    optional and depends on the application configuration.
189
190RTEMS_SYSINIT_POSIX_SEMAPHORE
191    Initialization of the POSIX Semaphore object class.  This step is optional
192    and depends on the application configuration.
193
194RTEMS_SYSINIT_POSIX_TIMER
195    Initialization of the POSIX Timer object class.  This step is optional and
196    depends on the application configuration.
197
198RTEMS_SYSINIT_POSIX_KEYS
199    Initialization of the POSIX Keys object class.  This step is optional
200    and depends on the application configuration.
201
202RTEMS_SYSINIT_POSIX_CLEANUP
203    Initialization of the POSIX Cleanup support.  This step is optional and
204    depends on the application configuration.
205
206RTEMS_SYSINIT_IDLE_THREADS
207    Initialization of idle threads.  This step is mandatory.
208
209RTEMS_SYSINIT_LIBIO
210    Initialization of IO library.  This step is optional and depends on the
211    application configuration.
212
213RTEMS_SYSINIT_ROOT_FILESYSTEM
214    Initialization of the root filesystem.  This step is optional and depends
215    on the application configuration.
216
217RTEMS_SYSINIT_DRVMGR
218    Driver manager initialization.  This step is optional and depends on the
219    application configuration.  Only available if the driver manager is
220    enabled.
221
222RTEMS_SYSINIT_MP_SERVER
223    MPCI server initialization.  This step is mandatory on MPCI configurations.
224
225RTEMS_SYSINIT_BSP_PRE_DRIVERS
226    Initialization step performed right before device drivers are initialized.
227    This step is mandatory.
228
229RTEMS_SYSINIT_DRVMGR_LEVEL_1
230    Driver manager level 1 initialization.  This step is optional and depends
231    on the application configuration.  Only available if the driver manager is
232    enabled.
233
234RTEMS_SYSINIT_DEVICE_DRIVERS
235    This step initializes all statically configured device drivers and performs
236    all RTEMS initialization which requires device drivers to be initialized.
237    This step is mandatory.  In a multiprocessor configuration, this service
238    will initialize the Multiprocessor Communications Interface (MPCI) and
239    synchronize with the other nodes in the system.
240
241RTEMS_SYSINIT_DRVMGR_LEVEL_2
242    Driver manager level 2 initialization.  This step is optional and depends
243    on the application configuration.  Only available if the driver manager is
244    enabled.
245
246RTEMS_SYSINIT_DRVMGR_LEVEL_3
247    Driver manager level 3 initialization.  This step is optional and depends
248    on the application configuration.  Only available if the driver manager is
249    enabled.
250
251RTEMS_SYSINIT_DRVMGR_LEVEL_4
252    Driver manager level 4 initialization.  This step is optional and depends
253    on the application configuration.  Only available if the driver manager is
254    enabled.
255
256RTEMS_SYSINIT_MP_FINALIZE
257    Finalize MPCI initialization.  This step is mandatory on MPCI
258    configurations.
259
260RTEMS_SYSINIT_CLASSIC_USER_TASKS
261    Creates and starts the Classic initialization tasks.  This step is optional
262    and depends on the application configuration.
263
264RTEMS_SYSINIT_POSIX_USER_THREADS
265    Creates POSIX initialization threads.  This step is optional and depends on
266    the application configuration.
267
268RTEMS_SYSINIT_STD_FILE_DESCRIPTORS
269    Open the standard input, output and error file descriptors.  This step is
270    optional and depends on the application configuration.
271
272The final action of the :c:func:`rtems_initialize_executive()` directive is to
273start multitasking and switch to the highest priority ready thread.  RTEMS does
274not return to the initialization context and the initialization stack may be
275re-used for interrupt processing.
276
277Many of RTEMS actions during initialization are based upon the contents of the
278Configuration Table.  For more information regarding the format and contents of
279this table, please refer to the chapter :ref:`Configuring a System`.
280
281Global Construction
282-------------------
283
284The global construction is carried out by the first Classic API initialization
285task (first is defined by index zero in the Classic API initialization task
286configuration table).  If no Classic API initialization task exists, then it is
287carried out by the first POSIX API initialization thread.  If no initialization
288task or thread exists, then no global construction is performed, see for
289example :ref:`Specify Idle Task Performs Application Initialization`.  The
290Classic API task or POSIX API thread which carries out global construction is
291called the main thread.
292
293Global construction runs before the entry function of the main thread.  The
294configuration of the main thread must take the global construction into
295account.  In particular, the main thread stack size, priority, attributes and
296initial modes must be set accordingly.  Thread-local objects and POSIX key
297values created during global construction are accessible by the main thread.
298If other initialization tasks are configured, and one of them has a higher
299priority than the main thread and the main thread is preemptible, this task
300executes before the global construction.  In case the main thread blocks during
301global construction, then other tasks may run.  In SMP configurations, other
302initialization tasks may run in parallel with global construction.  Tasks
303created during global construction may preempt the main thread or run in
304parallel in SMP configurations.  All RTEMS services allowed in task context are
305allowed during global construction.
306
307Global constructors are C++ global object constructors or functions with the
308constructor attribute.  For example, the following test program
309
310.. code-block:: c
311
312    #include <stdio.h>
313    #include <assert.h>
314
315    class A {
316      public:
317        A()
318        {
319          puts( "A:A()" );
320        }
321    };
322
323    static A a;
324
325    static thread_local int i;
326
327    static thread_local int j;
328
329    static __attribute__(( __constructor__ )) void b( void )
330    {
331      i = 1;
332      puts( "b()" );
333    }
334
335    static __attribute__(( __constructor__( 1000 ) )) void c( void )
336    {
337      puts( "c()" );
338    }
339
340    int main( void )
341    {
342      assert( i == 1 );
343      assert( j == 0 );
344      return 0;
345    }
346
347should output:
348
349.. code-block:: shell
350
351    c()
352    b()
353    A:A()
354
355Directives
356==========
357
358This section details the Initialization Manager's directives.  A subsection is
359dedicated to each of this manager's directives and describes the calling
360sequence, related constants, usage, and status codes.
361
362.. raw:: latex
363
364   \clearpage
365
366.. index:: initialize RTEMS
367.. index:: start multitasking
368.. index:: rtems_initialize_executive
369
370.. _rtems_initialize_executive:
371
372INITIALIZE_EXECUTIVE - Initialize RTEMS
373---------------------------------------
374
375CALLING SEQUENCE:
376    .. code-block:: c
377
378        void rtems_initialize_executive(void);
379
380DIRECTIVE STATUS CODES:
381    NONE - This function will not return to the caller.
382
383DESCRIPTION:
384    Iterates through the system initialization linker set and invokes the
385    registered handlers.  The final step is to start multitasking.
386
387NOTES:
388    This directive should be called by :c:func:`boot_card()` only.
389
390    This directive *does not return* to the caller.  Errors in the
391    initialization sequence are usually fatal and lead to a system termination.
Note: See TracBrowser for help on using the repository browser.