diff options
Diffstat (limited to 'doc/bsp_howto/init.t')
| -rw-r--r-- | doc/bsp_howto/init.t | 430 |
1 files changed, 0 insertions, 430 deletions
diff --git a/doc/bsp_howto/init.t b/doc/bsp_howto/init.t deleted file mode 100644 index ee67d59c11..0000000000 --- a/doc/bsp_howto/init.t +++ /dev/null @@ -1,430 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-1999. -@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 is in the following directory: - -@example -c/src/lib/libbsp/m68k/gen68340 -@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} -contains initialization for a 68349 based board as well. - -@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 usually declared in the file @code{startup/bspstart.c} -that provides most of the BSP specific initialization. The following is -a list of these global variables: - -@itemize @bullet -@item @code{BSP_Configuration} is the BSP's writable copy of the RTEMS -Configuration Table. - -@item @code{Cpu_table} is the RTEMS CPU Dependent Information Table. - -@item @code{bsp_isr_level} is the interrupt level that is set at -system startup. It will be restored when the executive returns -control to the BSP. - -@end itemize - -@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()}. - -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. - -@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: - -@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 may include increasing the maximum number -of some types of RTEMS system objects to reflect the needs of -the BSP and the base set of device drivers. This routine will -typically also 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 Workspace 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 the RTEMS Workspace 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 explicit 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. - -The RTEMS initialization procedure is described in the @b{Initialization -Manager} chapter of the @b{RTEMS Application C User's Guide}. -Please refer to that manual for more information. - -@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 API 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 set the debug level for the system and initialize the -RTEMS C Library support in their -implementation of @code{bsp_pretasking_hook()}. This initialization -includes the application heap used by the @code{malloc} family -of routines as well as the reentrancy support for the C Library. - -The routine @code{bsp_libc_init} routine invoked from the -@code{bsp_pretasking_hook()} routine is passed the starting -address, length, and growth amount passed to @code{sbrk}. -This "sbrk amount" is only used if the heap runs out of -memory. In this case, the RTEMS malloc implementation will -invoked @code{sbrk} to obtain more memory. See -@ref{Miscellaneous Support Files sbrk() Implementation} for more details. - -@subsection RTEMS Predriver Callback - -The @code{predriver_hook} entry in the RTEMS CPU Configuration -Table may be the address of a user provided routine that is -is invoked immediately before the the device drivers and MPCI -are initialized. RTEMS -initialization is complete but interrupts and tasking are disabled. -This field may be NULL to indicate that the hook is not utilized. - -Most BSPs do not use this callback. - -@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. The initialization routines are invoked -in the order they appear in the Device Driver Table. - -The Driver Address Table is part of the RTEMS Configuration Table. It -defines device drivers entry points (initialization, open, close, read, -write, and control). For more information about this table, please -refer to the @b{Configuring a System} chapter in the -@b{RTEMS Application C User's Guide}. - -The RTEMS initialization procedure calls the initialization function for -every driver defined in the RTEMS Configuration Table (this allows -one to include 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 - -@subsection RTEMS Postdriver Callback - -The @code{postdriver_hook} entry in the RTEMS CPU Configuration -Table may be the address of a user provided routine that is -invoked immediately after the the device drivers and MPCI are initialized. -Interrupts and tasking are disabled. The postdriver hook is optional. - -Although optional, most of the RTEMS BSPs provide a postdriver hook -callback. This routine is usually called @code{bsp_postdriver_hook} -and is found in the file: - -@example -c/src/lib/libbsp/CPU/BSP/startup/bsppost.c -@end example - -The @code{bsp_postdriver_hook()} routine is the appropriate place to -perform initialization that must be performed before the first task -executes but requires that a device driver be initialized. The -shared implementation of the postdriver hook opens the default -standard in, out, and error files and associates them with -@code{/dev/console}. - -@section The Interrupt Vector Table - -The Interrupt Vector Table is called different things on different -processor families but the basic functionality is the same. Each -entry in the Table corresponds to the handler routine for a particular -interrupt source. When an interrupt from that source occurs, the -specified handler routine is invoked. Some context information is -saved by the processor automatically when this happens. RTEMS saves -enough context information so that an interrupt service routine -can be implemented in a high level language. - -On some processors, the Interrupt Vector Table is at a fixed address. If -this address is in RAM, then usually the BSP only has to initialize -it to contain pointers to default handlers. If the table is in ROM, -then the application developer will have to take special steps to -fill in the table. - -If the base address of the Interrupt Vector Table can be dynamically -changed to an arbitrary address, then the RTEMS port to that processor -family will usually allocate its own table and install it. For example, -on some members of the Motorola MC68xxx family, the Vector Base Register -(@code{vbr}) contains this base address. - -@subsection Interrupt Vector Table on the gen68340 BSP - -The gen68340 BSP provides a default Interrupt Vector Table in the -file @code{$BSP_ROOT/start340/start340.s}. After the @code{entry} -label is the definition of space reserved for the table of -interrupts vectors. This space is assigned the symbolic name -of @code{__uhoh} in the @code{gen68340} BSP. - -At @code{__uhoh} label is the default interrupt handler routine. This -routine is only called when an unexpected interrupts is raised. One can -add their own routine there (in that case there's a call to a routine - -$BSP_ROOT/startup/dumpanic.c - that prints which address caused the -interrupt and the contents of the registers, stack, etc.), 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(s) to access. The following figure illustrates this: - -@example -@group - +-------------------+ - ------------| | - ------------| |------------ - ------------| Address |------------ - ------------| Decoder |------------ - ------------| |------------ - ------------| | - +-------------------+ - CPU Bus Chip Select -@end group -@end example - - -The Chip Select registers must be programmed such that they match -the @code{linkcmds} settings. In the gen68340 BSP, ROM and RAM -addresses can be found in both the @code{linkcmds} and initialization -code, but this is not a great way to do this. It is better to -define addresses in the linker script. - -@section Integrated Processor Registers Initialization - -The CPUs used in many embedded systems are highly complex devices -with multiple peripherals on the CPU itself. For these devices, -there are always some specific integrated processor registers -that must be initialized. Refer to the processors' manuals for -details on these registers and be VERY careful programming them. - -@section Data Section Recopy - -The next initialization part can be found in -@code{$BSP340_ROOT/start340/init68340.c}. First the Interrupt -Vector Table is copied into RAM, then the data section recopy is initiated -(_CopyDataClearBSSAndStart in @code{$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 @ref{Linker Script Initialized Data} for more details about this copy), - -@item clear @code{.bss} section (all the non-initialized -data will take value 0). - -@end itemize - -@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 dependent, which means that -one has to provide one per application. It is usually defined -by defining macros and including the header file @code{<confdefs.h>}. -In simple applications such as the tests provided with RTEMS, it is -commonly found in the main module of the application. For more complex -applications, it may be in a file by itself. - -The header file @code{<confdefs.h>} defines a constant table named -@code{Configuration}. It is common practice for the BSP to copy -this table into a modifiable copy named @code{BSP_Configuration}. -This copy of the table is modified to define the base address of the -RTEMS Executive Workspace as well as to reflect any BSP and -device driver requirements not automatically handled by the application. - -For more information on the RTEMS Configuration Table, refer to the -@b{RTEMS Application C User's Guide}. - |