RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

2010-12-16 Joel Sherrill <joel.sherrilL@OARcorp.com>

Browse Source 
* Makefile.am, configure.ac, common/cpright.texi, common/rtems.texi.in,
	cpu_supplement/.cvsignore, started/Makefile.am, started/binaries.t,
	started/buildc.t, started/buildrt.t, started/intro.t,
	started/nextstep.t, started/nt.t, started/require.t,
	started/sample.t, started/started.texi: Major update which includes
	removal of references to specific tool versions and patches.
	* started/tversions.texi.in: Removed.
This commit is contained in:
Joel Sherrill
2010-12-16 20:54:34 +00:00
parent 84d67445f4
commit 9aff0a7946
17 changed files with 1014 additions and 1233 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
doc/ChangeLog
View File

@@ -1,3 +1,13 @@
2010-12-16 Joel Sherrill <joel.sherrilL@OARcorp.com>
* Makefile.am, configure.ac, common/cpright.texi, common/rtems.texi.in,
cpu_supplement/.cvsignore, started/Makefile.am, started/binaries.t,
started/buildc.t, started/buildrt.t, started/intro.t,
started/nextstep.t, started/nt.t, started/require.t,
started/sample.t, started/started.texi: Major update which includes
removal of references to specific tool versions and patches.
* started/tversions.texi.in: Removed.
2010-12-16 Joel Sherrill <joel.sherrilL@OARcorp.com>
* Makefile.am, configure.ac, develenv/direct.t: Remove Getting Started

4
doc/Makefile.am
View File

@@ -8,7 +8,7 @@ ACLOCAL_AMFLAGS = -I ../aclocal
# + tools, common and images are shared across many documents
SUBDIRS = tools started user bsp_howto porting develenv posix_users \
posix1003.1 filesystem itron3.0 networking ada_user \
posix1003.1 filesystem networking ada_user \
new_chapters relnotes cpu_supplement shell
if USE_HTML
@@ -20,7 +20,9 @@ EXTRA_DIST = HELP.html rtems_header.html.in rtems_footer.html.in
EXTRA_DIST += common/cpright.texi common/setup.texi \
common/treedef.tex common/rtems.texi.in
if USE_HTML
html_imagesdir = $(htmldir)/images
endif
HTML_IMAGES = images/dir-arrow.gif images/dvi.gif images/missing-arrow.gif \
images/next-arrow.gif images/oaronly.jpg images/pdf.gif images/pdf1.gif \

6
doc/common/cpright.texi
View File

@@ -1,5 +1,5 @@
@c
@c COPYRIGHT (c) 1988-2008.
@c COPYRIGHT (c) 1988-2010.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@@ -17,7 +17,7 @@
@end tex
@vskip 0pt plus 1filll
COPYRIGHT @copyright{} 1988 - 2008.@*
COPYRIGHT @copyright{} 1988 - 2010.@*
On-Line Applications Research Corporation (OAR).@*
The authors have used their best efforts in preparing
@@ -36,5 +36,5 @@ Any inquiries concerning RTEMS, its related support
components, its documentation, or any custom services
for RTEMS should be directed to the contacts listed on
that site. A current list of RTEMS Support Providers
is at @uref{http://www.rtems.com/support.html}.
is at @uref{http://www.rtems.com/oarsupport}.

1
doc/common/rtems.texi.in
View File

@@ -11,4 +11,3 @@
@set RTEMSPREFIX @RTEMSPREFIX@
@set RTEMSAPI @RTEMSAPI@
@set RTEMSRPMPREFIX @RTEMSRPMPREFIX@
@set RTEMSRPMGROUP @RTEMSRPMGROUP@

46
doc/configure.ac
View File

@@ -137,30 +137,6 @@ dnl Checks for typedefs, structures, and compiler characteristics.
dnl Checks for library functions.
AC_MSG_CHECKING([for ./setup.def])
AS_IF([test -f ${srcdir}/setup.def],[
. ${srcdir}/setup.def
AC_MSG_RESULT([done])
],[
AC_MSG_ERROR([missing])
])
AS_IF([test -z "$binutils_patch_version"],
[set_binutils_patch="@clear BINUTILSPATCHVERSION"],
[set_binutils_patch="@set BINUTILSPATCHVERSION $binutils_patch_version"])
AS_IF([test -z "$newlib_patch_version"],
[set_newlib_patch="@clear NEWLIBPATCHVERSION"],
[set_newlib_patch="@set NEWLIBPATCHVERSION $newlib_patch_version"])
AS_IF([test -z "$gcc_patch_version"],
[set_gcc_patch="@clear GCCPATCHVERSION"],
[set_gcc_patch="@set GCCPATCHVERSION $gcc_patch_version"])
AS_IF([test -z "$gdb_patch_version"],
[set_gdb_patch="@clear GDBPATCHVERSION"],
[set_gdb_patch="@set GDBPATCHVERSION $gdb_patch_version"])
AC_CONFIG_SUBDIRS(tools)
AC_CONFIG_FILES([Makefile],[],[
@@ -170,7 +146,6 @@ cat << EOF > common/rtems.sed~
s/@RTEMSAPI@/RTEMS_API/;t t
s,@RTEMSPREFIX@,$prefix,;t t
s,@RTEMSRPMPREFIX@,$rpmprefix,;t t
s,@RTEMSRPMGROUP@,RTEMS/]RTEMS_API[,;t t
EOF
_RTEMS_UPDATE_CONDITIONAL([common/rtems.sed],[common/rtems.sed~])
])
@@ -181,33 +156,14 @@ develenv/Makefile
user/Makefile
bsp_howto/Makefile])
AC_CONFIG_FILES([started/Makefile],[],[
test -d started || mkdir started
cat << EOF > started/tversions.sed~
:t
s/@GCCVERSION@/$gcc_version/;t t
s/@BINUTILSVERSION@/$binutils_version/;t t
s/@NEWLIBVERSION@/$newlib_version/;t t
s/@GDBVERSION@/$gdb_version/;t t
s/@SETBINUTILSPATCHVERSION@/$set_binutils_patch/;t t
s/@SETGCCPATCHVERSION@/$set_gcc_patch/;t t
s/@SETNEWLIBPATCHVERSION@/$set_newlib_patch/;t t
s/@SETGDBPATCHVERSION@/$set_gdb_patch/;t t
s/@GCCRPMRELEASE@/$gccnewlib_rpm_release/;t t
s/@BINUTILSRPMRELEASE@/$binutils_rpm_release/;t t
s/@GDBRPMRELEASE@/$gdb_rpm_release/;t t
EOF
_RTEMS_UPDATE_CONDITIONAL([started/tversions.sed],[started/tversions.sed~])
])
AC_CONFIG_FILES([
porting/Makefile
networking/Makefile
posix_users/Makefile
posix1003.1/Makefile
filesystem/Makefile
itron3.0/Makefile
ada_user/Makefile
started/Makefile
relnotes/Makefile
new_chapters/Makefile
cpu_supplement/Makefile

4
doc/cpu_supplement/.cvsignore
View File

@@ -1,4 +1,5 @@
arm.texi
avr.texi
bfin.texi
cpu_supplement
cpu_supplement-?
@@ -24,6 +25,7 @@ cpu_supplement.vr
general.texi
i386.texi
index.html
lm32.texi
m68k.texi
Makefile
Makefile.in
@@ -35,6 +37,8 @@ rtems_header.html
rtemspie.pdf
sh.texi
sparc.texi
sparc64.texi
stamp-vti
states.pdf
tic4x.texi
version.texi

29
doc/started/Makefile.am
View File

@@ -1,5 +1,5 @@
#
# COPYRIGHT (c) 1988-2002.
# COPYRIGHT (c) 1988-2010.
# On-Line Applications Research Corporation (OAR).
# All rights reserved.
#
@@ -7,7 +7,6 @@
#
PROJECT = started
EDITION = 1
include $(top_srcdir)/project.am
include $(top_srcdir)/main.am
@@ -22,42 +21,43 @@ FILES =
info_TEXINFOS = started.texi
started_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES)
intro.texi: intro.t tversions.texi
intro.texi: intro.t
$(BMENU2) -c -p "Top" \
-u "Top" \
-n "Requirements" < $< > $@
require.texi: require.t tversions.texi
require.texi: require.t
$(BMENU2) -c -p "GCC Mailing Lists" \
-u "Top" \
-n "Prebuilt Toolset Executables" < $< > $@
binaries.texi: binaries.t tversions.texi
$(BMENU2) -c -p "Archive and Build Directory Format" \
binaries.texi: binaries.t
$(BMENU2) -c \
-p "GNU/Linux Distrobutions using Debian Packaging Format" \
-u "Top" \
-n "Building the GNU Cross Compiler Toolset" < $< > $@
buildc.texi: buildc.t tversions.texi
buildc.texi: buildc.t
$(BMENU2) -c -p "Removing Zipped Tar Files" \
-u "Top" \
-n "Building RTEMS" < $< > $@
buildrt.texi: buildrt.t tversions.texi
buildrt.texi: buildrt.t
$(BMENU2) -c -p "Error Messages Indicating Configuration Problems" \
-u "Top" \
-n "Building the Sample Applications" < $< > $@
sample.texi: sample.t tversions.texi
sample.texi: sample.t
$(BMENU2) -c -p "Using the RTEMS configure Script Directly" \
-u "Top" \
-n "Where To Go From Here" < $< > $@
nextstep.texi: nextstep.t tversions.texi
nextstep.texi: nextstep.t
$(BMENU2) -c -p "More Information on RTEMS Application Makefiles" \
-u "Top" \
-n "Using MS-Windows as a Development Host" < $< > $@
nt.texi: nt.t tversions.texi
nt.texi: nt.t
$(BMENU2) -c -p "Writing an Application" \
-u "Top" \
-n "" < $< > $@
@@ -83,11 +83,4 @@ PICTURES = pictures/bit_ada.jpg pictures/bit_ada.vsd pictures/bit_c.jpg \
EXTRA_DIST += $(PICTURES)
tversions.texi: tversions.texi.in tversions.sed
sed -f tversions.sed $(srcdir)/tversions.texi.in > tversions.texi
CLEANFILES += tversions.texi
EXTRA_DIST += tversions.texi.in
DISTCLEANFILES = tversions.sed
CLEANFILES += started.info started.info-?

325
doc/started/binaries.t
View File

@@ -1,5 +1,5 @@
@c
@c COPYRIGHT (c) 1988-2002.
@c COPYRIGHT (c) 1988-2010.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@@ -8,18 +8,22 @@
@chapter Prebuilt Toolset Executables
Precompiled toolsets are available for Linux, Cygwin, FreeBSD,
and Solaris. These are packaged in the following formats:
Precompiled toolsets are available for GNU/Linux and MS-Windows.
Other hosts will need to build from source. Packaged binaries are
in the following formats:
@itemize @bullet
@item Linux - RPM
@item GNU/Linux - RPM
@item Cygwin - tar.bz2
@item Solaris - tar.bz2
@item Mingw - tar.bz2
@end itemize
RPM is an acronym for the RPM Package Manager. RPM is the
native package installer for many Linux distributions including
RedHat, SuSE, and Fedora.
RPM is an acronym for the RPM Package Manager. RPM is the native package
installer for many GNU/Linux distributions including RedHat Enterprise
Linux, Centos, SuSE, and Fedora.
The RTEMS Project maintains a Yum Repository which makes it quite simple
to install and update RTEMS toolsets.
The prebuilt binaries are intended to be easy to install and
the instructions are similar regardless of the host environment.
@@ -27,18 +31,27 @@ There are a few structural issues with the packaging of the RTEMS
Cross Toolset binaries that you need to be aware of.
@enumerate
@item There are dependencies between the various packages.
This requires that certain packages be installed before others may be.
Some packaging formats enforce this dependency.
@item There are dependencies between the various packages. This requires
that certain packages be installed before others may be. Some packaging
formats enforce this dependency.
@item Some packages are target CPU family independent and shared
across all target architectures. These are referred to as
"base" packages.
@item Depending upon the version of GCC as well as the development
host and target CPU combination, pre-built supplemental packages may
be provided for Ada (gnat), Chill, Java (gcj), Fortran (g77), and
Objective-C (objc). These binaries are strictly optional.
@item Pre-built GNU Binary Utilities (binutils) packages are available
for all RTEMS targets. These include tools such as the assembler and
linker and must be installed.
@item Pre-built C language packages are available which include a C
compiler as well as the Standard C libraries for the embedded RTEMS
targets. These must be installed.
@item Pre-built C++ language packages are available for most target
architectures which includes a C++ compiler as well as the Standard C++
libraries for the embedded RTEMS targets. These are not part of the
minimum installation and need only be installed if the application is
using C++.
@end enumerate
@@ -50,30 +63,222 @@ step in the process.
This section provides information on installing and removing RPMs.
@subsection Installing RPMs
Note that RTEMS tools for multiple major versions of RTEMS can be
installed in parallel since they are installed into different host
directories. The tools also include the RTEMS Release Series in their
name.
The following is a sample session illustrating the installation
of a C/C++ toolset targeting the SPARC architecture.
@subsection Locating the RPMs for your GNU/Linux Distribution
The RTEMS Project maintains a Yum Repository of RPMs for its
toolsets. Whether you use Yum to install the RPMs or download and install
them via another procedure, you will need to locate the appropriate
set of RPMs on the RTEMS Yum Repository. The following instructions
are generalized.
If your host operating system uses Yum and RPMs, then you will only have
to download and install two RPMs by hand
@enumerate
@item Point your browser at
@uref{http://www.rtems.org/ftp/pub/rtems/linux,
http://www.rtems.org/ftp/pub/rtems/linux}. In this directory, you
will see a list of RTEMS major versions such as 4.11, 4.10, 4.9, etc..
Descend into the appropriate directory for the version of RTEMS you
are using.
@item Now that you are in the directory for a specific RTEMS major
version, you will be presented with a list of GNU/Linux distributions.
This will include options like redhat, centos, fedora, and suse.
Select the appropriate distribution.
@item Now that you are in the directory for your selected distribution,
you will be presented with a list of distribution versions for which
RTEMS pre-built RPMs are available. Select the appropriate distribution
version.
@item Now that you are in the directory for the proper version of
your selected distribution, you will be presented with a choice of
host architecture versions such as i386, i686, and x86_64. Select the
appropriate version for your development computer.
@item At this point, you will have a long list of RPMs to select from.
@end enumerate
The RTEMS Projects supports a wide variety of host OS and target
combinations. In addition, these toolsets are specific to a particular
RTEMS Release Series. Given the large number of possible combinations,
the instructions use variables to indicate where versions go in the real
package names you will use. These variable are used in the examples of
RPM version names:
@itemize @bullet
@item @code{<VERSION>} is the tool version will be found at this location
in the RPM name. This will be a release number such as @code{2.20}
or @code{4.4.5}.
@item @code{<DIST>} indicates the GNU/Linux distribution version.
This will be a string such as @code{fc14} or @code{el6}.
@item @code{<ARCH>} indicates the architecture used for RPMs on your
GNU/Linux installation. This will be a string such as @code{i386}
or @code{x86_64}.
@item @code{<RPM>} indicates the RPM revision level. This will be a
single integer.
@end itemize
The tool VERSION and RPM release may vary within the set of current RPMs for a particular RTEMS Release series based upon the target architecture.
If you are using Yum, please continue to the next section. If you are
downloading the RPMs to install by hand, then go to the @ref{Installing
RPMs Without Yum} section.
@subsection Managing RPMs Using Yum
This section describes how to install and remove RTEMS Toolsets using Yum.
@subsubsection Installing RPMs Using Yum
If you are on a host operating system that uses Yum, you are fortunate because this is the one of the simplest ways to install the tools. After locating the appropriate directory on the RTEMS Yum Repository using the instructions in @ref{Locating the RPMs for your GNU/Linux Distribution}, you will need to install the following RPMs:
@itemize @bullet
@item @value{RTEMSRPMPREFIX}-release-<VERSION>-<RPM>.<DIST>.noarch.rpm
@item @value{RTEMSRPMPREFIX}-yum-conf-<VERSION>-<RPM>.<DIST>.noarch.rpm
@end itemize
You can use the search within page feature of your browser to locate
the RPMs with "release" or "yum" in their names.
You will need to download the RPMs above or RPM can be given the URLs for
them and it will fetch them for you. Either way, the commands similar
to the following will install the common or base RPMs required.
@example
rpm -U @value{RTEMSRPMPREFIX}binutils-common-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
rpm -U @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
rpm -U @value{RTEMSRPMPREFIX}gcc-common-@value{GCCVERSION}-@value{GCCRPMRELEASE}.i386.rpm
rpm -U @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-newlib-@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
rpm -U @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-@value{GCCVERSION}-@value{GCCRPMRELEASE}.i386.rpm
rpm -U @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-c++-@value{GCCVERSION}-@value{GCCRPMRELEASE}.i386.rpm
rpm -U @value{RTEMSRPMPREFIX}gdb-common-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
rpm -U @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
rpm -U @value{RTEMSRPMPREFIX}-release-<VERSION>-<RPM>.<DIST>.noarch.rpm \
@value{RTEMSRPMPREFIX}-yum-conf-<VERSION>-<RPM>.<DIST>.noarch.rpm
@end example
Upon successful completion of the above command sequence, a
C/C++ cross development toolset targeting the SPARC is
installed in @code{@value{RTEMSPREFIX}}. In order to use this toolset,
the directory @code{@value{RTEMSPREFIX}/bin} must be included in your
PATH.
Once these are installed, Yum knows about the RTEMS Yum repository
for @value{RTEMSPREFIX}. This means that you can install and upgrade
RTEMS Toolsets just like the packages provided by your distribution.
To install complete C and C++ toolset targeting the SPARC architecture
for the RTEMS @value{RTEMSAPI} Release series, commands similar to the
following will be used.
Once you have successfully installed the RPMs for BINUTILS, GCC,
NEWLIB, and GDB, then you may proceed directly to @ref{Building RTEMS}.
@example
yum install @value{RTEMSPREFIX}-auto*
yum install @value{RTEMSPREFIX}-sparc-*
@end example
The first command installs GNU autoconf and automake which are used
by all RTEMS targets. The second command installs the complete
sparc-@value{RTEMSPREFIX} toolset including all dependencies.
@subsubsection Removing RPMs Using Yum
The following is a sample session illustrating the removal of a C/C++
toolset targeting the SPARC architecture.
@example
yum erase @value{RTEMSRPMPREFIX}-sparc-*
@end example
If this is the last target architecture for which tools are installed, then you can remove the RTEMS GNU autotools and common packages as follows:
@example
yum erase @value{RTEMSRPMPREFIX}-auto*
yum erase @value{RTEMSRPMPREFIX}-*common*
@end example
NOTE: If you have installed any RTEMS BSPs, then it is likely that RPM
will complain about not being able to remove everything. These will
have to be removed by hand.
@subsection Managing RPMs Without Using Yum
This section describes how to install and remove RTEMS Toolsets without
using Yum. This is NOT expected to be the norm for RPM users.
@subsubsection Installing RPMs Without Yum
The following is a sample session illustrating the installation of the
complete C and C++ toolset targeting the SPARC architecture for the
RTEMS @value{RTEMSAPI} Release series.
Since you are not using Yum, you will need to download all of the RPMs
you will install. Alternatively, RPM can be given a URL for an RPM file
and it will fetch it for you. Either way, the commands similar to the
following will install the common or base RPMs required.
@example
rpm -U @value{RTEMSRPMPREFIX}binutils-common-<VERSION>-<RPM>.<DIST>.noarch.rpm \
@value{RTEMSRPMPREFIX}gcc-common-<VERSION>-<RPM>.<DIST>.noarch.rpm \
@value{RTEMSRPMPREFIX}newlib-common-<VERSION>-<RPM>.<DIST>.noarch.rpm \
@value{RTEMSRPMPREFIX}gdb-common-<VERSION>-<RPM>.<DIST>.noarch.rpm
@end example
The above RPMs are shared across all RTEMS targets and include common
files such as the documentation. The following illustrates how to install
the GNU Autoconf and Automake RPMs that match your RTEMS installation.
RTEMS uses the GNU Autotools for its configure and build infrastructure
and you will need these if you modify the build infrastructure or check
out RTEMS from CVS and have to bootstrap the source tree.
@example
rpm -U @value{RTEMSRPMPREFIX}autoconf-<VERSION>-<RPM>.<DIST>.noarch.rpm \
@value{RTEMSRPMPREFIX}automake-<VERSION>-<RPM>.<DIST>.noarch.rpm
@end example
Now that you have installed all of the RPMs that are independent of the
target architecture you can install the C toolset for a specific target.
The following command will install the target architecture specific set
of the RPMs for a C toolset including GDB.
@example
rpm -U @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-binutils-<VERSION>-<RPM>.<ARCH>.rpm \
@value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-<VERSION>-<RPM>.<ARCH>.rpm \
@value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-newlib-<VERSION>-<RPM>.<ARCH>.rpm \
@value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-libgcc-<VERSION>-<RPM>.<ARCH>.rpm \
@value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gdb-<VERSION>-<RPM>.<ARCH>.rpm
@end example
The following command illustrates how to install the C++ specific portion of the RPMs.
@example
rpm -U @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-c++-<VERSION>-<RPM>.<ARCH>.rpm \
@value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-libstd++-<VERSION>-<RPM>.<ARCH>.rpm
@end example
Upon successful completion of the above command sequence, a C/C++
cross development toolset targeting the SPARC is installed in
@code{@value{RTEMSPREFIX}}. In order to use this toolset, the directory
@code{@value{RTEMSPREFIX}/bin} should be at the start of your PATH.
At this point, the tools are installed for a specific target architecture
adn you may proceed directly to @ref{Building RTEMS}.
If you want to build RTEMS for multiple target architectures, you will
need to install the target specific portion of the RPMs for each target.
@subsubsection Removing RPMs Without Using Yum
The following is a sample session illustrating the removal of a C/C++
toolset targeting the SPARC architecture.
@example
rpm -e `rpm -qa | grep @value{RTEMSRPMPREFIX}-sparc-`
@end example
If this is the last target architecture for which tools are installed, then you can remove the RTEMS GNU autotools and common packages as follows:
@example
rpm -e `rpm -qa | grep @value{RTEMSRPMPREFIX}-auto`
rpm -e `rpm -qa | grep @value{RTEMSRPMPREFIX} | grep common`
@end example
NOTE: If you have installed any RTEMS BSPs, then it is likely that RPM
will complain about not being able to remove everything. These will
have to be removed by hand.
@subsection Determining Which RTEMS RPMs are Installed
@@ -81,32 +286,14 @@ The following command will report which RTEMS RPMs are currently
installed:
@example
rpm -q -g @value{RTEMSRPMGROUP}
rpm -qa | grep @value{RTEMSAPI}
@end example
@subsection Removing RPMs
The following is a sample session illustrating the removal
of a C/C++ toolset targeting the SPARC architecture.
@example
rpm -e @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gdb
rpm -e @value{RTEMSRPMPREFIX}gdb-common
rpm -e @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-c++
rpm -e @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc
rpm -e @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-newlib
rpm -e @value{RTEMSRPMPREFIX}gcc-common
rpm -e @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-binutils
rpm -e @value{RTEMSRPMPREFIX}binutils-common
@end example
NOTE: If you have installed any RTEMS BSPs, then it is likely that
RPM will complain about not being able to remove everything.
@section Zipped Tar Files
This section provides information on installing and removing
Zipped Tar Files (e.g .tar.gz or .tar.bz2).
The tool binaries for some hosts are provided as compressed tar files.
This section provides information on installing and removing Zipped Tar
Files (e.g .tar.gz or .tar.bz2).
@subsection Installing Zipped Tar Files
@@ -117,13 +304,13 @@ files compressed with GNU Zip (gzip):
@example
cd /
tar xzf @value{RTEMSRPMPREFIX}binutils-common-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.tar.gz
tar xzf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.tar.gz
tar xzf @value{RTEMSRPMPREFIX}gcc-common-@value{GCCVERSION}-@value{GCCRPMRELEASE}.tar.gz
tar xzf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-@value{GCCVERSION}-@value{GCCRPMRELEASE}.tar.gz
tar xzf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-newlib-@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.tar.gz
tar xzf @value{RTEMSRPMPREFIX}gdb-common-@value{GDBVERSION}-@value{GDBRPMRELEASE}.tar.gz
tar xzf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.tar.gz
tar xzf @value{RTEMSRPMPREFIX}binutils-common-<VERSION>-<RPM>.tar.gz
tar xzf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-binutils-<VERSION>-<RPM>.tar.gz
tar xzf @value{RTEMSRPMPREFIX}gcc-common-<VERSION>-<RPM>.tar.gz
tar xzf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-<VERSION>-<RPM>.tar.gz
tar xzf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-newlib-<VERSION>-<RPM>.tar.gz
tar xzf @value{RTEMSRPMPREFIX}gdb-common-<VERSION>-<RPM>.tar.gz
tar xzf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gdb-<VERSION>-<RPM>.tar.gz
@end example
The following command set is the equivalent command sequence
@@ -132,13 +319,13 @@ GNU BZip (bzip2):
@example
cd /
tar xjf @value{RTEMSRPMPREFIX}binutils-common-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.tar.bz2
tar xjf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.tar.bz2
tar xjf @value{RTEMSRPMPREFIX}gcc-common-@value{GCCVERSION}-@value{GCCRPMRELEASE}.tar.bz2
tar xjf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-newlib-@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.tar.bz2
tar xjf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-@value{GCCVERSION}-@value{GCCRPMRELEASE}.tar.bz2
tar xjf @value{RTEMSRPMPREFIX}gdb-common-@value{GDBVERSION}-@value{GDBRPMRELEASE}.tar.bz2
tar xjf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.tar.bz2
tar xjf @value{RTEMSRPMPREFIX}binutils-common-<VERSION>-<RPM>.tar.bz2
tar xjf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-binutils-<VERSION>-<RPM>.tar.bz2
tar xjf @value{RTEMSRPMPREFIX}gcc-common-<VERSION>-<RPM>.tar.bz2
tar xjf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-newlib-<VERSION>-<RPM>.tar.bz2
tar xjf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gcc-<VERSION>-<RPM>.tar.bz2
tar xjf @value{RTEMSRPMPREFIX}gdb-common-<VERSION>-<RPM>.tar.bz2
tar xjf @value{RTEMSRPMPREFIX}sparc-rtems@value{RTEMSAPI}-gdb-<VERSION>-<RPM>.tar.bz2
@end example
Upon successful completion of the above command sequence, a

1102
doc/started/buildc.t
View File

File diff suppressed because it is too large Load Diff

132
doc/started/buildrt.t
View File

@@ -1,6 +1,5 @@
@c
@c
@c COPYRIGHT (c) 1988-2002.
@c COPYRIGHT (c) 1988-2010.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@@ -11,25 +10,23 @@
@section Obtain the RTEMS Source Code
This section provides pointers to the RTEMS source code and
Hello World example program. These files should be
placed in your @code{archive} directory.
This section provides pointers to the RTEMS source code and example
programs. These files should be placed in your @code{archive} directory.
The set of tarballs which comprise an RTEMS release is placed in a
directory whose name if the release on the ftp site. The RTEMS ftp site
is accessible via both the ftp and http protocols at the following URLs:
@subheading @value{RTEMSVERSION}
@example
FTP Site: @value{RTEMSFTPSITE}
Directory: @value{RTEMSFTPDIR}/@value{VERSION}
File: @value{RTEMSTAR}
URL: @uref{ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/@value{VERSION}/@value{RTEMSTAR},,ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/@value{VERSION}/@value{RTEMSTAR}}
@end example
@itemize @bullet
@item @uref{http://www.rtems.org/ftp/pub/rtems,http://www.rtems.org/ftp/pub/rtems}
@item @uref{ftp://www.rtems.org/pub/rtems,ftp://www.rtems.org/pub/rtems}
@end itemize
@subheading RTEMS Examples including Hello World
@example
FTP Site: @value{RTEMSFTPSITE}
Directory: @value{RTEMSFTPDIR}/@value{VERSION}
File: examples-@value{VERSION}.tar.bz2
URL: @uref{ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/@value{VERSION}/examples-@value{VERSION}.tar.bz2,,ftp://@value{RTEMSFTPSITE}@value{RTEMSFTPDIR}/@value{VERSION}/examples-@value{VERSION}.tar.bz2}
@end example
Associated with each RTEMS Release is a set of example programs.
Prior to the 4.10 Release Series, these examples were in a "Class
Examples" and an "Examples" collection. Beginning with the 4.10 Release
Series, these examples collections were merged and other examples added.
This new collection is called "Examples V2". It is contained in the file
@code{examples-v2-<VERSION>.tar.bz2>} within the RTEMS release directory.
@c
@c Unarchive the RTEMS Source
@@ -42,28 +39,29 @@ tools directory:
@example
cd tools
tar xjf ../archive/@value{RTEMSTAR}
tar xjf ../archive/rtems-@value{RTEMSAPI}.<VERSION>.tar.bz2
@end example
This creates the directory @value{RTEMSUNTAR}.
This creates the directory rtems-@value{RTEMSAPI}.<VERSION>
@section Add <INSTALL_POINT>/bin to Executable PATH
In order to compile RTEMS, you must have the cross compilation toolset
in your search path. It is important to have the RTEMS toolset first
in your path to ensure that you are using the intended version of all
tools. The following command prepends the directory
where the tools were installed in a previous step:
tools. The following command prepends the directory where
the tools were installed in a previous step. If you are using
binaries provided by the RTEMS Project, the <INSTALL_POINT> will be
@code{/opt/rtems-@value{RTEMSAPI}}
@example
export PATH=<INSTALL_POINT>/bin:$@{PATH@}
@end example
NOTE: The above command is in Bourne shell (@code{sh}) syntax and
should work with the Korn (@code{ksh}) and GNU Bourne Again Shell
(@code{bash}). It will not work with the C Shell (@code{csh}) or
derivatives of the C Shell.
@b{NOTE:} The above command is in Bourne shell (@code{sh}) syntax and should
work with the Korn (@code{ksh}) and GNU Bourne Again Shell (@code{bash}).
It will not work with the C Shell (@code{csh}) or derivatives of the
C Shell.
@section Verifying the Operation of the Cross Toolset
@@ -83,14 +81,14 @@ int f( int x )
Then assemble the file using a command similar to the following:
@example
m68k-rtems-gcc -v -S f.c
m68k-rtems@value{RTEMSAPI}-gcc -v -S f.c
@end example
Where @code{m68k-rtems-gcc} should be changed to match the installed
name of your cross compiler. The result of this command will be
a sequence of output showing where the cross-compiler searched for
and found its subcomponents. Verify that these paths correspond
to your <INSTALL_POINT>.
Where @code{m68k} should be changed to match the target architecture
of your cross compiler. The result of this command will be a sequence
of output showing where the cross-compiler searched for and found
its subcomponents. Verify that these paths correspond to your
<INSTALL_POINT>.
Look at the created file @code{f.s} and verify that it is in fact
for your target processor.
@@ -99,17 +97,16 @@ Then try to compile the file @code{f.c} directly to object code
using a command like the following:
@example
m68k-rtems-gcc -v -c f.c
m68k-rtems@code{RTEMSAPI}-gcc -v -c f.c
@end example
If this produces messages that indicate the assembly code is
not valid, then it is likely that you have fallen victim to
one of the problems described in
@ref{Error Message Indicates Invalid Option to Assembler}
Don't feel bad about this, one of the most common installation errors
is for the cross-compiler not to be able to find the cross assembler
and default to using the native @code{as}. This can result in very confusing
error messages.
If this produces messages that indicate the assembly code is not valid,
then it is likely that you have fallen victim to one of the problems
described in @ref{Error Message Indicates Invalid Option to Assembler}
Please do not feel bad about this and do not give up, one of the most
common installation errors is for the cross-compiler not to be able
to find the cross assembler and default to using the native @code{as}.
This can result in very confusing error messages.
@section Building RTEMS for a Specific Target and BSP
@@ -130,19 +127,20 @@ This section describes how to build RTEMS.
@subsection Using the RTEMS configure Script Directly
Make a build directory under tools and build the RTEMS product in this
directory. The @code{../@value{RTEMSUNTAR}/configure}
command has numerous command line
arguments. These arguments are discussed in detail in documentation that
comes with the RTEMS distribution. A full list of these arguments can be
obtained by running @code{../@value{RTEMSUNTAR}/configure --help}
If you followed the procedure
described in the section @ref{Unarchive the RTEMS Source}, these
configuration options can be found in the file
tools/@value{RTEMSUNTAR}/README.configure.
directory. The @code{../rtems-@value{RTEMSAPI}.<VERSION>/configure}
command has numerous command line arguments. These arguments are
discussed in detail in documentation that comes with the RTEMS
distribution. A full list of these arguments can be obtained by running
@code{../rtems-@value{RTEMSAPI}.<VERSION>/configure --help} If you
followed the procedure described in the section @ref{Unarchive the
RTEMS Source}, these configuration options can be found in the file
tools/rtems-@value{RTEMSAPI}.<VERSION>/README.configure.
@b{NOTE}: The GNAT/RTEMS run-time implementation is based on the POSIX
API. Thus the RTEMS configuration for a GNAT/RTEMS environment MUST
include the @code{--enable-posix} flag.
API and the GNAT/RTEMS run-time cannot be compiled with networking
disabled. Your application does not have to use networking but it must
be enabled. Thus the RTEMS configuration for a GNAT/RTEMS environment
MUST include the @code{--enable-posix --enable-networking} flag.
The following shows the command sequence required to configure,
compile, and install RTEMS with the POSIX API, FreeBSD TCP/IP,
@@ -152,26 +150,26 @@ the @code{BOARD_SUPPORT_PACKAGE} board.
@example
mkdir build-rtems
cd build-rtems
../@value{RTEMSUNTAR}/configure --target=<TARGET_CONFIGURATION> \
../rtems-@value{RTEMSAPI}.VERSION/configure --target=<TARGET_CONFIGURATION> \
--disable-posix --disable-networking --disable-cxx \
--enable-rtemsbsp=<BOARD_SUPPORT_PACKAGE>\
--enable-rtemsbsp=<BSP>\
--prefix=<INSTALL_POINT>
make all install
@end example
Where the list of currently supported <TARGET_CONFIGURATION>'s and
<BOARD_SUPPORT_PACKAGE>'s can be found in
tools/@value{RTEMSUNTAR}/README.configure.
<TARGET> is of the form <CPU>-rtems@value{RTEMSAPI} and the list of
currently supported <TARGET> configuration's and <BSP>'s can be found in
@code{tools/RTEMS-@value{RTEMSAPI}.<VERSION>/README.configure}.
<INSTALL_POINT> is typically the installation point for the
tools and defaults to @code{@value{RTEMSPREFIX}}.
<INSTALL_POINT> is typically the installation point for the tools and
defaults to @code{/opt/rtems-@value{RTEMSAPI}}.
BSP is a supported BSP for the selected CPU family. The list of
supported BSPs may be found in the file
tools/@value{RTEMSUNTAR}/README.configure
in the RTEMS source tree. If the BSP parameter is not specified,
then all supported BSPs for the selected CPU family will be built.
BSP is a supported BSP for the selected CPU family.
The list of supported BSPs may be found in the file
@code{tools/rtems-@value{RTEMSAPI}.<VERSION>/README.configure} in the
RTEMS source tree. If the BSP parameter is not specified, then all
supported BSPs for the selected CPU family will be built.
@b{NOTE:} The POSIX API must be enabled to use GNAT/RTEMS.
@b{NOTE:} The POSIX API and networking must be enabled to use GNAT/RTEMS.
@b{NOTE:} The @code{make} utility used should be GNU make.

34
doc/started/intro.t
View File

@@ -1,5 +1,5 @@
@c
@c COPYRIGHT (c) 1988-2002.
@c COPYRIGHT (c) 1988-2010.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@@ -18,7 +18,7 @@ essentials for performing a setup of the following items:
@itemize @bullet
@item GNU Cross Compilation Tools for RTEMS on your build-host system
@item RTEMS OS for the target
@item GDB Debugger
@item GNU Debugger (GDB)
@end itemize
The remainder of this chapter provides background information on real-time
@@ -159,31 +159,17 @@ http://www.gnu.org/manual/manual.html}
@uref{mailto:@value{RTEMSUSERS},@value{RTEMSUSERS}}
This mailing list is dedicated to the discussion of issues related
to RTEMS, including GNAT/RTEMS. If you have questions about RTEMS,
wish to make suggestions, or just want to pick up hints, this is a
good list to monitor. Subscribe by sending an empty mail message to
@uref{mailto:@value{RTEMSUSERSSUBSCRIBE},@value{RTEMSUSERSSUBSCRIBE}}.
Messages sent to @uref{mailto:@value{RTEMSUSERS},@value{RTEMSUSERS}}
are posted to the list.
@subsection CrossGCC Mailing List
@uref{mailto:crossgcc@@sources.redhat.com,crossgcc@@sources.redhat.com}
This mailing list is dedicated to the use of the GNU tools in
cross development environments. Most of the discussions
focus on embedded issues. Information on subscribing
to this mailing list is included in the
@uref{http://www.objsw.com/CrossGCC/,CrossGCC FAQ}.
The CrossGCC FAQ and Wiki are are available
at @uref{http://www.billgatliff.com,http://www.billgatliff.com}.
This is the primary mailing list for the discussion of issues
related to RTEMS, including GNAT/RTEMS. If you have questions
about RTEMS, wish to make suggestions, track development efforts,
or just want to pick up hints, this is a good list to monitor.
If you would like to browse the thousands of messages in the fifteen
year archive of the mailing list or subscribe to it, please visit
@uref{http://www.rtems.org/mailman,http://www.rtems.org/mailman} for
more information,
@subsection GCC Mailing Lists
The GCC Project is hosted at @uref{http://gcc.gnu.org,http://gcc.gnu.org}.
They maintain multiple mailing lists that are described at the web site
along with subscription information.

156
doc/started/nextstep.t
View File

@@ -1,6 +1,5 @@
@c
@c
@c COPYRIGHT (c) 1988-2002.
@c COPYRIGHT (c) 1988-2010.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@@ -9,77 +8,70 @@
@chapter Where To Go From Here
At this point, you should have successfully installed a
GNU Cross Compilation Tools for RTEMS on your host system
as well as the RTEMS OS for the target host. You should
have successfully linked the "hello world" program. You
may even have downloaded the executable to that target
and run it. What do you do next?
At this point, you should have successfully installed a GNU Cross
Compilation Tools for RTEMS on your host system as well as the RTEMS OS
for the target host. You should have successfully linked the "hello
world" program. You may even have downloaded the executable to that
target and run it. What do you do next?
The answer is that it depends. You may be interested in
writing an application that uses one of the multiple
APIs supported by RTEMS. You may need to investigate the
network or filesystem support in RTEMS. The common
thread is that you are largely finished with this
manual and ready to move on to others.
The answer is that it depends. You may be interested in writing an
application that uses one of the multiple APIs supported by RTEMS.
You may need to investigate the network or filesystem support in RTEMS.
The common thread is that you are largely finished with this manual and
ready to move on to others.
Whether or not you decide to dive in now and write
application code or read some documentation first,
this chapter is for you. The first section provides
a quick roadmap of some of the RTEMS documentation.
The next section provides a brief overview of the
RTEMS application structure.
Whether or not you decide to dive in now and write application code or
read some documentation first, this chapter is for you. The first section
provides a quick roadmap of some of the RTEMS documentation. The next
section provides a brief overview of the RTEMS application structure.
@section Documentation Overview
When writing RTEMS applications, you should find the
following manuals useful because they define the
calling interface to many of the services provided
by RTEMS:
When writing RTEMS applications, you should find the following manuals
useful because they define the calling interface to many of the services
provided by RTEMS:
@itemize @bullet
@item @b{RTEMS Applications C User's Guide} describes the
Classic RTEMS API based on the RTEID specification.
@item @b{RTEMS POSIX API User's Guide} describes the
RTEMS POSIX API that is based on the POSIX 1003.1b API.
@item @b{RTEMS POSIX API User's Guide} describes the RTEMS POSIX API
that is based on the POSIX 1003.1b API. If there is any place where
this manual is thin or unclear, please refer to the OpenGroup Single
UNIX Specification. RETEMS tracks that specification for future POSIX
revisions.
@item @b{RTEMS ITRON 3.0 API User's Guide} describes
the RTEMS implementation of the ITRON 3.0 API.
@item @b{RTEMS Network Supplement} provides information
on the network services provided by RTEMS.
@item @b{RTEMS Network Supplement} provides information on the network
services provided by RTEMS. RTEMS provides a BSD sockets programming
interface so any network programming book should be helpful.
@end itemize
In addition, the following manuals from the GNU Cross
Compilation Toolset include information on run-time services
available.
In addition, the following manuals from the GNU Cross Compilation Toolset
include information on run-time services available.
@itemize @bullet
@item @b{Cygnus C Support Library} describes the Standard
C Library functionality provided by Newlib's libc.
@item @b{Cygnus C Support Library} describes the Standard C Library
functionality provided by Newlib's libc.
@item @b{Cygnus C Math Library} describes the Standard
C Math Library functionality provided by Newlib's libm.
@item @b{Cygnus C Math Library} describes the Standard C Math Library
functionality provided by Newlib's libm.
@end itemize
Finally, the RTEMS FAQ and mailing list archives are available
at @uref{@value{RTEMSHTTPURL}}.
Finally, the RTEMS FAQ, Wiki, and mailing list archives are available
at @uref{http://www.rtems.org, http://www.rtems.org}.
There is a wealth of documentation available for RTEMS and
the GNU tools supporting it. If you run into something
that is not clear or missing, bring it to our attention.
There is a wealth of documentation available for RTEMS and the GNU tools
supporting it. If you run into something that is not clear or missing,
bring it to our attention.
Also, some of the RTEMS documentation is still under
construction. If you would like to contribute to this
effort, please contact the RTEMS Team at
@uref{mailto:@value{RTEMSUSERS}, @value{RTEMSUSERS}}.
If you are interested in sponsoring the development of a new
feature, BSP, device driver, port of an existing library, etc.,
please contact one of the RTEMS Service Providers listed
at @uref{@value{RTEMSHTTPURL}/support.html,@value{RTEMSHTTPURL}/support.html}.
Also, some of the RTEMS documentation is still under construction.
If you would like to contribute to this effort, please contact the
RTEMS Team at @uref{mailto:@value{RTEMSUSERS}, @value{RTEMSUSERS}}.
If you are interested in sponsoring the development of a new feature,
BSP, device driver, port of an existing library, etc., please contact
@uref{mailto:sales@@oarcorp.com, sales@@oarcorp.com}.
@section Writing an Application
@@ -89,36 +81,30 @@ RTEMS provides a single process, multi-threaded run-time
environment. However there are two important things that are
different from a standard UNIX hosted program.
First, the application developer must provide configuration
information for RTEMS. This configuration information
includes limits on the maximum number of various OS resources
available and networking configuration among other things.
See the @b{Configuring a System} in the
@b{RTEMS Applications C User's Guide} for more details.
First, the application developer must provide configuration information
for RTEMS. This configuration information includes limits on the maximum
number of various OS resources available and networking configuration
among other things. See the @b{Configuring a System} in the @b{RTEMS
Applications C User's Guide} for more details.
Second, RTEMS applications may or may not start at
@code{main()}. Applications begin execution at
one or more user configurable application
initialization tasks or threads. It is possible
to configure an application to start with a
single thread that whose entry point is @code{main()}.
Second, RTEMS applications may or may not start at @code{main()}.
Applications begin execution at one or more user configurable application
initialization tasks or threads. It is possible to configure an
application to start with a single thread that whose entry point is
@code{main()}.
Each API supported by RTEMS (Classic, POSIX, and ITRON)
allows the user to configure a set of one or more tasks
that are created and started automatically
during RTEMS initialization. The RTEMS Automatic
Configuration Generation (@code{confdefs.h}) scheme can be
used to easily generate the configuration information for
an application that starts with a single initialization task.
By convention, unless overridden, the default name of the
initialization task varies based up API.
Each API supported by RTEMS (Internal, Classic, and POSIX) allows
the user to configure a set of one or more tasks that are created and
started automatically during RTEMS initialization. The RTEMS Automatic
Configuration Generation (@code{confdefs.h}) scheme can be used to easily
generate the configuration information for an application that starts
with a single initialization task. By convention, unless overridden,
the default name of the initialization task varies based up API.
@itemize @bullet
@item @code{Init} - single Classic API Initialization Task
@item @code{POSIX_Init} - single POSIX API Initialization Thread
@item @code{ITRON_Init} - single ITRON API Initialization Task
@end itemize
Regardless of the API used, when the initialization task executes,
@@ -134,17 +120,15 @@ file @code{init.c} usually contains the initialization task. Although
not required, in most of the examples, the initialization task
completes by deleting itself.
As you begin to write RTEMS application code, you may be confused
by the range of alternatives. Supporting multiple tasking
APIs can make the choices confusing. Many application groups
writing new code choose one of the APIs as their primary API
and only use services from the others if nothing comparable
is in their preferred one. However, the support for multiple
APIs is a powerful feature when integrating code from multiple
sources. You can write new code using POSIX services and
still use services written in terms of the other APIs.
Moreover, by adding support for yet another API, one could
provide the infrastructure required to migrate from a
legacy RTOS with a non-standard API to an API like POSIX.
As you begin to write RTEMS application code, you may be confused by the
range of alternatives. Supporting multiple tasking APIs can make the
choices confusing. Many application groups writing new code choose one
of the APIs as their primary API and only use services from the others if
nothing comparable is in their preferred one. However, the support for
multiple APIs is a powerful feature when integrating code from multiple
sources. You can write new code using POSIX services and still use
services written in terms of the other APIs. Moreover, by adding support
for yet another API, one could provide the infrastructure required to
migrate from a legacy RTOS with a non-standard API to an API like POSIX.

103
doc/started/nt.t
View File

@@ -1,5 +1,5 @@
@c
@c COPYRIGHT (c) 1988-2002.
@c COPYRIGHT (c) 1988-2010.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@@ -15,31 +15,24 @@ This chapter was originally written by
@uref{mailto:g_montel@@yahoo.com, Geoffroy Montel <g_montel@@yahoo.com>}
with input from
@uref{mailto:<D.J@@fiddes.surfaid.org>, David Fiddes <D.J@@fiddes.surfaid.org>}.
It was based upon his successful but unnecessarily
painful efforts with Cygwin beta versions.
Cygwin and this chapter have been updated multiple times since
those early days although their pioneering efforts
and input is still greatly appreciated.
It was based upon his successful but unnecessarily painful efforts with
Cygwin beta versions. Cygwin and this chapter have been updated multiple
times since those early days although their pioneering efforts and input
is still greatly appreciated.
@section Microsoft Windows Version Requirements
RTEMS users report fewer problems when using Microsoft
Windows NT, 2000, or XP. Although, the open source tools
that are used in RTEMS development do execute on Windows 95,
98, or ME, they tend to be more stable when used with
the modern Windows variants.
RTEMS users report fewer problems when using Microsoft Windows XP or newer.
@section Cygwin
For RTEMS development, the recommended approach is to use
Cygwin 1.0 or later. Cygwin is available from
@uref{http://sources.redhat.com/cygwin, http://sources.redhat.com/cygwin}
Recent versions of Cygwin are vastly improved over the beta
versions. Most of the oddities, instabilities, and performance
problems have been resolved. The installation procedure
is much simpler. However, there are a handful of issues
that remain to successfully use Cygwin as an RTEMS development
environment.
For RTEMS development, the recommended approach is to use Cygwin. Cygwin
is available from @uref{http://www.cygwin.com, http://www.cygwin.com} .
The primary issues reported by users of Cygwin is that it is slower
on the same hardware than a native GNU/Linux installation and strange
issues over carriage return/line feed inconsistencies between UNIX and
Windows environments. However, there are a handful of other issues that
may turn up when using Cygwin as an RTEMS development environment.
@itemize @bullet
@@ -79,18 +72,17 @@ shell scripts properly.
filesystem (e.g. mounted with the @code{-b} option). Otherwise,
many confusing errors will result.
@item A user has reported that they needed
to set CYGWIN=ntsec for chmod to work correctly, but had to set
CYGWIN=nontsec for compile to work properly (otherwise there were
complaints about permissions on a temporary file).
@item A user has reported that they needed to set @code{CYGWIN=ntsec}
for chmod to work correctly, but had to set @code{CYGWIN=nontsec}
for compile to work properly (otherwise there were complaints about
permissions on a temporary file).
@item If you want to build the tools from source, you have the
same options as UNIX users.
@item You may have to uncompress archives during this
process. You must @b{NOT} use @code{WinZip} or
@code{PKZip}. Instead the un-archiving process uses
the GNU @code{zip} and @code{tar} programs as shown below:
@item You may have to uncompress archives during this process. You must
@b{NOT} use @code{WinZip} or @code{PKZip}. Instead the un-archiving
process uses the GNU @code{zip} and @code{tar} programs as shown below:
@example
tar -xzvf archive.tgz
@@ -102,20 +94,18 @@ tar -xzvf archive.tgz
@section Text Editor
You absolutely have to use a text editor which can
save files with Unix format. So do @b{NOT} use Notepad
or Wordpad! There are a number of editors
freely available that can be used.
You absolutely have to use a text editor which can save files with Unix
format. So do @b{NOT} use Notepad or Wordpad! There are a number of
editors freely available that can be used.
@itemize @bullet
@item @b{VIM} (@b{Vi IMproved}) is available from
@uref{http://www.vim.org/,http://www.vim.org/}.
This editor has the very handy ability to easily
read and write files in either DOS or UNIX style.
@uref{http://www.vim.org/,http://www.vim.org/}. This editor has the very
handy ability to easily read and write files in either DOS or UNIX style.
@item @b{GNU Emacs} is available for many platforms
including MS-Windows. The official homepage
is @uref{http://www.gnu.org/software/emacs/emacs.html,
including MS-Windows. The official homepage is
@uref{http://www.gnu.org/software/emacs/emacs.html,
http://www.gnu.org/software/emacs/emacs.html}.
The GNU Emacs on Windows NT and Windows 95/98 FAQ is at
@uref{http://www.gnu.org/software/emacs/windows/ntemacs.html,
@@ -123,11 +113,10 @@ http://www.gnu.org/software/emacs/windows/ntemacs.html}.
@end itemize
If you do accidentally end up with files
having MS-DOS style line termination, then you
may have to convert them to Unix format for some
Cygwin programs to operate on them properly. The
program @code{dos2unix} can be used to put them
If you do accidentally end up with files having MS-DOS style line
termination, then you may have to convert them to Unix format for some
Cygwin programs to operate on them properly. The program @code{dos2unix}
can be used to put them
back into Unix format as shown below:
@example
@@ -137,22 +126,16 @@ Dos2Unix: Cleaning file XYZ ...
@section System Requirements
Although the finished cross-compiler is fairly easy on resources,
building it can take a significant amount of processing power and
disk space.
@itemize @bullet
@item The faster the CPU, the better. The tools and Cygwin can be
@b{very} CPU hungry.
@item The more RAM, the better. Reports are that when building GCC
and GDB, peak memory usage can exceed 256 megabytes.
@item The more disk space, the better. You need more if you are building
the GNU tools and the amount of disk space for binaries is obviously
directly dependent upon the number of CPUs you have cross toolsets
installed for.
@end itemize
Although the finished cross-compiler is fairly easy on resources, building
it can take a significant amount of processing power and disk space.
Luckily, desktop computers have progressed very far since this guide
was originally written so it is unlikely you will have any problems.
Just do not use an old cast-off machine with < 1 GB RAM and a 1 Ghz CPU.
Unless, of course, you enjoy waiting for things to complete.
The more disk space, the better. You need more if you are building the
GNU tools and the amount of disk space for binaries is obviously directly
dependent upon the number of CPUs you have cross toolsets installed for.
In addition to the disk space requirements documented earlier for tool
building, you will also have to have enough space to install the Cygwin
environment.

113
doc/started/require.t
View File

@@ -1,5 +1,5 @@
@c
@c COPYRIGHT (c) 1988-2002.
@c COPYRIGHT (c) 1988-2010.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@@ -21,19 +21,18 @@ assessing the amount of disk space required for your installation:
+------------------------------------+--------------------------+
| Component | Disk Space Required |
+------------------------------------+--------------------------+
| archive directory | 55 Mbytes |
| tools src unarchived | 350 Mbytes |
| each individual build directory | up to 750 Mbytes |
| each installation directory | 20-200 Mbytes |
| archive directory | 120 Mbytes |
| tools src unarchived | 1400 Mbytes |
| each individual build directory | up to 2500 Mbytes |
| each installation directory | 900 Mbytes |
+------------------------------------+--------------------------+
@end example
It is important to understand that the above requirements only address
the GNU C/C++ Cross Compiler Tools themselves. Adding additional
languages such as Fortran or Objective-C can increase the size
of the build and installation directories. Also, the unarchived
source and build directories can be removed after the tools are
installed.
It is important to understand that the above requirements only address the
GNU C/C++ Cross Compiler Tools themselves. Adding additional languages
such as Ada or Go can increase the size of the build and installation
directories. Also, the unarchived source and build directories can be
removed after the tools are installed.
After the tools themselves are installed, RTEMS must be built
and installed for each Board Support Package that you wish
@@ -46,8 +45,11 @@ will tend to be in the 40-60 Mbyte range.
There are a number of factors which must be taken into
account in order to estimate the amount of disk space required
to build RTEMS itself. Attempting to build multiple BSPs in
a single step increases the disk space requirements. Similarly
enabling optional features increases the build and install
a single step increases the disk space requirements. One some
target architectures, this can lead to disk usage during the build
of over one gigabyte.
Similarly enabling optional features increases the build and install
space requirements. In particular, enabling and building
the RTEMS tests results in a significant increase in build
space requirements but since the tests are not installed has,
@@ -56,8 +58,9 @@ enabling them has no impact on installation requirements.
@section General Host Software Requirements
The instructions in this manual should work on any computer running
a UNIX variant. Some native GNU tools are used by this procedure
including:
a POSIX environment including GNU/Linux and Cygwin. Mingw users may
encounter additional issues due to the limited POSIX compatibility.
Some native GNU tools are used by this procedure including:
@itemize @bullet
@item GCC
@@ -65,8 +68,10 @@ including:
@item GNU makeinfo
@end itemize
In addition, some native utilities may be deficient for building
the GNU tools.
In addition, some native utilities may be deficient for building the
GNU tools. On hosts which have m4 but it is not GNU m4, it is not
uncommon to have to install GNU m4. Similarly, some shells are not
capable of fully supporting the RTEMS configure scripts.
@subsection GCC
@@ -129,9 +134,10 @@ are on a Solaris 2.x host, then use the @code{/bin/ksh} or
@end itemize
@subsection Linux
@subsection Distribution Independent Potential GNU/Linux Issues
The following problems have been reported by Linux users:
The following problems have been reported by users of various GNU/Linux
distributions:
@itemize @bullet
@@ -149,71 +155,10 @@ to at least GNU fileutils version 3.16 to resolve this problem.
@end itemize
@section Archive and Build Directories
@subsection GNU/Linux Distrobutions using Debian Packaging Format
If you are using RPM or another packaging format that supports
building a package from source, then there is probably a directory
structure assumed by that packaging format. Otherwise, you
are free to use whatever organization you like. However, this
document will use the directory organization described
in @ref{Archive and Build Directory Format}.
@subsection RPM Archive and Build Directory Format
For RPM, it is assumed that the following subdirectories
are under a root directory such as @code{/usr/src/redhat}:
@example
BUILD
RPMS
SOURCES
SPECS
SRPMS
@end example
For the purposes of this document, the RPM @code{SOURCES} directory
is the directory into which all tool source and patches are
assumed to reside. The @code{BUILD} directory is where the actual
build is performed when building binaries from a source RPM.
The @code{SOURCES} and @code{BUILD} are logically equivalent to
the @code{archive} and @code{tools} directory discussed in the
next section.
@subsection Archive and Build Directory Format
When no packaging format requirements are present, the root directory for
the storage of source archives and patches as well as for building the
tools is up to the user. The only concern is that there be enough
disk space to complete the build. In this document, the following
organization will be used.
Make an @code{archive} directory to contain the downloaded
source code and a @code{tools} directory to be used as a build
directory. The command sequence to do this is shown
below:
@example
mkdir archive
mkdir tools
@end example
This will result in an initial directory structure similar to the
one shown in the following figure:
@example
@group
/whatever/prefix/you/choose/
archive/
tools/
@end group
@end example
@c @ifset use-html
@c @html
@c <IMG SRC="sfile12c.jpg" WIDTH=417 HEIGHT=178
@c ALT="Starting Directory Organization">
@c @end html
@c @end ifset
The RTEMS Project does not currently provide prebuilt toolsets in the Debian packaging format used by the Debian and Ubuntu distributions. If you are using a distribution using this packaging format, then you have two options for installing the RTEMS toolset.
The first option is to build the toolset from source following the instructions in the @ref{Building the GNU Cross Compiler Toolset}. This is an approach taken by many users.
Alternatively, it is often possible to extract the contents of the RPM files which contain the portions of the toolset you require. In this case, you will follow the instructions in @ref{Locating the RPMs for your GNU/Linux Distribution} but assume your distribution is the RedHat Enterprise Linux version which is closest to yours from a shared library perspective. As of December 2010, this is usually RedHat Enterprise Linux version 5. As time passes, it is expected that version 6 will be appropriate in more cases. You will extract the contents of these RPM files using either @code{rpm2cpio} and install them or you may be able to use the @code{alien} tool to convert them to Debian packaging.

82
doc/started/sample.t
View File

@@ -1,5 +1,5 @@
@c
@c COPYRIGHT (c) 1988-2002.
@c COPYRIGHT (c) 1988-2010.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@@ -52,7 +52,7 @@ to your target board and executed is very dependent
on the board you are using. The following is a list of
commonly used BSPs classified by their RTEMS CPU family and pointers
to instructions on how to use them. [NOTE: All file names should be
prepended with @value{RTEMSUNTAR}/c/src/lib/libbsp.]
prepended with @code{rtems-@value{RTEMSAPI}.<VERSION>/c/src/lib/libbsp}.]
@need 1000
@table @b
@@ -147,31 +147,11 @@ the following to unarchive the sample applications:
@example
cd tools
tar xjf ../archive/examples-VERSION.tgz
tar xjf ../archive/examples-v2-@value{RTEMSAPI}.<VERSION>.tgz
@end example
The sample applications most likely to be of interest to you are:
@itemize @bullet
@item hello_world_c - C Hello World application with a simple
RTEMS configuration and an entry point not called @code{main()}.
@item simple_main - Very simple program starting at @code{main()}
and shutting down RTEMS via @code{exit()} without any other operations.
It uses the default configuration inside RTEMS which is only
intended to satisfy @code{autoconf} probes and extremely simple
console-based applications.
@item libcpp - Simple C++ library for RTEMS showing how to build an
application library written in C++.
@item psx_sched_report - POSIX Scheduler Reporter is a program
that prints out some scheduler attributes of the RTEMS POSIX API.
@end itemize
Each tests is found in a separate subdirectory and built using the
same command sequence. The @code{hello_world_c} sample will be used
Each tests is found in a separate subdirectory and built using the same
command sequence. The @code{hello/hello_world_c} sample will be used
as an example.
@c
@@ -192,25 +172,24 @@ If the sample application has successfully been built, then the application
executable is placed in the following directory:
@example
hello_world_c/o-optimize/<filename>.exe
hello_world_c/o-optimize/<filename>.ralf
@end example
The other C/C++ sample applications are built using a similar procedure.
The other sample applications are built using a similar procedure.
@c
@c Ada Sample Applications
@c
@section Ada Sample Applications
The Ada sample application set primarily includes a
a simple Hello World Ada program which can be used
as a starting point for GNAT/RTEMS applications.
Use the following command to unarchive the Ada sample
The Ada sample application set primarily includes a a simple Hello
World Ada program which can be used as a starting point for GNAT/RTEMS
applications. Use the following command to unarchive the Ada sample
applications:
@example
cd tools
tar xjf ../archive/ada-examples-@value{VERSION}.tar.bz2
tar xjf ../archive/ada-examples-@value{RTEMSAPI}.<VERSION>.tgz
@end example
@subheading Create a BSP Specific Makefile
@@ -219,11 +198,7 @@ Currently, the procedure for building and linking an Ada application
is a bit more difficult than a C or C++ application. This is certainly
an opportunity for a volunteer project.
At this time, there is a
Provided are example Makefiles for multiple BSPs. Copy one of these to
the file Makefile.<BOARD_SUPPORT_PACKAGE> and edit it as appropriate for
your local configuration.
If your BSP requires special arguments when linking, you may have to augment the file @code{ada-examples-@value{RTEMSAPI}.<VERSION>/Makefile.shared}. Most RTEMS BSPs do not require special linking arguments so this should not be frequently needed.
Use the <INSTALLATION_POINT> and <BOARD_SUPPORT_PACKAGE> specified when
configuring and installing RTEMS.
@@ -233,18 +208,13 @@ configuring and installing RTEMS.
Use the following command to start the build of the sample application:
@example
cd tools/hello_world_ada
make -f Makefile.<BOARD_SUPPORT_PACKAGE>
cd tools/ada-examples-@value{RTEMSAPI}.<VERSION>/ada-examples/hello_world_ada
@end example
NOTE: GNU make is the preferred @code{make} utility. Other @code{make}
implementations may work but all testing is done with GNU make.
If the BSP specific modifications to the Makefile were correct and
no errors are detected during the sample application build, it is
If no errors are detected during the sample application build, it is
reasonable to assume that the build of the GNAT/RTEMS Cross Compiler Tools
for RTEMS and RTEMS itself for the selected host and target
combination was done properly.
for RTEMS and RTEMS itself for the selected host and target combination
was done properly.
@section Application Executable
@@ -252,7 +222,7 @@ If the sample application has successfully been build, then the application
executable is placed in the following directory:
@example
tools/hello_world_ada/o-optimize/<filename>.exe
tools/@code{ada-examples-@value{RTEMSAPI}.<VERSION>}/hello_world_ada/o-optimize/<filename>.exe
@end example
How this executable is downloaded to the target board is very dependent
@@ -263,12 +233,14 @@ on the BOARD_SUPPORT_PACKAGE selected.
@c
@section More Information on RTEMS Application Makefiles
These sample applications are examples of simple
RTEMS applications that use the RTEMS Application Makefile
system. This Makefile system simplifies building
RTEMS applications by providing Makefile templates and
capturing the configuration information used to build
RTEMS specific to your BSP. Building an RTEMS application
for different BSPs is as simple as switching the
setting of @code{RTEMS_MAKEFILE_PATH}. This Makefile
These sample applications are examples of simple RTEMS applications
that use the RTEMS Application Makefile system. This Makefile system
simplifies building RTEMS applications by providing Makefile templates and
capturing the configuration information used to build RTEMS specific to
your BSP. Building an RTEMS application for different BSPs is as simple
as switching the setting of @code{RTEMS_MAKEFILE_PATH}. This Makefile
system is described in the file @code{make/README}.
It is very likely in the future that the RTEMS examples built using an
installed RTEMS will be converted to autoconf.

7
doc/started/started.texi
View File

@@ -8,7 +8,7 @@
@c %**end of header
@c
@c COPYRIGHT (c) 1988-2002.
@c COPYRIGHT (c) 1988-2010.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@@ -23,11 +23,6 @@
@include common/setup.texi
@include common/rtems.texi
@c
@c Now set all the tool version dependent information
@c
@include tversions.texi
@ifset use-ascii
@dircategory RTEMS On-Line Manual
@direntry

91
doc/started/tversions.texi.in
View File

@@ -1,91 +0,0 @@
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@c
@c This file contains all toolset version dependent information
@c
@c
@c Comment out setting the "XYZ-RTEMSPATCH" variable if there is no
@c patch required. The documentation will detect this and print
@c an appropriate message in a short section.
@c
@c
@c GCC Version
@c
@set GCCVERSION @GCCVERSION@
@set GCCUNTAR gcc-@value{GCCVERSION}
@set GCCTAR @value{GCCUNTAR}.tar.bz2
@set GCCFTPSITE ftp.gnu.org
@set GCCFTPDIR /pub/gnu/gcc/@value{GCCUNTAR}
@set GCCHTTPDIR /pub/gcc/releases/index.html
@SETGCCPATCHVERSION@
@ifset GCCPATCHVERSION
@set GCCRTEMSPATCH @value{GCCUNTAR}-@value{GCCPATCHVERSION}.diff
@end ifset
@set GCCRPMRELEASE @GCCRPMRELEASE@
@c
@c BINUTILS Version
@c
@c The "official" binutils
@set BINUTILSVERSION @BINUTILSVERSION@
@set BINUTILSUNTAR binutils-@value{BINUTILSVERSION}
@set BINUTILSTAR @value{BINUTILSUNTAR}.tar.gz
@set BINUTILSFTPSITE ftp.gnu.org
@set BINUTILSFTPDIR /pub/gnu/binutils
@SETBINUTILSPATCHVERSION@
@ifset BINUTILSPATCHVERSION
@set BINUTILSRTEMSPATCH @value{BINUTILSUNTAR}-@value{BINUTILSPATCHVERSION}.diff
@end ifset
@set BINUTILSRPMRELEASE @BINUTILSRPMRELEASE@
@c
@c NEWLIB Version
@c
@set NEWLIBVERSION @NEWLIBVERSION@
@set NEWLIBUNTAR newlib-@value{NEWLIBVERSION}
@set NEWLIBTAR @value{NEWLIBUNTAR}.tar.gz
@set NEWLIBFTPSITE sources.redhat.com
@set NEWLIBFTPDIR /pub/newlib
@SETNEWLIBPATCHVERSION@
@ifset NEWLIBPATCHVERSION
@set NEWLIBRTEMSPATCH @value{NEWLIBUNTAR}-@value{NEWLIBPATCHVERSION}.diff
@end ifset
@c
@c GDB Version
@c
@set GDBVERSION @GDBVERSION@
@set GDBUNTAR gdb-@value{GDBVERSION}
@set GDBTAR @value{GDBUNTAR}.tar.gz
@set GDBFTPSITE ftp.gnu.org
@set GDBFTPDIR /pub/gnu/gdb
@SETGDBPATCHVERSION@
@ifset GDBPATCHVERSION
@set GDBRTEMSPATCH @value{GDBUNTAR}-@value{GDBPATCHVERSION}.diff
@end ifset
@set GDBRPMRELEASE @GDBRPMRELEASE@
@set GDBFTPURL ftp://@value{GDBFTPSITE}@value{GDBFTPDIR}/@value{GDBTAR}
@c
@c RTEMS Version
@c
@set RTEMSVERSION RTEMS @value{VERSION}
@set RTEMSUNTAR rtems-@value{VERSION}
@set RTEMSTAR @value{RTEMSUNTAR}.tar.bz2
@set RTEMSFTPSITE ftp.rtems.com
@set RTEMSFTPDIR /pub/rtems