RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

2008-08-22 Joel Sherrill <joel.sherrill@oarcorp.com>

Browse Source 
* bsp_howto/Makefile.am, bsp_howto/init.t, bsp_howto/intro.t,
	bsp_howto/makefiles.t, bsp_howto/support.t: Update initialization
	sequence. Add another figure.
	* bsp_howto/BSPInitFlowchart-49.eps, bsp_howto/BSPInitFlowchart-49.png: New files.
This commit is contained in:
Joel Sherrill
2008-08-22 16:38:00 +00:00
parent a78df7ba0c
commit 0eb595a839
8 changed files with 258 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files

224
doc/bsp_howto/init.t
View File

@@ -1,5 +1,5 @@
@c
@c COPYRIGHT (c) 1988-2002.
@c COPYRIGHT (c) 1988-2008.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@@ -18,62 +18,97 @@ commonly found in the BSP related to initialization. The remainder of
this chapter covers special issues which require attention such
as interrupt vector table and chip select initialization.
Most of the examples in this chapter will be based on the gen68340 BSP
initialization code. Like most BSPs, the initialization for this
BSP is divided into two subdirectories under the BSP source directory.
The gen68340 BSP source code is in the following directory:
Most of the examples in this chapter will be based on the SPARC/ERC32 and
m68k/gen68340 BSP initialization code. Like most BSPs, the initialization
for these BSP is divided into two subdirectories under the BSP source
directory. The BSP source code for these BSPs is in the following
directories:
@example
c/src/lib/libbsp/m68k/gen68340
c/src/lib/libbsp/sparc/erc32
@end example
The following source code files are in this subdirectory.
@itemize @bullet
@item @code{start340}: assembly language code which contains early
initialization routines
@item @code{startup}: C code with higher level routines (RTEMS
initialization related)
@end itemize
@b{NOTE:} The directory @code{start340} is simply named @code{start} or
start followed by a BSP designation.
In the @code{start340} directory are two source files. The file
@code{startfor340only.s} is the simpler of these files as it only has
initialization code for a MC68340 board. The file @code{start340.s}
Both BSPs contain startup code written in assembly language and C.
The gen68340 BSP has its early initialization start code in the
@code{start340} subdirectory and its C startup code in the @code{startup}
directory. In the @code{start340} directory are two source files.
The file @code{startfor340only.s} is the simpler of these files as it only
has initialization code for a MC68340 board. The file @code{start340.s}
contains initialization for a 68349 based board as well.
Similarly, the ERC32 BSP has startup code written in assembly language
and C. However, this BSP shares this code with other SPARC BSPs.
Thus the @code{Makefile.am} explicitly references the following files
for this functionality.
@example
../../sparc/shared/start.S
../../sparc/shared/bspclean.c
@end example
@b{NOTE:} In most BSPs, the directory named @code{start340} in the
gen68340 BSP would be simply named @code{start} or start followed by a
BSP designation.
@section Required Global Variables
Although not strictly part of initialization, there are a few global
variables assumed to exist by many support components. These
global variables are normally not defined by the BSP since the RTEMS
Project strives to avoid duplication as much as possible.
The following is a list of these global variables:
variables assumed to exist by reusable device drivers. These global
variables should only defined by the BSP when using one of these device
drivers.
@itemize @bullet
@item @code{Configuration} is the RTEMS Configuration Table generated
by @code{<rtems/confdefs.h>}.
The BSP author probably should be aware of the @code{Configuration}
Table structure generated by @code{<rtems/confdefs.h>} during debug but
should not explicitly reference it in the source code. There are helper
routines provided by RTEMS to access individual fields.
@end itemize
In older RTEMS versions, the BSP included a number of required global
variables. We have made every attempt to eliminate these in the interest
of simplicity.
@section Board Initialization
This section describes the steps an application goes through from the
time the first BSP code is executed until the first application task
executes. The routines invoked during this will be discussed and
their location in the RTEMS source tree pointed out.
executes. The following figure illustrates the program flow during
this sequence:
@ifset use-ascii
IMAGE NOT AVAILABLE IN ASCII VERSION
@end ifset
@ifset use-tex
@image{BSPInitFlowchart-49,6in,,Initialization Sequence,.png}
@c @image{FILENAME[, WIDTH[, HEIGHT[, ALTTEXT[, EXTENSION]]]]}
@end ifset
@ifset use-html
@html
<center>
<IMG SRC="BSPInitFlowchart-49.png" WIDTH=800 ALT="Initialization Sequence">
</center>
@end html
@end ifset
The above figure illustrates the flow from assembly language start code
to the shared @code{bootcard.c} framework then through the C Library,
RTEMS, device driver initialization phases, and the context switch
to the first application task. After this, the application executes
until it calls @code{exit}, @code{rtems_shutdown_executive}, or some
other normal termination initiating routine and control is returned
to @code{bootcard.c} which allows the BSP to perform some clanup in C
(@code{bsp_cleanup}) and then @code{boot_card} returns to the assembly
language which initially invoked it.
The routines invoked during this will be discussed and their location
in the RTEMS source tree pointed out as we discuss each.
@subsection Start Code - Assembly Language Initialization
The assembly language code in the directory @code{start} is
the first part of the application to execute. It is
responsible for initializing the processor and board enough to execute
the rest of the BSP. This includes:
The assembly language code in the directory @code{start} is the first part
of the application to execute. It is responsible for initializing the
processor and board enough to execute the rest of the BSP. This includes:
@itemize @bullet
@item initializing the stack
@@ -82,26 +117,28 @@ the rest of the BSP. This includes:
@item copy the initialized data from ROM to RAM
@end itemize
The general rule of thumb is that the
start code in assembly should do the minimum necessary to allow C code
to execute to complete the initialization sequence.
The general rule of thumb is that the start code in assembly should
do the minimum necessary to allow C code to execute to complete the
initialization sequence.
The initial assembly language start code completes its execution by
invoking the shared routine @code{boot_card()}.
The label (symbolic name) associated with the starting address of the
program is typically called @code{start}. The start object file
is the first object file linked into the program image so it is insured
that the start code is at offset 0 in the @code{.text} section. It is
the responsibility of the linker script in conjunction with the
compiler specifications file to put the start code in the correct location
in the application image.
program is typically called @code{start}. The start object file is the
first object file linked into the program image so it is ensured that
the start code is at offset 0 in the @code{.text} section. It is the
responsibility of the linker script in conjunction with the compiler
specifications file to put the start code in the correct location in
the application image.
@subsection boot_card() - Boot the Card
The @code{boot_card()} is the first C code invoked. Most of the BSPs
use the same shared version of @code{boot_card()} which is located in
the following file:
The @code{boot_card()} is the first C code invoked. This file is the
core component in the RTEMS BSP Initialization Framework and provides
the proper sequencing of initialization steps for the BSP, RTEMS and
device drivers. All BSPs use the same shared version of @code{boot_card()}
which is located in the following file:
@example
c/src/lib/libbsp/shared/bootcard.c
@@ -111,23 +148,88 @@ The @code{boot_card()} routine performs the following functions:
@itemize @bullet
@item invokes the BSP specific routine @code{bsp_start()},
@item It disables processor interrupts.
@item invokes the RTEMS directive @code{rtems_initialize_executive_early()}
to initialize the executive, C Library, and all device drivers but
return without initiating multitasking or enabling interrupts,
@item It sets the global program name and command line argument variables
for later use by the application.
@item invokes the shared @code{main()} in the same file as
@code{boot_card()} which does not return until the
@code{rtems_shutdown_executive} directive is called, and
@item If the macro is BSP_BOOTCARD_HANDLES_RAM_ALLOCATION is defined, it
will invoke the BSP specific @code{bsp_get_work_area} function to obtain
information on the amount and location of BSP RAM that is available to
be allocated to the C Program Heap and RTEMS Workspace. If the amount
of memory available for the RTEMS Workspace is less than that required
by the application (e.g. @code{rtems_configuration_get_work_space_size()},
then a message is printed using @code{printk}, @code{bsp_cleanup} is
invoked, and -1 is return to the assembly language start code. BSPs which
use this memory allocation functionality in @code{bootcard.c}
must invoke the RTEMS specific autoconf macro
@code{RTEMS_BSP_BOOTCARD_HANDLES_RAM_ALLOCATION} in the BSP's
@code{configure.ac} file.
@item invokes the BSP specific routine @code{bsp_cleanup()} to perform
any necessary board specific shutdown actions.
@item It invokes the BSP specific routine @code{bsp_start()} which is
written in C and thus able to perform more advanced initialization.
Often MMU and bus initialization occurs here.
@item It invokes the RTEMS directive
@code{rtems_initialize_data_structures()} to initialize the RTEMS
executive to a state where objects can be created but tasking is not
enabled.
@item If the macro is BSP_BOOTCARD_HANDLES_RAM_ALLOCATION is defined,
it will calculate the memory available for the C Program Heap and invoke
the initialization routine for the C Library with this information.
@item It invokes the BSP specific routine @code{bsp_pretasking_hook}. On
most BSPs which utilize the framework, this routine does nothing.
@item If @code{RTEMS_DEBUG} is enabled, then the RTEMS debug mask level
is inialized appropriately.
@item It invokes the RTEMS directive
@code{rtems_initialize_before_drivers()} to initialize the MPCI Server
thread in a multiprocessor configuration and execute API specific
extensions.
@item It invokes the BSP specific routine @code{bsp_predriver_hook}. For
most BSPs, the implementation of this routine does nothing. However,
on some BSPs, required subsystems which utilize the C Library
(e.g. @code{malloc} in particular) may be initialized at this point.
@item It invokes the RTEMS directive
@code{rtems_initialize_device_drivers()} to initialize the statically
configured set of device drivers in the order they were specified in
the Configuration Table.
@item It invokes the BSP specific routine @code{bsp_postdriver_hook}. For
most BSPs, the implementation of this routine does nothing. However, some
BSPs use this hook and perform some initialization which must be done at
this point in the initialization sequence. This is the last opportunity
for the BSP to insert BSP specific code into the initialization sequence.
@item It invokes the RTEMS directive
@code{rtems_initialize_start_multitasking()} which starts multitasking and context switches to the first task. @code{boot_card()} will not return until the application is shutdown. As part of this sequence the following actions occur:
@itemize @bullet
@item RTEMS will context switch to the first application task. As a
side-effect of this context switch, processor interrupts will be enabled.
This is often the source of a fatal error during BSP development because
the BSP did not clear and/or disable all interrupt sources and a spurious
interrupt will occur .
@item When in the context of the first task but before its body has been
entered, any C++ Global Constructors will be invoked.
@end itemize
It is important to note that the executive and much of the
support environment must be initialized before invoking @code{main()}.
@item Finally after the application shutsdown RTEMS and control is
return to @code{boot_card()} from RTEMS, it invokes the BSP specific
routine @code{bsp_cleanup()} to perform any necessary board specific
shutdown actions.
@end itemize
That's it. We just went through the entire sequence.
@subsection bsp_start() - BSP Specific Initialization
@@ -180,7 +282,7 @@ support library and, most importantly, invokes the C++ global
constructors.
The precise placement of when @code{main()} is invoked in the
RTEMS initialization sequence insures that C Library and non-blocking
RTEMS initialization sequence ensures that C Library and non-blocking
calls can be made in global C++ constructors.
The shared implementation of this routine is located in the following file: