diff options
Diffstat (limited to 'doc/bsp_howto/init.t')
| -rw-r--r-- | doc/bsp_howto/init.t | 364 |
1 files changed, 0 insertions, 364 deletions
diff --git a/doc/bsp_howto/init.t b/doc/bsp_howto/init.t deleted file mode 100644 index 669d5f9d3b..0000000000 --- a/doc/bsp_howto/init.t +++ /dev/null @@ -1,364 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-1998. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c $Id$ -@c - -@chapter Initialization Code - -@section Introduction - -The initialization code is the first piece of code executed when there's a -reset/reboot. Its purpose is to initialize the board for the application. -This chapter contains a narrative description of the initialization -process followed by a description of each of the files and routines -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 in the following directory: - -@example -c/src/lib/libbsp/m68k/gen68340: -@end example - -@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} -contains initialization for a 68349 based board as well. - -@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. - -@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: - -@itemize @bullet -@item initializing the stack -@item zeroing out the uninitialized data section @code{.bss} -@item disabling external interrupts -@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 initial assembly language start code completes its execution by -invoking the shared routine @code{boot_card()}. - -@subsection boot_card() - Boot the Card - -The @code{boot_card()} is the first C code invoked. Most of the BSPs -use the sams shared version of @code{boot_card()} which is located in -the following file: - -@example -c/src/lib/libbsp/shared/main.c -@end example - -The @code{boot_card()} routine performs the following functions: - -@itemize @bullet - -@item initializes the shared fields of the CPU Configuration Table -(variable name @code{Cpu_table}) to a default state, - -@item copies the application's RTEMS Configuration Table -(variable name @code{Configuration}) to the BSP's Configuration -Table (variable name @code{BSP_Configuration}) so it can be modified -as necessary without copying the original table, - -@item invokes the BSP specific routine @code{bsp_start()}, - -@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 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 invokes the BSP specific routine @code{bsp_cleanup()} to perform -any necessary board specific shutdown actions. - -@end itemize - -It is important to note that the executive and much of the -support environment must be initialized before invoking @code{main()}. - -@subsection bsp_start() - BSP Specific Initialization - -This is the first BSP specific C routine to execute during system -initialization. This routine often performs required fundamental -hardware initialization such as setting bus controller registers -that do not have a direct impact on whether or not C code can execute. -The source code for this routine is usually found in the following -file: - -@example -c/src/lib/libbsp/CPU/BSP/startup/bspstart.c -@end example - -This routine is also responsible for overriding the default settings -in the CPU Configuration Table and setting port specific entries -in this table. This routine will typically install routines -for one or more of the following initialization hooks: - -@itemize @bullet -@item BSP Pretasking Hook -@item BSP Predriver Hook -@item BSP Postdriver Hook -@end itemize - -One of the most important functions performed by this routine -is determining where the RTEMS Executive Work Space is to be -located in memory. All RTEMS objects and task stacks will be -allocated from this Workspace. The RTEMS Workspace is distinct -from the application heap used for @code{malloc()}. - -Many BSPs place this area at the end of RAM although this is -certainly not a requirement. - -After completing execution, this routine returns to the -@code{boot_card()} routine. - -@subsection main() - C Main - -This routine is the C main entry point. This is a special routine -and the GNU Compiler Suite treats it as such. The GNU C Compiler -recognizes @code{main()} and automatically inserts a call to the -compiler run-time support routine @code{__main()} as the first -code executed in @code{main()}. - -The routine @code{__main()} initializes the compiler's basic run-time -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 -calls can be made in global C++ constructors. - -The shared implementation of this routine is located in the following file: - -@example -c/src/lib/libbsp/shared/main.c -@end example - -In addition to the implicit invocation of @code{__main}, this -routine performs some explitit initialization. This routine -sets the variable @code{rtems_progname} and initiates -multitasking via a call to the RTEMS directive -@code{rtems_initialize_executive_late}. It is important to note -that the executive does not return to this routine until the -RTEMS directive @code{rtems_shutdown_executive} is invoked. - -@subsection RTEMS Pretasking Callback - -The @code{pretasking_hook} entry in the RTEMS CPU Configuration -Table may be the address of a user provided routine that is -invoked once RTEMS initialization is complete but before interrupts -and tasking are enabled. No tasks -- not even the IDLE task -- have -been created when this hook is invoked. The pretasking hook is optional. - -Although optional, most of the RTEMS BSPs provide a pretasking hook -callback. This routine is usually called @code{bsp_pretasking_hook} -and is found in the file: - -@example -c/src/lib/libbsp/CPU/BSP/startup/bspstart.c -@end example - -The @code{bsp_pretasking_hook()} routine is the appropriate place to -initialize any support components which depend on the RTEMS APIs. -Most BSPs initialize the RTEMS C Library support in their -implementation of @code{bsp_pretasking_hook()}. This initialization -includes the application heap as well as the reentrancy support -for the C Library. - -@subsection RTEMS Predriver Callback - -XXX is the address of the user provided -routine which is invoked with tasking enabled immediately before -the MPCI and device drivers are initialized. RTEMS -initialization is complete, interrupts and tasking are enabled, -but no device drivers are initialized. This field may be NULL to -indicate that the hook is not utilized. - -@subsection Device Driver Initialization - -At this point in the initialization sequence, the initialization -routines for all of the device drivers specified in the Device -Driver Table are invoked. - -@subsection RTEMS Postdriver Callback - -XXX is the address of the user provided -routine which is invoked with tasking enabled immediately after -the MPCI and device drivers are initialized. RTEMS -initialization is complete, interrupts and tasking are enabled, -and the device drivers are initialized. This field may be NULL -to indicate that the hook is not utilized. - - -@section The Interrupts Vector Table - - - -After the entry label starts a code section in which some room is -allocated for the table of interrupts vectors. They are assigned to the -address of the __uhoh label. - -At __uhoh label you can find the default interrupt handler routine. This -routine is only called when an unexpected interrupts is raised. You can -add your own routine there (in that case there's a call to a routine - -$BSP_ROOT/startup/dumpanic.c - that pri nts which address caused the -interrupt and the contents of the registers, stack...), but this should -not return. - -@section Chip Select Initialization - -When the microprocessor accesses a memory area, address decoding is -handled by an address decoder (!), so that the microprocessor knows which -memory chip to access. - -Figure 4 : address decoding - -You have to program your Chip Select registers in order that they match -the linkcmds settings. In this BSP ROM and RAM addresses can be found in -both the linkcmds and initialization code, but this is not a great way to -do, better use some shared variables . - -@section Integrated processor registers initialization - -There are always some specific integrated processor registers -initialization to do. Integrated processors' user manuals often detail -them. - -@section Data section recopy - -The next initialization part can be found in -$BSP340_ROOT/start340/init68340.c. First the Interrupt Vector Table is -copied into RAM, then the data section recopy is initiated -(_CopyDataClearBSSAndStart in $BSP340_ROOT/start340/startfor340only.s). - -This code performs the following actions: - -@itemize @bullet - -@item copies the .data section from ROM to its location reserved in RAM -(see 5.2 for more details about this copy), - -@item clear .bss section (all the non-initialized data will take value 0). - -@end itemize - -Then control is passed to the RTEMS-specific initialization code. - -@section RTEMS-Specific Initialization - -@section The RTEMS configuration table - -The RTEMS configuration table contains the maximum number of objects RTEMS -can handle during the application (e.g. maximum number of tasks, -semaphores, etc.). It's used to allocate the size for the RTEMS inner data -structures. - -The RTEMS configuration table is application dependant, which means that -one has to provide one per application. It's usually an header file -included in the main module of the application. - -The BSP_Configuration label points on this table. - -For more information on the RTEMS configuration table, refer to C user's -guide, chapter 23 <insert a link here>. - -@section RTEMS initialization procedure - -The RTEMS initialization procedure is described in the 3rd chapter of the -C user's manual <insert a link here>. Please read it carefully. - -There are a few BSP specific functions called from the initialization -manager. They can be found in the startup directory of the BSP. - -@table @b - -@item bspstart.c - -It starts the application. It includes application, board, and monitor -specific initialization and configuration. - -@item bspstart.c - -@table @b -@item bsp_pretasking_hook - -It starts libc support (needed to allocate some memory using C primitive -malloc for example). Heap size must be passed in argument, this is the one -which is defined in the linkcmds (cf. 5.) - - -@end table - -@item bspclean.c - -@table @b - -@item bsp_cleanup - -Return control to the monitor. - -@end table - -@end table - -@section Drivers initialization - -The Driver Address Table is part of the RTEMS configuration table. It -defines RTEMS drivers entry points (initialization, open, close, read, -write, and control). For more information about this table, check C User's -manual chapter 21 section 6 <insert a l ink here>. - -The RTEMS initialization procedure calls the initialization function for -every driver defined in the RTEMS Configuration Table (this permits to add -only the drivers needed by the application). - -All these primitives have a major and a minor number as arguments: - -@itemize @bullet - -@item the major number refers to the driver type, - -@item the minor number is used to control two peripherals with the same -driver (for instance, we define only one major number for the serial -driver, but two minor numbers for channel A and B if there are two -channels in the UART). - -@end itemize - |