Changeset c4cbe17 in rtems


Ignore:
Timestamp:
Oct 21, 1998, 8:21:51 PM (21 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
d3b34d2
Parents:
b43744a6
Message:

Corrections from Jennifer and Jeff plus additions to the initialization
chapter.

Location:
doc/bsp_howto
Files:
5 edited

Legend:

Unmodified
Added
Removed
  • 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
    4848
    4949html: dirs $(FILES)
  • doc/bsp_howto/init.t

    rb43744a6 rc4cbe17  
    1212
    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:
    17 
    18 @itemize @bullet
    19 
    20 @item $BSP340_ROOT/start340/: assembly language code which contains early
    21 initialization routines,
    22 
    23 @item $BSP340_ROOT/startup/: C code with higher level routines (RTEMS
    24 initialization related).
    25 
    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.
     20
     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:
     25
     26@example
     27c/src/lib/libbsp/m68k/gen68340:
     28@end example
     29
     30@itemize @bullet
     31
     32@item @code{start340}: assembly language code which contains early
     33initialization routines
     34
     35@item @code{startup}: C code with higher level routines (RTEMS
     36initialization related)
     37
     38@end itemize
     39
     40@b{NOTE:} The directory @code{start340} is simply named @code{start} or
     41start followed by a BSP designation.
     42
     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.
    2747
    2848@section Board Initialization
    2949
    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.
    33 
    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.
     54
     55@subsection Start Code - Assembly Language Initialization
     56
     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:
     61
     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
     68
     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. 
     72
     73The initial assembly language start code completes its execution by
     74invoking the shared routine @code{boot_card()}.
     75
     76@subsection boot_card() - Boot the Card
     77
     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:
     81
     82@example
     83c/src/lib/libbsp/shared/main.c
     84@end example
     85
     86The @code{boot_card()} routine performs the following functions:
     87
     88@itemize @bullet
     89
     90@item initializes the shared fields of the CPU Configuration Table
     91(variable name @code{Cpu_table}) to a default state,
     92
     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,
     97
     98@item invokes the BSP specific routine @code{bsp_start()},
     99
     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,
     103
     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
     107
     108@item invokes the BSP specific routine @code{bsp_cleanup()} to perform
     109any necessary board specific shutdown actions.
     110
     111@end itemize
     112
     113It is important to note that the executive and much of the
     114support environment must be initialized before invoking @code{main()}.
     115
     116@subsection bsp_start() - BSP Specific Initialization
     117
     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
     123file:
     124
     125@example
     126c/src/lib/libbsp/CPU/BSP/startup/bspstart.c
     127@end example
     128
     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:
     133
     134@itemize @bullet
     135@item BSP Pretasking Hook
     136@item BSP Predriver Hook
     137@item BSP Postdriver Hook
     138@end itemize
     139
     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()}.
     145
     146Many BSPs place this area at the end of RAM although this is
     147certainly not a requirement.
     148
     149After completing execution, this routine returns to the
     150@code{boot_card()} routine.
     151
     152@subsection main() - C Main
     153
     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()}.
     159
     160The routine @code{__main()} initializes the compiler's basic run-time
     161support library and, most importantly, invokes the C++ global
     162constructors. 
     163
     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.
     167
     168The shared implementation of this routine is located in the following file:
     169
     170@example
     171c/src/lib/libbsp/shared/main.c
     172@end example
     173
     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.
     181
     182@subsection RTEMS Pretasking Callback
     183
     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.
     189
     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:
     193
     194@example
     195c/src/lib/libbsp/CPU/BSP/startup/bspstart.c
     196@end example
     197
     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.
     204
     205@subsection RTEMS Predriver Callback
     206
     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.
     213
     214@subsection Device Driver Initialization
     215
     216At this point in the initialization sequence, the initialization
     217routines for all of the device drivers specified in the Device
     218Driver Table are invoked.
     219
     220@subsection RTEMS Postdriver Callback
     221
     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.
     228
     229
     230@section The Interrupts Vector Table
     231
     232
    35233
    36234After the entry label starts a code section in which some room is
     
    45243not return.
    46244
    47 @subsection Chip Select Initialization
     245@section Chip Select Initialization
    48246
    49247When the microprocessor accesses a memory area, address decoding is
     
    58256do, better use some shared variables .
    59257
    60 @subsection Integrated processor registers initialization
     258@section Integrated processor registers initialization
    61259
    62260There are always some specific integrated processor registers
     
    64262them.
    65263
    66 @subsection Data section recopy
     264@section Data section recopy
    67265
    68266The next initialization part can be found in
     
    86284@section RTEMS-Specific Initialization
    87285
    88 @subsection The RTEMS configuration table
     286@section The RTEMS configuration table
    89287
    90288The RTEMS configuration table contains the maximum number of objects RTEMS
     
    102300guide, chapter 23 <insert a link here>.
    103301
    104 @subsection RTEMS initialization procedure
     302@section RTEMS initialization procedure
    105303
    106304The RTEMS initialization procedure is described in the 3rd chapter of the
     
    126324which is defined in the linkcmds (cf. 5.)
    127325
     326
    128327@end table
    129328
    130 @item bspstart.c
     329@item bspclean.c
    131330
    132331@table @b
    133 @item bsp_start
    134 
    135 Here the user and application specific configuration table has been
    136 "loaded" so that BSP_Configuration is up to date.
    137 
    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).
     332
     333@item bsp_cleanup
     334
     335Return control to the monitor.
    141336
    142337@end table
    143338
    144 @item bspclean.c
    145 
    146 @table @b
    147 
    148 @item bsp_cleanup
    149 
    150 Return control to the monitor.
    151 
    152339@end table
    153340
    154 @end table
    155 
    156 @subsection Drivers initialization
     341@section Drivers initialization
    157342
    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.
    1717
    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.
    4142
    4243This leads us to the structure of an embedded program.  In rough terms,
     
    7071
    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.
    7374
    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.
    8888
    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. 
     
    358358
    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?
    362362
     
    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.
    375375
     
    411411@end example
    412412
    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.
    417417
  • doc/bsp_howto/makefiles.t

    rb43744a6 rc4cbe17  
    6363There is a @code{Makefile.in} 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{Makefile.in}
    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{Makefile.in}.
    6767
    6868@b{NOTE:} The @code{Makefile.in} 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 makefile.in, 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{Makefile.in}, 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:
    7576
    7677@example
     
    126127time options necessary to execute on the target board.
    127128
    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:
    130131
    131132@itemize @bullet
     
    191192
    192193The basic steps for creating a @code{make/custom} file for a new BSP
    193 is as follows:
     194are as follows:
    194195
    195196@itemize @bullet
     
    202203@end itemize
    203204
    204 It is generally easier to copy a @code{make/custom} file which is for a
    205 BSP close to your own.
    206 
    207 
     205It is generally easier to copy a @code{make/custom} file from a
     206BSP similar to the one being developed.
     207
     208
  • doc/bsp_howto/target.t

    rb43744a6 rc4cbe17  
    2525
    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.
    4447
    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.
    5053
     
    5861engineer do the same thing.
    5962
     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.
     68
    6069@section Questions to Ask
    6170
    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:
    6373
    6474@itemize @bullet
     
    7282@end itemize
    7383
    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.
    7990
    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.
    8497
    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.
    89 
    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.
     101
     102Otherwise both CPU dependent code and the BSP will have to be written.
    91103
    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{http://www.oarcorp.com,,,http://www.oarcorp.com}.
     109@href{http://www.oarcorp.com,,,http://www.oarcorp.com}.
    97110@end ifset
    98111@ifclear use-html
    99 For more information, contact OAR Corporation
    100 at http://www.oarcorp.com.
     112http://www.oarcorp.com.
    101113@end ifclear
    102114
     
    108120
    109121@example
    110 c/src/exec/score/cpu/CPU
    111 @end example
    112 
    113 where CPU is replaced with the CPU family name.
     122c/src/exec/score/cpu/@i{CPU}
     123@end example
     124
     125where @i{CPU} is replaced with the CPU family name.
    114126
    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.
    118130
     
    126138
    127139@example
    128 c/src/lib/libcpu/CPU
     140c/src/lib/libcpu/@i{CPU}
    129141@end example
    130142
     
    132144
    133145@example
    134 c/src/lib/libcpu/CPU/CPU_MODEL
     146c/src/lib/libcpu/@i{CPU}/@i{CPU_MODEL}
    135147@end example
    136148
     
    147159@example
    148160c/src/lib/libbsp/shared
    149 c/src/lib/libbsp/CPU/shared
    150 c/src/lib/libbsp/CPU/BSP
    151 @end example
    152 
    153 Under each BSP specific directory, you will find a collection of
     161c/src/lib/libbsp/@i{CPU}/shared
     162c/src/lib/libbsp/@i{CPU}/@i{BSP}
     163@end example
     164
     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.