source: rtems/doc/user/init.t @ 1b03eed

4.8
Last change on this file since 1b03eed was 1b03eed, checked in by Glenn Humphrey <glenn.humphrey@…>, on 10/26/07 at 21:34:57

2007-10-26 Glenn Humphrey <glenn.humphrey@…>

  • user/rtmon.t: Fix report output.

2007-10-25 Glenn Humphrey <glenn.humphrey@…>

  • user/barrier.t, user/clock.t, user/concepts.t, user/cpuuse.t, user/init.t, user/intr.t, user/io.t, user/mp.t, user/rtmon.t, user/sem.t, user/stackchk.t, user/task.t, user/timer.t: Updated the Ada documentation to reflect the current binding.
  • Property mode set to 100644
File size: 13.2 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2007.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Initialization Manager
10
11@section Introduction
12
13The initialization manager is responsible for
14initiating and shutting down RTEMS.  Initiating RTEMS involves
15creating and starting all configured initialization tasks, and
16for invoking the initialization routine for each user-supplied
17device driver.  In a multiprocessor configuration, this manager
18also initializes the interprocessor communications layer.  The
19directives provided by the initialization manager are:
20
21@itemize @bullet
22@item @code{@value{DIRPREFIX}initialize_executive} - Initialize RTEMS
23@item @code{@value{DIRPREFIX}initialize_executive_early} - Initialize RTEMS and do NOT Start Multitasking
24@item @code{@value{DIRPREFIX}initialize_executive_late} - Complete Initialization and Start Multitasking
25@item @code{@value{DIRPREFIX}shutdown_executive} - Shutdown RTEMS
26@end itemize
27
28@section Background
29
30@subsection Initialization Tasks
31
32@cindex initialization tasks
33
34Initialization task(s) are the mechanism by which
35RTEMS transfers initial control to the user's application.
36Initialization tasks differ from other application tasks in that
37they are defined in the User Initialization Tasks Table and
38automatically created and started by RTEMS as part of its
39initialization sequence.  Since the initialization tasks are
40scheduled using the same algorithm as all other RTEMS tasks,
41they must be configured at a priority and mode which will insure
42that they will complete execution before other application tasks
43execute.  Although there is no upper limit on the number of
44initialization tasks, an application is required to define at
45least one.
46
47A typical initialization task will create and start
48the static set of application tasks.  It may also create any
49other objects used by the application.  Initialization tasks
50which only perform initialization should delete themselves upon
51completion to free resources for other tasks.  Initialization
52tasks may transform themselves into a "normal" application task.
53This transformation typically involves changing priority and
54execution mode.  RTEMS does not automatically delete the
55initialization tasks.
56
57@subsection The System Initialization Task
58
59The System Initialization Task is responsible for
60initializing all device drivers.  As a result, this task has a
61higher priority than all other tasks to insure that no
62application tasks executes until all device drivers are
63initialized.  After device initialization in a single processor
64system, this task will delete itself.
65
66The System Initialization Task must have enough stack
67space to successfully execute the initialization routines for
68all device drivers and, in multiprocessor configurations, the
69Multiprocessor Communications Interface Layer initialization
70routine.  The CPU Configuration Table contains a field which
71allows the application or BSP to increase the default amount of
72stack space allocated for this task.
73
74In multiprocessor configurations, the System
75Initialization Task does not delete itself after initializing
76the device drivers.  Instead it transforms itself into the
77Multiprocessing Server which initializes the Multiprocessor
78Communications Interface Layer, verifies multiprocessor system
79consistency, and processes all requests from remote nodes.
80
81@subsection The Idle Task
82
83The Idle Task is the lowest priority task in a system
84and executes only when no other task is ready to execute.  This
85task consists of an infinite loop and will be preempted when any
86other task is made ready to execute.
87
88@subsection Initialization Manager Failure
89
90The @code{@value{DIRPREFIX}ifatal_error_occurred} directive will be called
91from @code{@value{DIRPREFIX}initialize_executive}
92for any of the following reasons:
93
94@itemize @bullet
95@item If either the Configuration Table or the CPU Dependent
96Information Table is not provided.
97
98@item If the starting address of the RTEMS RAM Workspace,
99supplied by the application in the Configuration Table, is NULL
100or is not aligned on a four-byte boundary.
101
102@item If the size of the RTEMS RAM Workspace is not large
103enough to initialize and configure the system.
104
105@item If the interrupt stack size specified is too small.
106
107@item If multiprocessing is configured and the node entry in
108the Multiprocessor Configuration Table is not between one and
109the maximum_nodes entry.
110
111@item If a multiprocessor system is being configured and no
112Multiprocessor Communications Interface is specified.
113
114@item If no user initialization tasks are configured.  At
115least one initialization task must be configured to allow RTEMS
116to pass control to the application at the end of the executive
117initialization sequence.
118
119@item If any of the user initialization tasks cannot be
120created or started successfully.
121@end itemize
122
123@section Operations
124
125@subsection Initializing RTEMS
126
127The @code{@value{DIRPREFIX}initialize_executive}
128directive is called by the
129board support package at the completion of its initialization
130sequence.  RTEMS assumes that the board support package
131successfully completed its initialization activities.  The
132@code{@value{DIRPREFIX}initialize_executive}
133directive completes the initialization
134sequence by performing the following actions:
135
136@itemize @bullet
137@item Initializing internal RTEMS variables;
138@item Allocating system resources;
139@item Creating and starting the System Initialization Task;
140@item Creating and starting the Idle Task;
141@item Creating and starting the user initialization task(s); and
142@item Initiating multitasking.
143@end itemize
144
145This directive MUST be called before any other RTEMS
146directives.  The effect of calling any RTEMS directives before
147@code{@value{DIRPREFIX}initialize_executive}
148is unpredictable.  Many of RTEMS actions
149during initialization are based upon the contents of the
150Configuration Table and CPU Dependent Information Table.  For
151more information regarding the format and contents of these
152tables, please refer to the chapter Configuring a System.
153
154The final step in the initialization sequence is the
155initiation of multitasking.  When the scheduler and dispatcher
156are enabled, the highest priority, ready task will be dispatched
157to run.  Control will not be returned to the board support
158package after multitasking is enabled until
159@code{@value{DIRPREFIX}shutdown_executive}
160the directive is called.
161
162The @code{@value{DIRPREFIX}initialize_executive}
163directive provides a
164conceptually simple way to initialize RTEMS.  However, in
165certain cases, this mechanism cannot be used.  The
166@code{@value{DIRPREFIX}initialize_executive_early}
167and @code{@value{DIRPREFIX}initialize_executive_late}
168directives are provided as an alternative mechanism for
169initializing RTEMS.  The
170@code{@value{DIRPREFIX}initialize_executive_early} directive
171returns to the caller BEFORE initiating multitasking.  The
172@code{@value{DIRPREFIX}initialize_executive_late}
173directive is invoked to start
174multitasking.  It is critical that only one of the RTEMS
175initialization sequences be used in an application.
176
177@subsection Shutting Down RTEMS
178
179The @code{@value{DIRPREFIX}shutdown_executive} directive is invoked by the
180application to end multitasking and return control to the board
181support package.  The board support package resumes execution at
182the code immediately following the invocation of the
183@code{@value{DIRPREFIX}initialize_executive} directive.
184
185@section Directives
186
187This section details the initialization manager's
188directives.  A subsection is dedicated to each of this manager's
189directives and describes the calling sequence, related
190constants, usage, and status codes.
191
192@page
193@subsection INITIALIZE_EXECUTIVE - Initialize RTEMS
194
195@cindex initialize RTEMS
196
197@subheading CALLING SEQUENCE:
198
199@ifset is-C
200@findex rtems_initialize_executive
201@example
202void rtems_initialize_executive(
203  rtems_configuration_table *configuration_table,
204  rtems_cpu_table           *cpu_table
205);
206@end example
207@end ifset
208
209@ifset is-Ada
210@example
211NOT SUPPORTED FROM Ada BINDING
212@end example
213@end ifset
214
215@subheading DIRECTIVE STATUS CODES:
216
217NONE
218
219@subheading DESCRIPTION:
220
221This directive is called when the board support
222package has completed its initialization to allow RTEMS to
223initialize the application environment based upon the
224information in the Configuration Table, CPU Dependent
225Information Table, User Initialization Tasks Table, Device
226Driver Table, User Extension Table, Multiprocessor Configuration
227Table, and the Multiprocessor Communications Interface (MPCI)
228Table.  This directive starts multitasking and does not return
229to the caller until the @code{@value{DIRPREFIX}shutdown_executive}
230directive is invoked.
231
232@subheading NOTES:
233
234This directive MUST be the first RTEMS directive
235called and it DOES NOT RETURN to the caller until the
236@code{@value{DIRPREFIX}shutdown_executive}
237is invoked.
238
239This directive causes all nodes in the system to
240verify that certain configuration parameters are the same as
241those of the local node.  If an inconsistency is detected, then
242a fatal error is generated.
243
244The application must use only one of the two
245initialization sequences:
246@code{@value{DIRPREFIX}initialize_executive} or
247@code{@value{DIRPREFIX}initialize_executive_early} and
248@code{@value{DIRPREFIX}initialize_executive_late}.  The
249@code{@value{DIRPREFIX}initialize_executive}
250directive is logically equivalent to invoking
251@code{@value{DIRPREFIX}initialize_executive_early} and
252@code{@value{DIRPREFIX}initialize_executive_late}
253with no intervening actions.
254
255@page
256@subsection INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking
257
258@cindex initialize RTEMS
259
260@subheading CALLING SEQUENCE:
261
262@ifset is-C
263@findex rtems_initialize_executive_early
264@example
265rtems_interrupt_level rtems_initialize_executive_early(
266  rtems_configuration_table *configuration_table,
267  rtems_cpu_table           *cpu_table
268);
269@end example
270@end ifset
271
272@ifset is-Ada
273@example
274NOT SUPPORTED FROM Ada BINDING
275@end example
276@end ifset
277
278@subheading DIRECTIVE STATUS CODES:
279
280NONE
281
282@subheading DESCRIPTION:
283
284This directive is called when the board support
285package has completed its initialization to allow RTEMS to
286initialize the application environment based upon the
287information in the Configuration Table, CPU Dependent
288Information Table, User Initialization Tasks Table, Device
289Driver Table, User Extension Table, Multiprocessor Configuration
290Table, and the Multiprocessor Communications Interface (MPCI)
291Table.  This directive returns to the caller after completing
292the basic RTEMS initialization but before multitasking is
293initiated.  The interrupt level in place when the directive is
294invoked is returned to the caller.  This interrupt level should
295be the same one passed to
296@code{@value{DIRPREFIX}initialize_executive_late}.
297
298@subheading NOTES:
299
300The application must use only one of the two
301initialization sequences:
302@code{@value{DIRPREFIX}initialize_executive} or
303@code{@value{DIRPREFIX}initialize_executive_early} and
304@code{@value{DIRPREFIX}initialize_executive_late}.
305
306@page
307@subsection INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking
308
309@cindex initialize RTEMS
310@cindex start multitasking
311
312@subheading CALLING SEQUENCE:
313
314@ifset is-C
315@findex rtems_initialize_executive_late
316@example
317NOT SUPPORTED FROM Ada BINDING
318@end example
319@end ifset
320
321@ifset is-Ada
322@example
323procedure Initialize_Executive_Late(
324  BSP_Level : in    RTEMS.ISR_Level
325);
326@end example
327@end ifset
328
329@subheading DIRECTIVE STATUS CODES:
330
331NONE
332
333@subheading DESCRIPTION:
334
335This directive is called after the
336@code{@value{DIRPREFIX}initialize_executive_early}
337directive has been called to complete
338the RTEMS initialization sequence and initiate multitasking.
339The interrupt level returned by the
340@code{@value{DIRPREFIX}initialize_executive_early}
341directive should be in bsp_level and this value is restored as
342part of this directive returning to the caller after the
343@code{@value{DIRPREFIX}shutdown_executive}
344directive is invoked.
345
346@subheading NOTES:
347
348This directive MUST be the second RTEMS directive
349called and it DOES NOT RETURN to the caller until the
350@code{@value{DIRPREFIX}shutdown_executive} is invoked.
351
352This directive causes all nodes in the system to
353verify that certain configuration parameters are the same as
354those of the local node.  If an inconsistency is detected, then
355a fatal error is generated.
356
357The application must use only one of the two
358initialization sequences:
359@code{@value{DIRPREFIX}initialize_executive} or
360@code{@value{DIRPREFIX}initialize_executive_early} and
361@code{@value{DIRPREFIX}initialize_executive_late}.
362
363
364
365@page
366@subsection SHUTDOWN_EXECUTIVE - Shutdown RTEMS
367
368@cindex shutdown RTEMS
369
370@subheading CALLING SEQUENCE:
371
372@ifset is-C
373@findex rtems_shutdown_executive
374@example
375void rtems_shutdown_executive(
376  rtems_unsigned32 result
377);
378@end example
379@end ifset
380
381@ifset is-Ada
382@example
383procedure Shutdown_Executive(
384  Status : in     RTEMS.Unsigned32
385);
386@end example
387@end ifset
388
389@subheading DIRECTIVE STATUS CODES:
390
391NONE
392
393@subheading DESCRIPTION:
394
395This directive is called when the application wishes
396to shutdown RTEMS and return control to the board support
397package.  The board support package resumes execution at the
398code immediately following the invocation of the
399@code{@value{DIRPREFIX}initialize_executive} directive.
400
401@subheading NOTES:
402
403This directive MUST be the last RTEMS directive
404invoked by an application and it DOES NOT RETURN to the caller.
405
406This directive should not be invoked until the
407executive has successfully completed initialization.
Note: See TracBrowser for help on using the repository browser.