summaryrefslogtreecommitdiffstats
path: root/doc/started
diff options
context:
space:
mode:
Diffstat (limited to 'doc/started')
-rw-r--r--doc/started/Makefile87
-rw-r--r--doc/started/buildc.t66
-rw-r--r--doc/started/buildrt.t202
-rw-r--r--doc/started/gdb.t176
-rw-r--r--doc/started/intro.t19
-rw-r--r--doc/started/require.t25
-rw-r--r--doc/started/sample.t56
-rw-r--r--doc/started/started.texi111
8 files changed, 742 insertions, 0 deletions
diff --git a/doc/started/Makefile b/doc/started/Makefile
new file mode 100644
index 0000000000..be5d8e2b8d
--- /dev/null
+++ b/doc/started/Makefile
@@ -0,0 +1,87 @@
+#
+# COPYRIGHT (c) 1988-1998.
+# On-Line Applications Research Corporation (OAR).
+# All rights reserved.
+#
+# $Id$
+#
+
+PROJECT=started
+DISTRIBUTION_LEVEL=public
+
+include ../Make.config
+
+all: html info ps
+
+dirs:
+ $(make-dirs)
+
+COMMON_FILES=../common/cpright.texi ../common/setup.texi
+
+GENERATED_FILES= buildc.texi buildrt.texi gdb.texi intro.texi \
+ require.texi sample.texi
+
+FILES= $(PROJECT).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
+ $(BMENU) -c -p "Top" \
+ -u "Top" \
+ -n "Requirements" ${*}.t
+
+require.texi: require.t
+ $(BMENU) -c -p "Introduction" \
+ -u "Top" \
+ -n "Building the GNU C/C++ Cross Compiler Toolset" ${*}.t
+
+buildc.texi: buildc.t
+ $(BMENU) -c -p "Requirements" \
+ -u "Top" \
+ -n "Building RTEMS" ${*}.t
+
+buildrt.texi: buildrt.t
+ $(BMENU) -c -p "Running the bit script" \
+ -u "Top" \
+ -n "Building the Sample Application" ${*}.t
+
+sample.texi: sample.t
+ $(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
+ $(BMENU) -c -p "Application executable" \
+ -u "Top" \
+ -n "Command and Variable Index" ${*}.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/buildc.t b/doc/started/buildc.t
new file mode 100644
index 0000000000..ea3069236d
--- /dev/null
+++ b/doc/started/buildc.t
@@ -0,0 +1,66 @@
+@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/rtems-980219.tgz
+@end example
+
+@section Add the bin directory under the install point to the default PATH
+
+Use the following command to append the <INSTALL_POINT>/bin directory to
+the PATH variable:
+
+@example
+PATH=$PATH:<INSTALL_POINT>/bin
+@end example
+
+@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 ../rtems-980219/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:
+
+@example
+tools/rtems-980219/README.configure
+@end example
+
+A simple example of the configuration appears below:
+
+@example
+mkdir build-rtems
+cd build-rtems
+../rtems-980219/configure --target=<TARGET_CONFIGURATION> \
+--disable-posix --disable-ka9q --disable-cpp \
+--enable-rtemsbsp=<BOARD_SUPPORT_PACKAGE>\
+--prefix=< INSTALL_POINT>
+gmake all install
+@end example
+
+Where:
+
+The current summary of <TARGET_CONFIGURATION>'s and
+<BOARD_SUPPORT_PACKAGE>'s can be found in
+tools/rtems-980219/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/buildrt.t b/doc/started/buildrt.t
new file mode 100644
index 0000000000..d9eb918975
--- /dev/null
+++ b/doc/started/buildrt.t
@@ -0,0 +1,202 @@
+@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
+
+@section Get all the pieces
+
+The tree structure in the figure below is assumed to be present in the
+following discussions:
+
+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.
+
+Component Location
+
+egcs 1.0.2 FTP Site: egcs.cygnus.com
+Directory: /pub/egcs/releases/egcs-1.0.2
+File: egcs-1.0.2-980309-prerelease.tar.gz
+binutils 2.8.1 FTP Site: ftp.gnu.org
+Directory: /pub/gnu
+File: binutils-2.8.1.tar.gz
+newlib 1.8.0 FTP Site: ftp.cygnus.com
+Directory: /pub/newlib
+File: newlib-1.8.0.tar.gz
+rtems-980219.tgz FTP Site: ftp.oarcorp.com
+Directory: /oarcorp/private/snapshots
+File: rtems-980219.tgz
+File: bit
+File: binutils-2.8.1-rtems-diff-971221.gz
+File: newlib-1.8.0-diff.980120.gz
+File: simple_app.tgz
+
+
+@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/egcs-1.0.2-980309-prerelease.tar.gz
+tar xzf ../arc/binutls-2.8.1.tar.gz
+tar xzf ../arc/newlib-1.8.0.tar.gz
+@end example
+
+After the compressed tar files have been unpacked, the following
+directories will have been created under tools.
+
+· binutils-2.8.1
+· egcs-1.0.2
+· newlib-1.8.0
+
+@section Apply patches for newlib
+
+Apply the patches using the following command sequence:
+
+@example
+cd tools/newlib-1.8.0
+zcat arc/newlib-1.8.0-diff.980120.gz|patch -p1
+@end example
+
+Check to see if any of these patches have been rejected using the following
+sequence:
+
+@example
+cd tools/newlib-1.8.0
+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/newlib-1.8.0
+find . -name "*.orig" -print
+@end example
+
+The files that are found, have been modified by the patch file.
+
+
+@section Apply patches for binutils
+
+Apply the patches using the following command sequence:
+
+@example
+cd tools/binutils-2.8.1
+zcat arc/binutils-2.8.1-rtems-diff-971221.gz|patch -p1
+@end example
+
+Check to see if any of these patches have been rejected using the following
+sequence:
+
+@example
+cd tools/binutils-2.8.1
+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/binutils-2.8.1
+find . -name "*.orig" -print
+@end example
+
+The files that are found, have been modified by the patch file.
+
+@section Modify the bit script
+
+Copy the bit file from arc to the tools directory.
+
+Edit the bit file to alter the following environmental variables:
+
+· INSTALL_POINT
+· BINUTILS
+· NEWLIB
+· GCC
+· BUILD_DOCS
+
+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.
+#
+BINUTILS=gas-971208
+GCC=egcs-1.0.1
+NEWLIB=newlib-1.8.0
+BUILD_DOCS=yes
+INSTALL_POINT=/home/joel/${GCC}/${target}
+
+# USERCHANGE - uncomment this if you want to watch the commands.
+
+
+Where:
+
+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.
+
+BINUTILS is the directory under tools that contains binutils-2.8.1.
+BINUTILS=binutils-2.8.1
+
+GCC is the directory under tools that contains egcs-1.0.1.
+GCC=egcs-1.0.2-980309-prerelease
+
+NEWLIB is the directory under tools that contains newlib-1.8.0.
+NEWLIB=newlib-1.8.0
+
+BUILD_DOCS is set to "yes" if you want to install documentation.
+BUILD_DOCS=yes
+
+@section Running the bit script
+
+Run the modified bit script using the following sequence:
+
+@example
+cd tools
+./bit <target configuration>
+@end example
+
+Where:
+
+<target configuration> is one of the following:
+
+@example
+hppa1.1
+i386
+i386-go32
+i960
+m68k
+mips64orion
+powerpc
+sh
+sparc
+@end example
+
+@section GNU C/C++ cross compiler toolset complete
+
+At this point the GNU C/C++ cross compile tools should be built.
+
diff --git a/doc/started/gdb.t b/doc/started/gdb.t
new file mode 100644
index 0000000000..2bb66b66f0
--- /dev/null
+++ b/doc/started/gdb.t
@@ -0,0 +1,176 @@
+@c
+@c COPYRIGHT (c) 1988-1998.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+@c $Id$
+@c
+
+@chapter Building the GDB Debugger
+
+GDB is not currently RTEMS aware. The following configurations have been
+successfully used with RTEMS applications.
+
+@section GDB with Sparc Instruction Simulation (SIS)
+
+@subsection Unarchive the gdb distribution
+
+Use the following commands to unarchive the gdb distribution:
+
+@example
+cd tools
+tar xzf ../arc/gdb-980122.tar.gz
+@end example
+
+The directory gdb-980122 is created under the tools directory.
+
+@subsection Make the build directory
+
+Create a build directory for the SIS Debugger
+
+@example
+cd tools
+mkdir build-sis
+@end example
+
+@subsection Configure for the build
+
+Configure the general gdb distribution for Sparc Instruction Simulation
+
+@example
+cd tools/build-sis
+../gdb-980122/configure --target-sparc-erc32-aout \
+--program-prefix=sparc-rtems- \
+--disable-gdbtk \
+--with-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.
+
+@subsection Make the debugger
+
+From tools/build-sis run:
+
+@example
+gmake
+@end example
+
+
+@section GDB with PowerPC instruction Simulation(PSIM)
+
+@subsection Unarchive the gdb distribution
+
+Use the following commands to unarchive the gdb distribution:
+
+@example
+cd tools
+tar xzf ../arc/gdb-980122.tar.gz
+@end example
+
+The directory gdb-980122 is created under the tools directory.
+
+
+@subsection Make the build directory
+
+Create a build directory for the SIS Debugger
+
+@example
+cd tools
+mkdir build-ppc
+@end example
+
+@subsection Configure for the build
+
+Configure the general gdb distribution for PowerPC Instruction Simulation
+
+@example
+cd tools/build-ppc
+../gdb-980122/configure --host=i486-linux \
+ --target=powerpc-unknown-eabi \
+ --program-prefix=powerpc-rtems- \
+ --enable-sim-powerpc \
+ --enable-sim-timebase \
+ --enable-sim-inline \
+ --enable-sim-hardware \
+--prefix=<INSTALL_POINT_FOR_PPC>
+@end example
+
+Where:
+
+<INSTALL_POINT_FOR_PPC> is a unique location where the gdb with PSIM will
+be created.
+
+
+@subsection Make the debugger
+
+From tools/build-ppc run:
+
+@example
+gmake
+@end example
+
+
+@section GDB with Dink32
+
+@subsection Unarchive the gdb distribution
+
+Use the following commands to unarchive the gdb distribution:
+
+@example
+cd tools
+tar xzf ../arc/gdb-980122.tar.gz
+@end example
+
+The directory gdb-980122 is created under the tools directory.
+
+
+@subsection Make the build directory
+
+Create a build directory for the SIS Debugger
+
+@example
+cd tools
+mkdir build-dink32
+@end example
+
+@subsection Replace dink32-rom.c
+
+Obtain a valid copy of dink32-rom.c from RTEMS site.
+
+Replace the copy of dink32-rom.c that came with the gdb-980122
+distribution. It is located in:
+
+@example
+tools/gdb-980122/gdb/dink32-rom.c
+@end example
+
+
+@subsection Configure for the build
+
+Configure the general gdb distribution for Sparc Instruction Simulation
+
+@example
+cd tools/build-dink32
+../gdb-980122/configure --target-powerpc-elf \
+--program-prefix=powerpc-rtems- \
+--prefix=<INSTALL_POINT_FOR_DINK32>
+--with-targets=all \
+@end example
+
+Where:
+
+<INSTALL_POINT_FOR_DINK32> is a unique location where the gdb Dink32 will
+be created.
+
+@subsection Make the debugger
+
+From tools/build-dink32 run:
+
+@example
+gmake
+@end example
+
diff --git a/doc/started/intro.t b/doc/started/intro.t
new file mode 100644
index 0000000000..f97b8327f7
--- /dev/null
+++ b/doc/started/intro.t
@@ -0,0 +1,19 @@
+@c
+@c COPYRIGHT (c) 1988-1998.
+@c On-Line Applications Research Corporation (OAR).
+@c All rights reserved.
+@c
+@c $Id$
+@c
+
+@chapter Introduction
+
+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:
+
+· GNU C/C++ Cross Compilation Tools for RTEMS on your host system
+· RTEMS OS for the target host
+· GDB Debugger
+
+
diff --git a/doc/started/require.t b/doc/started/require.t
new file mode 100644
index 0000000000..7edab63381
--- /dev/null
+++ b/doc/started/require.t
@@ -0,0 +1,25 @@
+@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
+
diff --git a/doc/started/sample.t b/doc/started/sample.t
new file mode 100644
index 0000000000..ad2478d746
--- /dev/null
+++ b/doc/started/sample.t
@@ -0,0 +1,56 @@
+@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/simple_app.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 in step 4.3
+
+@section Build the Sample Application
+
+Use the following command to start the build of the sample application:
+
+@example
+cd tools/simple_app
+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 the build of the RTEMS OS for the selected host and target
+combination was done properly.
+
+@section Application executable
+
+If the application build has taken place without error, the application
+executable is placed in the following directory:
+
+@example
+tools/simple_app/o-<BOARD_SUPPORT_PACKAGE>/<filename>.exe
+@end example
+
diff --git a/doc/started/started.texi b/doc/started/started.texi
new file mode 100644
index 0000000000..c65cfe30bc
--- /dev/null
+++ b/doc/started/started.texi
@@ -0,0 +1,111 @@
+\input ../texinfo/texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename started
+@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
+
+@ignore
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* RTEMS Getting Started Guide (started):
+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 RTEMS
+@titlepage
+@finalout
+
+@title Getting Started with RTEMS
+@subtitle Edition @value{edition}, for RTEMS @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.t
+@include require.t
+@include buildc.t
+@include buildrt.t
+@include sample.t
+@include gdb.t
+
+@ifinfo
+@node Top, Preface, (dir), (dir)
+@top started
+
+This is the online version of the Getting Started with RTEMS for C/C++
+Developers.
+
+@menu
+* Introduction::
+* Requirements::
+* Building the GNU C/C++ Cross Compiler Toolset::
+* Building RTEMS::
+* Building the Sample Application::
+* Building the GNU Debugger::
+* Command and Variable Index::
+* Concept Index::
+@end menu
+
+@end ifinfo
+@c
+@c
+@c Need to copy the emacs stuff and "trailer stuff" (index, toc) into here
+@c
+
+@node Command and Variable Index, Concept Index, Overall Summary, Top
+@unnumbered Command and Variable Index
+
+There are currently no Command and Variable Index entries.
+
+@c @printindex fn
+
+@node Concept Index, , Command and Variable Index, Top
+@unnumbered Concept Index
+
+There are currently no Concept Index entries.
+@c @printindex cp
+
+@contents
+@bye
+