forked from Imagelibrary/rtems
2008-08-21 Joel Sherrill <joel.sherrill@oarcorp.com>
* bsp_howto/Makefile.am, 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.
This commit is contained in:
Joel Sherrill
@@ -1,3 +1,10 @@
|
||||
2008-08-21 Joel Sherrill <joel.sherrill@oarcorp.com>
|
||||
|
||||
* bsp_howto/Makefile.am, 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.
|
||||
|
||||
2008-08-21 Joel Sherrill <joel.sherrill@OARcorp.com>
|
||||
|
||||
* bsp_howto/ata.t, bsp_howto/clock.t, bsp_howto/ide-ctrl.t,
|
||||
|
||||
181
doc/bsp_howto/Developer-User-Timeline.eps
Normal file
181
doc/bsp_howto/Developer-User-Timeline.eps
Normal file
File diff suppressed because one or more lines are too long
BIN
doc/bsp_howto/Developer-User-Timeline.png
Normal file
BIN
doc/bsp_howto/Developer-User-Timeline.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
@@ -19,6 +19,12 @@ GENERATED_FILES = intro.texi target.texi makefiles.texi linkcmds.texi \
|
||||
|
||||
COMMON_FILES += $(top_srcdir)/common/cpright.texi
|
||||
|
||||
PNG_FILES = Developer-User-Timeline.png
|
||||
|
||||
if USE_HTML
|
||||
html_project_DATA += $(PNG_FILES)
|
||||
endif
|
||||
|
||||
FILES =
|
||||
|
||||
info_TEXINFOS = bsp_howto.texi
|
||||
@@ -124,4 +130,4 @@ CLEANFILES += bsp_howto.info bsp_howto.info-?
|
||||
|
||||
EXTRA_DIST = adaintr.t analog.t ata.t clock.t console.t discrete.t \
|
||||
ide-ctrl.t init.t intro.t linkcmds.t makefiles.t nvmem.t rtc.t shmsupp.t \
|
||||
support.t target.t timer.t
|
||||
support.t target.t timer.t $(PNG_FILES) $(EPS_IMAGES)
|
||||
|
||||
@@ -15,6 +15,13 @@ time. This file describes the memory configuration of the board as needed
|
||||
to link the program. Specifically it specifies where the code and data
|
||||
for the application will reside in memory.
|
||||
|
||||
The format of the linker script is defined by the GNU Loader @code{ld}
|
||||
which is included as a component of the GNU Binary Utilities. If you
|
||||
are using GNU/Linux, then you probably have the documentation installed
|
||||
already and are using these same tools configured for @b{native} use.
|
||||
Please visit the Binutils project @uref{http://sourceware.org/binutils/}
|
||||
if you need more information.
|
||||
|
||||
@section Program Sections
|
||||
|
||||
An embedded systems programmer must be much more aware of the
|
||||
|
||||
@@ -12,13 +12,41 @@ This chapter discusses the Makefiles associated with a BSP. It does not
|
||||
describe the process of configuring, building, and installing RTEMS.
|
||||
This chapter will not provide detailed information about this process.
|
||||
Nonetheless, it is important to remember that the general process consists
|
||||
of three parts:
|
||||
of four phases as shown here:
|
||||
|
||||
@ifset use-ascii
|
||||
@example
|
||||
@group
|
||||
@itemize @bullet
|
||||
@item bootstrap
|
||||
@item configure
|
||||
@item build
|
||||
@item install
|
||||
@end itemize
|
||||
@end group
|
||||
@end example
|
||||
@end ifset
|
||||
|
||||
|
||||
@ifset use-tex
|
||||
@image{Developer-User-Timeline,6in,,Developer User Timeline,.png}
|
||||
@c @image{FILENAME[, WIDTH[, HEIGHT[, ALTTEXT[, EXTENSION]]]]}
|
||||
|
||||
@end ifset
|
||||
|
||||
@ifset use-html
|
||||
@html
|
||||
<center>
|
||||
<IMG SRC="Developer-User-Timeline.png" WIDTH=800 ALT="Developer User Timeline">
|
||||
</center>
|
||||
@end html
|
||||
@end ifset
|
||||
|
||||
|
||||
During the bootstrap phase, you are using the @code{configure.ac} and
|
||||
@code{Makefile.am} files as input to GNU autoconf and automake to
|
||||
generate a variety of files. This is done by running the @code{bootstrap}
|
||||
script found at the top of the RTEMS source tree.
|
||||
|
||||
During the configure phase, a number of files are generated. These
|
||||
generated files are tailored for the specific host/target combination
|
||||
@@ -41,13 +69,25 @@ automatically generated files in each directory in the RTEMS
|
||||
source tree. The @code{bootstrap} script found in the top level
|
||||
directory of the RTEMS source tree is executed to produce the
|
||||
automatically generated files. That script must be run from
|
||||
a directory with a @code{configure.ac} file in it.
|
||||
a directory with a @code{configure.ac} file in it. The @code{bootstrap}
|
||||
command is usually invoked in one of the following manners:
|
||||
|
||||
There is a file named @code{Makefile.am} in each directory of a BSP.
|
||||
This file is used by @b{automake} to produce the file
|
||||
named @code{Makefile.in} which is also found in each directory of a BSP.
|
||||
The configure process specializes the @code{Makefile.in} files at
|
||||
the time that RTEMS
|
||||
@itemize @bullet
|
||||
@item @code{bootstrap} to regenerate all files that are generated by
|
||||
autoconf and automake.
|
||||
@item @code{bootstrap -c} to remove all files generated by autoconf and
|
||||
automake.
|
||||
@item @code{bootstrap -p} to regenerate @code{preinstall.am} files.
|
||||
@end itemize
|
||||
|
||||
There is a file named @code{Makefile.am} in each directory of
|
||||
a BSP. This file is used by @b{automake} to produce the file named
|
||||
@code{Makefile.in} which is also found in each directory of a BSP.
|
||||
When modifying a @code{Makefile.am}, you can probably find examples of
|
||||
anything you need to do in one of the BSPs.
|
||||
|
||||
|
||||
The configure process specializes the @code{Makefile.in} files at the time that RTEMS
|
||||
is configured for a specific development host and target. Makefiles
|
||||
are automatically generated from the @code{Makefile.in} files. It is
|
||||
necessary for the BSP developer to provide the @code{Makefile.am}
|
||||
@@ -60,87 +100,74 @@ and building RTEMS for a given BSP.
|
||||
|
||||
The BSP developer is responsible for generating @code{Makefile.am}
|
||||
files which properly build all the files associated with their BSP.
|
||||
There are generally three types of Makefiles in a BSP source tree:
|
||||
Most BSPs will only have a single @code{Makefile.am} which details
|
||||
the set of source files to build to compose the BSP support library
|
||||
along with the set of include files that are to be installed.
|
||||
|
||||
|
||||
@itemize @bullet
|
||||
@item Directory Makefiles
|
||||
@item Source Directory Makefiles
|
||||
@item Wrapup Makefile
|
||||
@end itemize
|
||||
|
||||
@subsection Directory Makefiles
|
||||
|
||||
The Directory class of Makefiles directs the build process through
|
||||
a set of subdirectories in a particular order. This order is usually
|
||||
chosen to insure that build dependencies are properly processed.
|
||||
Most BSPs only have one Directory class Makefile. The @code{Makefile.am}
|
||||
in the BSP root directory (@code{c/src/lib/libbsp/CPU/BSP}) specifies
|
||||
following Makefile fragment shows how a BSP would specify the
|
||||
directories to be built and their order:
|
||||
This single @code{Makefile.am} at the top of the BSP tree specifies
|
||||
the set of header files to install. This fragment from the SPARC/ERC32
|
||||
BSP results in four header files being installed.
|
||||
|
||||
@example
|
||||
SUB_DIRS=include start340 startup clock console timer \
|
||||
network wrapup
|
||||
include_HEADERS = include/bsp.h
|
||||
include_HEADERS += include/tm27.h
|
||||
include_HEADERS += include/erc32.h
|
||||
include_HEADERS += include/coverhd.h
|
||||
@end example
|
||||
|
||||
@subsection Source Directory Makefiles
|
||||
When adding new include files, you will be adding to the set of
|
||||
@code{include_HEADERS}. When you finish editing the @code{Makefile.am}
|
||||
file, do not forget to run @code{bootstrap -p} to regenerate the
|
||||
@code{preinstall.am}.
|
||||
|
||||
There is a @code{Makefile.am} in most of the directories in a BSP. This
|
||||
class of Makefile lists the files to be built as part of the driver.
|
||||
When adding new files to an existing directory, Do not forget to add
|
||||
the new files to the list of files to be built in the @code{Makefile.am}
|
||||
and run @code{bootstrap}.
|
||||
The @code{Makefile.am} also specifies which source files to build.
|
||||
By convention, logical components within the BSP each assign their
|
||||
source files to a unique variable. These variables which define
|
||||
the source files are collected into a single variable which instructs
|
||||
the GNU autotools that we are building @code{libbsp.a}. This fragment
|
||||
from the SPARC/ERC32 BSP shows how the startup related, miscellaneous
|
||||
support code, and the console device driver source is managed
|
||||
in the @code{Makefile.am}.
|
||||
|
||||
@example
|
||||
startup_SOURCES = ../../sparc/shared/bspclean.c ../../shared/bsplibc.c \
|
||||
../../shared/bsppredriverhook.c \
|
||||
../../shared/bsppost.c ../../sparc/shared/bspstart.c \
|
||||
../../shared/bootcard.c ../../shared/sbrk.c startup/setvec.c \
|
||||
startup/spurious.c startup/erc32mec.c startup/boardinit.S
|
||||
clock_SOURCES = clock/ckinit.c
|
||||
...
|
||||
noinst_LIBRARIES = libbsp.a
|
||||
libbsp_a_SOURCES = $(startup_SOURCES) $(console_SOURCES) ...
|
||||
@end example
|
||||
|
||||
When adding new files to an existing directory, do not forget to add
|
||||
the new files to the list of files to be built in the corresponding
|
||||
@code{XXX_SOURCES} variable in the @code{Makefile.am} and run
|
||||
@code{bootstrap}.
|
||||
|
||||
Some BSPs use code that is built in @code{libcpu}. If you BSP does
|
||||
this, then you will need to make sure the objects are pulled into your
|
||||
BSP library. The following from the SPARC/ERC32 BSP pulls in the cache,
|
||||
register window management and system call support code from the directory
|
||||
corresponding to its @code{RTEMS_CPU} model.
|
||||
|
||||
@example
|
||||
libbsp_a_LIBADD = ../../../libcpu/@@RTEMS_CPU@@/cache.rel \
|
||||
../../../libcpu/@@RTEMS_CPU@@/reg_win.rel \
|
||||
../../../libcpu/@@RTEMS_CPU@@/syscall.rel
|
||||
@end example
|
||||
|
||||
@b{NOTE:} The @code{Makefile.am} files are ONLY processed by
|
||||
@code{bootstrap} and the resulting @code{Makefile.in} files are
|
||||
only processed during the configure
|
||||
process of a RTEMS build. Therefore, when developing
|
||||
a BSP and adding a new file to a @code{Makefile.am}, the
|
||||
already generated @code{Makefile} will not automatically
|
||||
@code{bootstrap} and the resulting @code{Makefile.in} files are only
|
||||
processed during the configure process of a RTEMS build. Therefore,
|
||||
when developing a BSP and adding a new file to a @code{Makefile.am},
|
||||
the already generated @code{Makefile} will not automatically
|
||||
include the new references unless you configured RTEMS with the
|
||||
@code{--enable-maintainer-mode} option.
|
||||
Otherwise, the new file not being be taken into account!
|
||||
@code{--enable-maintainer-mode} option. Otherwise, the new file not
|
||||
being be taken into account!
|
||||
|
||||
If adding a new directory, be sure to add it to the list of
|
||||
automatically generated files in the BSP's @code{configure.ac}
|
||||
script.
|
||||
|
||||
@subsection Wrapup Makefile
|
||||
|
||||
This class of Makefiles produces a library. The BSP wrapup Makefile
|
||||
is responsible for producing the library @code{libbsp.a} which is later
|
||||
merged into the @code{librtemsall.a} library. This Makefile specifies
|
||||
which BSP components are to be placed into the library as well as which
|
||||
components from the CPU dependent support code library. For example,
|
||||
this component may choose to use a default exception handler from the
|
||||
CPU dependent support code or provide its own.
|
||||
|
||||
This Makefile makes use of the @code{foreach} construct in @b{GNU make}
|
||||
to pick up the required components:
|
||||
|
||||
@example
|
||||
BSP_PIECES=startup clock console timer
|
||||
CPU_PIECES=
|
||||
GENERIC_PIECES=
|
||||
|
||||
# bummer; have to use $foreach since % pattern subst
|
||||
# rules only replace 1x
|
||||
OBJS=$(foreach piece, $(BSP_PIECES), ../$(piece)/$(ARCH)/$(piece).o) \
|
||||
$(foreach piece, $(CPU_PIECES), \
|
||||
../../../../libcpu/$(RTEMS_CPU)/$(piece)/$(ARCH)/$(piece).o) \
|
||||
$(wildcard \
|
||||
../../../../libcpu/$(RTEMS_CPU)/$(RTEMS_CPU_MODEL)/fpsp/$(ARCH)/fpsp.rel) \
|
||||
$(foreach piece, \
|
||||
$(GENERIC_PIECES), ../../../$(piece)/$(ARCH)/$(piece).o)
|
||||
@end example
|
||||
|
||||
The variable @code{OBJS} is the list of "pieces" expanded to include
|
||||
path information to the appropriate object files. The @code{wildcard}
|
||||
function is used on pieces of @code{libbsp.a} which are optional and
|
||||
may not be present based upon the configuration options.
|
||||
|
||||
@section Makefiles Used Both During The BSP Design and its Use
|
||||
@section Creating a New BSP Make Customization File
|
||||
|
||||
When building a BSP or an application using that BSP, it is necessary
|
||||
to tailor the compilation arguments to account for compiler flags, use
|
||||
@@ -151,76 +178,46 @@ application. So a BSP must include a build configuration file. The
|
||||
configuration file is @code{make/custom/BSP.cfg}.
|
||||
|
||||
The configuration file is taken into account when building one's
|
||||
application using the RTEMS template Makefiles (@code{make/templates}).
|
||||
It is strongly advised to use these template Makefiles since they
|
||||
encapsulate a number of build rules along with the compile and link
|
||||
time options necessary to execute on the target board.
|
||||
application using the RTEMS template Makefiles (@code{make/templates}).
|
||||
These application template Makefiles have been included with the
|
||||
RTEMS source distribution since the early 1990's. However there is
|
||||
a desire in the RTEMS user community to move all provided examples to
|
||||
GNU autoconf. They are included in the 4.9 release series and used for
|
||||
all examples provided with RTEMS. There is no definite time table for
|
||||
obsoleting them. You are free to use these but be warned they have
|
||||
fallen out of favor with many in the RTEMS community and may disappear
|
||||
in the future.
|
||||
|
||||
There is a template Makefile provided for each of class of RTEMS
|
||||
Makefiles. The purpose of each class of RTEMS Makefile is to:
|
||||
|
||||
@itemize @bullet
|
||||
@item call recursively the makefiles in the directories beneath
|
||||
the current one,
|
||||
|
||||
@item build a library, or
|
||||
|
||||
@item build an executable.
|
||||
|
||||
@end itemize
|
||||
|
||||
The following is a shortened and heavily commented version of the
|
||||
make customization file for the gen68340 BSP. The original source
|
||||
for this file can be found in the @code{make/custom} directory.
|
||||
The following is a slightly shortened version of the make customization
|
||||
file for the gen68340 BSP. The original source for this file can be
|
||||
found in the @code{make/custom} directory.
|
||||
|
||||
@example
|
||||
|
||||
# The RTEMS CPU Family and Model
|
||||
RTEMS_CPU=m68k
|
||||
RTEMS_CPU_MODEL=mcpu32
|
||||
RTEMS_CPU_MODEL=m68340
|
||||
|
||||
include $(RTEMS_ROOT)/make/custom/default.cfg
|
||||
|
||||
# The name of the BSP directory used for the actual source code.
|
||||
# This allows for build variants of the same BSP source.
|
||||
# This is the actual bsp directory used during the build process.
|
||||
RTEMS_BSP_FAMILY=gen68340
|
||||
|
||||
# CPU flag to pass to GCC
|
||||
CPU_CFLAGS = -mcpu32
|
||||
# This contains the compiler options necessary to select the CPU model
|
||||
# and (hopefully) optimize for it.
|
||||
CPU_CFLAGS = -mcpu=cpu32
|
||||
|
||||
# optimization flag to pass to GCC
|
||||
CFLAGS_OPTIMIZE_V=-O4 -fomit-frame-pointer
|
||||
|
||||
# The name of the start file to be linked with. This file is the first
|
||||
# part of the BSP which executes.
|
||||
START_BASE=start340
|
||||
|
||||
# This make-exe macro is used in template makefiles to build the
|
||||
# final executable. Any other commands to follow, just as using
|
||||
# objcopy to build a PROM image or converting the executable to binary.
|
||||
|
||||
define make-exe
|
||||
$(CC) $(CFLAGS) $(CFLAGS_LD) -o $(basename $@@).exe $(LINK_OBJS)
|
||||
$(NM) -g -n $(basename $@@).exe > $(basename $@@).num
|
||||
$(SIZE) $(basename $@@).exe
|
||||
endif
|
||||
# optimize flag: typically -O2
|
||||
CFLAGS_OPTIMIZE_V = -O2 -g -fomit-frame-pointer
|
||||
@end example
|
||||
|
||||
@subsection Creating a New BSP Make Customization File
|
||||
|
||||
The basic steps for creating a @code{make/custom} file for a new BSP
|
||||
are as follows:
|
||||
|
||||
@itemize @bullet
|
||||
|
||||
@item copy any @code{.cfg} file to @code{BSP.cfg}
|
||||
|
||||
@item modify RTEMS_CPU, RTEMS_CPU_MODEL, RTEMS_BSP_FAMILY,
|
||||
RTEMS_BSP, CPU_CFLAGS, START_BASE, and make-exe rules.
|
||||
|
||||
@end itemize
|
||||
The make customization files have generally grown simpler and simpler
|
||||
with each RTEMS release. Beginning in the 4.9 release series, the rules
|
||||
for linking an RTEMS application are shared by all BSPs. Only BSPs which
|
||||
need to perform a transformation from linked ELF file to a downloadable
|
||||
format have any additional actions for program link time. In 4.8 and
|
||||
older, every BSP specified the "make executable" or @code{make-exe}
|
||||
rule and duplicated the same actions.
|
||||
|
||||
It is generally easier to copy a @code{make/custom} file from a
|
||||
BSP similar to the one being developed.
|
||||
|
||||
|
||||
|
||||
@@ -36,6 +36,22 @@ dependent on a particular CPU model. For example, the MC68000 and MC68020
|
||||
processors are both members of the m68k CPU family but there are significant
|
||||
differences between these CPU models which RTEMS must take into account.
|
||||
|
||||
The source code found in the @code{cpukit/score/cpu} is required to
|
||||
only depend upon the CPU model variations that GCC distinguishes
|
||||
for the purposes of multilib'ing. Multilib is the term the GNU
|
||||
community uses to refer to building a single library source multiple
|
||||
times with different compiler options so the binary code generated
|
||||
is compatible. As an example, from GCC's perspective, many PowerPC
|
||||
CPU models are just a PPC603e. Remember that GCC only cares about
|
||||
the CPU code itself and need not be aware of any peripherals. In
|
||||
the embedded community, we are exposed to thousands of CPU models
|
||||
which are all based upon only a relative small number of CPU cores.
|
||||
|
||||
Similarly for the SPARC/ERC32 BSP, the @code{RTEMS_CPU} is specified as
|
||||
@code{erc32} which is the name of the CPU model and BSP for this SPARC V7
|
||||
system on chip. But the multilib variant used is actually @code{v7}
|
||||
which indicates the ERC32 CPU core is a SPARC V7.
|
||||
|
||||
@section Board Dependent
|
||||
|
||||
This class of code provides the most specific glue between RTEMS and
|
||||
@@ -140,9 +156,14 @@ CPU model dependent support code is found in the following directory:
|
||||
c/src/lib/libcpu/@i{CPU}/@i{CPU_MODEL}
|
||||
@end example
|
||||
|
||||
@i{CPU_MODEL} may be a specific CPU model name or a name indicating a CPU
|
||||
core or a set of related CPU models. The file @code{configure.ac} in each
|
||||
@code{c/src/lib/libcpu/@i{CPU}} directory contains the logic which enables
|
||||
the appropriate subdirectories for the specific CPU model your BSP has.
|
||||
|
||||
@section Board Support Package Structure
|
||||
|
||||
The BSPs are all under the c/src/lib/libbsp directory. Below this
|
||||
The BSPs are all under the @code{c/src/lib/libbsp} directory. Below this
|
||||
directory, there is a subdirectory for each CPU family. Each BSP
|
||||
is found under the subdirectory for the appropriate processor
|
||||
family (m68k, powerpc, etc.). In addition, there is source code
|
||||
@@ -174,7 +195,7 @@ support for the clock tick -- a regular time basis to the kernel.
|
||||
@item @b{timer}:
|
||||
support of timer devices.
|
||||
|
||||
@item @b{rtc}:
|
||||
@item @b{rtc} or @code{tod}:
|
||||
support for the hardware real-time clock.
|
||||
|
||||
@item @b{nvmem}:
|
||||
@@ -189,11 +210,17 @@ support of shared memory driver MPCI layer in a multiprocessor system,
|
||||
@item @b{include}:
|
||||
include files for this BSP.
|
||||
|
||||
@item @b{wrapup}:
|
||||
bundles all the components necessary to construct the BSP library.
|
||||
@item @b{gnatsupp}:
|
||||
BSP specific support for the GNU Ada run-time. Each BSP that wishes
|
||||
to have the possibility to map faults or exceptions into Ada language
|
||||
exceptions or hardware interrupts into Ada interrupt tasks must provide
|
||||
this support.
|
||||
|
||||
@end itemize
|
||||
|
||||
There may be other directories in the BSP tree and the name should
|
||||
be indicative of the functionality of the code within that directory.
|
||||
|
||||
The build order of the BSP is determined by the Makefile structure.
|
||||
This structure is discussed in more detail in the @ref{Makefiles}
|
||||
chapter.
|
||||
|
||||
Reference in New Issue
Block a user