summaryrefslogtreecommitdiffstats
path: root/doc/user/init.t
blob: 4fb93048c2f58123f6ea0bba4c8d8be997b1b41f (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
@c
@c  COPYRIGHT (c) 1988-1998.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved.
@c
@c  $Id$
@c

@chapter Initialization Manager

@section Introduction

The initialization manager is responsible for
initiating and shutting down RTEMS.  Initiating RTEMS involves
creating and starting all configured initialization tasks, and
for invoking the initialization routine for each user-supplied
device driver.  In a multiprocessor configuration, this manager
also initializes the interprocessor communications layer.  The
directives provided by the initialization manager are:

@itemize @bullet
@item @code{@value{DIRPREFIX}initialize_executive} - Initialize RTEMS
@item @code{@value{DIRPREFIX}initialize_executive_early} - Initialize RTEMS and do NOT Start Multitasking
@item @code{@value{DIRPREFIX}initialize_executive_late} - Complete Initialization and Start Multitasking
@item @code{@value{DIRPREFIX}shutdown_executive} - Shutdown RTEMS
@end itemize

@section Background

@subsection Initialization Tasks

Initialization task(s) are the mechanism by which
RTEMS transfers initial control to the user's application.
Initialization tasks differ from other application tasks in that
they are defined in the User Initialization Tasks Table and
automatically created and started by RTEMS as part of its
initialization sequence.  Since the initialization tasks are
scheduled using the same algorithm as all other RTEMS tasks,
they must be configured at a priority and mode which will insure
that they will complete execution before other application tasks
execute.  Although there is no upper limit on the number of
initialization tasks, an application is required to define at
least one.

A typical initialization task will create and start
the static set of application tasks.  It may also create any
other objects used by the application.  Initialization tasks
which only perform initialization should delete themselves upon
completion to free resources for other tasks.  Initialization
tasks may transform themselves into a "normal" application task.
This transformation typically involves changing priority and
execution mode.  RTEMS does not automatically delete the
initialization tasks.

@subsection The System Initialization Task

The System Initialization Task is responsible for
initializing all device drivers.  As a result, this task has a
higher priority than all other tasks to insure that no
application tasks executes until all device drivers are
initialized.  After device initialization in a single processor
system, this task will delete itself.

The System Initialization Task must have enough stack
space to successfully execute the initialization routines for
all device drivers and, in multiprocessor configurations, the
Multiprocessor Communications Interface Layer initialization
routine.  The CPU Configuration Table contains a field which
allows the application or BSP to increase the default amount of
stack space allocated for this task.

In multiprocessor configurations, the System
Initialization Task does not delete itself after initializing
the device drivers.  Instead it transforms itself into the
Multiprocessing Server which initializes the Multiprocessor
Communications Interface Layer, verifies multiprocessor system
consistency, and processes all requests from remote nodes.

@subsection The Idle Task

The Idle Task is the lowest priority task in a system
and executes only when no other task is ready to execute.  This
task consists of an infinite loop and will be preempted when any
other task is made ready to execute.

@subsection Initialization Manager Failure

The fatal_error_occurred directive will be called
from @code{@value{DIRPREFIX}initialize_executive}
for any of the following reasons:

@itemize @bullet
@item If either the Configuration Table or the CPU Dependent
Information Table is not provided.

@item If the starting address of the RTEMS RAM Workspace,
supplied by the application in the Configuration Table, is NULL
or is not aligned on a four-byte boundary.

@item If the size of the RTEMS RAM Workspace is not large
enough to initialize and configure the system.

@item If the interrupt stack size specified is too small.

@item If multiprocessing is configured and the node entry in
the Multiprocessor Configuration Table is not between one and
the maximum_nodes entry.

@item If a multiprocessor system is being configured and no
Multiprocessor Communications Interface is specified.

@item If no user initialization tasks are configured.  At
least one initialization task must be configured to allow RTEMS
to pass control to the application at the end of the executive
initialization sequence.

@item If any of the user initialization tasks cannot be
created or started successfully.
@end itemize

@section Operations

@subsection Initializing RTEMS

The @code{@value{DIRPREFIX}initialize_executive}
directive is called by the
board support package at the completion of its initialization
sequence.  RTEMS assumes that the board support package
successfully completed its initialization activities.  The
@code{@value{DIRPREFIX}initialize_executive}
directive completes the initialization
sequence by performing the following actions:

@itemize @bullet
@item Initializing internal RTEMS variables;
@item Allocating system resources;
@item Creating and starting the System Initialization Task;
@item Creating and starting the Idle Task;
@item Creating and starting the user initialization task(s); and
@item Initiating multitasking.
@end itemize

This directive MUST be called before any other RTEMS
directives.  The effect of calling any RTEMS directives before
@code{@value{DIRPREFIX}initialize_executive}
is unpredictable.  Many of RTEMS actions
during initialization are based upon the contents of the
Configuration Table and CPU Dependent Information Table.  For
more information regarding the format and contents of these
tables, please refer to the chapter Configuring a System.

The final step in the initialization sequence is the
initiation of multitasking.  When the scheduler and dispatcher
are enabled, the highest priority, ready task will be dispatched
to run.  Control will not be returned to the board support
package after multitasking is enabled until
@code{@value{DIRPREFIX}shutdown_executive}
the directive is called.

The @code{@value{DIRPREFIX}initialize_executive}
directive provides a
conceptually simple way to initialize RTEMS.  However, in
certain cases, this mechanism cannot be used.  The
@code{@value{DIRPREFIX}initialize_executive_early}
and @code{@value{DIRPREFIX}initialize_executive_late}
directives are provided as an alternative mechanism for
initializing RTEMS.  The
@code{@value{DIRPREFIX}initialize_executive_early} directive
returns to the caller BEFORE initiating multitasking.  The
@code{@value{DIRPREFIX}initialize_executive_late}
directive is invoked to start
multitasking.  It is critical that only one of the RTEMS
initialization sequences be used in an application.

@subsection Shutting Down RTEMS

The @code{@value{DIRPREFIX}shutdown_executive} directive is invoked by the
application to end multitasking and return control to the board
support package.  The board support package resumes execution at
the code immediately following the invocation of the
@code{@value{DIRPREFIX}initialize_executive} directive.

@section Directives

This section details the initialization manager's
directives.  A subsection is dedicated to each of this manager's
directives and describes the calling sequence, related
constants, usage, and status codes.

@page
@subsection INITIALIZE_EXECUTIVE - Initialize RTEMS

@subheading CALLING SEQUENCE:

@ifset is-C
@c @findex rtems_initialize_executive
@example
void rtems_initialize_executive(
  rtems_configuration_table *configuration_table,
  rtems_cpu_table           *cpu_table
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Initialize_Executive (
  Configuration_Table : in     RTEMS.Configuration_Table_Pointer;
  CPU_Table           : in     RTEMS.CPU_Table_Pointer
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:

NONE

@subheading DESCRIPTION:

This directive is called when the board support
package has completed its initialization to allow RTEMS to
initialize the application environment based upon the
information in the Configuration Table, CPU Dependent
Information Table, User Initialization Tasks Table, Device
Driver Table, User Extension Table, Multiprocessor Configuration
Table, and the Multiprocessor Communications Interface (MPCI)
Table.  This directive starts multitasking and does not return
to the caller until the @code{@value{DIRPREFIX}shutdown_executive}
directive is invoked.

@subheading NOTES:

This directive MUST be the first RTEMS directive
called and it DOES NOT RETURN to the caller until the
@code{@value{DIRPREFIX}shutdown_executive}
is invoked.

This directive causes all nodes in the system to
verify that certain configuration parameters are the same as
those of the local node.  If an inconsistency is detected, then
a fatal error is generated.

The application must use only one of the two
initialization sequences: 
@code{@value{DIRPREFIX}initialize_executive} or
@code{@value{DIRPREFIX}initialize_executive_early} and 
@code{@value{DIRPREFIX}initialize_executive_late}.  The
@code{@value{DIRPREFIX}initialize_executive}
directive is logically equivalent to invoking 
@code{@value{DIRPREFIX}initialize_executive_early} and
@code{@value{DIRPREFIX}initialize_executive_late}
with no intervening actions.

@page
@subsection INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking

@subheading CALLING SEQUENCE:

@ifset is-C
@c @findex rtems_initialize_executive_early
@example
rtems_interrupt_level rtems_initialize_executive_early(
  rtems_configuration_table *configuration_table,
  rtems_cpu_table           *cpu_table
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Initialize_Executive_Early(
  Configuration_Table : in     RTEMS.Configuration_Table_Pointer;
  CPU_Table           : in     RTEMS.Cpu_Table;
  Level               :    out RTEMS.ISR_Level
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:

NONE

@subheading DESCRIPTION:

This directive is called when the board support
package has completed its initialization to allow RTEMS to
initialize the application environment based upon the
information in the Configuration Table, CPU Dependent
Information Table, User Initialization Tasks Table, Device
Driver Table, User Extension Table, Multiprocessor Configuration
Table, and the Multiprocessor Communications Interface (MPCI)
Table.  This directive returns to the caller after completing
the basic RTEMS initialization but before multitasking is
initiated.  The interrupt level in place when the directive is
invoked is returned to the caller.  This interrupt level should
be the same one passed to
@code{@value{DIRPREFIX}initialize_executive_late}.

@subheading NOTES:

The application must use only one of the two
initialization sequences:
@code{@value{DIRPREFIX}initialize_executive} or
@code{@value{DIRPREFIX}nitialize_executive_early} and 
@code{@value{DIRPREFIX}nitialize_executive_late}.

@page
@subsection INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking

@subheading CALLING SEQUENCE:

@ifset is-C
@c @findex rtems_initialize_executive_late
@example
void rtems_initialize_executive_late(
  rtems_interrupt_level  bsp_level
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Initialize_Executive_Late(
  BSP_Level : in    RTEMS.ISR_Level
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:

NONE

@subheading DESCRIPTION:

This directive is called after the
@code{@value{DIRPREFIX}initialize_executive_early}
directive has been called to complete
the RTEMS initialization sequence and initiate multitasking.
The interrupt level returned by the
@code{@value{DIRPREFIX}initialize_executive_early}
directive should be in bsp_level and this value is restored as
part of this directive returning to the caller after the
@code{@value{DIRPREFIX}shutdown_executive}
directive is invoked.

@subheading NOTES:

This directive MUST be the second RTEMS directive
called and it DOES NOT RETURN to the caller until the
@code{@value{DIRPREFIX}shutdown_executive} is invoked.

This directive causes all nodes in the system to
verify that certain configuration parameters are the same as
those of the local node.  If an inconsistency is detected, then
a fatal error is generated.

The application must use only one of the two
initialization sequences:
@code{@value{DIRPREFIX}initialize_executive} or
@code{@value{DIRPREFIX}nitialize_executive_early} and
@code{@value{DIRPREFIX}initialize_executive_late}.



@page
@subsection SHUTDOWN_EXECUTIVE - Shutdown RTEMS

@subheading CALLING SEQUENCE:

@ifset is-C
@c @findex rtems_shutdown_executive
@example
void rtems_shutdown_executive(
  rtems_unsigned32 result
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Shutdown_Executive(
  result : in     RTEMS.Unsigned32
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:

NONE

@subheading DESCRIPTION:

This directive is called when the application wishes
to shutdown RTEMS and return control to the board support
package.  The board support package resumes execution at the
code immediately following the invocation of the
@code{@value{DIRPREFIX}initialize_executive} directive.

@subheading NOTES:

This directive MUST be the last RTEMS directive
invoked by an application and it DOES NOT RETURN to the caller.

This directive should not be invoked until the
executive has successfully completed initialization.