Initial revision

7 files changed, 1696 insertions, 0 deletions

diff --git a/doc/develenv/Makefile b/doc/develenv/Makefile
new file mode 100644
index 0000000000..d94fae665f
--- /dev/null
+++ b/doc/develenv/Makefile
@@ -0,0 +1,55 @@
+#
+#  COPYRIGHT (c) 1996.
+#  On-Line Applications Research Corporation (OAR).
+#  All rights reserved.
+#
+
+include ../Make.config
+
+PROJECT=develenv
+
+all:  
+
+COMMON_FILES=../common/cpright.texi
+
+FILES=compile.texi $(PROJECT).texi direct.texi intro.texi sample.texi utils.texi
+
+all:
+
+info: $(PROJECT)
+	cp $(PROJECT) $(INFO_INSTALL)
+
+$(PROJECT): $(FILES)
+	$(MAKEINFO) $(PROJECT).texi
+
+vinfo: info
+	$(INFO) -f $(PROJECT)
+
+dvi: $(PROJECT).dvi
+ps: $(PROJECT).ps
+	
+$(PROJECT).ps: $(PROJECT).dvi
+	dvips -o $(PROJECT).ps $(PROJECT).dvi
+	cp $(PROJECT).ps $(PS_INSTALL)
+
+view: ps
+	$(GHOSTVIEW) $(PROJECT).ps
+
+dv: dvi
+	$(XDVI) $(PROJECT).dvi
+
+$(PROJECT).dvi: $(FILES)
+	$(TEXI2DVI) $(PROJECT).texi
+
+html:
+	-mkdir $(WWW_INSTALL)/$(PROJECT)
+	$(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \
+ 	    $(PROJECT).texi
+	cp ../rtems.html $(WWW_INSTALL)
+
+
+clean:
+	rm -f *.o $(PROG) *.txt core *.html 
+	rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE)
+	rm -f $(PROJECT) $(PROJECT)-* _*
+
diff --git a/doc/develenv/compile.texi b/doc/develenv/compile.texi
new file mode 100644
index 0000000000..7ef2e99b92
--- /dev/null
+++ b/doc/develenv/compile.texi
@@ -0,0 +1,157 @@
+@c This chapter is not currently in the Development Environment Guide.
+
+@c
+@c  COPYRIGHT (c) 1988-1997.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+
+@ifinfo
+@node Compilation and GNU Make Stanzas, Compilation and GNU Make Stanzas Building the Entire Tree, Test Suite Source Directory, Top
+@end ifinfo
+@chapter Compilation and GNU Make Stanzas
+@ifinfo
+@menu
+* Compilation and GNU Make Stanzas Building the Entire Tree::
+* Compilation and GNU Make Stanzas Making a Component::
+* Compilation and GNU Make Stanzas Optional Manager Support::
+@end menu
+@end ifinfo
+
+RTEMS is compiled using the GNU gmake(1G) utilities.
+All examples in this section are with the gmake(1G) command.
+Note that the installation procedure for GNU Make installs it as
+make.  It is referred to as gmake in this document to
+distinguish it from any other make utilities which may also be
+on the development system.
+
+The GNU Make utility uses a file that describes the
+relationships among the files and the operations necessary for
+updating each file. The GNU Make utility uses stanzas to specify
+which set of relationships to update.  Each component and suite
+control directory contains a make control file, Makefile, which
+describes the relationships which must be checked and the
+associated update operations for each stanza. This facility is
+used to perform compilation, to remove intermediate files, to
+install RTEMS, and to maintain release and working set source
+and documentation notebooks. The following is a list of stanzas
+used by RTEMS make control files:
+
+@ifset use-texinfo-tables
+@table @code
+@item all
+perform compilation but do not install
+
+@item install
+perform compilation if directory contains source but do not install
+
+@item clean
+delete most generated files and directories for the current CPU and target
+
+@item clobber
+delete all generated files and directories for the current CPU and target
+@end table
+@end ifset
+
+@ifclear use-texinfo-tables
+@html
+<CENTER>
+  <TABLE COLS=2 WIDTH="80%" BORDER=2>
+<TR><TD ALIGN=center>all</TD>
+    <TD ALIGN=center>perform compilation but do not install</TD></TR>
+<TR><TD ALIGN=center>install</TD>
+    <TD ALIGN=center>perform compilation if directory contains source 
+        but do not install</TD></TR>
+<TR><TD ALIGN=center>clean</TD>
+    <TD ALIGN=center>delete most generated files and directories for 
+        the current CPU and target</TD></TR>
+<TR><TD ALIGN=center>clobber</TD>
+    <TD ALIGN=center>delete all generated files and directories for 
+        the current CPU and target</TD></TR>
+  </TABLE>
+</CENTER>
+@end html
+@end ifclear
+
+@ifinfo
+@node Compilation and GNU Make Stanzas Building the Entire Tree, Compilation and GNU Make Stanzas Making a Component, Compilation and GNU Make Stanzas, Compilation and GNU Make Stanzas
+@end ifinfo
+@section Building the Entire Tree
+
+At the top of the C source tree, execute the command
+gmake all.  This will build and install all components and tests
+into the directory <TARGET> in this directory.
+
+@ifinfo
+@node Compilation and GNU Make Stanzas Making a Component, Compilation and GNU Make Stanzas Optional Manager Support, Compilation and GNU Make Stanzas Building the Entire Tree, Compilation and GNU Make Stanzas
+@end ifinfo
+@section Making a Component
+
+A single component can be compiled by changing to the
+directory which contains that component and performing the
+following command:
+
+@example
+gmake
+@end example
+
+
+This is equivalent to the following command:
+
+@example
+gmake all
+@end example
+
+Both commands will result in the GNU Make utility
+determining which files require compilation or assembly.  If any
+files require compilation or assembly, then these operations
+will be performed followed by the appropriate archive or link
+command. Files installed are placed in subdirectories under the
+install point.  The install point is determined by the setting
+of the variable PROJECT_HOME in the file
+c/make/custom/<TARGET>.cfg.
+
+If the current directory is not a leaf directory,
+then the requested operation will be performed recursively to
+all subdirectories under the current directory.
+
+By specifying one of the other stanzas supported by
+the Makefile, the GNU Make utility can be used to perform such
+operations as removing all automatically generated files in a
+component (clean and clobbers stanza).
+
+NOTE: For many components it is not possible to
+compile them until other components have been installed.
+
+@ifinfo
+@node Compilation and GNU Make Stanzas Optional Manager Support, Sample Applications, Compilation and GNU Make Stanzas Making a Component, Compilation and GNU Make Stanzas
+@end ifinfo
+@section Optional Manager Support
+
+RTEMS allows the C applications developer to build
+images that only contain those components of the executive that
+are needed, leaving out those that will not be utilized.  This
+is accomplished by the RTEMS Makefile system linking in the
+"stub" versions of the optional managers in the place of those
+managers not needed by the specific application.   The
+application Makefile sets the system variable $(MANAGERS) list
+to contain those managers that are required by the application.
+The RTEMS Makefile system then is able to build a list of
+managers that are unwanted, effectively linking in the stubbed
+versions of these managers before the RTEMS library is built.
+
+For more information and implementation details refer
+to the following files:
+
+@itemize @bullet
+@item c/make/leaf.cfg,
+
+@item a Makefile for a test or sample application, and
+
+@item a compiler description file from c/make/compilers
+@end itemize
+
+These files demonstrate the use of $(MANAGERS) and
+how the unwanted managers are handled.
+
+
diff --git a/doc/develenv/develenv.texi b/doc/develenv/develenv.texi
new file mode 100644
index 0000000000..7c6eeeb370
--- /dev/null
+++ b/doc/develenv/develenv.texi
@@ -0,0 +1,119 @@
+\input ../texinfo/texinfo   @c -*-texinfo-*-
+@c %**start of header
+@setfilename develenv
+@syncodeindex vr fn
+@synindex ky cp
+@paragraphindent 0
+@c @smallbook
+@c %**end of header
+
+@c
+@c  COPYRIGHT (c) 1988-1997.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+
+@c
+@c   Master file
+@c
+
+@c Joel's Questions
+@c
+@c  1.  Why does paragraphindent only impact makeinfo?
+@c  2.  Why does paragraphindent show up in HTML?
+@c
+
+@include ../common/setup.texi
+
+@ignore
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* RTEMS C User: (develenv).             The C User's Guide
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+@end ignore
+
+@c variable substitution info:
+@c
+@c @set RTEMS-LANGUAGE C
+@c the language is @value{RTEMS-LANGUAGE}
+@c NOTE:  don't use underscore in the name
+@c
+
+@c
+@c  Title Page Stuff
+@c
+
+@set edition 4.0.0a
+@set update-date 25 April 1997
+@set update-month April 1997
+
+@c
+@c  I don't really like having a short title page.  --joel
+@c
+@c @shorttitlepage RTEMS Development Environment Guide
+
+@setchapternewpage odd
+@settitle RTEMS Development Environment Guide
+@titlepage
+@finalout
+
+@title RTEMS Development Environment Guide
+@subtitle Edition @value{edition}, for RTEMS 4.0.0
+@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 direct.texi
+@c @include compile.texi
+@include sample.texi
+@include utils.texi
+
+@ifinfo
+@node Top, Introduction, (dir), (dir)
+@top develenv
+
+This is the online version of the RTEMS Development Environment Guide.
+
+@c * Compilation and GNU Make Stanzas::
+
+@menu
+* Introduction::
+* Directory Structure::
+* Sample Applications::
+* RTEMS Specific Utilities::
+* 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, RTEMS Specific Utilities Ada Language Specific Utilities, 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
+
diff --git a/doc/develenv/direct.texi b/doc/develenv/direct.texi
new file mode 100644
index 0000000000..cea5959241
--- /dev/null
+++ b/doc/develenv/direct.texi
@@ -0,0 +1,712 @@
+@c
+@c  COPYRIGHT (c) 1988-1997.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+
+@ifinfo
+@node Directory Structure, Directory Structure Suites, Introduction, Top
+@end ifinfo
+@chapter Directory Structure
+@ifinfo
+@menu
+* Directory Structure Suites::
+@end menu
+@end ifinfo
+
+The RTEMS directory structure is designed to meet
+the following requirements:
+
+@itemize @bullet
+@item encourage development of modular components.
+
+@item isolate processor and target dependent code, while
+allowing as much common source code as possible to be shared
+across multiple processors and targets.
+
+@item allow multiple RTEMS users to perform simultaneous
+compilation of RTEMS and its support facilities for different
+processors and targets.
+@end itemize
+
+The resulting directory structure has processor and
+target dependent source files isolated from generic files.  When
+RTEMS is built, object directories and an install point will be
+automatically created based upon the target BSP selected.  The
+placement of object files based upon the selected BSP name
+insures that object files are not mixed across CPUs or targets.
+This in combination with the make files allows the specific
+compilation options to be tailored for a particular target
+board.  For example, the efficiency of the memory subsystem for
+a particular target board may be sensitive to the alignment of
+data structures, while on another target board with the same
+processor memory may be very limited.  For the first target, the
+options could specify very strict alignment requirements, while
+on the second the data structures could be "packed" to conserve
+memory.  It is impossible to achieve this degree of flexibility
+without providing source code.
+@ifinfo
+@node Directory Structure Suites, C Suites, Directory Structure, Directory Structure
+@end ifinfo
+@section Suites
+@ifinfo
+@menu
+* C Suites::
+* Executive Source Directory::
+* Support Library Source Directory::
+* Test Suite Source Directory::
+@end menu
+@end ifinfo
+
+The RTEMS source tree is organized based on the
+following four variables:
+
+@itemize @bullet
+@item language,
+
+@item target processor,
+
+@item target board, and
+
+@item compiler vendor (Ada only).
+@end itemize
+
+The language may be either C or Ada and there is
+currently nothing shared between the source trees for these two
+implementations of RTEMS.  The user generally selects the
+subdirectory for the implementation they are using and ignores
+that for the other implementation.  The only exceptions to this
+normally occurs when comparing the source code for the two
+implementations or when porting both to a new CPU or target
+board.  The following shows the top level RTEMS directory
+structure which includes directories for each language
+implementation and a language independent source documentation
+directory.  The source documentation directory is currently not
+supported.
+
+@c
+@c  Tree 1 - Top Level
+@c
+
+@ifset use-ascii
+@example
+@group
+                      RTEMS
+                        |
++-----------------------+-----------------------+
+|                                               |
+c                                              doc
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@sp 1
+
+@tex
+{\parskip=0pt\offinterlineskip%
+\hskip 15.0em
+\hskip 1.25em\hbox to 3.00em{\hss{RTEMS}\hss}%
+\vrule width0em height1.972ex depth0.812ex\par\penalty10000
+\hskip 15.0em
+\hskip 2.75em\vrule width.04em%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 15.0em
+\hskip 0.25em\vrule width2.50em height-0.407ex depth0.500ex%
+\vrule width.04em\vrule width2.50em height-0.407ex depth0.500ex%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 15.0em
+\hskip 0.25em\vrule width.04em%
+\hskip 4.92em\vrule width.04em%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 15.0em
+\hskip 0.00em\hbox to 0.50em{\hss{c}\hss}%
+\hskip 1.50em\hbox to 1.50em{\hss{   }\hss}%
+\hskip 1.00em\hbox to 1.50em{\hss{doc}\hss}%
+\vrule width0em height1.972ex depth0.812ex\par}
+@end tex
+@end ifset
+
+@c
+@c for now continue to use the ascii
+@c
+@ifset use-html
+@example
+@group
+                      RTEMS
+                        |
++-----------------------+-----------------------+
+|                                               |
+c                                              doc
+@end group
+@end example
+@html
+@end html
+@end ifset
+
+Each of the following sections will describe the
+contents of the directories in the RTEMS source
+tree.
+
+@ifinfo
+@node C Suites, Executive Source Directory, Directory Structure Suites, Directory Structure Suites
+@end ifinfo
+@subsection C Suites
+
+The following table lists the suites currently included with the
+C implementation of RTEMS and the directory in which they may be located:
+
+@ifset use-texinfo-tables
+@table @code
+@item Support Libraries (BSPs, C library, CPU support)
+$RTEMS_ROOT/c/src/lib
+
+@item Single Processor Tests
+$RTEMS_ROOT/c/src/tests/sptests
+
+@item Timing Tests
+$RTEMS_ROOT/c/src/tests/tmtests
+
+@item Multiprocessor Tests
+$RTEMS_ROOT/c/src/tests/mptests
+
+@item Sample Applications
+$RTEMS_ROOT/c/src/tests/samples
+
+@item RTEMS Build Tools
+$RTEMS_SRC_BASE/c/build_tools
+
+@item Make Support
+$RTEMS_ROOT/c/make
+@end table
+@end ifset
+
+@ifclear use-texinfo-tables
+@html
+<CENTER>
+  <TABLE COLS=2 WIDTH="80%" BORDER=2>
+<TR><TD ALIGN=center>Support Libraries (BSPs, C library, CPU support)</TD>
+    <TD ALIGN=center>$RTEMS_ROOT/c/src/lib</TD></TR>
+<TR><TD ALIGN=center>Single Processor Tests</TD>
+    <TD ALIGN=center>$RTEMS_ROOT/c/src/tests/sptests</TD></TR>
+<TR><TD ALIGN=center>Timing Tests</TD>
+    <TD ALIGN=center>$RTEMS_ROOT/c/src/tests/tmtests</TD></TR>
+<TR><TD ALIGN=center>Multiprocessor Tests</TD>
+    <TD ALIGN=center>$RTEMS_ROOT/c/src/tests/mptests</TD></TR>
+<TR><TD ALIGN=center>Sample Applications</TD>
+    <TD ALIGN=center>$RTEMS_ROOT/c/src/tests/samples</TD></TR>
+<TR><TD ALIGN=center>RTEMS Build Tools</TD>
+    <TD ALIGN=center>$RTEMS_SRC_BASE/c/build_tools</TD></TR>
+<TR><TD ALIGN=center>Make Support</TD>
+    <TD ALIGN=center>$RTEMS_ROOT/c/make</TD></TR>
+  </TABLE>
+</CENTER>
+@end html
+@end ifclear
+
+
+The top level directory structure for the C implementation of RTEMS 
+is as follows:
+
+@c
+@c  Tree 2 - Top C Level
+@c
+
+@ifset use-ascii
+@example
+@group
+                     C
+                     |
+    +----------+-----------+----------+
+    |          |           |          |
+build_tools   make        src   update_tools
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@sp 1
+
+@tex
+{\parskip=0pt\offinterlineskip%
+\hskip 08.0em
+\hskip 13.00em\hbox to 0.50em{\hss{C}\hss}%
+\vrule width0em height1.972ex depth0.812ex\par\penalty10000
+\hskip 08.0em
+\hskip 13.25em\vrule width.04em%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 08.0em
+\hskip 1.75em\vrule width11.50em height-0.407ex depth0.500ex%
+\vrule width.04em\vrule width11.50em height-0.407ex depth0.500ex%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 08.0em
+\hskip 1.75em\vrule width.04em%
+\hskip 5.71em\vrule width.04em%
+\hskip 5.71em\vrule width.04em%
+\hskip 5.71em\vrule width.04em%
+\hskip 5.71em\vrule width.04em%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 08.0em
+\hskip 0.00em\hbox to 3.50em{\hss{Modules}\hss}%
+\hskip 1.00em\hbox to 6.00em{\hss{build\_tools}\hss}%
+\hskip 1.75em\hbox to 2.00em{\hss{make}\hss}%
+\hskip 4.00em\hbox to 1.50em{\hss{src}\hss}%
+\hskip 1.75em\hbox to 6.50em{\hss{update\_tools}\hss}%
+\vrule width0em height1.972ex depth0.812ex\par}
+@end tex
+@end ifset
+
+@ifset use-html
+@example
+@group
+                     C
+                     |
+    +----------+-----------+----------+
+    |          |           |          |
+build_tools   make        src   update_tools
+@end group
+@end example
+@html
+@end html
+@end ifset
+
+This directory contains the subdirectories which
+contain the entire C implementation of the RTEMS executive.  
+The "build-tools" directory contains an assortment of support tools
+for the RTEMS development environment.  Two subdirectories exist
+under "build-tools" which contain scripts (executables) and
+source for the support tools.  The "make" directory contains
+configuration files and subdirectories which provide a robust
+host and cross-target makefile system supporting the building of
+the  executive for numerous application environments.  The
+"update_tools" directory contains utilities which aid in the
+updating from a previous version to the current version of the
+RTEMS executive.
+
+The "src" directory structure for the C implementation of RTEMS is as follows:
+
+@c
+@c  Tree 3 - Top C src Level
+@c
+
+@ifset use-ascii
+@example
+@group
+                     C Source
+                         |
+ +-----------------------+-----------------------+
+ |                       |                       |
+exec                    lib                    tests
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@sp 1
+
+@tex
+{\parskip=0pt\offinterlineskip%
+\hskip 15.0em
+\hskip 2.00em\hbox to 4.00em{\hss{C Source}\hss}%
+\vrule width0em height1.972ex depth0.812ex\par\penalty10000
+\hskip 15.0em
+\hskip 4.00em\vrule width.04em%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 15.0em
+\hskip 1.00em\vrule width3.00em height-0.407ex depth0.500ex%
+\vrule width.04em\vrule width3.00em height-0.407ex depth0.500ex%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 15.0em
+\hskip 1.00em\vrule width.04em%
+\hskip 2.96em\vrule width.04em%
+\hskip 2.96em\vrule width.04em%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 15.0em
+\hskip 0.00em\hbox to 2.00em{\hss{exec}\hss}%
+\hskip 1.25em\hbox to 1.50em{\hss{lib}\hss}%
+\hskip 1.00em\hbox to 2.50em{\hss{tests}\hss}%
+\vrule width0em height1.972ex depth0.812ex\par}
+@end tex
+@end ifset
+
+@ifset use-html
+@example
+@group
+                     C Source
+                         |
+ +-----------------------+-----------------------+
+ |                       |                       |
+exec                    lib                    tests
+@end group
+@end example
+@html
+@end html
+@end ifset
+
+This directory contains all source files that
+comprises the RTEMS executive, supported target board support
+packages, and the RTEMS Test Suite.
+
+@ifinfo
+@node Executive Source Directory, Support Library Source Directory, C Suites, Directory Structure Suites
+@end ifinfo
+@subsection Executive Source Directory
+
+The "exec" directory structure for the C implementation is as follows:
+
+@c
+@c  Tree 4 - C Executive Tree
+@c
+
+@ifset use-ascii
+@example
+@group
+                    C Executive
+                         |
+  +-----------+----------+-----------+----------+
+  |           |          |           |          |
+posix       rtems       sapi       score     wrapup
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@sp 1
+
+@tex
+{\parskip=0pt\offinterlineskip%
+\hskip 10.0em
+\hskip 6.00em\hbox to 5.50em{\hss{C Executive}\hss}%
+\vrule width0em height1.972ex depth0.812ex\par\penalty10000
+\hskip 10.0em
+\hskip 8.75em\vrule width.04em%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 10.0em
+\hskip 1.25em\vrule width7.50em height-0.407ex depth0.500ex%
+\vrule width.04em\vrule width7.50em height-0.407ex depth0.500ex%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 10.0em
+\hskip 1.25em\vrule width.04em%
+\hskip 3.71em\vrule width.04em%
+\hskip 3.71em\vrule width.04em%
+\hskip 3.71em\vrule width.04em%
+\hskip 3.71em\vrule width.04em%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 10.0em
+\hskip 0.00em\hbox to 2.50em{\hss{posix}\hss}%
+\hskip 1.25em\hbox to 2.50em{\hss{rtems}\hss}%
+\hskip 1.50em\hbox to 2.00em{\hss{sapi}\hss}%
+\hskip 1.50em\hbox to 2.50em{\hss{score}\hss}%
+\hskip 1.00em\hbox to 3.00em{\hss{wrapup}\hss}%
+\vrule width0em height1.972ex depth0.812ex\par}
+@end tex
+@end ifset
+
+@ifset use-html
+                    C Executive
+                         |
+  +-----------+----------+-----------+----------+
+  |           |          |           |          |
+posix       rtems       sapi       score     wrapup
+@html
+@end html
+@end ifset
+
+This directory contains a set of subdirectories which
+contains the source files comprising the executive portion of
+the RTEMS development environment.  At this point the API
+specific and "supercore" source code files are separated into
+distinct directory trees.  The "rtems" and the "posix"
+subdirectories contain the C language source files for each
+module comprising the respective API.  Also included in this
+directory are the subdirectories "sapi" and "score" which are
+the supercore modules.  Within the "score" directory the CPU
+dependent modules are found.
+
+The "cpu" directory contains a subdirectory for each
+target CPU supported by the @value{RTEMS-RELEASE} release of the RTEMS
+executive.  Each processor directory contains the CPU dependent
+code necessary to host RTEMS.  The "no_cpu" directory provides a
+starting point for developing a new port to an unsupported
+processor.  The files contained within the "no_cpu" directory
+may also be used as a reference for the other ports to specific
+processors.
+
+@ifinfo
+@node Support Library Source Directory, Test Suite Source Directory, Executive Source Directory, Directory Structure Suites
+@end ifinfo
+@subsection Support Library Source Directory
+
+The "lib" directory contains the support libraries and BSPS.  
+Board support packages (BSPs), processor environment start up code,
+C library support, the KA9Q TCP/IP stack, common BSP header files,
+and miscellaneous support functions are provided in the subdirectories.
+These are combined with the RTEMS executive object to form the single 
+RTEMS library which installed.  
+
+@c
+@c  Tree 6 - Libraries
+@c
+
+
+The "libbsp" directory contains a directory for each CPU family supported
+by RTEMS.  Beneath each CPU directory is a directory for each BSP for that
+processor family.
+
+@c
+@c  Tree 7 - C BSP Library
+@c
+
+Th "libbsp" directory provides all the BSPs provided with this
+release of the RTEMS executive.  The subdirectories are
+divided,  as discussed previously, based on specific processor
+family, then further breaking down into specific target board
+environments.  The "shmdr" subdirectory provides the
+implementation of a shared memory driver which supports the
+multiprocessing portion of the executive.  In addition, two
+starting point subdirectories are provided for reference.  The
+"no_cpu" subdirectory provides a template BSP which can be used
+to develop a specific BSP for an unsupported target board.  The
+"stubdr" subdirectory provides stubbed out BSPs.  These files
+may aid in preliminary testing of the RTEMS development
+environment that has been built for no particular target in mind.
+
+Below each CPU dependent directory is a directory for each target BSP
+supported in this release.
+
+Each BSP provides the modules which comprise an RTEMS BSP.  The 
+modules are separated into the subdirectories "clock", "console", 
+"include", "shmsupp", "startup", and "timer" as shown in the following 
+figure:
+
+@c
+@c  Tree 8 - Each BSP
+@c
+
+@ifset use-ascii
+@example
+@group
+                           Each BSP
+                               |
+  +-----------+----------+-----+-----+----------+----------+
+  |           |          |           |          |          |
+clock      console    include     shmsupp    startup     timer
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@sp 1
+
+@tex
+{\parskip=0pt\offinterlineskip%
+\hskip 10.0em
+\hskip 10.25em\hbox to 4.50em{\hss{Each BSP}\hss}%
+\vrule width0em height1.972ex depth0.812ex\par\penalty10000
+\hskip 10.0em
+\hskip 12.50em\vrule width.04em%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 10.0em
+\hskip 1.25em\vrule width11.25em height-0.407ex depth0.500ex%
+\vrule width.04em\vrule width11.25em height-0.407ex depth0.500ex%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 10.0em
+\hskip 1.25em\vrule width.04em%
+\hskip 4.46em\vrule width.04em%
+\hskip 4.46em\vrule width.04em%
+\hskip 4.46em\vrule width.04em%
+\hskip 4.46em\vrule width.04em%
+\hskip 4.46em\vrule width.04em%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 10.0em
+\hskip 0.00em\hbox to 2.50em{\hss{clock}\hss}%
+\hskip 1.50em\hbox to 3.50em{\hss{console}\hss}%
+\hskip 1.00em\hbox to 3.50em{\hss{include}\hss}%
+\hskip 1.00em\hbox to 3.50em{\hss{shmsupp}\hss}%
+\hskip 1.00em\hbox to 3.50em{\hss{startup}\hss}%
+\hskip 1.50em\hbox to 2.50em{\hss{timer}\hss}%
+\vrule width0em height1.972ex depth0.812ex\par}
+@end tex
+@end ifset
+
+@ifset use-html
+                           Each BSP
+                               |
+  +-----------+----------+-----+-----+----------+----------+
+  |           |          |           |          |          |
+clock      console    include     shmsupp    startup     timer
+@html
+@end html
+@end ifset
+
+@ifinfo
+@node Test Suite Source Directory, Sample Applications, Support Library Source Directory, Directory Structure Suites
+@end ifinfo
+@subsection Test Suite Source Directory
+
+The "tests" directory structure for the C
+implementation is as follows:
+
+@c
+@c  Tree 9 - C Tests
+@c
+
+@ifset use-ascii
+@example
+@group
+                                C Tests
+                                   |
+   +----------+---------+----------+---------+---------+---------+
+   |          |         |          |         |         |         |
+libtests   sptests   support    tmtests   mptests    tools    samples
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@sp 1
+
+@tex
+{\parskip=0pt\offinterlineskip%
+\hskip 05.0em
+\hskip 14.50em\hbox to 3.50em{\hss{C Tests}\hss}%
+\vrule width0em height1.972ex depth0.812ex\par\penalty10000
+\hskip 05.0em
+\hskip 16.25em\vrule width.04em%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 05.0em
+\hskip 2.00em\vrule width14.25em height-0.407ex depth0.500ex%
+\vrule width.04em\vrule width14.25em height-0.407ex depth0.500ex%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 05.0em
+\hskip 2.00em\vrule width.04em%
+\hskip 4.71em\vrule width.04em%
+\hskip 4.71em\vrule width.04em%
+\hskip 4.71em\vrule width.04em%
+\hskip 4.71em\vrule width.04em%
+\hskip 4.71em\vrule width.04em%
+\hskip 4.71em\vrule width.04em%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 05.0em
+\hskip 0.00em\hbox to 4.00em{\hss{libtests}\hss}%
+\hskip 1.00em\hbox to 3.50em{\hss{sptests}\hss}%
+\hskip 1.25em\hbox to 3.50em{\hss{support}\hss}%
+\hskip 1.25em\hbox to 3.50em{\hss{tmtests}\hss}%
+\hskip 1.25em\hbox to 3.50em{\hss{mptests}\hss}%
+\hskip 1.75em\hbox to 2.50em{\hss{tools}\hss}%
+\hskip 1.75em\hbox to 3.50em{\hss{samples}\hss}%
+\vrule width0em height1.972ex depth0.812ex\par}
+@end tex
+@end ifset
+
+@ifset use-html
+                                C Tests
+                                   |
+   +----------+---------+----------+---------+---------+---------+
+   |          |         |          |         |         |         |
+libtests   sptests   support    tmtests   mptests    tools    samples
+@html
+@end html
+@end ifset
+
+This directory provides the entire RTEMS Test Suite
+which includes the single processor tests, multiprocessor tests,
+timing tests, library tests, and sample tests.   Additionally,
+subdirectories for support functions and test related header
+files are provided.
+
+The "sptests" subdirectory consists of twenty-four
+tests designed to cover the entire executive code.  The
+"spfatal" test will verify any code associated with the
+occurrence of a fatal error.   Also provided is a test which
+will determine the size of the RTEMS executive.
+
+The multiprocessor test are provided in "mptests".
+Fourteen tests are provided in this subdirectory which address
+two node configurations and cover the multiprocessor code found
+in RTEMS.
+
+Tests that time each directive and a set of critical
+executive functions are provided in the "tmtests" subdirectory.
+Within this subdirectory  thirty-one tests are provided along
+with a subdirectory to contain each targets timing results.
+
+The "samples" directory structure for the C
+implementation is as follows:
+
+@c
+@c  Tree 10 - C Samples
+@c
+
+@ifset use-ascii
+@example
+@group
+                            C Samples
+                                |
+   +-----------+----------+-----+-----+----------+----------+
+   |           |          |           |          |          |
+base_mp     base_sp    cdtest       hello     paranoia    ticker
+@end group
+@end example
+@end ifset
+
+@ifset use-tex
+@sp 1
+
+@tex
+{\parskip=0pt\offinterlineskip%
+\hskip 05.0em
+\hskip 12.25em\hbox to 4.50em{\hss{C Samples}\hss}%
+\vrule width0em height1.972ex depth0.812ex\par\penalty10000
+\hskip 05.0em
+\hskip 14.50em\vrule width.04em%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 05.0em
+\hskip 2.00em\vrule width12.50em height-0.407ex depth0.500ex%
+\vrule width.04em\vrule width12.50em height-0.407ex depth0.500ex%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 05.0em
+\hskip 2.00em\vrule width.04em%
+\hskip 4.96em\vrule width.04em%
+\hskip 4.96em\vrule width.04em%
+\hskip 4.96em\vrule width.04em%
+\hskip 4.96em\vrule width.04em%
+\hskip 4.96em\vrule width.04em%
+\vrule width0em height1.500ex depth0.500ex\par\penalty10000
+\hskip 05.0em
+\hskip 0.00em\hbox to 4.00em{\hss{base\_mp}\hss}%
+\hskip 1.00em\hbox to 4.00em{\hss{base\_sp}\hss}%
+\hskip 1.50em\hbox to 3.00em{\hss{cdtest}\hss}%
+\hskip 2.25em\hbox to 2.50em{\hss{hello}\hss}%
+\hskip 1.75em\hbox to 4.00em{\hss{paranoia}\hss}%
+\hskip 1.50em\hbox to 3.00em{\hss{ticker}\hss}%
+\vrule width0em height1.972ex depth0.812ex\par}
+@end tex
+@end ifset
+
+@ifset use-html
+                            C Samples
+                                |
+   +-----------+----------+-----+-----+----------+----------+
+   |           |          |           |          |          |
+base_mp     base_sp    cdtest       hello     paranoia    ticker
+@html
+@end html
+@end ifset
+
+This directory provides sample application tests
+which aid in the testing a newly built RTEMS environment, a new
+BSP, or as starting points for the development of an application
+using the RTEMS executive.  A Hello World test is provided in
+the subdirectory "hello".  This test is helpful when testing new
+versions of RTEMS, BSPs, or modifications to any portion of the
+RTEMS development environment.  The "ticker" subdirectory
+provides a test for verification of clock chip device drivers of
+BSPs.  A simple single processor test similar to those in the
+single processor test suite is provided in "base_sp".  A simple
+two node multiprocessor test capable of testing an newly
+developed MPCI layer is provided in "base_mp".  The "cdtest"
+subdirectory provides a simple C++ application using
+constructors and destructors.   The final sample test is a
+public domain floating point and math library toolset test is
+provided in "paranoia".
diff --git a/doc/develenv/intro.texi b/doc/develenv/intro.texi
new file mode 100644
index 0000000000..c8fdde131d
--- /dev/null
+++ b/doc/develenv/intro.texi
@@ -0,0 +1,56 @@
+@c
+@c  COPYRIGHT (c) 1988-1997.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+
+@ifinfo
+@node Introduction, Directory Structure, Top, Top
+@end ifinfo
+@chapter Introduction
+
+This document describes the RTEMS development
+environment.  Discussions are provided for the following topics:
+
+@itemize @bullet
+@item the directory structure used by RTEMS,
+
+@item usage of the GNU Make utility within the RTEMS
+development environment,
+
+@item sample applications, and
+
+@item the RTEMS specific utilities.
+@end itemize
+
+RTEMS was designed as a reusable software component.
+Highly reusable software such as RTEMS is typically distributed
+in the form of source code without providing any support tools.
+RTEMS is the foundation for a complex family of facilities
+including board support packages, device drivers, and support
+libraries.  The RTEMS Development Environment is not a CASE
+tool.  It is a collection of tools designed to reduce the
+complexity of using and enhancing the RTEMS family.  Tools are
+provided which aid in the management of the development,
+maintenance, and usage of RTEMS, its run-time support
+facilities, and applications which utilize the executive.
+
+A key component of the RTEMS development environment
+is the GNU family of free tools.  This is  robust set of
+development and POSIX compatible tools for which source code is
+freely available.  The primary compilers, assemblers, linkers,
+and make utility used by the RTEMS development team are the GNU
+tools.  They are highly portable supporting a wide variety of
+host computers and, in the case of the development tools, a wide
+variety of target processors.
+
+It is recommended that the RTEMS developer become
+familiar with the RTEMS Development Environment before
+proceeding with any modifications to the executive source tree.
+The source code for the executive is very modular and source
+code is divided amongst directories based upon functionality as
+well as dependencies on CPU and target board.  This organization
+is aimed at isolating and minimizing non-portable code.  This
+has the immediate result that adding support for a new CPU or
+target board requires very little "wandering" around the source
+tree.
diff --git a/doc/develenv/sample.texi b/doc/develenv/sample.texi
new file mode 100644
index 0000000000..3c7f55ab35
--- /dev/null
+++ b/doc/develenv/sample.texi
@@ -0,0 +1,287 @@
+@c
+@c  COPYRIGHT (c) 1988-1997.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+
+@ifinfo
+@node Sample Applications, Sample Applications Introduction, Test Suite Source Directory, Top
+@end ifinfo
+@chapter Sample Applications
+@ifinfo
+@menu
+* Sample Applications Introduction::
+* Sample Applications Hello World::
+* Sample Applications Clock Tick::
+* Sample Applications Base Single Processor Application::
+* Sample Applications Base Multiple Processor Application::
+* Sample Applications Constructor/Destructor C++ Application::
+* Sample Applications Paranoia Floating Point Application::
+@end menu
+@end ifinfo
+
+@ifinfo
+@node Sample Applications Introduction, Sample Applications Hello World, Sample Applications, Sample Applications
+@end ifinfo
+@section Introduction
+
+RTEMS is shipped with the following sample
+applications:
+
+@itemize @bullet
+@item Hello World - C and Ada
+
+@item Clock Tick - C and Ada
+
+@item Base Single Processor - C and Ada
+
+@item Base Multiple Processor - C and Ada
+
+@item Constructor/Destructor C++ Test - C only if C++
+enabled
+
+@item Paranoia Floating Point Test - C only
+@end itemize
+
+These applications are intended to illustrate the
+basic format of RTEMS single and multiple processor
+applications.  In addition, these relatively simple applications
+can be used to test locally developed board support packages and
+device drivers.
+
+The reader should be familiar with the terms used and
+material presented in the RTEMS C Applications User's Guide or
+the RTEMS Ada Applications User's Guide.
+
+@ifinfo
+@node Sample Applications Hello World, Sample Applications Clock Tick, Sample Applications Introduction, Sample Applications
+@end ifinfo
+@section Hello World
+
+This sample application is in the following directory:
+
+@example
+$RTEMS_SRC_BASE/tests/samples/hello
+@end example
+
+It provides a rudimentary test of the BSP start up
+code and the console output routine.  The C version of this
+sample application uses the printf function from the RTEMS
+Standard C Library to output messages.   The Ada version of this
+sample use the TEXT_IO package to output the hello messages.
+The following messages are printed:
+
+@example
+@group
+*** HELLO WORLD TEST ***
+Hello World
+*** END OF HELLO WORLD TEST ***
+@end group
+@end example
+
+These messages are printed from the application's
+single initialization task.  If the above messages are not
+printed correctly, then either the BSP start up code or the
+console output routine is not operating properly.
+
+@ifinfo
+@node Sample Applications Clock Tick, Sample Applications Base Single Processor Application, Sample Applications Hello World, Sample Applications
+@end ifinfo
+@section Clock Tick
+
+This sample application is in the following directory:
+
+@example
+$RTEMS_SRC_BASE/tests/samples/ticker
+@end example
+
+This application is designed as a simple test of the
+clock tick device driver.  In addition, this application also
+tests the printf function from the RTEMS Standard C Library by
+using it to output the following messages:
+
+@example
+@group
+*** CLOCK TICK TEST ***
+TA1 - tm_get - 09:00:00   12/31/1988
+TA2 - tm_get - 09:00:00   12/31/1988
+TA3 - tm_get - 09:00:00   12/31/1988
+TA1 - tm_get - 09:00:05   12/31/1988
+TA1 - tm_get - 09:00:10   12/31/1988
+TA2 - tm_get - 09:00:10   12/31/1988
+TA1 - tm_get - 09:00:15   12/31/1988
+TA3 - tm_get - 09:00:15   12/31/1988
+TA1 - tm_get - 09:00:20   12/31/1988
+TA2 - tm_get - 09:00:20   12/31/1988
+TA1 - tm_get - 09:00:25   12/31/1988
+TA1 - tm_get - 09:00:30   12/31/1988
+TA2 - tm_get - 09:00:30   12/31/1988
+TA3 - tm_get - 09:00:30   12/31/1988
+*** END OF CLOCK TICK TEST ***
+@end group
+@end example
+
+The clock tick sample application utilizes a single
+initialization task and three copies of the single application
+task.  The initialization task prints the test herald, sets the
+time and date, and creates and starts the three application
+tasks before deleting itself.  The three application tasks
+generate the rest of the output.  Every five seconds, one or
+more of the tasks will print the current time obtained via the
+tm_get directive.  The first task, TA1, executes every five
+seconds, the second task, TA2, every ten seconds, and the third
+task, TA3, every fifteen seconds. If the time printed does not
+match the above output, then the clock device driver is not
+operating properly.
+
+@ifinfo
+@node Sample Applications Base Single Processor Application, Sample Applications Base Multiple Processor Application, Sample Applications Clock Tick, Sample Applications
+@end ifinfo
+@section Base Single Processor Application
+
+This sample application is in the following directory:
+
+@example
+$RTEMS_SRC_BASE/tests/samples/base_sp
+@end example
+
+It provides a framework from which a single processor
+RTEMS application can be developed. The use of the task argument
+is illustrated.  This sample application uses the printf
+function from the RTEMS Standard C Library or TEXT_IO functions
+when using the Ada version to output the following messages:
+
+@example
+@group
+*** SAMPLE SINGLE PROCESSOR APPLICATION ***
+Creating and starting an application task
+Application task was invoked with argument (0) and has id of 0x10002
+*** END OF SAMPLE SINGLE PROCESSOR APPLICATION ***
+@end group
+@end example
+
+The first two messages are printed from the
+application's single initialization task.  The final messages
+are printed from the single application task.
+
+@ifinfo
+@node Sample Applications Base Multiple Processor Application, Sample Applications Constructor/Destructor C++ Application, Sample Applications Base Single Processor Application, Sample Applications
+@end ifinfo
+@section Base Multiple Processor Application
+
+This sample application is in the following directory:
+
+@example
+$RTEMS_SRC_BASE/tests/samples/base_mp
+@end example
+
+It provides a framework from which a multiprocessor
+RTEMS application can be developed. This directory has a
+subdirectory for each node in the multiprocessor system.  The
+task argument is used to distinguish the node on which the
+application task is executed.  The first node will print the
+following messages:
+
+@example
+@group
+*** SAMPLE MULTIPROCESSOR APPLICATION ***
+Creating and starting an application task
+This task was invoked with the node argument (1)
+This task has the id of 0x10002
+*** END OF SAMPLE MULTIPROCESSOR APPLICATION ***
+@end group
+@end example
+
+The second node will print the following messages:
+
+@example
+@group
+*** SAMPLE MULTIPROCESSOR APPLICATION ***
+Creating and starting an application task
+This task was invoked with the node argument (2)
+This task has the id of 0x20002
+*** END OF SAMPLE MULTIPROCESSOR APPLICATION ***
+@end group
+@end example
+
+The herald is printed from the application's single
+initialization task on each node.  The final messages are
+printed from the single application task on each node.
+
+In this sample application, all source code is shared
+between the nodes except for the node dependent configuration
+files.  These files contains the definition of the node number
+used in the initialization of the  RTEMS Multiprocessor
+Configuration Table. This file is not shared because the node
+number field in the RTEMS Multiprocessor Configuration Table
+must be unique on each node.
+
+@ifinfo
+@node Sample Applications Constructor/Destructor C++ Application, Sample Applications Paranoia Floating Point Application, Sample Applications Base Multiple Processor Application, Sample Applications
+@end ifinfo
+@section Constructor/Destructor C++ Application
+
+This sample application is in the following directory:
+
+@example
+$RTEMS_SRC_BASE/tests/samples/cdtest
+@end example
+
+This sample application demonstrates that RTEMS is
+compatible with C++ applications.  It uses constructors,
+destructor, and I/O stream output in testing these various
+capabilities.  The board support package responsible for this
+application must support a C++ environment.
+
+This sample application uses the printf function from
+the RTEMS Standard C Library to output the following messages:
+
+@example
+@group
+Hey I'M in base class constructor number 1 for 0x400010cc.
+Hey I'M in base class constructor number 2 for 0x400010d4.
+Hey I'M in derived class constructor number 3 for 0x400010d4.
+*** CONSTRUCTOR/DESTRUCTOR TEST ***
+Hey I'M in base class constructor number 4 for 0x4009ee08.
+Hey I'M in base class constructor number 5 for 0x4009ee10.
+Hey I'M in base class constructor number 6 for 0x4009ee18.
+Hey I'M in base class constructor number 7 for 0x4009ee20.
+Hey I'M in derived class constructor number 8 for 0x4009ee20.
+Testing a C++ I/O stream
+Hey I'M in derived class constructor number 8 for 0x4009ee20.
+Derived class - Instantiation order 8
+Hey I'M in base class constructor number 7 for 0x4009ee20.
+Instantiation order 8
+Hey I'M in base class constructor number 6 for 0x4009ee18.
+Instantiation order 6
+Hey I'M in base class constructor number 5 for 0x4009ee10.
+Instantiation order 5
+Hey I'M in base class constructor number 4 for 0x4009ee08.
+Instantiation order 5
+*** END OF CONSTRUCTOR/DESTRUCTOR TEST ***
+Hey I'M in base class constructor number 3 for 0x400010d4.
+Hey I'M in base class constructor number 2 for 0x400010d4.
+Hey I'M in base class constructor number 1 for 0x400010cc.
+@end group
+@end example
+
+@ifinfo
+@node Sample Applications Paranoia Floating Point Application, RTEMS Specific Utilities, Sample Applications Constructor/Destructor C++ Application, Sample Applications
+@end ifinfo
+@section Paranoia Floating Point Application
+
+This sample application is in the following directory:
+
+@example
+$RTEMS_SRC_BASE/tests/samples/paranoia
+@end example
+
+This sample application uses a public domain floating
+point and math library test to verify these capabilities of the
+RTEMS executive.  Deviations between actual and expected results
+are reported to the screen.  This is a very extensive test which
+tests all mathematical and number conversion functions.
+Paranoia is also very large and requires a long period of time
+to run.   Problems which commonly prevent this test from
+executing to completion include stack overflow and FPU exception
+handlers not installed.
diff --git a/doc/develenv/utils.texi b/doc/develenv/utils.texi
new file mode 100644
index 0000000000..b76c94ae7e
--- /dev/null
+++ b/doc/develenv/utils.texi
@@ -0,0 +1,310 @@
+@c
+@c  COPYRIGHT (c) 1988-1997.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+
+@ifinfo
+@node RTEMS Specific Utilities, RTEMS Specific Utilities C Language Specific Utilities, Sample Applications Paranoia Floating Point Application, Top
+@end ifinfo
+@chapter RTEMS Specific Utilities
+@ifinfo
+@menu
+* RTEMS Specific Utilities C Language Specific Utilities::
+* RTEMS Specific Utilities Ada Language Specific Utilities::
+@end menu
+@end ifinfo
+
+This section describes the additional commands
+available within the RTEMS Development Environment.  Although
+some of these commands are of general use, most are included to
+provide some capability necessary to perform a required function
+in the development of the RTEMS executive, one of its support
+components, or an RTEMS based application.  The commands have
+been classified into the following categories for clarity:
+
+@itemize @bullet
+@item C Language Specific Utilities
+
+@item Ada Language Specific Utilities
+@end itemize
+
+Some of the commands are implemented as C programs.
+However, most commands are implemented as Bourne shell scripts.
+Even if the current user has selected a different shell, the
+scripts will automatically invoke the Bourne shell during their
+execution lifetime.
+
+The commands are presented in UNIX manual page style
+for compatibility and convenience.  A standard set of paragraph
+headers were used for all of the command descriptions.  If a
+section contained no data, the paragraph header was omitted to
+conserve space.  Each of the permissible paragraph headers and
+their contents are described below:
+
+@table @code
+@item SYNOPSIS
+describes the command syntax
+
+@item DESCRIPTION
+a full description of the command
+
+@item OPTIONS
+describes each of the permissible options for the command
+
+@item NOTES
+lists any special noteworthy comments about the command
+
+@item ENVIRONMENT
+describes all environment variables utilized by the command
+
+@item EXAMPLES
+illustrates the use of the command with specific examples
+
+@item FILES
+provides a list of major files that the command references
+
+@item SEE ALSO
+lists any relevant commands which can be consulted
+@end table
+
+Most environment variables referenced by the commands
+are defined for the RTEMS Development Environment during the
+login procedure.  During login, the user selects a default RTEMS
+environment through the use of the Modules package.  This tool
+effectively sets the environment variables to provide a
+consistent development environment for a specific user.
+Additional environment variables within the RTEMS environment
+were set by the system administrator during installation.  When
+specifying paths, a command description makes use of these
+environment variables.
+
+When referencing other commands in the SEE ALSO
+paragraph, the following notation is used:   command(code).
+Where command is the name of a related command, and code is a
+section number.  Valid section numbers are as follows:
+
+@table @code
+@item 1 
+Section 1 of the standard UNIX documentation
+
+@item  1G 
+Section 1 of the GNU documentation
+
+@item  1R 
+a manual page from this document, the RTEMS Development Environment Guide
+@end table
+
+For example, ls(1) means see the standard ls command
+in section 1 of the UNIX documentation.  gcc020(1G) means see
+the description of gcc020 in section 1 of the GNU documentation.
+
+@ifinfo
+@node RTEMS Specific Utilities C Language Specific Utilities, packhex - Compress Hexadecimal File, RTEMS Specific Utilities, RTEMS Specific Utilities
+@end ifinfo
+@section C Language Specific Utilities
+@ifinfo
+@menu
+* packhex - Compress Hexadecimal File::
+* unhex - Convert Hexadecimal File into Binary::
+* size_rtems - report RTEMS size information::
+@end menu
+@end ifinfo
+
+The C language utilities provide a powerful set of
+tools which combine to allow operations within the RTEMS
+Development Environment to be consistent and easy to use.  Much
+effort was devoted to providing as close to the standard UNIX
+and GNU style of operations as possible.  Each of these
+utilities are described in the section below.
+
+@ifinfo
+@node packhex - Compress Hexadecimal File, unhex - Convert Hexadecimal File into Binary, RTEMS Specific Utilities C Language Specific Utilities, RTEMS Specific Utilities C Language Specific Utilities
+@end ifinfo
+@subsection packhex - Compress Hexadecimal File
+
+@subheading SYNOPSIS
+
+@example
+packhex <source >destination
+@end example
+
+@subheading DESCRIPTION
+
+packhex accepts Intel Hexadecimal or Motorola Srecord
+on its standard input and attempts to pack as many contiguous
+bytes as possible into a single hexadecimal record.  Many
+programs output hexadecimal records which are less than 80 bytes
+long (for human viewing).  The overhead required by each
+unnecessary record is significant and packhex can often reduce
+the size of the download image by 20%.  packhex attempts to
+output records which are as long as the hexadecimal format
+allows.
+
+@subheading OPTIONS
+
+This command has no options.
+
+@subheading EXAMPLES
+
+Assume the current directory contains the Motorola
+Srecord file download.sr. Then executing the command:
+
+@example
+packhex <download.sr >packed.sr
+@end example
+
+will generate the file packed.sr which is usually
+smaller than download.sr.
+
+@subheading CREDITS
+
+The source for packhex first appeared in the May 1993
+issue of Embedded Systems magazine.  The code was downloaded
+from their BBS.  Unfortunately, the author's name was not
+provided in the listing.
+
+@ifinfo
+@node unhex - Convert Hexadecimal File into Binary, size_rtems - report RTEMS size information, packhex - Compress Hexadecimal File, RTEMS Specific Utilities C Language Specific Utilities
+@end ifinfo
+@subsection unhex - Convert Hexadecimal File into Binary Equivalent
+
+@subheading SYNOPSIS
+
+@example
+unhex [-valF] [-o file] [file [file ...] ]
+@end example
+
+@subheading DESCRIPTION
+
+unhex accepts Intel Hexadecimal, Motorola Srecord, or
+TI 'B' records and converts them to their binary equivalent.
+The output may sent to standout or may be placed in a specified
+file with the -o option.  The designated output file may not be
+an input file.  Multiple input files may be specified with their
+outputs logically concatenated into the output file.
+
+@subheading OPTIONS
+
+This command has the following options:
+
+@table @code
+@item v
+Verbose
+
+@item a base
+First byte of output corresponds with base
+address
+
+@item l
+Linear Output
+
+@item o file
+Output File
+
+@item F k_bits
+Fill holes in input with 0xFFs up to k_bits * 1024 bits
+@end table
+
+@subheading EXAMPLES
+
+The following command will create a binary equivalent
+file for the two Motorola S record files in the specified output
+file binary.bin:
+
+@example
+unhex -o binary.bin downloadA.sr downloadB.sr
+@end example
+
+@ifinfo
+@node size_rtems - report RTEMS size information, RTEMS Specific Utilities Ada Language Specific Utilities, unhex - Convert Hexadecimal File into Binary, RTEMS Specific Utilities C Language Specific Utilities
+@end ifinfo
+@subsection size_rtems - report RTEMS size information
+
+@subheading SYNOPSIS
+
+@example
+size_rtems
+@end example
+
+@subheading DESCRIPTION
+
+size_rtems analyzes RTEMS and determines all of the
+critical sizing information which is reported in the related
+documentation.
+
+@subheading EXAMPLES
+
+To generate the RTEMS size report for the currently
+configured processor, execute the following command:
+
+@example
+size_rtems
+@end example
+
+Although the actual size information will differ, a
+report of the following format will be output:
+
+@example
+     RTEMS SIZE REPORT
+
+CODE  DATA    BSS
+==================
+MANAGERS: 15988 0       0
+CORE    : 4568  0       0
+CPU     : 364   0       0
+OVERALL : 20556 0       0
+MINIMUM : 8752  0       0
+
+init    : 1592  0       0
+tasks   : 2440  0       0
+intr    : 64    0       0
+clock   : 2252  0       0
+sem     : 876   0       0
+msg     : 1624  0       0
+event   : 604   0       0
+signal  : 212   0       0
+part    : 872   0       0
+region  : 844   0       0
+dpmem   : 532   0       0
+timer   : 424   0       0
+io      : 288   0       0
+fatal   : 40    0       0
+rtmon   : 764   0       0
+mp      : 2984  0       0
+
+sem     : 4     0       0
+msg     : 4     0       0
+event   : 4     0       0
+signal  : 4     0       0
+part    : 4     0       0
+region  : 4     0       0
+timer   : 4     0       0
+dpmem   : 4     0       0
+io      : 4     0       0
+rtmon   : 4     0       0
+mp      : 8     0       0
+@end example
+
+@subheading SEE ALSO
+
+gsize020(1G), gsize386(1G), gsize960(1G)
+
+
+@ifinfo
+@node RTEMS Specific Utilities Ada Language Specific Utilities, Command and Variable Index, size_rtems - report RTEMS size information, RTEMS Specific Utilities
+@end ifinfo
+@section Ada Language Specific Utilities
+
+The Ada language utilities provide a powerful set of
+tools which combine to allow operations within the RTEMS
+Development Environment to be consistent and easy to use.  Much
+effort was devoted to providing as close to the standard UNIX
+and GNU style of operations as possible.  Each of these
+utilities are described in the section below.
+
+NOTE:  The Ada implementation is not included in this
+release.
+
+
+