Base line -- copied from C/C++

10 files changed, 1238 insertions, 0 deletions

diff --git a/doc/started_ada/Makefile b/doc/started_ada/Makefile
new file mode 100644
index 0000000000..74704a686d
--- /dev/null
+++ b/doc/started_ada/Makefile
@@ -0,0 +1,87 @@
+#
+#  COPYRIGHT (c) 1988-1998.
+#  On-Line Applications Research Corporation (OAR).
+#  All rights reserved.
+#
+#  $Id$
+#
+
+PROJECT=started_ada
+DISTRIBUTION_LEVEL=public
+
+include ../Make.config
+
+all: html info ps
+
+dirs:
+	$(make-dirs)
+
+COMMON_FILES=../common/cpright.texi ../common/setup.texi
+
+GENERATED_FILES= buildada.texi buildrt.texi gdb.texi intro.texi \
+    require.texi sample.texi
+
+FILES= $(PROJECT).texi versions.texi $(GENERATED_FILES)
+
+INFOFILES=$(wildcard $(PROJECT) $(PROJECT)-*)
+
+info: dirs $(PROJECT)
+	#cp $(wildcard $(PROJECT) $(PROJECT)-*) $(INFO_INSTALL)
+	cp $(PROJECT) $(INFO_INSTALL)
+
+$(PROJECT): $(FILES)
+	$(MAKEINFO) $(PROJECT).texi
+
+dvi: $(PROJECT).dvi
+ps: dirs $(PROJECT).ps
+	
+$(PROJECT).ps: $(PROJECT).dvi
+	dvips -o $(PROJECT).ps $(PROJECT).dvi
+	cp $(PROJECT).ps $(PS_INSTALL)
+
+# run texi2dvi twice to generate the xref's properly.
+$(PROJECT).dvi: $(FILES)
+	$(TEXI2DVI) -v $(PROJECT).texi
+	texi2dvi -v $(PROJECT).texi
+
+intro.texi: intro.t versions.texi
+	$(BMENU) -c -p "Top" \
+	    -u "Top" \
+	    -n "Requirements" ${*}.t
+
+require.texi: require.t versions.texi
+	$(BMENU) -c -p "Introduction" \
+	    -u "Top" \
+	    -n "Building the GNAT Cross Compiler Toolset" ${*}.t
+
+buildada.texi: buildada.t versions.texi
+	$(BMENU) -c -p "Requirements" \
+	    -u "Top" \
+	    -n "Building RTEMS" ${*}.t
+
+buildrt.texi: buildrt.t versions.texi
+	$(BMENU) -c -p "Running the bit Script" \
+	    -u "Top" \
+	    -n "Building the Sample Application" ${*}.t
+
+sample.texi: sample.t versions.texi
+	$(BMENU) -c -p "Generate RTEMS for a specific target and board support package" \
+	    -u "Top" \
+	    -n "Building the GNU Debugger" ${*}.t
+
+gdb.texi: gdb.t versions.texi
+	$(BMENU) -c -p "Application executable" \
+	    -u "Top" \
+	    -n "" ${*}.t
+
+html: dirs $(FILES)
+	-mkdir -p $(WWW_INSTALL)/$(PROJECT)
+	$(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \
+ 	    $(PROJECT).texi
+
+clean:
+	rm -f *.o $(PROG) *.txt core 
+	rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE)
+	rm -f $(PROJECT) $(PROJECT)-* $(GENERATED_FILES)
+	rm -f *.fixed _*
+
diff --git a/doc/started_ada/buildada.t b/doc/started_ada/buildada.t
new file mode 100644
index 0000000000..a078985e0f
--- /dev/null
+++ b/doc/started_ada/buildada.t
@@ -0,0 +1,351 @@
+@c
+@c  COPYRIGHT (c) 1988-1998.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+@chapter Building the GNU C/C++ Cross Compiler Toolset
+
+This chapter describes the steps required to acquire the
+source code for a GNU cross compiler toolset, apply 
+any required RTEMS specific patches, compile that 
+toolset and install it.
+
+@section Get all the pieces 
+
+The tree structure in the figure below is assumed to be present in the
+following discussions: 
+
+@center @b{XXX directory tree figure goes here}
+
+Gather the components that will be required for the installation and place
+them in an archive directory. Call this directory arc. Be sure that there
+is sufficient space to hold all necessary information. This will amount to
+approximately 20 megabytes. 
+
+@subheading @value{GCC-VERSION}
+@example
+    FTP Site:    @value{GCC-FTPSITE}
+    Directory:   @value{GCC-FTPDIR}
+    File:        @value{GCC-TAR}
+@end example
+
+@subheading @value{BINUTILS-VERSION}
+@example
+    FTP Site:    @value{BINUTILS-FTPSITE}
+    Directory:   @value{BINUTILS-FTPDIR}
+    File:        @value{BINUTILS-TAR}
+@end example
+
+@subheading @value{NEWLIB-VERSION}
+@example
+    FTP Site:    @value{NEWLIB-FTPSITE}
+    Directory:   @value{NEWLIB-FTPDIR}
+    File:        @value{NEWLIB-TAR}
+@end example
+
+@subheading @value{RTEMS-VERSION}
+@example
+    FTP Site:    @value{RTEMS-FTPSITE}
+    Directory:   @value{RTEMS-FTPDIR}
+    File:        @value{RTEMS-TAR}
+    File:        bit
+    File:        @value{BINUTILS-RTEMSPATCH}
+    File:        @value{NEWLIB-RTEMSPATCH}
+    File:        @value{GCC-RTEMSPATCH}
+    File:        hello_world_c.tgz
+@end example
+
+
+@section Create the tools directory
+
+Create a directory called tools that will serve as a working directory to
+perform the build of the cross compiler tools.
+
+Unpack the compressed tar files using the following command sequence: 
+
+@example
+cd tools
+tar xzf ../arc/@value{GCC-TAR}
+tar xzf ../arc/@value{BINUTILS-TAR}
+tar xzf ../arc/@value{NEWLIB-TAR}
+@end example
+
+After the compressed tar files have been unpacked, the following
+directories will have been created under tools. 
+
+@itemize @bullet
+@item @value{BINUTILS-UNTAR}
+@item @value{GCC-UNTAR}
+@item @value{NEWLIB-UNTAR}
+@end itemize
+
+@c
+@c  EGCS patches
+@c
+
+@section Apply RTEMS Patch to EGCS
+
+@ifclear GCC-RTEMSPATCH
+No RTEMS specific patches are required for @value{GCC-VERSION} to
+support @value{RTEMS-VERSION}.
+@end ifclear
+
+@ifset GCC-RTEMSPATCH
+
+Apply the patch using the following command sequence:
+
+@example
+cd tools/@value{GCC-UNTAR}
+zcat arc/@value{GCC-RTEMSPATCH} | patch -p1
+@end example
+
+Check to see if any of these patches have been rejected using the following
+sequence:
+
+@example
+cd tools/@value{GCC-UNTAR}
+find . -name "*.rej" -print
+@end example
+
+If any files are found with the .rej extension, a patch has been rejected.
+This should not happen with a good patch file.
+
+To see the files that have been modified use the sequence:
+
+@example
+cd tools/@value{GCC-UNTAR}
+find . -name "*.orig" -print
+@end example
+
+The files that are found, have been modified by the patch file.
+
+@end ifset
+
+@c
+@c  BINUTILS patches
+@c
+
+@section Apply RTEMS Patch to binutils
+
+@ifclear BINUTILS-RTEMSPATCH
+No RTEMS specific patches are required for @value{BINUTILS-VERSION} to
+support @value{RTEMS-VERSION}.
+@end ifclear
+
+@ifset BINUTILS-RTEMSPATCH
+Apply the patch using the following command sequence:
+
+@example
+cd tools/@value{BINUTILS-UNTAR}
+zcat arc/@value{BINUTILS-RTEMSPATCH} | patch -p1
+@end example
+
+Check to see if any of these patches have been rejected using the following
+sequence: 
+
+@example
+cd tools/@value{BINUTILS-UNTAR}
+find . -name "*.rej" -print
+@end example
+
+If any files are found with the .rej extension, a patch has been rejected.
+This should not happen with a good patch file. 
+
+To see the files that have been modified use the sequence:
+
+@example
+cd tools/@value{BINUTILS-UNTAR}
+find . -name "*.orig" -print
+@end example
+
+The files that are found, have been modified by the patch file. 
+
+@end ifset
+
+@c
+@c  Newlib patches
+@c
+
+@section Apply RTEMS Patch to newlib
+
+@ifclear NEWLIB-RTEMSPATCH
+No RTEMS specific patches are required for @value{NEWLIB-VERSION} to
+support @value{RTEMS-VERSION}.
+@end ifclear
+
+@ifset NEWLIB-RTEMSPATCH
+
+Apply the patch using the following command sequence:
+
+@example
+cd tools/@value{NEWLIB-UNTAR}
+zcat arc/@value{NEWLIB-RTEMSPATCH} | patch -p1
+@end example
+
+Check to see if any of these patches have been rejected using the following
+sequence: 
+
+@example
+cd tools/@value{NEWLIB-UNTAR}
+find . -name "*.rej" -print
+@end example
+
+If any files are found with the .rej extension, a patch has been rejected.
+This should not happen with a good patch file. 
+
+To see the files that have been modified use the sequence:
+
+@example
+cd tools/@value{NEWLIB-UNTAR}
+find . -name "*.orig" -print
+@end example
+
+The files that are found, have been modified by the patch file. 
+
+@end ifset
+
+@c
+@c  Modify the bit script
+@c
+
+@section Modify the bit Script
+
+Copy the @code{bit} script from arc to the tools directory.
+
+Edit the @code{bit} file to alter the following environmental variables:
+
+@itemize @bullet
+@item INSTALL_POINT
+@item BINUTILS
+@item NEWLIB
+@item GCC
+@item BUILD_DOCS
+@item BUILD_OTHER_LANGUAGES
+@end itemize
+
+These variables are located in the script section that resembles the
+extract below: 
+
+
+@example
+# USERCHANGE -- localize these.
+#
+#  INSTALL_POINT: Directory tools are installed into.
+#      Recommended installation point for various OS's:
+#         Linux:    /usr/local/rtems
+#         Solaris:  /opt/gnu/rtems
+#   BINUTILS:     Binutils source directory
+#   NEWLIB:       Newlib source directory
+#   GCC:          Newlib source directory
+#   BUILD_DOCS:   Set to "yes" if you want to install documentation.
+#   BUILD_OTHER_LANGUAGES:
+#                 Set to "yes" if you want to build Fortran and Objective-C
+#
+BINUTILS=@value{BINUTILS-UNTAR}
+GCC=@value{GCC-UNTAR}
+NEWLIB=@value{NEWLIB-UNTAR}
+BUILD_DOCS=yes
+BUILD_OTHER_LANGUAGES=yes
+INSTALL_POINT=/home/joel/$@{GCC@}/$@{target@}
+
+# USERCHANGE - uncomment this if you want to watch the commands.
+@end example
+
+Where each of the variables which may be modified is described below:
+
+@table @code
+@item INSTALL_POINT
+is the location where you wish the GNU C/C++ cross compilation tools for
+RTEMS to be built. It is recommended that the directory chosen to receive
+these tools be named so that it is clear from which egcs distribution it
+was generated and for which target system the tools are to produce code for.
+
+@item BINUTILS
+is the directory under tools that contains @value{BINUTILS-UNTAR}. 
+For example,
+
+@example
+BINUTILS=@value{BINUTILS-UNTAR}.
+@end example
+
+@item GCC
+is the directory under tools that contains @value{GCC-UNTAR}.
+For example,
+
+@example
+GCC=@value{GCC-UNTAR}.
+@end example
+
+@item NEWLIB
+is the directory under tools that contains @value{NEWLIB-UNTAR}.
+For example,
+
+@example
+NEWLIB=@value{NEWLIB-UNTAR}.
+@end example
+
+@item BUILD_DOCS
+is set to "yes" if you want to install documentation.
+For example, 
+
+@example
+BUILD_DOCS=yes
+@end example
+
+@item BUILD_OTHER_LANGUAGES
+is set to "yes" if you want to build languages other than C and C++.  At
+the current time, this enables Fortan and Objective-C.
+For example,
+
+@example
+BUILD_OTHER_LANGUAGES=yes
+@end example
+
+@end table
+
+@section Running the bit Script
+
+After the @code{bit} script has been modified to reflect the
+local installation, the modified @code{bit} script is run
+using the following sequence:
+
+@example
+cd tools
+./bit <target configuration>
+@end example
+
+Where <target configuration> is one of the following:
+
+@itemize @bullet
+@item hppa1.1
+@item i386
+@item i386-elf
+@item i386-go32
+@item i960
+@item m68k
+@item mips64orion
+@item powerpc
+@item sh
+@item sparc
+@end itemize
+
+If no errors are encountered, the @code{bit} script will conclude by 
+printing messages similar to the following:
+
+@example
+
+The src and build-i386-tools subdirectory may now be removed.
+
+Started:  Fri Apr 10 10:14:07 CDT 1998
+Finished: Fri Apr 10 12:01:33 CDT 1998
+@end example
+
+If the @code{bit} script successfully completes, then the
+GNU C/C++ cross compilation tools are installed.
+
+If the @code{bit} script does not successfully complete, then investigation
+will be required to determine the source of the error.
+
diff --git a/doc/started_ada/buildrt.t b/doc/started_ada/buildrt.t
new file mode 100644
index 0000000000..daaf72f88b
--- /dev/null
+++ b/doc/started_ada/buildrt.t
@@ -0,0 +1,70 @@
+@c
+@c
+@c  COPYRIGHT (c) 1988-1998.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+@chapter Building RTEMS
+
+@section Unpack the RTEMS source
+
+Use the following command sequence to unpack the RTEMS source into the
+tools directory: 
+
+@example
+cd tools
+tar xzf ../arc/@value{RTEMS-TAR}
+@end example
+
+@section Add the bin directory under the install point to the default PATH
+
+In order to compile RTEMS, you must have the cross compilation toolset
+in your search patch.  The following command appends the directory
+where the tools were installed in the previous chapter:
+
+@example
+export PATH=$PATH:<INSTALL_POINT>/bin
+@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.
+
+@section Generate RTEMS for a specific target and board support package
+
+Make a build directory under tools and build the RTEMS product in this
+directory. The ../@value{RTEMS-UNTAR}/configure
+command has numerous command line
+arguments. These arguments are discussed in detail in documentation that
+comes with the RTEMS distribution. In the installation described in the
+section "Unpack the RTEMS source", these configuration options can be found
+in file tools/@value{RTEMS-UNTAR}/README.configure.
+
+The following shows the command sequence required to configure,
+compile, and install RTEMS with the POSIX API, KA9Q TCP/IP,
+and C++ support disabled.  RTEMS will be built to target 
+the @code{BOARD_SUPPORT_PACKAGE} board.
+
+@example
+mkdir build-rtems
+cd build-rtems
+../@value{RTEMS-UNTAR}/configure --target=<TARGET_CONFIGURATION> \
+    --disable-posix --disable-ka9q --disable-cxx \
+    --enable-rtemsbsp=<BOARD_SUPPORT_PACKAGE>\
+    --prefix=<INSTALL_POINT>
+gmake all install
+@end example
+
+Where:
+
+The list of currently supported of <TARGET_CONFIGURATION>'s and
+<BOARD_SUPPORT_PACKAGE>'s can be found in
+tools/@value{RTEMS-UNTAR}/README.configure.
+
+<INSTALL_POINT> is the installation point from the previous step
+"Modify the bit script" in the build of the tools. 
+
+
diff --git a/doc/started_ada/gdb.t b/doc/started_ada/gdb.t
new file mode 100644
index 0000000000..7ae7c2d9cd
--- /dev/null
+++ b/doc/started_ada/gdb.t
@@ -0,0 +1,194 @@
+@c
+@c  COPYRIGHT (c) 1988-1998.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+@chapter Building the GNU Debugger
+
+GDB is not currently RTEMS aware. The following configurations have been
+successfully used with RTEMS applications:
+
+@itemize @bullet
+@item Sparc Instruction Simulator (SIS)
+@item PowerPC Instruction Simulator (PSIM)
+@item DINK32
+@end itemize
+
+Other configurations of gdb have successfully been used by RTEMS users
+but are not documented here.
+
+@section Unarchive the gdb distribution
+
+Use the following commands to unarchive the gdb distribution:
+
+@example
+cd tools
+tar xzf ../arc/@value{GDB-TAR}
+@end example
+
+The directory @value{GDB-UNTAR} is created under the tools directory.
+
+@c
+@c  GDB Patch
+@c
+
+@section Apply RTEMS Patch to GDB
+
+@ifclear GDB-RTEMSPATCH
+No RTEMS specific patches are required for @value{GDB-VERSION} to
+support @value{RTEMS-VERSION}.
+@end ifclear
+
+@ifset GDB-RTEMSPATCH
+
+Apply the patch using the following command sequence:
+
+@example
+cd tools/@value{GDB-UNTAR}
+zcat arc/@value{GDB-RTEMSPATCH} | patch -p1
+@end example
+
+Check to see if any of these patches have been rejected using the following
+sequence:
+
+@example
+cd tools/@value{GDB-UNTAR}
+find . -name "*.rej" -print
+@end example
+
+If any files are found with the .rej extension, a patch has been rejected.
+This should not happen with a good patch file.
+
+To see the files that have been modified use the sequence:
+
+@example
+cd tools/@value{GDB-UNTAR}
+find . -name "*.orig" -print
+@end example
+
+The files that are found, have been modified by the patch file.
+
+@end ifset
+
+
+@section GDB with Sparc Instruction Simulation (SIS)
+
+@subheading Make the build directory
+
+Create a build directory for the SIS Debugger
+
+@example
+cd tools
+mkdir build-sis
+@end example
+
+@subheading Configure for the build
+
+Configure the GNU Debugger for the
+Sparc Instruction Simulator (SIS):
+
+@example
+cd tools/build-sis
+../@value{GDB-UNTAR}/configure --target-sparc-erc32-aout \
+    --program-prefix=sparc-rtems- \
+    --disable-gdbtk \
+    --enable-targets=all \
+    --prefix=<INSTALL_POINT_FOR_SIS>
+@end example
+
+Where <INSTALL_POINT_FOR_SIS> is a unique location where the gdb
+with SIS will be created. 
+
+@subheading Make the debugger
+
+From tools/build-sis execute the following command sequence:
+
+@example
+gmake all install
+@end example
+
+
+@section GDB with PowerPC Instruction Simulator
+
+@subheading Make the build directory
+
+Create a build directory for the SIS Debugger
+
+@example
+cd tools
+mkdir build-ppc
+@end example
+
+@subheading Configure for the build
+
+Configure the GNU Debugger for the PowerPC
+Instruction Simulator (PSIM):
+
+@example
+cd tools/build-ppc
+../@value{GDB-UNTAR}/configure \
+      --target=powerpc-unknown-eabi \
+      --program-prefix=powerpc-rtems- \
+      --enable-sim-powerpc \
+      --enable-sim-timebase \
+      --enable-sim-inline \
+      --enable-sim-hardware \
+      --enable-targets=all \
+      --prefix=<INSTALL_POINT_FOR_PPC>
+@end example
+
+Where <INSTALL_POINT_FOR_PPC> is a unique location where the gdb
+with PSIM will be created. 
+
+
+@subheading Make the debugger
+
+From tools/build-ppc execute the following command sequence:
+
+@example
+gmake all install
+@end example
+
+
+@section GDB for DINK32
+
+@subheading Unarchive the gdb distribution
+
+Use the following commands to unarchive the gdb distribution:
+
+@subheading Make the build directory
+
+Create a build directory for the DINK32 Debugger
+
+@example
+cd tools
+mkdir build-dink32
+@end example
+
+@subheading Configure for the build
+
+Configure the GNU Debugger to communicate with
+the DINK32 ROM monitor:
+
+@example
+cd tools/build-dink32
+../@value{GDB-UNTAR}/configure --target-powerpc-elf \
+    --program-prefix=powerpc-rtems- \
+    --enable-targets=all \
+    --prefix=<INSTALL_POINT_FOR_DINK32>
+@end example
+
+Where <INSTALL_POINT_FOR_DINK32> is a unique location where the
+gdb Dink32 will be created. 
+
+@subheading Make the debugger
+
+From tools/build-dink32 execute the following command sequence:
+
+@example
+gmake all install
+@end example
+
diff --git a/doc/started_ada/intro.t b/doc/started_ada/intro.t
new file mode 100644
index 0000000000..87e0552aa0
--- /dev/null
+++ b/doc/started_ada/intro.t
@@ -0,0 +1,122 @@
+@c
+@c  COPYRIGHT (c) 1988-1998.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+@chapter Introduction
+
+The purpose of this document is to guide you through the process of 
+installing a GNU cross development environment to use with RTEMS.
+
+If you are already familiar with the concepts behind a cross compiler and
+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 host system
+@item RTEMS OS for the target host
+@item GDB Debugger
+@end itemize
+
+The remainder of this chapter provides background information on real-time
+embedded systems and cross development.  If you are not familiar with either
+of these areas, please read them.  This will help familiarize you with the
+types of systems RTEMS is designed to be used in and the cross development
+process used when developing RTEMS applications.
+
+@section Real-Time Embedded Systems
+
+Real-time embedded systems are found in practically every facet of our
+everyday lives.  Today's systems range from the common telephone, automobile
+control systems, and kitchen appliances to complex air traffic control
+systems, military weapon systems, an d production line control including
+robotics and automation. However, in the current climate of rapidly changing
+technology, it is difficult to reach a consensus on the definition of a
+real-time embedded system. Hardware costs are continuing to rapidly decline 
+while at the same time the hardware is increasing in power and functionality.
+As a result, embedded systems that were not considered viable two years ago
+are suddenly a cost effective solution. In this domain, it is not uncommon
+for a single hardware configuration to employ a variety of architectures and
+technologies. Therefore, we shall define an embedded system as any computer
+system that is built into a larger system consisting of multiple technologies
+such as digital and analog electronics,  mechanical devices, and sensors.
+
+Even as hardware platforms become more powerful, most embedded systems are
+critically dependent on the real-time software embedded in the systems
+themselves.  Regardless of how efficiently the hardware operates, the
+performance of the embedded real-time software determines the success of the
+system.  As the complexity of the embedded hardware platform grows, so does
+the size and complexity of the embedded software. Software systems must
+routinely perform activities which were only dreamed of a short time ago.
+These large, complex, real-time embedded applications now commonly contain
+one million lines of code or more.
+
+Real-time embedded systems have a complex set of characteristics that
+distinguish them from other software applications.  Real-time embedded
+systems are driven by and must respond to real world events while adhering to
+rigorous requirements imposed by the environment with which they interact. 
+The correctness of the system depends not only on the results of
+computations, but also on the time at which the results are produced.  The
+most important and complex characteristic of real-time application systems is
+that they must receive and respond to a set of external stimuli within rigid
+and critical time constraints. 
+
+A single real-time application can be composed of both soft and hard
+real-time components. A typical example of a hard real-time system is a
+nuclear reactor control system that must not only detect failures, but must
+also respond quickly enough to prevent a meltdown. This application also has
+soft real-time requirements because it may involve a man-machine interface.
+Providing an interactive input to the control system is not as critical as
+setting off an alarm to indicate a failure condition. However, th e
+interactive system component must respond within an acceptable time limit to
+allow the operator to interact efficiently with the control system. 
+
+@section Cross Development
+
+Today almost all real-time embedded software systems are developed in a 
+@b{cross development} environment using cross development tools. In the cross
+development environment, software development activities are typically
+performed on one computer system, the @b{host} system, while the result of the
+development effort (produced by the cross tools) is a software system that
+executes on the @b{target} platform. The requirements for the target platform are
+usually incompatible and quite often in direct conflict with the requirements
+for the host.  Moreover, the target hardware is often custom designed for a
+particular project.  This means that the cross development toolset must allow
+the developer to customize the tools to address target specific run-time
+issues.  The toolset must have provisions for board dependent initialization
+code, device drivers, and error handling code. 
+
+The host computer is optimized to support the code development cycle with
+support for code editors, compilers, and linkers requiring large disk drives,
+user development windows, and multiple developer connections.  Thus the host
+computer is typically a traditional UNIX workstation such as are available
+from SUN or Silicon Graphics, or a PC running either a version of MS-Windows
+or UNIX.  The host system may also be required to execute office productivity
+applications to allow the software developer to write  documentation, make
+presentations, or track the project's progress using a project management
+tool.  This necessitates that the host computer be general purpose with
+resources such as a thirty-two or sixty-four bit processor, large amounts of
+RAM, a  monitor, mouse, keyboard, hard and floppy disk drives, CD-ROM drive,
+and a graphics card.  It is likely that the system will be multimedia capable
+and have some networking capability. 
+
+Conversely, the target platform generally has limited traditional computer
+resources.  The hardware is designed for the particular functionality and
+requirements of the embedded system and optimized to perform those tasks
+effectively.  Instead of hard  driverss and keyboards, it is composed of
+sensors, relays, and stepper motors. The per-unit cost of the target platform
+is typically a critical concern.  No hardware component is included without
+being cost justified.  As a result, the processor of the target system is
+often from a different processor family than that of the host system and
+usually has lower performance.  In addition to the processor families
+targeted only for use in embedded systems, there are versions of nearly every
+general-purpose process or specifically tailored for real-time embedded
+systems.  For example, many of the processors targeting the embedded market
+do not include hardware floating point units, but do include peripherals such
+as timers, serial controllers, or network interfaces. 
+
+
+
diff --git a/doc/started_ada/intro.t.bak b/doc/started_ada/intro.t.bak
new file mode 100644
index 0000000000..2dceabb5b2
--- /dev/null
+++ b/doc/started_ada/intro.t.bak
@@ -0,0 +1,122 @@
+@c
+@c  COPYRIGHT (c) 1988-1998.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+@chapter Introduction
+
+The purpose of this document is to guide you through the process of 
+installing a GNU cross development environment to use with RTEMS.
+
+If you are already familiar with the concepts behind a cross compiler and
+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 host system
+@item RTEMS OS for the target host
+@item GDB Debugger
+@end itemize
+
+The remainder of this chapter provides background information on real-time
+embedded systems and cross development.  If you are not familiar with either
+of these areas, please read them.  This will help familiarize you with the
+types of systems RTEMS is designed to be used in and the cross development
+process used when developing RTEMS applications.
+
+@section Real-Time Embedded Systems
+
+Real-time embedded systems are found in practically every facet of our
+everyday lives.  Today's systems range from the common telephone, automobile
+control systems, and kitchen appliances to complex air traffic control
+systems, military weapon systems, an d production line control including
+robotics and automation. However, in the current climate of rapidly changing
+technology, it is difficult to reach a consensus on the definition of a
+real-time embedded system. Hardware costs are continuing to rapidly de cline
+while at the same time the hardware is increasing in power and functionality.
+As a result, embedded systems that were not considered viable two years ago
+are suddenly a cost effective solution. In this domain, it is not uncommon
+for a single hardware configuration to employ a variety of architectures and
+technologies. Therefore, we shall define an embedded system as any computer
+system that is built into a larger system consisting of multiple technologies
+such as digital and analog electronics, mec hanical devices, and sensors.
+
+Even as hardware platforms become more powerful, most embedded systems are
+critically dependent on the real-time software embedded in the systems
+themselves.  Regardless of how efficiently the hardware operates, the
+performance of the embedded real-time s oftware determines the success of the
+system.  As the complexity of the embedded hardware platform grows, so does
+the size and complexity of the embedded software. Software systems must
+routinely perform activities which were only dreamed of a short time ago.
+These large, complex, real-time embedded applications now commonly contain
+one million lines of code or more.
+
+Real-time embedded systems have a complex set of characteristics that
+distinguish them from other software applications.  Real-time embedded
+systems are driven by and must respond to real world events while adhering to
+rigorous requirements imposed by the environment with which they interact. 
+The correctness of the system depends not only on the results of
+computations, but also on the time at which the results are produced.  The
+most important and complex characteristic of real-time application systems is
+that they must receive and respond to a set of external stimuli within rigid
+and critical time constraints. 
+
+A single real-time application can be composed of both soft and hard
+real-time components. A typical example of a hard real-time system is a
+nuclear reactor control system that must not only detect failures, but must
+also respond quickly enough to prevent a meltdown. This application also has
+soft real-time requirements because it may involve a man-machine interface.
+Providing an interactive input to the control system is not as critical as
+setting off an alarm to indicate a failure condition. However, th e
+interactive system component must respond within an acceptable time limit to
+allow the operator to interact efficiently with the control system. 
+
+@section Cross Development
+
+Today almost all real-time embedded software systems are developed in a 
+@b{cross development} environment using cross development tools. In the cross
+development environment, software development activities are typically
+performed on one computer system, the @b{host} system, while the result of the
+development effort (produced by the cross tools) is a software system that
+executes on the @b{target} platform. The requirements for the target platform are
+usually incompatible and quite often in direct conflict with the requirements
+for the host.  Moreover, the target hardware is often custom designed for a
+particular project.  This means that the cross development toolset must allow
+the developer to customize the tools to address target specific run-time
+issues.  The toolset must have provisions for board dependent initialization
+code, device drivers, and error handling code. 
+
+The host computer is optimized to support the code development cycle with
+support for code editors, compilers, and linkers requiring large disk drives,
+user development windows, and multiple developer connections.  Thus the host
+computer is typically a traditional UNIX workstation such as are available
+from SUN or Silicon Graphics, or a PC running either a version of MS-Windows
+or UNIX.  The host system may also be required to execute office productivity
+applications to allow the software developer to write  documentation, make
+presentations, or track the project's progress using a project management
+tool.  This necessitates that the host computer be general purpose with
+resources such as a thirty-two or sixty-four bit processor, large amounts of
+RAM, a  monitor, mouse, keyboard, hard and floppy disk drives, CD-ROM drive,
+and a graphics card.  It is likely that the system will be multimedia capable
+and have some networking capability. 
+
+Conversely, the target platform generally has limited traditional computer
+resources.  The hardware is designed for the particular functionality and
+requirements of the embedded system and optimized to perform those tasks
+effectively.  Instead of hard  driverss and keyboards, it is composed of
+sensors, relays, and stepper motors. The per-unit cost of the target platform
+is typically a critical concern.  No hardware component is included without
+being cost justified.  As a result, the processor of the target system is
+often from a different processor family than that of the host system and
+usually has lower performance.  In addition to the processor families
+targeted only for use in embedded systems, there are versions of nearly every
+general-purpose process or specifically tailored for real-time embedded
+systems.  For example, many of the processors targeting the embedded market
+do not include hardware floating point units, but do include peripherals such
+as timers, serial controllers, or network interfaces. 
+
+
+
diff --git a/doc/started_ada/require.t b/doc/started_ada/require.t
new file mode 100644
index 0000000000..e598e088ca
--- /dev/null
+++ b/doc/started_ada/require.t
@@ -0,0 +1,36 @@
+@c
+@c  COPYRIGHT (c) 1988-1998.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+@chapter Requirements
+
+A fairly large amount of disk space is required to perform the build of the
+GNU C/C++ Cross Compiler Tools for RTEMS. The following table may help in
+assessing the amount of disk space required for your installation: 
+
+@example
++----------------------------------------+------------------------------+
+|                Component               |     Disk Space Required      |
++----------------------------------------+------------------------------+
+|             arc directory              |          20 Mbytes           |
+|          tools src unzipped            |          77 Mbytes           |
+|    each individual build directory     |    120 Mbytes worst case     |
+|       each installation directory      |         20-60 Mbytes         |
++----------------------------------------+------------------------------+
+@end example
+
+The instructions in this manual should work on any computer running
+a UNIX variant.  Some native GNU tools are used by this procedure
+including:
+
+@itemize @bullet
+@item GCC
+@item GNU make
+@end itemize
+
+In addition, some native utilities may be deficient for building 
+the GNU tools.
diff --git a/doc/started_ada/sample.t b/doc/started_ada/sample.t
new file mode 100644
index 0000000000..2ff35bda63
--- /dev/null
+++ b/doc/started_ada/sample.t
@@ -0,0 +1,59 @@
+@c
+@c  COPYRIGHT (c) 1988-1998.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+@chapter Building the Sample Application
+
+@section Unpack the sample application 
+
+Use the following command to unarchive the sample application:
+
+@example
+cd tools
+tar xzf ../arc/hello_world_c.tgz
+@end example
+
+@section Set the environment variable RTEMS_MAKEFILE_PATH 
+
+It must point to the appropriate directory containing RTEMS build for our
+target and board support package combination. 
+
+@example
+export RTEMS_MAKEFILE_PATH = \
+<INSTALLATION_POINT>/rtems/<BOARD_SUPPORT_PACKAGE>
+@end example
+
+Where:
+
+<INSTALLATION_POINT> and <BOARD_SUPPORT_PACKAGE> are those used 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_c
+gmake
+@end example
+
+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
+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/simple_app/o-<BOARD_SUPPORT_PACKAGE>/<filename>.exe
+@end example
+
+How this executable is downloaded to the target board is very dependent
+on the BOARD_SUPPORT_PACKAGE selected.
diff --git a/doc/started_ada/started_ada.texi b/doc/started_ada/started_ada.texi
new file mode 100644
index 0000000000..a6809734ff
--- /dev/null
+++ b/doc/started_ada/started_ada.texi
@@ -0,0 +1,115 @@
+\input ../texinfo/texinfo   @c -*-texinfo-*-
+@c %**start of header
+@setfilename started_ada
+@syncodeindex vr fn
+@synindex ky cp
+@paragraphindent 0
+@c @smallbook
+@c %**end of header
+
+@c
+@c  COPYRIGHT (c) 1988-1998.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+@c
+@c   Master file for the Getting Started (C) Guide
+@c
+
+@include ../common/setup.texi
+
+@c
+@c  Now set all the tool version dependent information
+@c
+@include versions.texi
+
+@ignore
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* Getting Started with GNAT/RTEMS (started_ada):
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+@end ignore
+
+@c
+@c  Title Page Stuff
+@c
+
+@set edition @value{RTEMS-EDITION}
+@set version @value{RTEMS-VERSION}
+@set update-date @value{RTEMS-UPDATE-DATE}
+@set update-month @value{RTEMS-UPDATE-MONTH}
+
+@c
+@c  I don't really like having a short title page.  --joel
+@c
+@c @shorttitlepage Getting Started with RTEMS
+
+@setchapternewpage odd
+@settitle Getting Started with GNAT/RTEMS
+@titlepage
+@finalout
+
+@title Getting Started with GNAT/RTEMS
+@subtitle Edition @value{edition}, for @value{version}
+@sp 1
+@subtitle @value{update-month}
+@author On-Line Applications Research Corporation
+@page
+@include ../common/cpright.texi
+@end titlepage
+
+@c  This prevents a black box from being printed on "overflow" lines.
+@c  The alternative is to rework a sentence to avoid this problem.
+
+@include intro.texi
+@include require.texi
+@include buildada.texi
+@include buildrt.texi
+@include sample.texi
+@include gdb.texi
+
+@ifinfo
+@node Top, Introduction, (dir), (dir)
+@top started_ada
+
+This is the online version of the Getting Started with GNAT/RTEMS.
+
+@menu
+* Introduction::
+* Requirements::
+* Building the GNAT Cross Compiler Toolset::
+* Building RTEMS::
+* Building the Sample Application::
+* Building the GNU Debugger::
+@end menu
+
+@c * Command and Variable Index::
+@c * Concept Index::
+@end ifinfo
+@c 
+@c 
+@c Need to copy the emacs stuff and "trailer stuff" (index, toc) into here
+@c
+
+@c @node Command and Variable Index, Concept Index, GDB for DINK32, Top
+@c @unnumbered Command and Variable Index
+
+@c There are currently no Command and Variable Index entries.
+
+@c @printindex fn
+
+@c @node Concept Index, , Command and Variable Index, Top
+@c @unnumbered Concept Index
+
+@c There are currently no Concept Index entries.
+@c @printindex cp
+
+@contents
+@bye
+
diff --git a/doc/started_ada/versions.texi b/doc/started_ada/versions.texi
new file mode 100644
index 0000000000..ce84d3633a
--- /dev/null
+++ b/doc/started_ada/versions.texi
@@ -0,0 +1,82 @@
+@c
+@c  COPYRIGHT (c) 1988-1998.
+@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/EGCS Version
+@c
+
+@set GCC-VERSION     egcs 1.0.2
+@set GCC-TAR         egcs-1.0.2.tar.gz
+@set GCC-UNTAR       egcs-1.0.2
+@set GCC-FTPSITE     egcs.cygnus.com
+@set GCC-FTPDIR      /pub/egcs/releases/egcs-1.0.2
+@set GCC-RTEMSPATCH  egcs-1.0.2-rtems-diff-980331.gz
+
+@c
+@c  BINUTILS Version
+@c
+
+@c The "official" binutils
+@c @set BINUTILS-VERSION     binutils 2.8.1
+@c @set BINUTILS-TAR         binutils-2.8.1.tar.gz
+@c @set BINUTILS-UNTAR       binutils-2.8.1
+@c @set BINUTILS-FTPSITE     ftp.gnu.org
+@c @set BINUTILS-FTPDIR      /pub/GNU
+@c @set BINUTILS-RTEMSPATCH  binutils-2.8.1-rtems-diff-980321.gz
+
+@c When forced to use a snapshot
+@set BINUTILS-VERSION     gas 980314
+@set BINUTILS-TAR         gas-980314.tgz
+@set BINUTILS-UNTAR       gas-980314
+@set BINUTILS-FTPSITE     ftp.OARcorp.com
+@set BINUTILS-FTPDIR      /OARcorp/private/beta2/c_tools
+@c @set BINUTILS-RTEMSPATCH  binutils-2.8.1-rtems-diff-980321.gz
+
+@c
+@c  NEWLIB Version
+@c
+
+@set NEWLIB-VERSION     newlib 1.8.0
+@set NEWLIB-TAR         newlib-1.8.0.tar.gz
+@set NEWLIB-UNTAR       newlib-1.8.0
+@set NEWLIB-FTPSITE     ftp.cygnus.com
+@set NEWLIB-FTPDIR      /pub/newlib
+@set NEWLIB-RTEMSPATCH  newlib-1.8.0-rtems-diff-980331.gz
+
+@c
+@c  GDB Version
+@c
+
+@set GDB-VERSION     gdb 4.16.86
+@set GDB-TAR         gdb-4.16.86.tar.gz
+@set GDB-UNTAR       gdb-4.16.86
+@set GDB-FTPSITE     ftp.cygnus.com
+@set GDB-FTPDIR      /private/gdb
+@set GDB-RTEMSPATCH  TBD
+
+@c
+@c  RTEMS Version
+@c
+
+@set RTEMS-VERSION     RTEMS 4.0.0-beta2
+@set RTEMS-TAR         rtems-4.0.0-beta2.tgz
+@set RTEMS-UNTAR       rtems-4.0.0-beta2
+@set RTEMS-FTPSITE     ftp.OARcorp.com
+@set RTEMS-FTPDIR      /OARcorp/private/beta2
+