user/conf.t: Address User Feedback from Stephen Tether

Stephen Tether <tether@slac.stanford.edu> posted to the users list:

http://www.rtems.org/pipermail/rtems-users/2013-April/011273.html

I tried to make the requested changes.

1 files changed, 78 insertions, 68 deletions

diff --git a/doc/user/conf.t b/doc/user/conf.t
index 412759a84c..a1aabd4cc3 100644
--- a/doc/user/conf.t
+++ b/doc/user/conf.t
@@ -20,17 +20,16 @@
 @section Introduction
 
 RTEMS must be configured for an application.  This configuration
-information encompasses a variety of information including
-the length of each clock tick, the maximum number of each RTEMS
-object that can be created, the application initialization tasks,
-the task scheduling algorithm to be used, and the device drivers in
-the application.
+encompasses a variety of information including the length of each clock
+tick, the maximum number of each information RTEMS object that can
+be created, the application initialization tasks, the task scheduling
+algorithm to be used, and the device drivers in the application.
 
 Although this information is contained in data structures that are used
-to RTEMS at system initialization time, the data structures themselves
-should only rarely to be generated by hand. RTEMS provides a macro based
-system which provides the standard and simple mechanism to automate the
-generation of these structures.
+by RTEMS at system initialization time, the data structures themselves
+should only rarely to be generated by hand. RTEMS provides a set of
+macros system which provides a simple standard mechanism to automate
+the generation of these structures.
 
 @ifset is-Ada
 System configuration is ALWAYS done from C.  When developing
@@ -46,7 +45,7 @@ and data structures shown in this chapter are in C.
 @cindex <rtems/confdefs.h>
 @findex <rtems/confdefs.h>
 
-The RTEMS header file @code{<rtems/confdefs.h>} is the core of the
+The RTEMS header file @code{<rtems/confdefs.h>} is at the core of the
 automatic generation of system configuration. It is based on the idea
 of setting macros which define configuration parameters of interest to
 the application and defaulting or calculating all others. This variety
@@ -55,19 +54,21 @@ required for an RTEMS application.
 
 Trivia: @code{confdefs} is shorthand for a @b{Configuration Defaults}.
 
-As a general rule, the application developer only specifies values
+As a general rule, application developers only specify values
 for the configuration parameters of interest to them. They define what
 resources or features they require. In most cases, when a parameter is
 not specified, it defaults to zero (0) instances, a standards compliant
 value, or disabled as appropriate. For example, by default there will be
 256 task priority levels but this can be lowered by the application. This
-number of priority levels is required to be standards compliant.
+number of priority levels is required to be compliant with the RTEID/ORKID
+standards upon which the Classic API is based. There are similar cases
+where the default is selected to be compliant with with the POSIX standard.
 
 For each configuration parameter in the configuration tables, the macro
-corresponding to that field is discussed. It is expected that all systems
-can be easily configured using the @code{<rtems/confdefs.h>} mechanism. It
-is also expected that using this mechanism will avoid internal RTEMS
-configuration changes impacting applications.
+corresponding to that field is discussed. The RTEMS Maintainers
+expect that all systems can be easily configured using the
+@code{<rtems/confdefs.h>} mechanism and that using this mechanism will
+avoid internal RTEMS configuration changes impacting applications.
 
 @c
 @c === Philospohy ===
@@ -77,7 +78,7 @@ configuration changes impacting applications.
 The user should be aware that the defaults are intentionally set as
 low as possible.  By default, no application resources are configured.
 The @code{<rtems/confdefs.h>} file ensures that at least one application
-tasks or thread is configured and that at least one of the initialization
+task or thread is configured and that at least one of the initialization
 task/thread tables is configured.
 
 @c
@@ -94,51 +95,53 @@ from the RTEMS Workspace.
 
 The @code{<rtems/confdefs.h>} mechanism calculates the size of the RTEMS
 Workspace automatically.  It assumes that all tasks are floating point and
-that all will be allocated the mininum stack space.  This calculation also
-automatically includes the memory that will be allocated for internal
-use by RTEMS. In the event, there is an under-estimation of the amount
-of memoryy required, the @code{CONFIGURE_MEMORY_OVERHEAD} is provided
-as a work-around.
-
-The starting address of the RTEMS Workspace is determined
-by the BSP must be aligned on at least a four-byte boundary.
-Failure to properly align the workspace area will result in the
-@code{@value{DIRPREFIX}fatal_error_occurred} directive being invoked
-with the @code{@value{RPREFIX}INVALID_ADDRESS} error code.
-
-The file @code{<rtems/confdefs.h>} will calculate the value that is
-specified as the @code{work_space_size} parameter of the Configuration
-Table. There are many parameters the application developer can
-specify to help @code{<rtems/confdefs.h>} in its calculations.
-Correctly specifying the application requirements via parameters such
-as @code{CONFIGURE_EXTRA_TASK_STACKS} and @code{CONFIGURE_MAXIMUM_TASKS}
+that all will be allocated the mininum stack space.  This calculation
+includes the amount of memory that will be allocated for internal use
+by RTEMS. The automatic calculation may underestimate the workspace
+size truly needed by the application, in which case one can use the
+@code{CONFIGURE_MEMORY_OVERHEAD} macro to add a value to the estimate. See
+@ref{Configuring a System Specify Memory Overhead} for more details.
+
+@c XXX - ************* REMOVE ME *************
+@c The starting address of the RTEMS Workspace is determined
+@c by the BSP and must be aligned on at least a four-byte boundary.
+@c Failure to properly align the workspace will result in the
+@c @code{@value{DIRPREFIX}fatal_error_occurred} directive being invoked
+@c with the @code{@value{RPREFIX}INVALID_ADDRESS} error code.
+
+The file @code{<rtems/confdefs.h>} will calculate the value of the
+@code{work_space_size} parameter of the Configuration Table. There
+are many parameters the application developer can specify to
+help @code{<rtems/confdefs.h>} in its calculations.  Correctly
+specifying the application requirements via parameters such as
+@code{CONFIGURE_EXTRA_TASK_STACKS} and @code{CONFIGURE_MAXIMUM_TASKS}
 is critical for production software.
 
-The allocation of objects can operate in two modes. The default mode
-has an object number ceiling. No more than the specified number of
-objects can be allocated from the RTEMS Workspace. The number of objects
-specified in the particular API Configuration table fields are
-allocated at initialisation. The second mode allows the number of
-objects to grow to use the available free memory in the RTEMS Workspace.
+For each class of objects, the allocation can operate in one of two ways.
+The default way has an ceiling on the maximum number of object instances
+which can concurrently exist in the system. Memory for all instances of
+that object class is reserved at system initialization.  The second
+way allocates memory for an initial number of objects and increases the
+current allocation by a fixed increment when required. Both ways allocate
+space from inside the RTEMS Workspace.
 
 See @ref{Configuring a System Unlimited Objects} for more details about
-the second mode, which allows for dynamic allocation of objects and
+the second way, which allows for dynamic allocation of objects and
 therefore does not provide determinism.  This mode is useful mostly for
 when the number of objects cannot be determined ahead of time or when
 porting software for which you do not know the object requirements.
 
-Note that future versions of RTEMS may not have the same memory
-requirements per object. Although the value calculated is sufficient
-for a particular target processor and release of RTEMS, memory usage
-is subject to change across versions and target processors.  To avoid
-problems, users should accurately specify each configuration parameter and
-allow @code{<rtems/confdefs.h>} to calculate the memory requirements.
-The memory requirements are likely to change each time one of the
-following events occurs:
+The space needed for stacks and for RTEMS objects will vary from
+one version of RTEMS and from one target processor to another.
+Therefore it is safest to use @code{<rtems/confdefs.h>} and specify
+your application's requirements in terms of the numbers of objects and
+multiples of @code{RTEMS_MINIMUM_STACK_SIZE}, as far as is possible. The
+automatic estimates of space required will in general change when:
 
 @itemize @bullet
-@item a configuration parameter is modified,
-@item task or interrupt stack requirements change,
+@item a configuration parameter is changed,
+@item task or interrupt stack sizes change,
+@item the floating point attribute of a task changes,
 @item task floating point attribute is altered,
 @item RTEMS is upgraded, or
 @item the target processor is changed.
@@ -151,7 +154,7 @@ with the appropriate error code.
 @c
 @c === Potential Issues ===
 @c
-@section Potential Issues with RTEMS Workspace Estimation
+@section Potential Issues with RTEMS Workspace Size Estimation
 
 The @code{<rtems/confdefs.h>} file estimates the amount of memory
 required for the RTEMS Workspace.  This estimate is only as accurate
@@ -163,7 +166,7 @@ too high or too low for a variety of reasons.  Some of the reasons that
 @item All tasks/threads are assumed to be floating point.
 @end itemize
 
-Conversely, there are many more reasons, the resource estimate could be
+Conversely, there are many more reasons that the resource estimate could be
 too low:
 
 @itemize @bullet
@@ -189,7 +192,7 @@ account for its resources.
 @section Configuration Example
 
 In the following example, the configuration information for a system
-with a single message queue, four (4) tasks, and a time slice
+with a single message queue, four (4) tasks, and a timeslice of
 fifty (50) milliseconds is as follows:
 
 @example
@@ -222,28 +225,35 @@ impact of these are as follows:
 
 @item The example specified @code{CONFIGURE_RTEMS_INIT_TASK_TABLE}
 but did not specify any additional parameters. This results in a
-configuration which will begin execution at  single initialization task
-named @code{Init} which is non-preemptible and at priority one (1).
+configuration of an application which will begin execution of a single
+initialization task named @code{Init} which is non-preemptible and at
+priority one (1).
 
 @item By specifying @code{CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER},
 this application is configured to have a clock tick device
-driver. This is required for the passage of time including
-delays and wall time. Further configuration details about time
-are provided. Per @code{CONFIGURE_MICROSECONDS_PER_TICK} and
+driver. Without a clock tick device driver, RTEMS has no way to know
+that time is passing and will be unable to support delays and wall
+time. Further configuration details about time are
+provided. Per @code{CONFIGURE_MICROSECONDS_PER_TICK} and
 @code{CONFIGURE_TICKS_PER_TIMESLICE}, the user specified they wanted a
 clock tick to occur each millisecond, and that the length of a timeslice
 would be fifty (50) milliseconds.
 
 @item By specifying @code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER},
-the application will include a console device driver. This provides
-for standard I/O) on at least @code{/dev/console}. Implicitly, the
-Configuration Defaults header file configures enough resources for three
-(3) file descriptors to be used for standard in, out, and error on a
-device that supports the POSIX @i{termios} interface.
-
-@item The example above specifies via @code{CONFIGURE_MAXIMUM_TASKS},
+the application will include a console device driver. Although the
+console device driver may support a combination of multiple serial
+ports and display and keyboard combinations, it is only required to
+provide a single device named @code{/dev/console}. This device will
+be used for Standard Input, Output and Error I/O Streams. Thus when
+@code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER} is specified, implicitly
+three (3) file descriptors are reserved for the Standard I/O Streams and
+those file descriptors are associated with @code{/dev/console} during
+initialization. All console devices are expected to support the POSIX
+@i{termios} interface.
+
+@item The example above specifies via @code{CONFIGURE_MAXIMUM_TASKS}
 that the application requires a maximum of four (4)
-concurrently existent Classic API tasks. Similarly, by specifying
+simultaneously existing Classic API tasks. Similarly, by specifying
 @code{CONFIGURE_MAXIMUM_MESSAGE_QUEUES}, there may be a maximum of only
 one (1) concurrently existent Classic API message queues.