summaryrefslogtreecommitdiffstats
path: root/doc/bsp_howto/init.t
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/bsp_howto/init.t413
1 files changed, 0 insertions, 413 deletions
diff --git a/doc/bsp_howto/init.t b/doc/bsp_howto/init.t
deleted file mode 100644
index 1c0cd09113..0000000000
--- a/doc/bsp_howto/init.t
+++ /dev/null
@@ -1,413 +0,0 @@
-@c
-@c COPYRIGHT (c) 1988-2008.
-@c On-Line Applications Research Corporation (OAR).
-@c All rights reserved.
-
-@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 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
-
-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
-@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 reusable device drivers. These global
-variables should only defined by the BSP when using one of these device
-drivers.
-
-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.
-
-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 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 a fatal system state is
-reached. The optional @code{bsp_fatal_extension} initial extension can perform
-BSP specific system termination.
-
-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:
-
-@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 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. 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
-@end example
-
-The @code{boot_card()} routine performs the following functions:
-
-@itemize @bullet
-
-@item It disables processor interrupts.
-
-@item It sets the command line argument variables
-for later use by the application.
-
-@item It invokes the BSP specific routine @code{bsp_work_area_initialize()}
-which is supposed to initialize the RTEMS Workspace and the C Program Heap.
-Usually the default implementation in
-@code{c/src/lib/libbsp/shared/bspgetworkarea.c} should be sufficient. Custom
-implementations can use @code{bsp_work_area_initialize_default()} or
-@code{bsp_work_area_initialize_with_table()} available as inline functions from
-@code{#include <bsp/bootcard.h>}.
-
-@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, bus and interrupt controller initialization occurs here. Since the
-RTEMS Workspace and the C Program Heap was already initialized by
-@code{bsp_work_area_initialize()}, this routine may use @code{malloc()}, etc.
-
-@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 It invokes the BSP specific routine @code{bsp_libc_init()} to initialize
-the C Library. Usually the default implementation in
-@code{c/src/lib/libbsp/shared/bsplibc.c} should be sufficient.
-
-@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.
-
-@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 initiates multitasking and performs a context switch to the
-first user application task and may enable interrupts as a side-effect of
-that context switch. The context switch saves the executing context. The
-application runs now. The directive rtems_shutdown_executive() will return
-to the saved context. The exit() function will use this directive.
-
-After a return to the saved context a fatal system state is reached. The
-fatal source is RTEMS_FATAL_SOURCE_EXIT with a fatal code set to the value
-passed to rtems_shutdown_executive().
-
-The enabling of interrupts during the first context switch is often the source
-for fatal errors during BSP development because the BSP did not clear and/or
-disable all interrupt sources and a spurious interrupt will occur.
-
-When in the context of the first task but before its body has been
-entered, any C++ Global Constructors will be invoked.
-
-@end itemize
-
-That's it. We just went through the entire sequence.
-
-@subsection bsp_work_area_initialize() - BSP Specific Work Area Initialization
-
-This is the first BSP specific C routine to execute during system
-initialization. It must initialize the support for allocating memory from the
-C Program Heap and RTEMS Workspace commonly referred to as the work areas.
-Many BSPs place the work areas at the end of RAM although this is certainly not
-a requirement. Usually the default implementation in
-@file{c/src/lib/libbsp/shared/bspgetworkarea.c} should be sufficient. Custom
-implementations can use @code{bsp_work_area_initialize_default()} or
-@code{bsp_work_area_initialize_with_table()} available as inline functions from
-@code{#include <bsp/bootcard.h>}.
-
-@subsection bsp_start() - BSP Specific Initialization
-
-This is the second BSP specific C routine to execute during system
-initialization. It is called right after @code{bsp_work_area_initialize()}.
-The @code{bsp_start()} 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 interrupt controllers
-are usually initialized here. The source code for this routine is usually
-found in the file @file{c/src/lib/libbsp/$@{CPU@}/$@{BSP@}/startup/bspstart.c}.
-It is not allowed to create any operating system objects, e.g. RTEMS
-semaphores.
-
-After completing execution, this routine returns to the @code{boot_card()}
-routine. In case of errors, the initialization should be terminated via
-@code{bsp_fatal()}.
-
-@subsection bsp_predriver_hook() - BSP Specific Predriver Hook
-
-The @code{bsp_predriver_hook()} method is the BSP specific routine that is
-invoked immediately before the the device drivers are initialized. RTEMS
-initialization is complete but interrupts and tasking are disabled.
-
-The BSP may use the shared version of this routine which is empty.
-Most BSPs do not provide a specific implementation of 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{bsp_postdriver_hook()} BSP specific routine is invoked
-immediately after the the device drivers and MPCI are initialized.
-Interrupts and tasking are disabled.
-
-Most 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:
-
-@example
-c/src/lib/libbsp/shared/bsppost.c
-@end example
-
-@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 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{<rtems/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{<rtems/confdefs.h>} defines a constant table
-named @code{Configuration}. With RTEMS 4.8 and older, it was accepted
-practice for the BSP to copy this table into a modifiable copy named
-@code{BSP_Configuration}. This copy of the table was 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. In 4.9 and newer, we have eliminated the BSP copies of the
-configuration tables and are making efforts to make the configuration
-information generated by @code{<rtems/confdefs.h>} constant and read only.
-
-For more information on the RTEMS Configuration Table, refer to the
-@b{RTEMS Application C User's Guide}.
-