source: rtems-docs/c-user/initialization.rst @ 6c56401

5
Last change on this file since 6c56401 was 6c56401, checked in by Chris Johns <chrisj@…>, on 11/12/17 at 03:34:48

c-user: Fix index locations.

Update #3229.

  • Property mode set to 100644
File size: 12.5 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:ref:`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_CONDITION_VARIABLE
187    Initialization of the POSIX Condition Variable object class.  This step is
188    optional and depends on the application configuration.
189
190RTEMS_SYSINIT_POSIX_MUTEX
191    Initialization of the POSIX Mutex object class.  This step is optional and
192    depends on the application configuration.
193
194RTEMS_SYSINIT_POSIX_MESSAGE_QUEUE
195    Initialization of the POSIX Message Queue object class.  This step is
196    optional and depends on the application configuration.
197
198RTEMS_SYSINIT_POSIX_SEMAPHORE
199    Initialization of the POSIX Semaphore object class.  This step is optional
200    and depends on the application configuration.
201
202RTEMS_SYSINIT_POSIX_TIMER
203    Initialization of the POSIX Timer object class.  This step is optional and
204    depends on the application configuration.
205
206RTEMS_SYSINIT_POSIX_BARRIER
207    Initialization of the POSIX Barrier object class.  This step is optional
208    and depends on the application configuration.
209
210RTEMS_SYSINIT_POSIX_RWLOCK
211    Initialization of the POSIX Read-Write Locks object class.  This step is
212    optional and depends on the application configuration.
213
214RTEMS_SYSINIT_POSIX_KEYS
215    Initialization of the POSIX Keys object class.  This step is optional
216    and depends on the application configuration.
217
218RTEMS_SYSINIT_POSIX_CLEANUP
219    Initialization of the POSIX Cleanup support.  This step is optional and
220    depends on the application configuration.
221
222RTEMS_SYSINIT_IDLE_THREADS
223    Initialization of idle threads.  This step is mandatory.
224
225RTEMS_SYSINIT_LIBIO
226    Initialization of IO library.  This step is optional and depends on the
227    application configuration.
228
229RTEMS_SYSINIT_ROOT_FILESYSTEM
230    Initialization of the root filesystem.  This step is optional and depends
231    on the application configuration.
232
233RTEMS_SYSINIT_DRVMGR
234    Driver manager initialization.  This step is optional and depends on the
235    application configuration.  Only available if the driver manager is
236    enabled.
237
238RTEMS_SYSINIT_MP_SERVER
239    MPCI server initialization.  This step is mandatory on MPCI configurations.
240
241RTEMS_SYSINIT_BSP_PRE_DRIVERS
242    Initialization step performed right before device drivers are initialized.
243    This step is mandatory.
244
245RTEMS_SYSINIT_DRVMGR_LEVEL_1
246    Driver manager level 1 initialization.  This step is optional and depends
247    on the application configuration.  Only available if the driver manager is
248    enabled.
249
250RTEMS_SYSINIT_DEVICE_DRIVERS
251    This step initializes all statically configured device drivers and performs
252    all RTEMS initialization which requires device drivers to be initialized.
253    This step is mandatory.  In a multiprocessor configuration, this service
254    will initialize the Multiprocessor Communications Interface (MPCI) and
255    synchronize with the other nodes in the system.
256
257RTEMS_SYSINIT_DRVMGR_LEVEL_2
258    Driver manager level 2 initialization.  This step is optional and depends
259    on the application configuration.  Only available if the driver manager is
260    enabled.
261
262RTEMS_SYSINIT_DRVMGR_LEVEL_3
263    Driver manager level 3 initialization.  This step is optional and depends
264    on the application configuration.  Only available if the driver manager is
265    enabled.
266
267RTEMS_SYSINIT_DRVMGR_LEVEL_4
268    Driver manager level 4 initialization.  This step is optional and depends
269    on the application configuration.  Only available if the driver manager is
270    enabled.
271
272RTEMS_SYSINIT_MP_FINALIZE
273    Finalize MPCI initialization.  This step is mandatory on MPCI
274    configurations.
275
276RTEMS_SYSINIT_CLASSIC_USER_TASKS
277    Creates and starts the Classic initialization tasks.  This step is optional
278    and depends on the application configuration.
279
280RTEMS_SYSINIT_POSIX_USER_THREADS
281    Creates POSIX initialization threads.  This step is optional and depends on
282    the application configuration.
283
284RTEMS_SYSINIT_STD_FILE_DESCRIPTORS
285    Open the standard input, output and error file descriptors.  This step is
286    optional and depends on the application configuration.
287
288The final action of the :c:func:`rtems_initialize_executive()` directive is to
289start multitasking and switch to the highest priority ready thread.  RTEMS does
290not return to the initialization context and the initialization stack may be
291re-used for interrupt processing.
292
293Many of RTEMS actions during initialization are based upon the contents of the
294Configuration Table.  For more information regarding the format and contents of
295this table, please refer to the chapter :ref:`Configuring a System`.
296
297Directives
298==========
299
300This section details the Initialization Manager's directives.  A subsection is
301dedicated to each of this manager's directives and describes the calling
302sequence, related constants, usage, and status codes.
303
304.. raw:: latex
305
306   \clearpage
307
308.. _rtems_initialize_executive:
309.. index:: initialize RTEMS
310.. index:: start multitasking
311.. index:: rtems_initialize_executive
312
313INITIALIZE_EXECUTIVE - Initialize RTEMS
314---------------------------------------
315
316CALLING SEQUENCE:
317    .. code-block:: c
318
319        void rtems_initialize_executive(void);
320
321DIRECTIVE STATUS CODES:
322    NONE - This function will not return to the caller.
323
324DESCRIPTION:
325    Iterates through the system initialization linker set and invokes the
326    registered handlers.  The final step is to start multitasking.
327
328NOTES:
329    This directive should be called by :c:func:`boot_card()` only.
330
331    This directive *does not return* to the caller.  Errors in the
332    initialization sequence are usually fatal and lead to a system termination.
Note: See TracBrowser for help on using the repository browser.