2003-03-24 Joel Sherrill <joel@OARcorp.com>

* direct.t, sample.t, utils.t: Significantly updated.

doc/develenv/ChangeLog

@@ -1,3 +1,7 @@
+2003-03-24	Joel Sherrill <joel@OARcorp.com>
+
+	* direct.t, sample.t, utils.t: Significantly updated.
+
 2003-02-28	Joel Sherrill <joel@OARcorp.com>
 
 	* .cvsignore: Add newly generated .texi files.

doc/develenv/sample.t

@@ -10,38 +10,84 @@
 
 @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
+The RTEMS source distribution includes a set of sample applications
+that are located in the @code{$@{RTEMS_ROOT@}/c/src/tests/samples/}
+directory.  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.
+applications and the use of some features.  In addition, these
+relatively simple applications can be used to test locally
+developed board support packages and device drivers as they
+exercise a critical subset of RTEMS functionality that is often
+broken in new BSPs.
 
-The reader should be familiar with the terms used and
-material presented in the RTEMS Applications User's Guide.
+Each of the following sample applications will be listed in
+more detail in the following sections:
+
+@table @b
+@item Hello World
+The RTEMS Hello World test is provided in
+the subdirectory @code{$@{RTEMS_ROOT@}/c/src/tests/samples/hello/}.
+This test is helpful when testing new
+versions of RTEMS, BSPs, or modifications to any portion of the
+RTEMS development environment.  
+
+@item Clock Tick
+The @code{$@{RTEMS_ROOT@}/c/src/tests/samples/ticker/}
+subdirectory provides a test for verification of clock chip
+device drivers of BSPs.  
+
+@item Base Single Processor
+A simple single processor test similar to those in the
+single processor test suite is provided in
+@code{$@{RTEMS_ROOT@}/c/src/tests/samples/base_sp/}.
+
+@item Base Multiple Processor
+A simple two node multiprocessor test capable of testing an newly
+developed MPCI layer is provided in 
+@code{$@{RTEMS_ROOT@}/c/src/tests/samples/base_mp/}.
+
+@item Constructor/Destructor C++ Test
+The @code{$@{RTEMS_ROOT@}/c/src/tests/samples/cdtest/}
+subdirectory provides a simple C++ application using
+constructors and destructors.  It is only built when
+C++ is enabled.  
+
+
+@item Paranoia Floating Point Test
+The directory @code{$@{RTEMS_ROOT@}/c/src/tests/samples/paranoia/}
+contains the public domain floating point and math library test.
+
+@item Minimum Size Test
+The directory
+@code{$@{RTEMS_ROOT@}/c/src/tests/samples/minimum/}
+contains a simple RTEMS program that results in a non-functional 
+executable.  It is intended to show the size of a minimum footprint
+application based upon the current RTEMS configuration.  
+
+@item Unlimited Object Allocation
+The @code{$@{RTEMS_ROOT@}/c/src/tests/samples/unlimited/}
+directory contains a sample test that demonstrates the use of the
+@i{unlimited} object allocation configuration option to RTEMS.
+
+@item Network Loopback Test
+The @code{$@{RTEMS_ROOT@}/c/src/tests/samples/loopback/}
+directory contains a sample test that demonstrates the use of 
+sockets and the loopback network device.  It does not require
+the presence of network hardware in order to run.
+It is only built if RTEMS was configured with networking enabled.
+
+@end table
+
+The sample tests are written using the Classic API so the reader
+should be familiar with the terms used and
+material presented in the @b{RTEMS Applications Users Guide}.
 
 @section Hello World
 
 This sample application is in the following directory:
 
 @example
-$RTEMS_SRC_BASE/tests/samples/hello
+$@{RTEMS_ROOT@}/tests/samples/hello/
 @end example
 
 It provides a rudimentary test of the BSP start up
@@ -69,7 +115,7 @@ console output routine is not operating properly.
 This sample application is in the following directory:
 
 @example
-$RTEMS_SRC_BASE/tests/samples/ticker
+$@{RTEMS_ROOT@}/tests/samples/ticker/
 @end example
 
 This application is designed as a simple test of the
@@ -116,7 +162,7 @@ operating properly.
 This sample application is in the following directory:
 
 @example
-$RTEMS_SRC_BASE/tests/samples/base_sp
+$@{RTEMS_ROOT@}/tests/samples/base_sp/
 @end example
 
 It provides a framework from which a single processor
@@ -143,7 +189,7 @@ are printed from the single application task.
 This sample application is in the following directory:
 
 @example
-$RTEMS_SRC_BASE/tests/samples/base_mp
+$@{RTEMS_ROOT@}/tests/samples/base_mp/
 @end example
 
 It provides a framework from which a multiprocessor
@@ -192,7 +238,7 @@ must be unique on each node.
 This sample application is in the following directory:
 
 @example
-$RTEMS_SRC_BASE/tests/samples/cdtest
+$@{RTEMS_ROOT@}/tests/samples/cdtest/
 @end example
 
 This sample application demonstrates that RTEMS is
@@ -233,12 +279,28 @@ Hey I'M in base class constructor number 1 for 0x400010cc.
 @end group
 @end example
 
+@section Minimum Size Test
+
+This sample application is in the following directory:
+
+@example
+$@{RTEMS_ROOT@}/tests/samples/minimum/
+@end example
+
+This sample application is designed to produce the 
+minimum code space required for any RTEMS application
+based upon the current RTEMS configuration and
+BSP.  In many situations, the bulk of this executable
+consists of hardware and RTEMS initialization, basic
+infrastructure such as malloc(), and RTEMS and
+hardware shutdown support.
+
 @section Paranoia Floating Point Application
 
 This sample application is in the following directory:
 
 @example
-$RTEMS_SRC_BASE/tests/samples/paranoia
+$@{RTEMS_ROOT@}/tests/samples/paranoia/
 @end example
 
 This sample application uses a public domain floating
@@ -250,3 +312,17 @@ 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.
+
+@section Network Loopback Test
+
+This sample application is in the following directory:
+
+@example
+$@{RTEMS_ROOT@}/tests/samples/loopback/
+@end example
+
+This sample application uses the network loopback device to
+demonstrate the use of the RTEMS TCP/IP stack.  This sample
+test illustrates the basic configuration and initialization
+of the TCP/IP stack as well as simple socket usage.
+

doc/develenv/utils.t

@@ -9,18 +9,11 @@
 @chapter RTEMS Specific Utilities
 
 This section describes the additional commands
-available within the RTEMS Development Environment.  Although
+available within the @b{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
+components, or an RTEMS based application.  
 
 Some of the commands are implemented as C programs.
 However, most commands are implemented as Bourne shell scripts.
@@ -92,16 +85,10 @@ 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.
 
-@section C Language Specific Utilities
-
-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.
-
-@subsection packhex - Compress Hexadecimal File
+@c
+@c packhex
+@c
+@section packhex - Compress Hexadecimal File
 
 @subheading SYNOPSIS
 
@@ -144,7 +131,10 @@ issue of Embedded Systems magazine.  The code was downloaded
 from their BBS.  Unfortunately, the author's name was not
 provided in the listing.
 
-@subsection unhex - Convert Hexadecimal File into Binary Equivalent
+@c
+@c unhex
+@c
+@section unhex - Convert Hexadecimal File into Binary Equivalent
 
 @subheading SYNOPSIS
 
@@ -193,7 +183,10 @@ file binary.bin:
 unhex -o binary.bin downloadA.sr downloadB.sr
 @end example
 
-@subsection size_rtems - report RTEMS size information
+@c
+@c size_rtems
+@c
+@section size_rtems - report RTEMS size information
 
 @subheading SYNOPSIS