Changeset c7ff10af in rtems

Aug 21, 2008, 9:31:02 PM (11 years ago)
Joel Sherrill <joel.sherrill@…>
4.10, 4.11, 4.9, master

2008-08-21 Joel Sherrill <joel.sherrill@…>

  • bsp_howto/, bsp_howto/linkcmds.t, bsp_howto/makefiles.t, bsp_howto/target.t: Update some of this manual.
  • bsp_howto/Developer-User-Timeline.eps, bsp_howto/Developer-User-Timeline.png: New files.
2 added
5 edited


  • doc/ChangeLog

    r9353a0d4 rc7ff10af  
     12008-08-21      Joel Sherrill <>
     3        * bsp_howto/, bsp_howto/linkcmds.t, bsp_howto/makefiles.t,
     4        bsp_howto/target.t: Update some of this manual.
     5        * bsp_howto/Developer-User-Timeline.eps,
     6        bsp_howto/Developer-User-Timeline.png: New files.
    182008-08-21      Joel Sherrill <>
  • doc/bsp_howto/

    r9353a0d4 rc7ff10af  
    2020COMMON_FILES += $(top_srcdir)/common/cpright.texi
     22PNG_FILES = Developer-User-Timeline.png
     24if USE_HTML
     25html_project_DATA += $(PNG_FILES)
    2228FILES =
    125131EXTRA_DIST = adaintr.t analog.t ata.t clock.t console.t discrete.t \
    126132    ide-ctrl.t init.t intro.t linkcmds.t makefiles.t nvmem.t rtc.t shmsupp.t \
    127     support.t target.t timer.t
     133    support.t target.t timer.t $(PNG_FILES) $(EPS_IMAGES)
  • doc/bsp_howto/linkcmds.t

    r9353a0d4 rc7ff10af  
    1515to link the program.  Specifically it specifies where the code and data
    1616for the application will reside in memory.
     18The format of the linker script is defined by the GNU Loader @code{ld}
     19which is included as a component of the GNU Binary Utilities.  If you
     20are using GNU/Linux, then you probably have the documentation installed
     21already and are using these same tools configured for @b{native} use.
     22Please visit the Binutils project @uref{}
     23if you need more information.
    1825@section Program Sections
  • doc/bsp_howto/makefiles.t

    r9353a0d4 rc7ff10af  
    1313This chapter will not provide detailed information about this process.
    1414Nonetheless, it is important to remember that the general process consists
    15 of three parts:
     15of four phases as shown here:
     17@ifset use-ascii
    1720@itemize @bullet
     21@item bootstrap
    1822@item configure
    1923@item build
    2024@item install
    2125@end itemize
     26@end group
     27@end example
     28@end ifset
     31@ifset use-tex
     32@image{Developer-User-Timeline,6in,,Developer User Timeline,.png}
     33@c      @image{FILENAME[, WIDTH[, HEIGHT[, ALTTEXT[, EXTENSION]]]]}
     35@end ifset
     37@ifset use-html
     40<IMG SRC="Developer-User-Timeline.png" WIDTH=800 ALT="Developer User Timeline">
     42@end html
     43@end ifset
     46During the bootstrap phase, you are using the @code{} and
     47@code{} files as input to GNU autoconf and automake to
     48generate a variety of files.  This is done by running the @code{bootstrap}
     49script found at the top of the RTEMS source tree. 
    2351During the configure phase, a number of files are generated.  These
    4270directory of the RTEMS source tree is executed to produce the
    4371automatically generated files.  That script must be run from
    44 a directory with a @code{} file in it.
    46 There is a file named @code{} in each directory of a BSP.
    47 This file is used by @b{automake} to produce the file
    48 named @code{} which is also found in each directory of a BSP.
    49 The configure process specializes the @code{} files at
    50 the time that RTEMS
     72a directory with a @code{} file in it.  The @code{bootstrap}
     73command is usually invoked in one of the following manners:
     75@itemize @bullet
     76@item @code{bootstrap} to regenerate all files that are generated by
     77autoconf and automake.
     78@item @code{bootstrap -c} to remove all files generated by autoconf and
     80@item @code{bootstrap -p} to regenerate @code{} files.
     81@end itemize
     83There is a file named @code{} in each directory of
     84a BSP.  This file is used by @b{automake} to produce the file named
     85@code{} which is also found in each directory of a BSP.
     86When modifying a @code{}, you can probably find examples of
     87anything you need to do in one of the BSPs.
     90The configure process specializes the @code{} files at the time that RTEMS
    5191is configured for a specific development host and target.  Makefiles
    5292are automatically generated from the @code{} files.  It is
    61101The BSP developer is responsible for generating @code{}
    62102files which properly build all the files associated with their BSP.
    63 There are generally three types of Makefiles in a BSP source tree:
    66 @itemize @bullet
    67 @item Directory Makefiles
    68 @item Source Directory Makefiles
    69 @item Wrapup Makefile
    70 @end itemize
    72 @subsection Directory Makefiles
    74 The Directory class of Makefiles directs the build process through
    75 a set of subdirectories in a particular order.  This order is usually
    76 chosen to insure that build dependencies are properly processed.
    77 Most BSPs only have one Directory class Makefile.  The @code{}
    78 in the BSP root directory (@code{c/src/lib/libbsp/CPU/BSP}) specifies
    79 following Makefile fragment shows how a BSP would specify the
    80 directories to be built and their order:
    82 @example
    83 SUB_DIRS=include start340 startup clock console timer \
    84     network wrapup
    85 @end example
    87 @subsection Source Directory Makefiles
    89 There is a @code{} in most of the directories in a BSP. This
    90 class of Makefile lists the files to be built as part of the driver.
    91 When adding new files to an existing directory, Do not forget to add
    92 the new files to the list of files to be built in the @code{}
    93 and run @code{bootstrap}.
     103Most BSPs will only have a single @code{} which details
     104the set of source files to build to compose the BSP support library
     105along with the set of include files that are to be installed. 
     107This single @code{} at the top of the BSP tree specifies
     108the set of header files to install.  This fragment from the SPARC/ERC32
     109BSP results in four header files being installed.
     112include_HEADERS = include/bsp.h
     113include_HEADERS += include/tm27.h
     114include_HEADERS += include/erc32.h
     115include_HEADERS += include/coverhd.h
     116@end example
     118When adding new include files, you will be adding to the set of
     119@code{include_HEADERS}.  When you finish editing the @code{}
     120file, do not forget to run @code{bootstrap -p} to regenerate the
     123The @code{} also specifies which source files to build.
     124By convention, logical components within the BSP each assign their
     125source files to a unique variable.  These variables which define
     126the source files are collected into a single variable which instructs
     127the GNU autotools that we are building @code{libbsp.a}.  This fragment
     128from the SPARC/ERC32 BSP shows how the startup related, miscellaneous
     129support code, and the console device driver source is managed
     130in the @code{}.
     133startup_SOURCES = ../../sparc/shared/bspclean.c ../../shared/bsplibc.c \
     134    ../../shared/bsppredriverhook.c \
     135    ../../shared/bsppost.c ../../sparc/shared/bspstart.c \
     136    ../../shared/bootcard.c ../../shared/sbrk.c startup/setvec.c \
     137    startup/spurious.c startup/erc32mec.c startup/boardinit.S
     138clock_SOURCES = clock/ckinit.c
     140noinst_LIBRARIES = libbsp.a
     141libbsp_a_SOURCES = $(startup_SOURCES) $(console_SOURCES) ...
     142@end example
     144When adding new files to an existing directory, do not forget to add
     145the new files to the list of files to be built in the corresponding
     146@code{XXX_SOURCES} variable in the @code{} and run
     149Some BSPs use code that is built in @code{libcpu}.  If you BSP does
     150this, then you will need to make sure the objects are pulled into your
     151BSP library.  The following from the SPARC/ERC32 BSP pulls in the cache,
     152register window management and system call support code from the directory
     153corresponding to its @code{RTEMS_CPU} model.
     156libbsp_a_LIBADD  = ../../../libcpu/@@RTEMS_CPU@@/cache.rel \
     157    ../../../libcpu/@@RTEMS_CPU@@/reg_win.rel \
     158    ../../../libcpu/@@RTEMS_CPU@@/syscall.rel
     159@end example
    95161@b{NOTE:} The @code{} files are ONLY processed by
    96 @code{bootstrap} and the resulting @code{} files are
    97 only processed during the configure
    98 process of a RTEMS build. Therefore, when developing
    99 a BSP and adding a new file to a @code{}, the
    100 already generated @code{Makefile} will not automatically
     162@code{bootstrap} and the resulting @code{} files are only
     163processed during the configure process of a RTEMS build. Therefore,
     164when developing a BSP and adding a new file to a @code{},
     165the already generated @code{Makefile} will not automatically
    101166include the new references unless you configured RTEMS with the
    102 @code{--enable-maintainer-mode} option.
    103 Otherwise, the new file not being be taken into account!
    105 If adding a new directory, be sure to add it to the list of
    106 automatically generated files in the BSP's @code{}
    107 script.
    109 @subsection Wrapup Makefile
    111 This class of Makefiles produces a library.  The BSP wrapup Makefile
    112 is responsible for producing the library @code{libbsp.a} which is later
    113 merged into the @code{librtemsall.a} library.  This Makefile specifies
    114 which BSP components are to be placed into the library as well as which
    115 components from the CPU dependent support code library.  For example,
    116 this component may choose to use a default exception handler from the
    117 CPU dependent support code or provide its own.
    119 This Makefile makes use of the @code{foreach} construct in @b{GNU make}
    120 to pick up the required components:
    122 @example
    123 BSP_PIECES=startup clock console timer
    124 CPU_PIECES=
    127 # bummer; have to use $foreach since % pattern subst
    128 #              rules only replace 1x
    129 OBJS=$(foreach piece, $(BSP_PIECES), ../$(piece)/$(ARCH)/$(piece).o) \
    130  $(foreach piece, $(CPU_PIECES), \
    131    ../../../../libcpu/$(RTEMS_CPU)/$(piece)/$(ARCH)/$(piece).o) \
    132  $(wildcard \
    133    ../../../../libcpu/$(RTEMS_CPU)/$(RTEMS_CPU_MODEL)/fpsp/$(ARCH)/fpsp.rel) \
    134  $(foreach piece, \
    135    $(GENERIC_PIECES), ../../../$(piece)/$(ARCH)/$(piece).o)
    136 @end example
    138 The variable @code{OBJS} is the list of "pieces" expanded to include
    139 path information to the appropriate object files.  The @code{wildcard}
    140 function is used on pieces of @code{libbsp.a} which are optional and
    141 may not be present based upon the configuration options.
    143 @section Makefiles Used Both During The BSP Design and its Use
     167@code{--enable-maintainer-mode} option.  Otherwise, the new file not
     168being be taken into account!
     170@section Creating a New BSP Make Customization File
    145172When building a BSP or an application using that BSP, it is necessary
    153180The configuration file is taken into account when building one's
    154 application using the RTEMS template Makefiles (@code{make/templates}).
    155 It is strongly advised to use these template Makefiles since they
    156 encapsulate a number of build rules along with the compile and link
    157 time options necessary to execute on the target board.
    159 There is a template Makefile provided for each of class of RTEMS
    160 Makefiles.  The purpose of each class of RTEMS Makefile is to:
    162 @itemize @bullet
    163 @item call recursively the makefiles in the directories beneath
    164 the current one,
    166 @item build a library, or
    168 @item build an executable.
    170 @end itemize
    172 The following is a shortened and heavily commented version of the
    173 make customization file for the gen68340 BSP.  The original source
    174 for this file can be found in the @code{make/custom} directory.
    176 @example
     181application using the RTEMS template Makefiles (@code{make/templates}).
     182These application template Makefiles have been included with the
     183RTEMS source distribution since the early 1990's.  However there is
     184a desire in the RTEMS user community to move all provided examples to
     185GNU autoconf. They are included in the 4.9 release series and used for
     186all examples provided with RTEMS. There is no definite time table for
     187obsoleting them.  You are free to use these but be warned they have
     188fallen out of favor with many in the RTEMS community and may disappear
     189in the future.
     191The following is a slightly shortened version of the make customization
     192file for the gen68340 BSP.  The original source for this file can be
     193found in the @code{make/custom} directory.
    178196# The RTEMS CPU Family and Model
    180 RTEMS_CPU_MODEL=mcpu32
    182200include $(RTEMS_ROOT)/make/custom/default.cfg
    184 # The name of the BSP directory used for the actual source code.
    185 # This allows for build variants of the same BSP source.
     202# This is the actual bsp directory used during the build process.
    188 # CPU flag to pass to GCC
    189 CPU_CFLAGS = -mcpu32
    191 # optimization flag to pass to GCC
    192 CFLAGS_OPTIMIZE_V=-O4 -fomit-frame-pointer
    194 # The name of the start file to be linked with.  This file is the first
    195 # part of the BSP which executes.
    196 START_BASE=start340
    198 # This make-exe macro is used in template makefiles to build the
    199 # final executable. Any other commands to follow, just as using
    200 # objcopy to build a PROM image or converting the executable to binary.
    202 define make-exe
    203         $(CC) $(CFLAGS) $(CFLAGS_LD) -o $(basename $@@).exe $(LINK_OBJS)
    204         $(NM) -g -n $(basename $@@).exe > $(basename $@@).num
    205         $(SIZE) $(basename $@@).exe
    206 endif
    207 @end example
    209 @subsection Creating a New BSP Make Customization File
    211 The basic steps for creating a @code{make/custom} file for a new BSP
    212 are as follows:
    214 @itemize @bullet
    216 @item copy any @code{.cfg} file to @code{BSP.cfg}
    219 RTEMS_BSP, CPU_CFLAGS, START_BASE, and make-exe rules.
    221 @end itemize
     205# This contains the compiler options necessary to select the CPU model
     206# and (hopefully) optimize for it.
     207CPU_CFLAGS = -mcpu=cpu32
     209# optimize flag: typically -O2
     210CFLAGS_OPTIMIZE_V = -O2 -g -fomit-frame-pointer
     211@end example
     213The make customization files have generally grown simpler and simpler
     214with each RTEMS release.  Beginning in the 4.9 release series, the rules
     215for linking an RTEMS application are shared by all BSPs.  Only BSPs which
     216need to perform a transformation from linked ELF file to a downloadable
     217format have any additional actions for program link time. In 4.8 and
     218older, every BSP specified the "make executable" or @code{make-exe}
     219rule and duplicated the same actions.
    223221It is generally easier to copy a @code{make/custom} file from a
    224222BSP similar to the one being developed.
  • doc/bsp_howto/target.t

    r9353a0d4 rc7ff10af  
    3737differences between these CPU models which RTEMS must take into account.
     39The source code found in the @code{cpukit/score/cpu} is required to
     40only depend upon the CPU model variations that GCC distinguishes
     41for the purposes of multilib'ing.  Multilib is the term the GNU
     42community uses to refer to building a single library source multiple
     43times with different compiler options so the binary code generated
     44is compatible.  As an example, from GCC's perspective, many PowerPC
     45CPU models are just a PPC603e.  Remember that GCC only cares about
     46the CPU code itself and need not be aware of any peripherals.  In
     47the embedded community, we are exposed to thousands of CPU models
     48which are all based upon only a relative small number of CPU cores.
     50Similarly for the SPARC/ERC32 BSP, the @code{RTEMS_CPU} is specified as
     51@code{erc32} which is the name of the CPU model and BSP for this SPARC V7
     52system on chip.  But the multilib variant used is actually @code{v7}
     53which indicates the ERC32 CPU core is a SPARC V7.
    3955@section Board Dependent
    141157@end example
     159@i{CPU_MODEL} may be a specific CPU model name or a name indicating a CPU
     160core or a set of related CPU models.  The file @code{} in each
     161@code{c/src/lib/libcpu/@i{CPU}} directory contains the logic which enables
     162the appropriate subdirectories for the specific CPU model your BSP has.
    143164@section Board Support Package Structure
    145 The BSPs are all under the c/src/lib/libbsp directory.  Below this
     166The BSPs are all under the @code{c/src/lib/libbsp} directory.  Below this
    146167directory, there is a subdirectory for each CPU family.  Each BSP
    147168is found under the subdirectory for the appropriate processor
    175196support of timer devices.
    177 @item @b{rtc}:
     198@item @b{rtc} or @code{tod}:
    178199support for the hardware real-time clock.
    190211include files for this BSP.
    192 @item @b{wrapup}:
    193 bundles all the components necessary to construct the BSP library.
     213@item @b{gnatsupp}:
     214BSP specific support for the GNU Ada run-time.  Each BSP that wishes
     215to have the possibility to map faults or exceptions into Ada language
     216exceptions or hardware interrupts into Ada interrupt tasks must provide
     217this support.
    195219@end itemize
     221There may be other directories in the BSP tree and the name should
     222be indicative of the functionality of the code within that directory.
    197224The build order of the BSP is determined by the Makefile structure.
Note: See TracChangeset for help on using the changeset viewer.