Subversion Repositories or1k

@c

@c  COPYRIGHT (c) 1988-2002.

@c  On-Line Applications Research Corporation (OAR).

@c  All rights reserved.

@c

@c  support.t,v 1.4 2002/01/17 21:47:44 joel Exp

@c

@chapter Miscellaneous Support Files

@section GCC Compiler Specifications File

The file @code{bsp_specs} defines the start files and libraries

that are always used with this BSP.  The format of this file

is admittedly cryptic and this document will make no attempt

to explain it completely.  Below is the @code{bsp_specs}

file from the PowerPC psim BSP:

@example

@group

%rename cpp old_cpp

%rename lib old_lib

%rename endfile old_endfile

%rename startfile old_startfile

%rename link old_link

*cpp:

%(old_cpp) %@{qrtems: -D__embedded__@} -Asystem(embedded)

*lib:

%@{!qrtems: %(old_lib)@} %@{qrtems: --start-group \

%@{!qrtems_debug: -lrtemsall@} %@{qrtems_debug: -lrtemsall_g@} \

-lc -lgcc --end-group  ecrtn%O%s \

%@{!qnolinkcmds: -T linkcmds%s@}@}

*startfile:

%@{!qrtems: %(old_startfile)@} %@{qrtems:  ecrti%O%s \

%@{!qrtems_debug: startsim.o%s@} \

%@{qrtems_debug: startsim_g.o%s@}@}

*link:

%@{!qrtems: %(old_link)@} %@{qrtems: -Qy -dp -Bstatic \

-T linkcmds%s -e _start -u __vectors@}

@end group

@end example

The first section of this file renames the built-in definition of

some specification variables so they can be augmented without

embedded their original definition.  The subsequent sections

specify what behavior is expected when the @code{-qrtems} or

@code{-qrtems_debug} option is specified.

The @code{*cpp} definition specifies that when @code{-qrtems}

is specified, predefine the preprocessor symbol @code{__embedded__}.

The @code{*lib} section insures that the RTEMS library, BSP specific

linker script, gcc support library, and the EABI specific @code{ecrtn}

file are used.

The @code{*startfile} section specifies that the BSP specific file

@code{startsim.o} will be used instead of @code{crt0.o}.  In addition,

the EABI specific file @code{ecrti.o} will be linked in with the

executable.

The @code{*link} section specifies the arguments that will be passed to

the linker.

The format of this file is specific to the GNU Compiler Suite.  The

argument used to override and extend the compiler built-in specifications

is relatively new to the toolset.  The @code{-specs} option is present

in all @code{egcs} distributions and @code{gcc} distributions starting

with version 2.8.0.

@section README Files

Most BSPs provide one or more @code{README} files.  Generally, there

is a @code{README} file at the top of the BSP source.  This file

describes the board and its hardware configuration, provides vendor

information, local configuration information, information on downloading

code to the board, debugging, etc..  The intent of this

file is to help someone begin to use the BSP faster.

A @code{README} file in a BSP subdirectory typically explains something

about the contents of that subdirectory in greater detail.  For example,

it may list the documentation available for a particular peripheral

controller and how to obtain that documentation.  It may also explain some

particularly cryptic part of the software in that directory or provide

rationale on the implementation.

@section times

This file contains the results of the RTEMS Timing Test Suite.  It is

in a standard format so that results from one BSP can be easily compared

with those of another target board.

If a BSP supports multiple variants, then there may be multiple @code{times}

files.  Usually these are named @code{times.VARIANTn}.

@section Tools Subdirectory

Some BSPs provide additional tools that aid in using the target board.

These tools run on the development host and are built as part of building

the BSP.  Most common is a script to automate running the RTEMS Test Suites

on the BSP.  Examples of this include:

@itemize @bullet

@item @code{powerpc/psim} includes scripts to ease use of the simulator

@item @code{m68k/mvme162} includes a utility to download across the

VMEbus into target memory if the host is a VMEbus board in the same

chasis.

@item @code{unix/posix} includes scripts to run the tests automatically

on this BSP.

@end itemize

@section bsp.h Include File

The file @code{include/bsp.h} contains prototypes and definitions

specific to this board.  Every BSP is required to provide a @code{bsp.h}.

The best approach to writing a @code{bsp.h} is copying an existing one

as a starting point.

Many @code{bsp.h} files provide prototypes of variables defined

in the linker script (@code{linkcmds}).

There are a number of fields in this file that are used only by the

RTEMS Test Suites.  The following is a list of these:

@itemize @bullet

@item @code{MAX_LONG_TEST_DURATION} - the longest length of time a

"long running" test should run.

@item @code{MAX_SHORT_TEST_DURATION} - the longest length of time a

"short running" test should run.

@item @code{MUST_WAIT_FOR_INTERRUPT} - modifies behavior of @code{tm27}.

@item @code{Install_tm27_vector} - installs the interrupt service

routine for the Interrupt Benchmark Test (@code{tm27}).

@item @code{Cause_tm27_intr} - generates the interrupt source

used in the Interrupt Benchmark Test (@code{tm27}).

@item @code{Clear_tm27_intr} - clears the interrupt source

used in the Interrupt Benchmark Test (@code{tm27}).

@item @code{Lower_tm27_intr} - lowers the interrupt mask so the

interrupt source used in the Interrupt Benchmark Test (@code{tm27})

can generate a nested interrupt.

@end itemize

@section Calling Overhead File

The file @code{include/coverhd.h} contains the overhead associated

with invoking each directive.  This overhead consists of the execution

time required to package the parameters as well as to execute the "jump to

subroutine" and "return from subroutine" sequence.  The intent of this

file is to help separate the calling overhead from the actual execution

time of a directive.  This file is only used by the tests in the

RTEMS Timing Test Suite.

The numbers in this file are obtained by running the "Timer Overhead"

@code{tmoverhd} test.  The numbers in this file may be 0 and no

overhead is subtracted from the directive execution times reported by

the Timing Suite.

@section sbrk() Implementation

If the BSP wants to dynamically extend the heap used by the

C Library memory allocation routines (i.e. @code{malloc} family),

then this routine must be functional.  The following is the

prototype for this routine:

@example

void * sbrk(size_t increment)

@end example

The @code{increment} amount is based upon the @code{sbrk_amount}

parameter passed to the @code{RTEMS_Malloc_Initialize} during system

initialization.

See @ref{Initialization Code RTEMS Pretasking Callback} for more

information.

There is a default implementation which returns an error to indicate

that the heap can not be extended.  This implementation can be

found in @code{c/src/lib/libbsp/shared/sbrk.c}.  Many of the BSPs

use this shared implementation.  In order to use this implementation,

the file @code{Makefile.in} in the BSP's @code{startup} directory

must be modified so that the @code{$VPATH} variable searches

both the @code{startup} directory and the shared directory.  The following

illustates the @code{VPATH} setting in the PowerPC psim BSP's

@code{startup/Makefile.in}:

@example

VPATH = @@srcdir@@:@@srcdir@@/../../../shared

@end example

This instructs make to look in all of the directories in the @code{VPATH}

for the source files.  The directories will be examined in the order

they are specified.

@section bsp_cleanup() - Cleanup the Hardware

The @code{bsp_cleanup()} is the last C code invoked.  Most of the BSPs

use the same shared version of @code{bsp_cleanup()} that does nothing.

This implementation is located in the following file:

@example

c/src/lib/libbsp/shared/bspclean.c

@end example

The @code{bsp_cleanup()} routine can be used to return to a ROM monitor,

insure that interrupt sources are disabled, etc..  This routine is the

last place to insure a clean shutdown of the hardware.

@section set_vector() - Install an Interrupt Vector

The @code{set_vector} routine is responsible for installing an interrupt

vector.  It invokes the support routines necessary to install an

interrupt handler as either a "raw" or an RTEMS interrupt handler.  Raw

handlers bypass the RTEMS interrupt structure and are responsible for

saving and restoring all their own registers.  Raw handlers are useful

for handling traps, debug vectors, etc..

The @code{set_vector} routine is a central place to perform

interrupt controller manipulation and encapsulate that information.

It is usually implemented as follows:

@example

@group

rtems_isr_entry set_vector(                     /* returns old vector */

  rtems_isr_entry     handler,                  /* isr routine        */

  rtems_vector_number vector,                   /* vector number      */

  int                 type                      /* RTEMS or RAW intr  */

)

@{

  if the type is RAW

    install the raw vector

  else

    use rtems_interrupt_catch to install the vector

  perform any interrupt controller necessary to unmask

    the interrupt source

  return the previous handler

@}

@end group

@end example

@b{NOTE:}  @code{set_vector} is provided by the majority of BSPs but

not all.  In particular, the i386 BSPs use a different scheme.