source: rtems/doc/bsp_howto/init.t @ c4cbe17

4.104.114.84.95
Last change on this file since c4cbe17 was c4cbe17, checked in by Joel Sherrill <joel.sherrill@…>, on 10/21/98 at 20:21:51

Corrections from Jennifer and Jeff plus additions to the initialization
chapter.

  • Property mode set to 100644
File size: 12.4 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1998.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Initialization Code
10
11@section Introduction
12
13The initialization code is the first piece of code executed when there's a
14reset/reboot. Its purpose is to initialize the board for the application.
15This chapter contains a narrative description of the initialization
16process followed by a description of each of the files and routines
17commonly found in the BSP related to initialization.  The remainder of
18this chapter covers special issues which require attention such
19as interrupt vector table and chip select initialization.
20
21Most of the examples in this chapter will be based on the gen68340 BSP
22initialization code.  Like most BSPs, the initialization for this
23BSP is divided into two subdirectories under the BSP source directory.
24The gen68340 BSP source code in the following directory:
25
26@example
27c/src/lib/libbsp/m68k/gen68340:
28@end example
29
30@itemize @bullet
31
32@item @code{start340}: assembly language code which contains early
33initialization routines
34
35@item @code{startup}: C code with higher level routines (RTEMS
36initialization related)
37
38@end itemize
39
40@b{NOTE:} The directory @code{start340} is simply named @code{start} or
41start followed by a BSP designation.
42
43In the @code{start340} directory are two source files.  The file
44@code{startfor340only.s} is the simpler of these files as it only has
45initialization code for a MC68340 board.  The file @code{start340.s}
46contains initialization for a 68349 based board as well.
47
48@section Board Initialization
49
50This section describes the steps an application goes through from the
51time the first BSP code is executed until the first application task
52executes.  The routines invoked during this will be discussed and
53their location in the RTEMS source tree pointed out.
54
55@subsection Start Code - Assembly Language Initialization
56
57The assembly language code in the directory @code{start} is
58the first part of the application to execute.  It is
59responsible for initializing the processor and board enough to execute
60the rest of the BSP.  This includes:
61
62@itemize @bullet
63@item initializing the stack
64@item zeroing out the uninitialized data section @code{.bss}
65@item disabling external interrupts
66@item copy the initialized data from ROM to RAM
67@end itemize
68
69The general rule of thumb is that the
70start code in assembly should do the minimum necessary to allow C code
71to execute to complete the initialization sequence. 
72
73The initial assembly language start code completes its execution by
74invoking the shared routine @code{boot_card()}.
75
76@subsection boot_card() - Boot the Card
77
78The @code{boot_card()} is the first C code invoked.  Most of the BSPs
79use the sams shared version of @code{boot_card()} which is located in
80the following file:
81
82@example
83c/src/lib/libbsp/shared/main.c
84@end example
85
86The @code{boot_card()} routine performs the following functions:
87
88@itemize @bullet
89
90@item initializes the shared fields of the CPU Configuration Table
91(variable name @code{Cpu_table}) to a default state,
92
93@item copies the application's RTEMS Configuration Table
94(variable name @code{Configuration}) to the BSP's Configuration
95Table (variable name @code{BSP_Configuration}) so it can be modified
96as necessary without copying the original table,
97
98@item invokes the BSP specific routine @code{bsp_start()},
99
100@item invokes the RTEMS directive @code{rtems_initialize_executive_early()}
101to initialize the executive, C Library, and all device drivers but
102return without initiating multitasking or enabling interrupts,
103
104@item invokes the shared @code{main()} in the same file as
105@code{boot_card()} which does not return until the
106@code{rtems_shutdown_executive} directive is called, and
107
108@item invokes the BSP specific routine @code{bsp_cleanup()} to perform
109any necessary board specific shutdown actions.
110
111@end itemize
112
113It is important to note that the executive and much of the
114support environment must be initialized before invoking @code{main()}.
115
116@subsection bsp_start() - BSP Specific Initialization
117
118This is the first BSP specific C routine to execute during system
119initialization.  This routine often performs required fundamental
120hardware initialization such as setting bus controller registers
121that do not have a direct impact on whether or not C code can execute.
122The source code for this routine is usually found in the following
123file:
124
125@example
126c/src/lib/libbsp/CPU/BSP/startup/bspstart.c
127@end example
128
129This routine is also responsible for overriding the default settings
130in the CPU Configuration Table and setting port specific entries
131in this table.  This routine will typically install routines
132for one or more of the following initialization hooks:
133
134@itemize @bullet
135@item BSP Pretasking Hook
136@item BSP Predriver Hook
137@item BSP Postdriver Hook
138@end itemize
139
140One of the most important functions performed by this routine
141is determining where the RTEMS Executive Work Space is to be
142located in memory.  All RTEMS objects and task stacks will be
143allocated from this Workspace.  The RTEMS Workspace is distinct
144from the application heap used for @code{malloc()}.
145
146Many BSPs place this area at the end of RAM although this is
147certainly not a requirement.
148
149After completing execution, this routine returns to the
150@code{boot_card()} routine.
151
152@subsection main() - C Main
153
154This routine is the C main entry point.  This is a special routine
155and the GNU Compiler Suite treats it as such.  The GNU C Compiler
156recognizes @code{main()} and automatically inserts a call to the
157compiler run-time support routine @code{__main()} as the first
158code executed in @code{main()}.
159
160The routine @code{__main()} initializes the compiler's basic run-time
161support library and, most importantly, invokes the C++ global
162constructors. 
163
164The precise placement of when @code{main()} is invoked in the
165RTEMS initialization sequence insures that C Library and non-blocking
166calls can be made in global C++ constructors.
167
168The shared implementation of this routine is located in the following file:
169
170@example
171c/src/lib/libbsp/shared/main.c
172@end example
173
174In addition to the implicit invocation of @code{__main}, this
175routine performs some explitit initialization.  This routine
176sets the variable @code{rtems_progname} and initiates
177multitasking via a call to the RTEMS directive
178@code{rtems_initialize_executive_late}.  It is important to note
179that the executive does not return to this routine until the
180RTEMS directive @code{rtems_shutdown_executive} is invoked.
181
182@subsection RTEMS Pretasking Callback
183
184The @code{pretasking_hook} entry in the RTEMS CPU Configuration
185Table may be the address of a user provided routine that is
186invoked once RTEMS initialization is complete but before interrupts
187and tasking are enabled.  No tasks -- not even the IDLE task -- have
188been created when this hook is invoked.  The pretasking hook is optional.
189
190Although optional, most of the RTEMS BSPs provide a pretasking hook
191callback.  This routine is usually called @code{bsp_pretasking_hook}
192and is found in the file:
193
194@example
195c/src/lib/libbsp/CPU/BSP/startup/bspstart.c
196@end example
197
198The @code{bsp_pretasking_hook()} routine is the appropriate place to
199initialize any support components which depend on the RTEMS APIs.
200Most BSPs initialize the RTEMS C Library support in their
201implementation of @code{bsp_pretasking_hook()}.  This initialization
202includes the application heap as well as the reentrancy support
203for the C Library.
204
205@subsection RTEMS Predriver Callback
206
207XXX is the address of the user provided
208routine which is invoked with tasking enabled immediately before
209the MPCI and device drivers are initialized. RTEMS
210initialization is complete, interrupts and tasking are enabled,
211but no device drivers are initialized.  This field may be NULL to
212indicate that the hook is not utilized.
213
214@subsection Device Driver Initialization
215
216At this point in the initialization sequence, the initialization
217routines for all of the device drivers specified in the Device
218Driver Table are invoked.
219
220@subsection RTEMS Postdriver Callback
221
222XXX is the address of the user provided
223routine which is invoked with tasking enabled immediately after
224the MPCI and device drivers are initialized. RTEMS
225initialization is complete, interrupts and tasking are enabled,
226and the device drivers are initialized.  This field may be NULL
227to indicate that the hook is not utilized.
228
229
230@section The Interrupts Vector Table
231
232
233
234After the entry label starts a code section in which some room is
235allocated for the table of interrupts vectors. They are assigned to the
236address of the __uhoh label.
237
238At __uhoh label you can find the default interrupt handler routine. This
239routine is only called when an unexpected interrupts is raised. You can
240add your own routine there (in that case there's a call to a routine -
241$BSP_ROOT/startup/dumpanic.c - that pri nts which address caused the
242interrupt and the contents of the registers, stack...), but this should
243not return.
244
245@section Chip Select Initialization
246
247When the microprocessor accesses a memory area, address decoding is
248handled by an address decoder (!), so that the microprocessor knows which
249memory chip to access.
250
251Figure 4 : address decoding
252
253You have to program your Chip Select registers in order that they match
254the linkcmds settings. In this BSP ROM and RAM addresses can be found in
255both the linkcmds and initialization code, but this is not a great way to
256do, better use some shared variables .
257
258@section Integrated processor registers initialization
259
260There are always some specific integrated processor registers
261initialization to do. Integrated processors' user manuals often detail
262them.
263
264@section Data section recopy
265
266The next initialization part can be found in
267$BSP340_ROOT/start340/init68340.c. First the Interrupt Vector Table is
268copied into RAM, then the data section recopy is initiated
269(_CopyDataClearBSSAndStart in $BSP340_ROOT/start340/startfor340only.s).
270
271This code performs the following actions:
272
273@itemize @bullet
274
275@item copies the .data section from ROM to its location reserved in RAM
276(see 5.2 for more details about this copy),
277
278@item clear .bss section (all the non-initialized data will take value 0).
279
280@end itemize
281
282Then control is passed to the RTEMS-specific initialization code.
283
284@section RTEMS-Specific Initialization
285
286@section The RTEMS configuration table
287
288The RTEMS configuration table contains the maximum number of objects RTEMS
289can handle during the application (e.g. maximum number of tasks,
290semaphores, etc.). It's used to allocate the size for the RTEMS inner data
291structures.
292
293The RTEMS configuration table is application dependant, which means that
294one has to provide one per application. It's usually an header file
295included in the main module of the application.
296
297The BSP_Configuration label points on this table.
298
299For more information on the RTEMS configuration table, refer to C user's
300guide, chapter 23 <insert a link here>.
301
302@section RTEMS initialization procedure
303
304The RTEMS initialization procedure is described in the 3rd chapter of the
305C user's manual <insert a link here>. Please read it carefully.
306
307There are a few BSP specific functions called from the initialization
308manager. They can be found in the startup directory of the BSP.
309
310@table @b
311
312@item bspstart.c
313
314It starts the application.  It includes application, board, and monitor
315specific initialization and configuration.
316
317@item bspstart.c
318
319@table @b
320@item bsp_pretasking_hook
321
322It starts libc support (needed to allocate some memory using C primitive
323malloc for example). Heap size must be passed in argument, this is the one
324which is defined in the linkcmds (cf. 5.)
325
326
327@end table
328
329@item bspclean.c
330
331@table @b
332
333@item bsp_cleanup
334
335Return control to the monitor.
336
337@end table
338
339@end table
340
341@section Drivers initialization
342
343The Driver Address Table is part of the RTEMS configuration table. It
344defines RTEMS drivers entry points (initialization, open, close, read,
345write, and control). For more information about this table, check C User's
346manual chapter 21 section 6 <insert a l ink here>.
347
348The RTEMS initialization procedure calls the initialization function for
349every driver defined in the RTEMS Configuration Table (this permits to add
350only the drivers needed by the application).
351
352All these primitives have a major and a minor number as arguments:
353
354@itemize @bullet
355
356@item the major number refers to the driver type,
357
358@item the minor number is used to control two peripherals with the same
359driver (for instance, we define only one major number for the serial
360driver, but two minor numbers for channel A and B if there are two
361channels in the UART).
362
363@end itemize
364
Note: See TracBrowser for help on using the repository browser.