Changeset c4cbe17 in rtems

Oct 21, 1998, 8:21:51 PM (21 years ago)
Joel Sherrill <joel.sherrill@…>
4.10, 4.11, 4.8, 4.9, master

Corrections from Jennifer and Jeff plus additions to the initialization

5 edited


  • doc/bsp_howto/Makefile

    rb43744a6 rc4cbe17  
    4444# run texi2dvi twice to generate the xref's properly.
    4545$(PROJECT).dvi: $(FILES)
    46         $(TEXI2DVI) -v $(PROJECT).texi
    47         texi2dvi -v $(PROJECT).texi
     46        $(TEXI2DVI) $(PROJECT).texi
     47        $(TEXI2DVI) $(PROJECT).texi
    4949html: dirs $(FILES)
  • doc/bsp_howto/init.t

    rb43744a6 rc4cbe17  
    1313The initialization code is the first piece of code executed when there's a
    14 reset/reboot. It aims at initializing the main functions of the board. As
    15 an introduction I advise you to give a look to the gen68340 BSP
    16 initialization code, which is split onto t wo directories:
    18 @itemize @bullet
    20 @item $BSP340_ROOT/start340/: assembly language code which contains early
    21 initialization routines,
    23 @item $BSP340_ROOT/startup/: C code with higher level routines (RTEMS
    24 initialization related).
    26 @end itemize
     14reset/reboot. Its purpose is to initialize the board for the application.
     15This chapter contains a narrative description of the initialization
     16process followed by a description of each of the files and routines
     17commonly found in the BSP related to initialization.  The remainder of
     18this chapter covers special issues which require attention such
     19as interrupt vector table and chip select initialization.
     21Most of the examples in this chapter will be based on the gen68340 BSP
     22initialization code.  Like most BSPs, the initialization for this
     23BSP is divided into two subdirectories under the BSP source directory.
     24The gen68340 BSP source code in the following directory:
     28@end example
     30@itemize @bullet
     32@item @code{start340}: assembly language code which contains early
     33initialization routines
     35@item @code{startup}: C code with higher level routines (RTEMS
     36initialization related)
     38@end itemize
     40@b{NOTE:} The directory @code{start340} is simply named @code{start} or
     41start followed by a BSP designation.
     43In the @code{start340} directory are two source files.  The file
     44@code{startfor340only.s} is the simpler of these files as it only has
     45initialization code for a MC68340 board.  The file @code{start340.s}
     46contains initialization for a 68349 based board as well.
    2848@section Board Initialization
    30 You'll find two files under the $BSP340_ROOT/start340/ directory, open
    31 rtemsfor340only.s which holds initialization code for a MC68340 board only
    32 and is simpler.
    34 @subsection The Interrupts Vector Table
     50This section describes the steps an application goes through from the
     51time the first BSP code is executed until the first application task
     52executes.  The routines invoked during this will be discussed and
     53their location in the RTEMS source tree pointed out.
     55@subsection Start Code - Assembly Language Initialization
     57The assembly language code in the directory @code{start} is
     58the first part of the application to execute.  It is
     59responsible for initializing the processor and board enough to execute
     60the rest of the BSP.  This includes:
     62@itemize @bullet
     63@item initializing the stack
     64@item zeroing out the uninitialized data section @code{.bss}
     65@item disabling external interrupts
     66@item copy the initialized data from ROM to RAM
     67@end itemize
     69The general rule of thumb is that the
     70start code in assembly should do the minimum necessary to allow C code
     71to execute to complete the initialization sequence. 
     73The initial assembly language start code completes its execution by
     74invoking the shared routine @code{boot_card()}.
     76@subsection boot_card() - Boot the Card
     78The @code{boot_card()} is the first C code invoked.  Most of the BSPs
     79use the sams shared version of @code{boot_card()} which is located in
     80the following file:
     84@end example
     86The @code{boot_card()} routine performs the following functions:
     88@itemize @bullet
     90@item initializes the shared fields of the CPU Configuration Table
     91(variable name @code{Cpu_table}) to a default state,
     93@item copies the application's RTEMS Configuration Table
     94(variable name @code{Configuration}) to the BSP's Configuration
     95Table (variable name @code{BSP_Configuration}) so it can be modified
     96as necessary without copying the original table,
     98@item invokes the BSP specific routine @code{bsp_start()},
     100@item invokes the RTEMS directive @code{rtems_initialize_executive_early()}
     101to initialize the executive, C Library, and all device drivers but
     102return without initiating multitasking or enabling interrupts,
     104@item invokes the shared @code{main()} in the same file as
     105@code{boot_card()} which does not return until the
     106@code{rtems_shutdown_executive} directive is called, and
     108@item invokes the BSP specific routine @code{bsp_cleanup()} to perform
     109any necessary board specific shutdown actions.
     111@end itemize
     113It is important to note that the executive and much of the
     114support environment must be initialized before invoking @code{main()}.
     116@subsection bsp_start() - BSP Specific Initialization
     118This is the first BSP specific C routine to execute during system
     119initialization.  This routine often performs required fundamental
     120hardware initialization such as setting bus controller registers
     121that do not have a direct impact on whether or not C code can execute.
     122The source code for this routine is usually found in the following
     127@end example
     129This routine is also responsible for overriding the default settings
     130in the CPU Configuration Table and setting port specific entries
     131in this table.  This routine will typically install routines
     132for one or more of the following initialization hooks:
     134@itemize @bullet
     135@item BSP Pretasking Hook
     136@item BSP Predriver Hook
     137@item BSP Postdriver Hook
     138@end itemize
     140One of the most important functions performed by this routine
     141is determining where the RTEMS Executive Work Space is to be
     142located in memory.  All RTEMS objects and task stacks will be
     143allocated from this Workspace.  The RTEMS Workspace is distinct
     144from the application heap used for @code{malloc()}.
     146Many BSPs place this area at the end of RAM although this is
     147certainly not a requirement.
     149After completing execution, this routine returns to the
     150@code{boot_card()} routine.
     152@subsection main() - C Main
     154This routine is the C main entry point.  This is a special routine
     155and the GNU Compiler Suite treats it as such.  The GNU C Compiler
     156recognizes @code{main()} and automatically inserts a call to the
     157compiler run-time support routine @code{__main()} as the first
     158code executed in @code{main()}.
     160The routine @code{__main()} initializes the compiler's basic run-time
     161support library and, most importantly, invokes the C++ global
     164The precise placement of when @code{main()} is invoked in the
     165RTEMS initialization sequence insures that C Library and non-blocking
     166calls can be made in global C++ constructors.
     168The shared implementation of this routine is located in the following file:
     172@end example
     174In addition to the implicit invocation of @code{__main}, this
     175routine performs some explitit initialization.  This routine
     176sets the variable @code{rtems_progname} and initiates
     177multitasking via a call to the RTEMS directive
     178@code{rtems_initialize_executive_late}.  It is important to note
     179that the executive does not return to this routine until the
     180RTEMS directive @code{rtems_shutdown_executive} is invoked.
     182@subsection RTEMS Pretasking Callback
     184The @code{pretasking_hook} entry in the RTEMS CPU Configuration
     185Table may be the address of a user provided routine that is
     186invoked once RTEMS initialization is complete but before interrupts
     187and tasking are enabled.  No tasks -- not even the IDLE task -- have
     188been created when this hook is invoked.  The pretasking hook is optional.
     190Although optional, most of the RTEMS BSPs provide a pretasking hook
     191callback.  This routine is usually called @code{bsp_pretasking_hook}
     192and is found in the file:
     196@end example
     198The @code{bsp_pretasking_hook()} routine is the appropriate place to
     199initialize any support components which depend on the RTEMS APIs.
     200Most BSPs initialize the RTEMS C Library support in their
     201implementation of @code{bsp_pretasking_hook()}.  This initialization
     202includes the application heap as well as the reentrancy support
     203for the C Library.
     205@subsection RTEMS Predriver Callback
     207XXX is the address of the user provided
     208routine which is invoked with tasking enabled immediately before
     209the MPCI and device drivers are initialized. RTEMS
     210initialization is complete, interrupts and tasking are enabled,
     211but no device drivers are initialized.  This field may be NULL to
     212indicate that the hook is not utilized.
     214@subsection Device Driver Initialization
     216At this point in the initialization sequence, the initialization
     217routines for all of the device drivers specified in the Device
     218Driver Table are invoked.
     220@subsection RTEMS Postdriver Callback
     222XXX is the address of the user provided
     223routine which is invoked with tasking enabled immediately after
     224the MPCI and device drivers are initialized. RTEMS
     225initialization is complete, interrupts and tasking are enabled,
     226and the device drivers are initialized.  This field may be NULL
     227to indicate that the hook is not utilized.
     230@section The Interrupts Vector Table
    36234After the entry label starts a code section in which some room is
    45243not return.
    47 @subsection Chip Select Initialization
     245@section Chip Select Initialization
    49247When the microprocessor accesses a memory area, address decoding is
    58256do, better use some shared variables .
    60 @subsection Integrated processor registers initialization
     258@section Integrated processor registers initialization
    62260There are always some specific integrated processor registers
    66 @subsection Data section recopy
     264@section Data section recopy
    68266The next initialization part can be found in
    86284@section RTEMS-Specific Initialization
    88 @subsection The RTEMS configuration table
     286@section The RTEMS configuration table
    90288The RTEMS configuration table contains the maximum number of objects RTEMS
    102300guide, chapter 23 <insert a link here>.
    104 @subsection RTEMS initialization procedure
     302@section RTEMS initialization procedure
    106304The RTEMS initialization procedure is described in the 3rd chapter of the
    126324which is defined in the linkcmds (cf. 5.)
    128327@end table
    130 @item bspstart.c
     329@item bspclean.c
    132331@table @b
    133 @item bsp_start
    135 Here the user and application specific configuration table has been
    136 "loaded" so that BSP_Configuration is up to date.
    138 You can make last modifications here, for instance reserve more room for
    139 the RTEMS Work Space, or adjust the heap size (you can for example use the
    140 memory left for the lone heap).
     333@item bsp_cleanup
     335Return control to the monitor.
    142337@end table
    144 @item bspclean.c
    146 @table @b
    148 @item bsp_cleanup
    150 Return control to the monitor.
    152339@end table
    154 @end table
    156 @subsection Drivers initialization
     341@section Drivers initialization
    158343The Driver Address Table is part of the RTEMS configuration table. It
  • doc/bsp_howto/linkcmds.t

    rb43744a6 rc4cbe17  
    1414time.  This file describes the memory configuration of the board as needed
    1515to link the program.  Specifically it specifies where the code and data
    16 for your application will reside in memory.
     16for the application will reside in memory.
    1818@section Program Sections
    3838are a bit different for embedded targets: the target will execute the
    3939program each time it is rebooted or switched on.   The application
    40 program is stored in ROM. On the other hand, data processing occurs in RAM.
     40program is stored in non-volatile memory such as ROM, PROM, EEPROM,
     41or Flash. On the other hand, data processing occurs in RAM.
    4243This leads us to the structure of an embedded program.  In rough terms,
    7172That brings us up to the notion of the image of an executable: it consists
    72 in the set of the program sections.
     73of the set of the sections that together constitute the application.
    7475@section Image of an Executable
    8485The connection between a section and where that section is loaded into
    8586memory is made at link time.  One has to let the linker know where
    86 the different sections location are to be placed once they are in
    87 memory.
     87the different sections are to be placed once they are in memory.
    8989The following example shows a simple layout of program sections.  With
    132132 *  allocated using malloc() come from this area.  Having a tight heap size
    133133 *  is somewhat difficult and multiple attempts to squeeze it may be needed
    134  *  if you want to save the memory usage.  If you allocate all objects from
     134 *  reducing memory usage is important.  If all objects are allocated from
    135135 *  the heap at system initialization time, this eases the sizing of the
    136136 *  application heap. 
    359359Now there's a problem with the initialized data: the @code{.data} section
    360 has to be in RAM as these data may be modified during the program execution.
     360has to be in RAM as this data may be modified during the program execution.
    361361But how will the values be initialized at boot time?
    370370area of memory and copy it into the proper location each time the
    371371program is started.  It is common practice to place a copy of the initialized
    372 @code{.data} section the end of the code (@code{.text} section
    373 (i.e. in ROM) when building a PROM image. The GNU tool @code{objcopy}
     372@code{.data} section at the end of the code (@code{.text}) section
     373in ROM when building a PROM image. The GNU tool @code{objcopy}
    374374can be used for this purpose.
    411411@end example
    413 NOTE: The address at which the copy of the @code{.data} section is
    414 specified by extracting the address of the end of the @code{.text}
    415 section (i.e. in ROM) with an @code{awk} script.  The details of how
     413NOTE: The address of the "copy of @code{.data} section" is
     414created by extracting the last address in the @code{.text}
     415section with an @code{awk} script.  The details of how
    416416this is done are not relevant.
  • doc/bsp_howto/makefiles.t

    rb43744a6 rc4cbe17  
    6363There is a @code{} in most of the directories in a BSP. This
    6464class of Makefile lists the files to be built as part of the driver.
    65 Do not forget to add the reference to a new file in the @code{}
    66 it is created!
     65When adding new files to an existing directory, Do not forget to add
     66the new files to the list of files to be built in the @code{}.
    6868@b{NOTE:} The @code{} files are ONLY processed during the configure
    69 process of a RTEMS build. It means that, when you're working on the design
    70 of your BSP, and that you're adding a file to a folder and to the
    71 corresponding, it will not be taken into account! You have to
    72 run configure again or modify the @code{Makefile} (the result of the
    73 configure process) by hand.  This file will be in a directory such as
    74 the following:
     69process of a RTEMS build. Therefore, when developing
     70a BSP and adding a new file to a @code{}, the
     71already generated @code{Makefile} will not include the new references.
     72This results in the new file not being be taken into account!
     73The @code{configure} script must be run again or the @code{Makefile}
     74(the result of the configure process) modified by hand.  This file will
     75be in a directory such as the following:
    126127time options necessary to execute on the target board.
    128 There are template Makefiles provided for each of the classes of RTEMS
    129 Makefiles.  This include Makefiles to:
     129There is a template Makefile provided for each of class of RTEMS
     130Makefiles.  The purpose of each class of RTEMS Makefile is to:
    131132@itemize @bullet
    192193The basic steps for creating a @code{make/custom} file for a new BSP
    193 is as follows:
     194are as follows:
    195196@itemize @bullet
    202203@end itemize
    204 It is generally easier to copy a @code{make/custom} file which is for a
    205 BSP close to your own.
     205It is generally easier to copy a @code{make/custom} file from a
     206BSP similar to the one being developed.
  • doc/bsp_howto/target.t

    rb43744a6 rc4cbe17  
    2626This class of code includes the foundation
    27 routines for the executive proper such as as the context switch and
     27routines for the executive proper such as the context switch and
    2828the interrupt subroutine implementations.  Sources for the supported
    2929processor families can be found in @code{c/src/exec/score/cpu}.
    4141This class of code provides the most specific glue between RTEMS and
    4242a particular board.  This code is represented by the Board Support Packages
    43 and associated Device Drivers.
     43and associated Device Drivers.  Sources for the BSPs included in the
     44RTEMS distribution are located in the directory @code{c/src/lib/libbsp}.
     45The BSP source directory is further subdivided based on the CPU family
     46and BSP.
    4548Some BSPs may support multiple board models within a single board family.
    46 This is necessary when the board's vendor supports build variants on a
    47 single base base.  For example, the Motorola MVME162 board family has a
    48 a fairly large number of variations based upon the particular CPU model
     49This is necessary when the board supports multiple variants on a
     50single base board.  For example, the Motorola MVME162 board family has a
     51fairly large number of variations based upon the particular CPU model
    4952and the peripherals actually placed on the board.
    5861engineer do the same thing.
     63The source code for the reusable peripheral driver library may be found
     64in the directory @code{c/src/lib/libchip}.  The source code is further
     65divided based upon the class of hardware.  Example classes include serial
     66communications controllers, real-time clocks, non-volatile memory, and
     67network controllers.
    6069@section Questions to Ask
    62 Porting RTEMS on a new board should raise some questions:
     71When evaluating what is required to support RTEMS applications on
     72a particular target board, the following questions should be asked:
    6474@itemize @bullet
    7282@end itemize
    74 If there is already a BSP for your board, then you may already be ready
    75 to start developing application software.  You should verify that the
    76 existing BSP provides device drivers for all the peripherals on the board
    77 that your application will be using.  For example, the board may have
    78 an Ethernet controller which is not supported by the existing BSP.
     84If there is already a BSP for the board, then things may already be ready
     85to start developing application software.  All that remains is to verify
     86that the existing BSP provides device drivers for all the peripherals
     87on the board that the application will be using.  For example, the application
     88in question may require that the board's Ethernet controller be used and
     89the existing BSP may not support this.
    8091If the BSP does not exist and the board's CPU model is supported, then
    81 you should look at existing BSPs for a close match.  This will help
    82 reduce the effort required.  It is often possible to reuse device drivers
    83 from BSPs from different CPU families.
     92examine the reusable chip library and existing BSPs for a close match. 
     93This will help reduce the development effort required.  It is often
     94possible to copy existing components in the reusable chip library or
     95device drivers from BSPs from different CPU families as the starting
     96point for a new device driver.
    8598If the board's CPU family is supported but the particular CPU model on
    8699that board is not, then the RTEMS port to that CPU family will have to
    87 be augmented.  After this is done, then you can proceed to developing
    88 the new BSP.
    90 Otherwise you'll have to write both CPU dependent code and the BSP.
     100be augmented.  After this is done, development of the new BSP can proceed.
     102Otherwise both CPU dependent code and the BSP will have to be written.
    92104Regardless of the amount of development required, OAR Corporation
    93 offers custom development services to help you use RTEMS.
     105offers custom development services to assist RTEMS users.
     106For more information on custom development, training courses, and
     107support, contact OAR Corporation at
    94108@ifset use-html
    95 For more information, contact OAR Corporation
    96 at @href{,,,}.
    97110@end ifset
    98111@ifclear use-html
    99 For more information, contact OAR Corporation
    100 at
    101113@end ifclear
    110 c/src/exec/score/cpu/CPU
    111 @end example
    113 where CPU is replaced with the CPU family name.
     123@end example
     125where @i{CPU} is replaced with the CPU family name.
    115127Within each CPU dependent directory inside the executive proper is a
    116 file named @code{CPU.h} which contains information about each of the
     128file named @code{@i{CPU}.h} which contains information about each of the
    117129supported CPU models within that family.
    128 c/src/lib/libcpu/CPU
    129141@end example
    134 c/src/lib/libcpu/CPU/CPU_MODEL
    135147@end example
    149 c/src/lib/libbsp/CPU/shared
    150 c/src/lib/libbsp/CPU/BSP
    151 @end example
    153 Under each BSP specific directory, you will find a collection of
     163@end example
     165Under each BSP specific directory, there is a collection of
    154166subdirectories.  For commonly provided functionality, the BSPs
    155167follow a convention on subdirectory naming.  The following list
Note: See TracChangeset for help on using the changeset viewer.