source: rtems/doc/bsp_howto/init.t @ 452eec43

Last change on this file since 452eec43 was 452eec43, checked in by Sebastian Huber <sebastian.huber@…>, on Dec 7, 2015 at 1:42:43 PM

doc: Remove reference to debug mask

Update #2477.

  • Property mode set to 100644
File size: 17.4 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 Code
7
8@section Introduction
9
10The initialization code is the first piece of code executed when there's a
11reset/reboot. Its purpose is to initialize the board for the application.
12This chapter contains a narrative description of the initialization
13process followed by a description of each of the files and routines
14commonly found in the BSP related to initialization.  The remainder of
15this chapter covers special issues which require attention such
16as interrupt vector table and chip select initialization.
17
18Most of the examples in this chapter will be based on the SPARC/ERC32 and
19m68k/gen68340 BSP initialization code.  Like most BSPs, the initialization
20for these BSP is divided into two subdirectories under the BSP source
21directory.  The BSP source code for these BSPs is in the following
22directories:
23
24@example
25c/src/lib/libbsp/m68k/gen68340
26c/src/lib/libbsp/sparc/erc32
27@end example
28
29Both BSPs contain startup code written in assembly language and C.
30The gen68340 BSP has its early initialization start code in the
31@code{start340} subdirectory and its C startup code in the @code{startup}
32directory.  In the @code{start340} directory are two source files.
33The file @code{startfor340only.s} is the simpler of these files as it only
34has initialization code for a MC68340 board.  The file @code{start340.s}
35contains initialization for a 68349 based board as well.
36
37Similarly, the ERC32 BSP has startup code written in assembly language
38and C.  However, this BSP shares this code with other SPARC BSPs.
39Thus the @code{Makefile.am} explicitly references the following files
40for this functionality.
41
42@example
43../../sparc/shared/start.S
44@end example
45
46@b{NOTE:} In most BSPs, the directory named @code{start340} in the
47gen68340 BSP would be simply named @code{start} or start followed by a
48BSP designation.
49
50@section Required Global Variables
51
52Although not strictly part of initialization, there are a few global
53variables assumed to exist by reusable device drivers.  These global
54variables should only defined by the BSP when using one of these device
55drivers.
56
57The BSP author probably should be aware of the @code{Configuration}
58Table structure generated by @code{<rtems/confdefs.h>} during debug but
59should not explicitly reference it in the source code.  There are helper
60routines provided by RTEMS to access individual fields.
61
62In older RTEMS versions, the BSP included a number of required global
63variables.  We have made every attempt to eliminate these in the interest
64of simplicity.
65
66@section Board Initialization
67
68This section describes the steps an application goes through from the
69time the first BSP code is executed until the first application task
70executes.  The following figure illustrates the program flow during
71this sequence:
72
73@ifset use-ascii
74IMAGE NOT AVAILABLE IN ASCII VERSION
75@end ifset
76
77@ifset use-tex
78@image{BSPInitFlowchart-49,6in,,Initialization Sequence,.png}
79@c      @image{FILENAME[, WIDTH[, HEIGHT[, ALTTEXT[, EXTENSION]]]]}
80@end ifset
81
82@ifset use-html
83@html
84<center>
85<IMG SRC="BSPInitFlowchart-49.png" WIDTH=800 ALT="Initialization Sequence">
86</center>
87@end html
88@end ifset
89
90The above figure illustrates the flow from assembly language start code
91to the shared @code{bootcard.c} framework then through the C Library,
92RTEMS, device driver initialization phases, and the context switch
93to the first application task.  After this, the application executes
94until it calls @code{exit}, @code{rtems_shutdown_executive}, or some
95other normal termination initiating routine and a fatal system state is
96reached.  The optional @code{bsp_fatal_extension} initial extension can perform
97BSP specific system termination.
98
99The routines invoked during this will be discussed and their location
100in the RTEMS source tree pointed out as we discuss each.
101
102@subsection Start Code - Assembly Language Initialization
103
104The assembly language code in the directory @code{start} is the first part
105of the application to execute.  It is responsible for initializing the
106processor and board enough to execute the rest of the BSP.  This includes:
107
108@itemize @bullet
109@item initializing the stack
110@item zeroing out the uninitialized data section @code{.bss}
111@item disabling external interrupts
112@item copy the initialized data from ROM to RAM
113@end itemize
114
115The general rule of thumb is that the start code in assembly should
116do the minimum necessary to allow C code to execute to complete the
117initialization sequence.
118
119The initial assembly language start code completes its execution by
120invoking the shared routine @code{boot_card()}.
121
122The label (symbolic name) associated with the starting address of the
123program is typically called @code{start}.  The start object file is the
124first object file linked into the program image so it is ensured that
125the start code is at offset 0 in the @code{.text} section.  It is the
126responsibility of the linker script in conjunction with the compiler
127specifications file to put the start code in the correct location in
128the application image.
129
130@subsection boot_card() - Boot the Card
131
132The @code{boot_card()} is the first C code invoked.  This file is the
133core component in the RTEMS BSP Initialization Framework and provides
134the proper sequencing of initialization steps for the BSP, RTEMS and
135device drivers. All BSPs use the same shared version of @code{boot_card()}
136which is located in the following file:
137
138@example
139c/src/lib/libbsp/shared/bootcard.c
140@end example
141
142The @code{boot_card()} routine performs the following functions:
143
144@itemize @bullet
145
146@item It disables processor interrupts.
147
148@item It sets the command line argument variables
149for later use by the application.
150
151@item It invokes the BSP specific routine @code{bsp_start()} which is
152written in C and thus able to perform more advanced initialization.
153Often MMU and bus initialization occurs here.
154
155@item It invokes the BSP specific routine @code{bsp_work_area_initialize()}
156which is supposed to initialize the RTEMS Workspace and the C Program Heap.
157Usually the default implementation in
158@code{c/src/lib/libbsp/shared/bspgetworkarea.c} should be sufficient.  Custom
159implementations can use @code{bsp_work_area_initialize_default()} or
160@code{bsp_work_area_initialize_with_table()} available as inline functions from
161@code{#include <bsp/bootcard.h>}.
162
163@item It invokes the RTEMS directive
164@code{rtems_initialize_data_structures()} to initialize the RTEMS
165executive to a state where objects can be created but tasking is not
166enabled.
167
168@item It invokes the BSP specific routine @code{bsp_libc_init()} to initialize
169the C Library.  Usually the default implementation in
170@code{c/src/lib/libbsp/shared/bsplibc.c} should be sufficient.
171
172@item It invokes the BSP specific routine @code{bsp_pretasking_hook}. On
173most BSPs which utilize the framework, this routine does nothing.
174
175@item It invokes the RTEMS directive
176@code{rtems_initialize_before_drivers()} to initialize the MPCI Server
177thread in a multiprocessor configuration and execute API specific
178extensions.
179
180@item It invokes the BSP specific routine @code{bsp_predriver_hook}. For
181most BSPs, the implementation of this routine does nothing.
182
183@item It invokes the RTEMS directive
184@code{rtems_initialize_device_drivers()} to initialize the statically
185configured set of device drivers in the order they were specified in
186the Configuration Table.
187
188@item It invokes the BSP specific routine @code{bsp_postdriver_hook}. For
189most BSPs, the implementation of this routine does nothing.  However, some
190BSPs use this hook and perform some initialization which must be done at
191this point in the initialization sequence.  This is the last opportunity
192for the BSP to insert BSP specific code into the initialization sequence.
193
194@item It invokes the RTEMS directive
195@code{rtems_initialize_start_multitasking()}
196which initiates multitasking and performs a context switch to the
197first user application task and may enable interrupts as a side-effect of
198that context switch.  The context switch saves the executing context.  The
199application runs now.  The directive rtems_shutdown_executive() will return
200to the saved context.  The exit() function will use this directive.
201
202After a return to the saved context a fatal system state is reached.  The
203fatal source is RTEMS_FATAL_SOURCE_EXIT with a fatal code set to the value
204passed to rtems_shutdown_executive().
205
206The enabling of interrupts during the first context switch is often the source
207for fatal errors during BSP development because the BSP did not clear and/or
208disable all interrupt sources and a spurious interrupt will occur.
209
210When in the context of the first task but before its body has been
211entered, any C++ Global Constructors will be invoked.
212
213@end itemize
214
215That's it.  We just went through the entire sequence.
216
217@subsection bsp_start() - BSP Specific Initialization
218
219This is the first BSP specific C routine to execute during system
220initialization.  This routine often performs required fundamental
221hardware initialization such as setting bus controller registers
222that do not have a direct impact on whether or not C code can execute.
223The source code for this routine is usually found in the following
224file:
225
226@example
227c/src/lib/libbsp/CPU/BSP/startup/bspstart.c
228@end example
229
230On older BSPs not using @code{boot_card()}'s support for allocating memory
231to the C Program Heap and RTEMS Workspace, one of the most important
232functions performed by this routine is determining where the RTEMS
233Workspace is to be located in memory.  All RTEMS objects and task stacks
234will be allocated from this Workspace.  The RTEMS Workspace is distinct
235from the application heap used for @code{malloc()}.  Many BSPs place
236the RTEMS Workspace area at the end of RAM although this is certainly
237not a requirement.
238
239After completing execution, this routine returns to the @code{boot_card()}
240routine.
241
242@subsection RTEMS Pretasking Callback
243
244The method @code{bsp_pretasking_hook()} is the BSP specific routine invoked
245once RTEMS API initialization is complete but before interrupts and tasking are
246enabled.  The idle thread exists at this time.  The pretasking hook is optional
247and the user may use the shared version.
248
249The @code{bsp_pretasking_hook()} routine is the appropriate place to initialize
250any BSP specific support components which depend on the RTEMS APIs.
251
252@subsection RTEMS Predriver Callback
253
254The @code{bsp_predriver_hook()} method is the BSP specific routine that
255is is invoked immediately before the the device drivers and MPCI are
256initialized. RTEMS initialization is complete but interrupts and tasking
257are disabled.
258
259The BSP may use the shared version of this routine which is empty.
260Most BSPs do not provide a specific implementation of this callback.
261
262@subsection Device Driver Initialization
263
264At this point in the initialization sequence, the initialization
265routines for all of the device drivers specified in the Device
266Driver Table are invoked.  The initialization routines are invoked
267in the order they appear in the Device Driver Table.
268
269The Driver Address Table is part of the RTEMS Configuration Table. It
270defines device drivers entry points (initialization, open, close, read,
271write, and control). For more information about this table, please
272refer to the @b{Configuring a System} chapter in the
273@b{RTEMS Application C User's Guide}.
274
275The RTEMS initialization procedure calls the initialization function for
276every driver defined in the RTEMS Configuration Table (this allows
277one to include only the drivers needed by the application).
278
279All these primitives have a major and a minor number as arguments:
280
281@itemize @bullet
282
283@item the major number refers to the driver type,
284
285@item the minor number is used to control two peripherals with the same
286driver (for instance, we define only one major number for the serial
287driver, but two minor numbers for channel A and B if there are two
288channels in the UART).
289
290@end itemize
291
292@subsection RTEMS Postdriver Callback
293
294The @code{bsp_postdriver_hook()} BSP specific routine is invoked
295immediately after the the device drivers and MPCI are initialized.
296Interrupts and tasking are disabled.
297
298Most BSPs use the shared implementation of this routine which is responsible for opening the device @code{/dev/console} for standard input, output and error if the application has configured the Console Device Driver.  This file is located at:
299
300@example
301c/src/lib/libbsp/shared/bsppost.c
302@end example
303
304@section The Interrupt Vector Table
305
306The Interrupt Vector Table is called different things on different
307processor families but the basic functionality is the same.  Each
308entry in the Table corresponds to the handler routine for a particular
309interrupt source.  When an interrupt from that source occurs, the
310specified handler routine is invoked.  Some context information is
311saved by the processor automatically when this happens.  RTEMS saves
312enough context information so that an interrupt service routine
313can be implemented in a high level language.
314
315On some processors, the Interrupt Vector Table is at a fixed address.  If
316this address is in RAM, then usually the BSP only has to initialize
317it to contain pointers to default handlers.  If the table is in ROM,
318then the application developer will have to take special steps to
319fill in the table.
320
321If the base address of the Interrupt Vector Table can be dynamically
322changed to an arbitrary address, then the RTEMS port to that processor
323family will usually allocate its own table and install it.  For example,
324on some members of the Motorola MC68xxx family, the Vector Base Register
325(@code{vbr}) contains this base address. 
326
327@subsection Interrupt Vector Table on the gen68340 BSP
328
329The gen68340 BSP provides a default Interrupt Vector Table in the
330file @code{$BSP_ROOT/start340/start340.s}.  After the @code{entry}
331label is the definition of space reserved for the table of
332interrupts vectors.  This space is assigned the symbolic name
333of @code{__uhoh} in the @code{gen68340} BSP.
334
335At @code{__uhoh} label is the default interrupt handler routine. This
336routine is only called when an unexpected interrupts is raised.  One can
337add their own routine there (in that case there's a call to a routine -
338$BSP_ROOT/startup/dumpanic.c - that prints which address caused the
339interrupt and the contents of the registers, stack, etc.), but this should
340not return.
341
342@section Chip Select Initialization
343
344When the microprocessor accesses a memory area, address decoding is
345handled by an address decoder, so that the microprocessor knows which
346memory chip(s) to access.   The following figure illustrates this:
347
348@example
349@group
350                     +-------------------+
351         ------------|                   |
352         ------------|                   |------------
353         ------------|      Address      |------------
354         ------------|      Decoder      |------------
355         ------------|                   |------------
356         ------------|                   |
357                     +-------------------+
358           CPU Bus                           Chip Select
359@end group
360@end example
361
362
363The Chip Select registers must be programmed such that they match
364the @code{linkcmds} settings. In the gen68340 BSP, ROM and RAM
365addresses can be found in both the @code{linkcmds} and initialization
366code, but this is not a great way to do this.  It is better to
367define addresses in the linker script.
368
369@section Integrated Processor Registers Initialization
370
371The CPUs used in many embedded systems are highly complex devices
372with multiple peripherals on the CPU itself.  For these devices,
373there are always some specific integrated processor registers
374that must be initialized.  Refer to the processors' manuals for
375details on these registers and be VERY careful programming them.
376
377@section Data Section Recopy
378
379The next initialization part can be found in
380@code{$BSP340_ROOT/start340/init68340.c}. First the Interrupt
381Vector Table is copied into RAM, then the data section recopy is initiated
382(_CopyDataClearBSSAndStart in @code{$BSP340_ROOT/start340/startfor340only.s}).
383
384This code performs the following actions:
385
386@itemize @bullet
387
388@item copies the .data section from ROM to its location reserved in RAM
389(see @ref{Linker Script Initialized Data} for more details about this copy),
390
391@item clear @code{.bss} section (all the non-initialized
392data will take value 0).
393
394@end itemize
395
396@section The RTEMS Configuration Table
397
398The RTEMS configuration table contains the maximum number of objects RTEMS
399can handle during the application (e.g. maximum number of tasks,
400semaphores, etc.). It's used to allocate the size for the RTEMS inner data
401structures.
402
403The RTEMS configuration table is application dependent, which means that
404one has to provide one per application. It is usually defined by defining
405macros and including the header file @code{<rtems/confdefs.h>}.  In simple
406applications such as the tests provided with RTEMS, it is commonly found
407in the main module of the application.  For more complex applications,
408it may be in a file by itself.
409
410The header file @code{<rtems/confdefs.h>} defines a constant table
411named @code{Configuration}.  With RTEMS 4.8 and older, it was accepted
412practice for the BSP to copy this table into a modifiable copy named
413@code{BSP_Configuration}.  This copy of the table was modified to define
414the base address of the RTEMS Executive Workspace as well as to reflect
415any BSP and device driver requirements not automatically handled by the
416application.  In 4.9 and newer, we have eliminated the BSP copies of the
417configuration tables and are making efforts to make the configuration
418information generated by @code{<rtems/confdefs.h>} constant and read only.
419
420For more information on the RTEMS Configuration Table, refer to the
421@b{RTEMS Application C User's Guide}.
422
Note: See TracBrowser for help on using the repository browser.