source: rtems/doc/user/init.t @ 48bff53b

4.115
Last change on this file since 48bff53b was 48bff53b, checked in by Sebastian Huber <sebastian.huber@…>, on 12/06/12 at 16:47:30

score: rtems_initialize_start_multitasking()

Do not return from rtems_initialize_start_multitasking() and call
rtems_fatal() instead with a fatal source of RTEMS_FATAL_SOURCE_EXIT and
a fatal code with the exit status.

Remove all bsp_cleanup() functions. The boot_card() is now a no return
function.

  • Property mode set to 100644
File size: 13.7 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2008.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5
6@chapter Initialization Manager
7
8@section Introduction
9
10The Initialization Manager is responsible for
11initiating and shutting down RTEMS.  Initiating RTEMS involves
12creating and starting all configured initialization tasks, and
13for invoking the initialization routine for each user-supplied
14device driver.  In a multiprocessor configuration, this manager
15also initializes the interprocessor communications layer.  The
16directives provided by the Initialization Manager are:
17
18@itemize @bullet
19@item @code{@value{DIRPREFIX}initialize_data_structures} - Initialize RTEMS Data Structures
20@item @code{@value{DIRPREFIX}initialize_before_drivers} - Perform Initialization Before Device Drivers
21@item @code{@value{DIRPREFIX}initialize_device_drivers} - Initialize Device Drivers
22@item @code{@value{DIRPREFIX}initialize_start_multitasking} - Complete Initialization and Start Multitasking
23@item @code{@value{DIRPREFIX}shutdown_executive} - Shutdown RTEMS
24@end itemize
25
26@section Background
27
28@subsection Initialization Tasks
29
30@cindex initialization tasks
31
32Initialization task(s) are the mechanism by which
33RTEMS transfers initial control to the user's application.
34Initialization tasks differ from other application tasks in that
35they are defined in the User Initialization Tasks Table and
36automatically created and started by RTEMS as part of its
37initialization sequence.  Since the initialization tasks are
38scheduled using the same algorithm as all other RTEMS tasks,
39they must be configured at a priority and mode which will ensure
40that they will complete execution before other application tasks
41execute.  Although there is no upper limit on the number of
42initialization tasks, an application is required to define at
43least one.
44
45A typical initialization task will create and start
46the static set of application tasks.  It may also create any
47other objects used by the application.  Initialization tasks
48which only perform initialization should delete themselves upon
49completion to free resources for other tasks.  Initialization
50tasks may transform themselves into a "normal" application task.
51This transformation typically involves changing priority and
52execution mode.  RTEMS does not automatically delete the
53initialization tasks.
54
55@subsection System Initialization
56
57System Initialization begins with board reset and continues
58through RTEMS initialization, initialization of all device
59drivers, and eventually a context switch to the first user
60task.  Remember, that interrupts are disabled during
61initialization and the @i{initialization thread} is not
62a task in any sense and the user should be very careful
63during initialzation.
64
65The BSP must ensure that the there is enough stack
66space reserved for the initialization "thread" to
67successfully execute the initialization routines for
68all device drivers and, in multiprocessor configurations, the
69Multiprocessor Communications Interface Layer initialization
70routine.
71
72@subsection The Idle Task
73
74The Idle Task is the lowest priority task in a system
75and executes only when no other task is ready to execute.  This
76default implementation of this task consists of an infinite
77loop. RTEMS allows the Idle Task body to be replaced by a CPU
78specific implementation, a BSP specific implementation or an
79application specific implementation.
80
81The Idle Task is preemptible and @b{WILL} be preempted when
82any other task is made ready to execute.  This characteristic is
83critical to the overall behavior of any application.
84
85@subsection Initialization Manager Failure
86
87The @code{@value{DIRPREFIX}fatal_error_occurred} directive will
88be invoked from @code{@value{DIRPREFIX}initialize_executive}
89for any of the following reasons:
90
91@itemize @bullet
92@item If either the Configuration Table or the CPU Dependent
93Information Table is not provided.
94
95@item If the starting address of the RTEMS RAM Workspace,
96supplied by the application in the Configuration Table, is NULL
97or is not aligned on a four-byte boundary.
98
99@item If the size of the RTEMS RAM Workspace is not large
100enough to initialize and configure the system.
101
102@item If the interrupt stack size specified is too small.
103
104@item If multiprocessing is configured and the node entry in
105the Multiprocessor Configuration Table is not between one and
106the maximum_nodes entry.
107
108@item If a multiprocessor system is being configured and no
109Multiprocessor Communications Interface is specified.
110
111@item If no user initialization tasks are configured.  At
112least one initialization task must be configured to allow RTEMS
113to pass control to the application at the end of the executive
114initialization sequence.
115
116@item If any of the user initialization tasks cannot be
117created or started successfully.
118@end itemize
119 
120A discussion of RTEMS actions when a fatal error occurs
121may be found @ref{Fatal Error Manager Announcing a Fatal Error}.
122
123
124@section Operations
125
126@subsection Initializing RTEMS
127
128The Initialization Manager directives are called by the
129Board Support Package framework as part of its initialization
130sequence.  RTEMS assumes that the Board Support Package
131successfully completed its initialization activities.  These
132directives initialize RTEMS by performing the following actions:
133
134@itemize @bullet
135@item Initializing internal RTEMS variables;
136@item Allocating system resources;
137@item Creating and starting the Idle Task;
138@item Initialize all device drivers;
139@item Creating and starting the user initialization task(s); and
140@item Initiating multitasking.
141@end itemize
142
143The initialization directives MUST be called in the proper
144sequence before any blocking directives may be used.  The services
145in this manager should be invoked just once per application
146and in precisely the following order:
147
148@itemize @bullet
149@item @code{@value{DIRPREFIX}initialize_data_structures}
150@item @code{@value{DIRPREFIX}initialize_before_drivers}
151@item @code{@value{DIRPREFIX}initialize_device_drivers}
152@item @code{@value{DIRPREFIX}initialize_start_multitasking}
153@end itemize
154
155It is recommended that the Board Support Package use the
156provided framework which will invoke these services as
157part of the executing the function @code{boot_card} in the
158file @code{c/src/lib/libbsp/shared/bootcard.c}.  This
159framework will also assist in allocating memory to the
160RTEMS Workspace and C Program Heap and initializing the
161C Library.
162
163The effect of calling any blocking RTEMS directives before
164@code{@value{DIRPREFIX}initialize_start_multitasking}
165is unpredictable but guaranteed to be bad.  After the
166directive @code{@value{DIRPREFIX}initialize_data_structures}
167is invoked, it is permissible to allocate RTEMS objects and
168perform non-blocking operations.  But the user should be
169distinctly aware that multitasking is not available yet
170and they are @b{NOT} executing in a task context.
171
172Many of RTEMS actions during initialization are based upon
173the contents of the Configuration Table.  For more information
174regarding the format and contents of this table, please refer
175to the chapter @ref{Configuring a System}.
176
177The final step in the initialization sequence is the
178initiation of multitasking.  When the scheduler and dispatcher
179are enabled, the highest priority, ready task will be dispatched
180to run.  Control will not be returned to the Board Support
181Package after multitasking is enabled until the
182@code{@value{DIRPREFIX}shutdown_executive} directive is called.
183This directive is called as a side-effect of POSIX calls
184including @code{exit}.
185
186@subsection Shutting Down RTEMS
187
188The @code{@value{DIRPREFIX}shutdown_executive} directive is invoked by the
189application to end multitasking and return control to the board
190support package.  The board support package resumes execution at
191the code immediately following the invocation of the
192@code{@value{DIRPREFIX}initialize_start_multitasking} directive.
193
194@section Directives
195
196This section details the Initialization Manager's
197directives.  A subsection is dedicated to each of this manager's
198directives and describes the calling sequence, related
199constants, usage, and status codes.
200
201@page
202@subsection INITIALIZE_DATA_STRUCTURES - Initialize RTEMS Data Structures
203
204@cindex initialize RTEMS data structures
205
206@subheading CALLING SEQUENCE:
207
208@ifset is-C
209@findex rtems_initialize_data_structures
210@example
211void rtems_initialize_data_structures(void);
212@end example
213@end ifset
214
215@ifset is-Ada
216@example
217NOT SUPPORTED FROM Ada BINDING
218@end example
219@end ifset
220
221@subheading DIRECTIVE STATUS CODES:
222
223NONE
224
225@subheading DESCRIPTION:
226
227This directive is called when the Board Support
228Package has completed its basic initialization and
229allows RTEMS to initialize the application environment based upon the
230information in the Configuration Table, User Initialization
231Tasks Table, Device Driver Table, User Extension Table,
232Multiprocessor Configuration Table, and the Multiprocessor
233Communications Interface (MPCI) Table.  This directive returns
234to the caller after completing the basic RTEMS initialization.
235
236@subheading NOTES:
237
238The Initialization Manager directives must be used in the
239proper sequence and invokved only once in the life of an application.
240
241This directive must be invoked with interrupts disabled.
242Interrupts should be disabled as early as possible in
243the initialization sequence and remain disabled until
244the first context switch.
245
246@page
247@subsection INITIALIZE_BEFORE_DRIVERS - Perform Initialization Before Device Drivers
248
249@cindex initialize RTEMS before device drivers
250
251@subheading CALLING SEQUENCE:
252
253@ifset is-C
254@findex rtems_initialize_before_drivers
255@example
256void rtems_initialize_before_drivers(void);
257@end example
258@end ifset
259
260@ifset is-Ada
261@example
262NOT SUPPORTED FROM Ada BINDING
263@end example
264@end ifset
265
266@subheading DIRECTIVE STATUS CODES:
267
268NONE
269
270@subheading DESCRIPTION:
271
272This directive is called by the Board Support Package as the
273second step in initializing RTEMS.  This directive performs
274initialization that must occur between basis RTEMS data structure
275initialization and device driver initialization.  In particular,
276in a multiprocessor configuration, this directive will create the
277MPCI Server Task.  This directive returns to the caller after
278completing the basic RTEMS initialization.
279
280@subheading NOTES:
281
282The Initialization Manager directives must be used in the
283proper sequence and invokved only once in the life of an application.
284
285This directive must be invoked with interrupts disabled.
286Interrupts should be disabled as early as possible in
287the initialization sequence and remain disabled until
288the first context switch.
289
290@page
291@subsection INITIALIZE_DEVICE_DRIVERS - Initialize Device Drivers
292
293@cindex initialize device drivers
294
295@subheading CALLING SEQUENCE:
296
297@ifset is-C
298@findex rtems_initialize_device_drivers
299@example
300void rtems_initialize_device_drivers(void);
301@end example
302@end ifset
303
304@ifset is-Ada
305@example
306NOT SUPPORTED FROM Ada BINDING
307@end example
308@end ifset
309
310@subheading DIRECTIVE STATUS CODES:
311
312NONE
313
314@subheading DESCRIPTION:
315
316This directive is called by the Board Support Package as the
317third step in initializing RTEMS.  This directive initializes
318all statically configured device drivers and performs all RTEMS
319initialization which requires device drivers to be initialized.
320
321In a multiprocessor configuration, this service will initialize
322the Multiprocessor Communications Interface (MPCI) and synchronize
323with the other nodes in the system.
324
325After this directive is executed, control will be returned to
326the Board Support Package framework.
327
328@subheading NOTES:
329
330The Initialization Manager directives must be used in the
331proper sequence and invokved only once in the life of an application.
332
333This directive must be invoked with interrupts disabled.
334Interrupts should be disabled as early as possible in
335the initialization sequence and remain disabled until
336the first context switch.
337
338@page
339@subsection INITIALIZE_START_MULTITASKING - Complete Initialization and Start Multitasking
340
341@cindex initialize RTEMS
342@cindex start multitasking
343
344@subheading CALLING SEQUENCE:
345
346@ifset is-C
347@findex rtems_initialize_start_multitasking
348@example
349void rtems_initialize_start_multitasking(void);
350@end example
351@end ifset
352
353@ifset is-Ada
354@example
355NOT SUPPORTED FROM Ada BINDING
356@end example
357@end ifset
358
359@subheading DIRECTIVE STATUS CODES:
360
361NONE
362
363@subheading DESCRIPTION:
364
365This directive initiates multitasking and performs a context switch to the
366first user application task and may enable interrupts as a side-effect of
367that context switch.  The context switch saves the executing context.  The
368application runs now.  The directive rtems_shutdown_executive() will return
369to the saved context.  The exit() function will use this directive.
370
371After a return to the saved context a fatal system state is reached.  The
372fatal source is RTEMS_FATAL_SOURCE_EXIT with a fatal code set to the value
373passed to rtems_shutdown_executive().
374
375@subheading NOTES:
376
377This directive @b{DOES NOT RETURN} to the caller.
378
379This directive causes all nodes in the system to
380verify that certain configuration parameters are the same as
381those of the local node.  If an inconsistency is detected, then
382a fatal error is generated.
383
384@page
385@subsection SHUTDOWN_EXECUTIVE - Shutdown RTEMS
386
387@cindex shutdown RTEMS
388
389@subheading CALLING SEQUENCE:
390
391@ifset is-C
392@findex rtems_shutdown_executive
393@example
394void rtems_shutdown_executive(
395  uint32_t result
396);
397@end example
398@end ifset
399
400@ifset is-Ada
401@example
402procedure Shutdown_Executive(
403  Status : in     RTEMS.Unsigned32
404);
405@end example
406@end ifset
407
408@subheading DIRECTIVE STATUS CODES:
409
410NONE
411
412@subheading DESCRIPTION:
413
414This directive is called when the application wishes
415to shutdown RTEMS and return control to the board support
416package.  The board support package resumes execution at the
417code immediately following the invocation of the
418@code{@value{DIRPREFIX}initialize_executive} directive.
419
420@subheading NOTES:
421
422This directive MUST be the last RTEMS directive
423invoked by an application and it DOES NOT RETURN to the caller.
424
425This directive should not be invoked until the
426executive has successfully completed initialization.
Note: See TracBrowser for help on using the repository browser.