2003-10-02 Joel Sherrill <joel@OARcorp.com>

* Makefile.am, binaries.t, buildc.t, intro.t, nextstep.t, require.t, sample.t, started.texi: General improvements and merge enough Ada information to justify dropping the Ada specific manual. There is likely still Ada specific information to merge though.
2003-10-02 18:01:48 +00:00
parent e931dbbeba
commit 48cd0b8e25
9 changed files with 249 additions and 53 deletions
--- a/doc/started/ChangeLog
+++ b/doc/started/ChangeLog
@@ -1,3 +1,10 @@
+2003-10-02	Joel Sherrill <joel@OARcorp.com>
+
+	* Makefile.am, binaries.t, buildc.t, intro.t, nextstep.t, require.t,
+	sample.t, started.texi: General improvements and merge enough Ada
+	information to justify dropping the Ada specific manual. There is
+	likely still Ada specific information to merge though.
+
 2003-10-02	Chris Caudle <chris@chriscaudle.org>

 	* nextstep.t: RTEMS applications can now use main() so correct the
--- a/doc/started/Makefile.am
+++ b/doc/started/Makefile.am
@@ -36,7 +36,7 @@ require.texi: require.t tversions.texi
 binaries.texi: binaries.t tversions.texi
 	$(BMENU2) -c -p "Archive and Build Directory Format" \
 	    -u "Top" \
-	    -n "Building the GNU C/C++ Cross Compiler Toolset" < $< > $@
+	    -n "Building the GNU Cross Compiler Toolset" < $< > $@

 buildc.texi: buildc.t tversions.texi
 	$(BMENU2) -c -p "Removing Zipped Tar Files" \
@@ -46,7 +46,7 @@ buildc.texi: buildc.t tversions.texi
 buildrt.texi: buildrt.t tversions.texi
 	$(BMENU2) -c -p "Error Messages Indicating Configuration Problems" \
 	    -u "Top" \
-	    -n "Building the Sample Application" < $< > $@
+	    -n "Building the Sample Applications" < $< > $@

 sample.texi: sample.t tversions.texi
 	$(BMENU2) -c -p "Using the RTEMS configure Script Directly" \
--- a/doc/started/binaries.t
+++ b/doc/started/binaries.t
@@ -44,8 +44,8 @@ These binaries are strictly optional.

@end enumerate

-NOTE: Installing toolset binaries does not install RTEMS itself, only the tools
-required to build RTEMS.  See @ref{Building RTEMS} for the next
+NOTE: Installing toolset binaries does not install RTEMS itself, only
+the tools required to build RTEMS.  See @ref{Building RTEMS} for the next
 step in the process.

@section RPMs
@@ -61,6 +61,7 @@ of a C/C++ toolset targeting the SPARC architecture.
 rpm -i rtems-base-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
 rpm -i sparc-rtems-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
 rpm -i rtems-base-gcc-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
+rpm -i sparc-rtems-c++-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
 rpm -i sparc-rtems-gcc-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
 rpm -i rtems-base-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
 rpm -i sparc-rtems-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
@@ -93,6 +94,7 @@ of a C/C++ toolset targeting the SPARC architecture.
 rpm -e sparc-rtems-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
 rpm -e rtems-base-gdb-@value{GDBVERSION}-@value{GDBRPMRELEASE}.i386.rpm
 rpm -e sparc-rtems-gcc-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
+rpm -e sparc-rtems-c++-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
 rpm -e rtems-base-gcc-gcc@value{GCCVERSION}newlib@value{NEWLIBVERSION}-@value{GCCRPMRELEASE}.i386.rpm
 rpm -e sparc-rtems-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
 rpm -e rtems-base-binutils-@value{BINUTILSVERSION}-@value{BINUTILSRPMRELEASE}.i386.rpm
--- a/doc/started/buildc.t
+++ b/doc/started/buildc.t
@@ -6,7 +6,7 @@
@c  $Id$
@c

-@chapter Building the GNU C/C++ Cross Compiler Toolset
+@chapter Building the GNU Cross Compiler Toolset

 NOTE:  This chapter does @b{NOT} apply if you installed
 prebuilt toolset executables for BINUTILS, GCC, NEWLIB,
@@ -537,15 +537,16 @@ ln -s ../@value{NEWLIBUNTAR}/newlib .

 The following example illustrates the invocation of
@code{configure} and @code{make}
-to build and install @value{BINUTILSUNTAR} for the
-sparc-rtems target:
+to build and install @value{GCCUNTAR} with only
+C and C++ support for the sparc-rtems target:

@example
 mkdir b-gcc
 cd b-gcc
 ../@value{GCCUNTAR}/configure --target=sparc-rtems \
   --with-gnu-as --with-gnu-ld --with-newlib --verbose \
-   --enable-threads --prefix=@value{RTEMSPREFIX}
+   --enable-threads --enable-languages="c,c++" \
+   --prefix=@value{RTEMSPREFIX}
 make all
 make info
 make install
@@ -559,6 +560,47 @@ refer to the documentation for @value{GCCUNTAR} or
 invoke the @value{GCCUNTAR} @code{configure} command with the
@code{--help} option.

+@c
+@c Building GCC with Ada Support
+@c
+@subheading Building GCC with Ada Support
+
+If you want a GCC toolset that includes support for Ada
+(e.g. GNAT), there are some additional requirements on
+the host environment and additional build steps to perform.
+It is critical that you use the same version of GCC/GNAT as
+the native compiler.  GNAT must be compiled with an Ada compiler
+and when building a GNAT cross-compiler, it should be 
+the same version of GNAT itself. 
+
+The build procedure is the same until the configure step. 
+A GCC toolset with GNAT enabled requires that @code{ada}
+be included in the set of enabled languages.
+The following example illustrates the invocation of
+@code{configure} and @code{make}
+to build and install @value{GCCUNTAR} with only
+C, C++, and Ada support for the sparc-rtems target:
+
+@example
+mkdir b-gcc
+cd @value{GCCUNTAR}/gcc/ada
+touch treeprs.ads [es]info.h nmake.ad[bs]
+cd ../../../b-gcc
+../@value{GCCUNTAR}/configure --target=sparc-rtems \
+   --with-gnu-as --with-gnu-ld --with-newlib --verbose \
+   --enable-threads --enable-languages="c,c++,ada" \
+   --prefix=@value{RTEMSPREFIX}
+make all
+make info
+make -C gcc cross-gnattools
+make -C gcc ada.all.cross
+make -C gcc GNATLIBCFLAGS="USER_SELECTED_CPU_CFLAGS" gnatlib
+make install
+@end example
+
+After @value{GCCUNTAR} is built and installed the 
+build directory @code{b-gcc} may be removed.
+
@c
@c Building the GNU Debugger GDB
@c
@@ -577,12 +619,17 @@ specific.  The following configurations have been
 successfully used with RTEMS applications:

@itemize @bullet
-@item Sparc Instruction Simulator (SIS)
-@item PowerPC Instruction Simulator (PSIM)
-@item DINK32
-@item BDM with 68360 and MPC860 CPUs
+@item BDM with ColdFire, 683xx, MPC860 CPUs
@item Motorola Mxxxbug found on M68xxx VME boards
-@item Motorola PPCbug found on PowerPC VME and CompactPCI boards
+@item Motorola PPCbug found on PowerPC VME, CompactPCI, and MTX boards
+@item ARM based Cogent EDP7312
+@item PC's using various Intel and AMD CPUs including i386,
+i486, Pentium and above, and Athlon
+@item PowerPC Instruction Simulator in GDB (PSIM)
+@item MIPS Instruction Simulator in GDB (JMR3904)
+@item Sparc Instruction Simulator in GDB (SIS)
+@item Sparc Instruction Simulator (TSIM)
+@item DINK32 on various PowerPC boards
@end itemize

 GDB is currently RTEMS thread/task aware only if you are using the
--- a/doc/started/intro.t
+++ b/doc/started/intro.t
@@ -16,7 +16,7 @@ have a background in Unix, these instructions should provide the bare
 essentials for performing a setup of the following items: 

@itemize @bullet
-@item GNU C/C++ Cross Compilation Tools for RTEMS on your build-host system
+@item GNU Cross Compilation Tools for RTEMS on your build-host system
@item RTEMS OS for the target
@item GDB Debugger
@end itemize
--- a/doc/started/nextstep.t
+++ b/doc/started/nextstep.t
@@ -10,7 +10,7 @@
@chapter Where To Go From Here

 At this point, you should have successfully installed a
-GNU C/C++ Cross Compilation Tools for RTEMS on your host system
+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
@@ -52,7 +52,7 @@ on the network services provided by RTEMS.

@end itemize

-In addition, the following manuals from the GNU C/C++ Cross
+In addition, the following manuals from the GNU Cross
 Compilation Toolset include information on run-time services
 available.

--- a/doc/started/require.t
+++ b/doc/started/require.t
@@ -9,7 +9,7 @@
@chapter Requirements

 This chapter describes the build-host system requirements and initial steps 
-in installing the GNU C/C++ Cross Compiler Tools and RTEMS on a build-host.
+in installing the GNU Cross Compiler Tools and RTEMS on a build-host.

@section Disk Space

--- a/doc/started/sample.t
+++ b/doc/started/sample.t
@@ -6,21 +6,22 @@
@c  $Id$
@c

-@chapter Building the Sample Application
+@chapter Building the Sample Applications

-@section Unarchive the Sample Application 
-
-Use the following command to unarchive the sample application:
-
-@example
-cd tools
-tar xzf ../archive/hello_world_c.tgz
-@end example
+The RTEMS distribution includes a number of sample C, C++, 
+Ada, and networking applications.  This chapter will provide
+an overview of those sample applications.

+@c
+@c Set the Environment Variable RTEMS_MAKEFILE_PATH 
+@c 
@section Set the Environment Variable RTEMS_MAKEFILE_PATH 

-RTEMS_MAKEFILE_PATH must point to the appropriate directory containing
-RTEMS build for our target and board support package combination. 
+The sample application sets use the RTEMS Application Makefiles.
+This requires that the environment variable 
+@code{RTEMS_MAKEFILE_PATH} point to the appropriate directory containing
+the installed RTEMS image built to target your particular CPU and
+board support package combination. 

@example
 export RTEMS_MAKEFILE_PATH=<INSTALLATION_POINT>/<BOARD_SUPPORT_PACKAGE>
@@ -33,35 +34,22 @@ NOTE:  In release 4.0, BSPs were installed at
@code{<INSTALLATION_POINT>/rtems/<BOARD_SUPPORT_PACKAGE>}.  This
 was changed to be more in compliance with GNU standards.

-@section Build the Sample Application
-
-Use the following command to start the build of the sample hello 
-world application: 
-
-@example
-cd hello_world_c
-make
-@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 no errors are detected during the sample application build, it is
-reasonable to assume that the build of the GNU C/C++ Cross Compiler Tools
+reasonable to assume that the build of the GNU Cross Compiler Tools
 for RTEMS and RTEMS itself for the selected host and target
 combination was done properly. 

-@section Application Executable 
+@c
+@c Executing the Sample Applications
+@c
+@section Executing the Sample Applications

-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
-@end example
-
-How this executable is downloaded to the target board is very dependent
-on the BOARD_SUPPORT_PACKAGE selected.  The following is a list of
+How each sample application executable is downloaded
+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.]
@@ -69,6 +57,14 @@ prepended with @value{RTEMSUNTAR}/c/src/lib/libbsp.]
@need 1000
@table @b

+@item arm/edp7312
+The arm/edp7312 BSP is for the ARM7-based Cogent EDP7312 board.
+
+@item c4x/c4xsim
+The c4x/c4xsim BSP is designed to execute on any member of
+the Texas Instruments C3x/C4x DSP family using only on-CPU
+peripherals for the console and timers.
+
@item i386/pc386
 See @code{i386/pc386/HOWTO}

@@ -93,6 +89,22 @@ See @code{m68k/mvme162/README}.
@item m68k/mvme167
 See @code{m68k/mvme167/README}.

+@item mips/jmr3904
+This is a BSP for the Toshiba TX3904 evaluation board
+simulator included with @code{mipstx39-rtems-gdb}.  The
+BSP is located in @code{mips/jmr3904}.
+The TX3904 is a MIPS R3000 class CPU with serial ports and timers
+integrated with the processor.  This BSP can be used with
+either real  hardware or with the simulator included with
+@code{mipstx39-rtems-gdb}.  An application can be run on the simulator
+by executing the following commands upon entering @code{mipstx39-rtems-gdb}: 
+
+@example
+target sim --board=jmr3904
+load
+run
+@end example
+
@item powerpc/mcp750
 See @code{powerpc/motorola_shared/README}.

@@ -121,6 +133,135 @@ run
 RTEMS has many more BSPs and new BSPs for commercial boards and CPUs
 with on-CPU peripherals are generally welcomed.

+@c
+@c  C/C++ Sample Applications
+@c
+@section C/C++ Sample Applications
+
+The C/C++ sample application set includes a number of simple applications.
+Some demonstrate some basic functionality in RTEMS such as writing
+a file, closing it, and reading it back while others can serve as
+starting points for RTEMS applications or libraries.  Start by 
+unarchiving them so you can peruse them.  Use a command similar to
+the following to unarchive the sample applications:
+
+@example
+cd tools
+tar xjf ../archive/examples-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
+as an example.
+
+@c
+@c Build the C Hello World Application
+@c
+@subheading Build the C Hello World Application
+
+Use the following command to start the build of the sample hello 
+world application: 
+
+@example
+cd hello_world_c
+make
+@end example
+
+
+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
+@end example
+
+The other C/C++ 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
+applications:
+
+@example
+cd tools
+tar xzf ../archive/hello_world_ada.tgz
+@end example
+
+@subheading Create a BSP Specific Makefile
+
+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.
+
+Use the  <INSTALLATION_POINT> and <BOARD_SUPPORT_PACKAGE> specified when
+configuring and installing RTEMS.
+
+@section Build the Sample Application
+
+Use the following command to start the build of the sample application: 
+
+@example
+cd tools/hello_world_ada
+make -f Makefile.<BOARD_SUPPORT_PACKAGE>
+@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
+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. 
+
+@section Application Executable 
+
+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
+@end example
+
+How this executable is downloaded to the target board is very dependent
+on the BOARD_SUPPORT_PACKAGE selected.
+----------------------------------------------------
+
+@c
+@c More Information on RTEMS Application Makefiles
+@c
@section More Information on RTEMS Application Makefiles

 The hello world sample application is a simple example of an
@@ -131,5 +272,4 @@ 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}.
+system is described in the file @code{make/README}.
--- a/doc/started/started.texi
+++ b/doc/started/started.texi
@@ -80,9 +80,9 @@ This is the online version of the Getting Started with RTEMS for C/C++ Users.
 * Introduction::
 * Requirements::
 * Prebuilt Toolset Executables::
-* Building the GNU C/C++ Cross Compiler Toolset::
+* Building the GNU Cross Compiler Toolset::
 * Building RTEMS::
-* Building the Sample Application::
+* Building the Sample Applications::
 * Where To Go From Here::
 * Using MS-Windows as a Development Host::
@end menu