From 8e8676daae33d27c42ba95ff0a3721316c2245c7 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Sat, 11 Apr 1998 13:55:14 +0000 Subject: Base line -- copied from C/C++ --- doc/started_ada/Makefile | 87 ++++++++++ doc/started_ada/buildada.t | 351 +++++++++++++++++++++++++++++++++++++++ doc/started_ada/buildrt.t | 70 ++++++++ doc/started_ada/gdb.t | 194 ++++++++++++++++++++++ doc/started_ada/intro.t | 122 ++++++++++++++ doc/started_ada/intro.t.bak | 122 ++++++++++++++ doc/started_ada/require.t | 36 ++++ doc/started_ada/sample.t | 59 +++++++ doc/started_ada/started_ada.texi | 115 +++++++++++++ doc/started_ada/versions.texi | 82 +++++++++ 10 files changed, 1238 insertions(+) create mode 100644 doc/started_ada/Makefile create mode 100644 doc/started_ada/buildada.t create mode 100644 doc/started_ada/buildrt.t create mode 100644 doc/started_ada/gdb.t create mode 100644 doc/started_ada/intro.t create mode 100644 doc/started_ada/intro.t.bak create mode 100644 doc/started_ada/require.t create mode 100644 doc/started_ada/sample.t create mode 100644 doc/started_ada/started_ada.texi create mode 100644 doc/started_ada/versions.texi (limited to 'doc/started_ada') 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 +@end example + +Where 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:/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= \ + --disable-posix --disable-ka9q --disable-cxx \ + --enable-rtemsbsp=\ + --prefix= +gmake all install +@end example + +Where: + +The list of currently supported of 's and +'s can be found in +tools/@value{RTEMS-UNTAR}/README.configure. + + 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= +@end example + +Where 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= +@end example + +Where 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= +@end example + +Where 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 = \ +/rtems/ +@end example + +Where: + + and 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-/.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 + -- cgit v1.2.3