2008-06-13 Joel Sherrill <joel.sherrill@oarcorp.com>

	* user/bsp.t, user/conf.t, user/task.t: Add ability for application to
	configure minimum stack size. Add RTEMS_CONFIGURED_MINIMUM_STACK_SIZE
	constant so user can clearly indicate they want the configured as
	opposed to the recommended minimum stack size.

4 files changed, 73 insertions, 42 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index b749e1412f..776538a16a 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,10 @@
+2008-06-13	Joel Sherrill <joel.sherrill@oarcorp.com>
+
+	* user/bsp.t, user/conf.t, user/task.t: Add ability for application to
+	configure minimum stack size. Add RTEMS_CONFIGURED_MINIMUM_STACK_SIZE
+	constant so user can clearly indicate they want the configured as
+	opposed to the recommended minimum stack size.
+
 2008-06-06	Joel Sherrill <joel.sherrill@oarcorp.com>
 
 	* started/buildc.t: Add paragraph on see CVS for latest patches.
diff --git a/doc/user/bsp.t b/doc/user/bsp.t
index 50ff42ee11..7d722a01d4 100644
--- a/doc/user/bsp.t
+++ b/doc/user/bsp.t
@@ -65,8 +65,13 @@ following requirements:
 @item If the processor supports multiple privilege levels, must leave
 the processor in the most privileged, or supervisory, state.
 
-@item Must allocate a stack of at least @code{@value{RPREFIX}MINIMUM_STACK_SIZE}
-bytes and initialize the stack pointer for the initialization process.
+@item Must allocate a stack of sufficient size to execute the initialization
+and shutdown of the system.  This stack area will NOT be used by any task
+once the system is initialized.  This stack is often reserved via the
+linker script or in the assembly language start up file.
+
+@item Must initialize the stack pointer for the initialization process to
+that allocated.
 
 @item Must initialize the processor's Interrupt Vector Table.
 
@@ -107,7 +112,7 @@ stack usage must account for the following requirements:
 @end itemize
 
 The size of the interrupt stack must be greater than or equal to the
-constant @code{@value{RPREFIX}MINIMUM_STACK_SIZE}.
+confugured minimum stack size.
 
 @subsection Processors with a Separate Interrupt Stack
 
diff --git a/doc/user/conf.t b/doc/user/conf.t
index aeb79e390d..cfe2afd48a 100644
--- a/doc/user/conf.t
+++ b/doc/user/conf.t
@@ -204,16 +204,6 @@ This section defines the general system configuration parameters supported by
 if the application is providing their own complete set of configuration 
 tables.
 
-@findex CONFIGURE_INTERRUPT_STACK_SIZE
-@item @code{CONFIGURE_INTERRUPT_STACK_SIZE} is set to the 
-size of the interrupt stack.  The interrupt stack size is
-usually set by the BSP but since this memory is allocated
-from the RTEMS Ram Workspace, it must be accounted for.  The
-default for this field is RTEMS_MINIMUM_STACK_SIZE.  [NOTE:
-In some BSPs, changing this constant does NOT change the
-size of the interrupt stack, only the amount of memory
-reserved for it.]
-
 @findex CONFIGURE_EXECUTIVE_RAM_WORK_AREA
 @item @code{CONFIGURE_EXECUTIVE_RAM_WORK_AREA} is the base 
 address of the RTEMS RAM Workspace.  By default, this value
@@ -232,9 +222,15 @@ default, this is 50.
 
 @fnindex CONFIGURE_INTERRUPT_STACK_SIZE
 @item @code{CONFIGURE_INTERRUPT_STACK_SIZE} is set to the 
-desired stack size for the interrupt.  If not specified,
-the interrupt stack will be of minimum size.  The default
-value is @code{RTEMS_MINIMUM_STACK_SIZE}.
+size of the interrupt stack.  The interrupt stack size is
+usually set by the BSP but since this memory may be allocated
+from the RTEMS Ram Workspace, it must be accounted for.  The
+default for this field is the configured minimum stack size.  [NOTE:
+In some BSPs, changing this constant does NOT change the
+size of the interrupt stack, only the amount of memory
+reserved for it.] If not specified, the interrupt stack
+will be of minimum size.  The default value is the configured
+minimum stack size.
 
 @findex CONFIGURE_TASK_STACK_ALLOCATOR
 @item @code{CONFIGURE_TASK_STACK_ALLOCATOR}
@@ -333,7 +329,7 @@ be used.  The default value is NULL.
 @item @code{CONFIGURE_IDLE_TASK_STACK_SIZE} is set to the 
 desired stack size for the IDLE task.  If not specified,
 the IDLE task will have a stack of minimum size.  The default
-value is @code{RTEMS_MINIMUM_STACK_SIZE}.
+value is the configured minimum stack size.
 
 @end itemize
 
@@ -553,7 +549,7 @@ the value is @code{rtems_build_name( 'U', 'I', '1', ' ' )}.
 is the stack size
 of the single initialization task defined by the
 Classic API Initialization Tasks Table.  By default
-the value is @code{RTEMS_MINIMUM_STACK_SIZE}.
+value is the configured minimum stack size.
 
 @findex CONFIGURE_INIT_TASK_PRIORITY
 @item @code{CONFIGURE_INIT_TASK_PRIORITY}
@@ -677,7 +673,7 @@ the value is @code{POSIX_Init}.
 @item @code{CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE}
 is the stack size of the single initialization thread defined by the
 POSIX API Initialization Threads Table.  By default
-the value is @code{RTEMS_MINIMUM_STACK_SIZE * 2}.
+value is twice the configured minimum stack size.
 
 @end itemize
 
@@ -786,7 +782,7 @@ in the ITRON API.
 @item @code{CONFIGURE_ITRON_INIT_TASK_STACK_SIZE}
 is the stack size of the single initialization task defined by the
 ITRON API Initialization Tasks Table.  By default
-the value is @code{RTEMS_MINIMUM_STACK_SIZE}.
+value is the configured minimum stack size.
 
 @end itemize
 
@@ -912,22 +908,18 @@ for configuring an RTEMS application, the value for this field
 corresponds to the setting of the macro @code{CONFIGURE_IDLE_TASK_BODY}.
 
 @item idle_task_stack_size
-is the size of the RTEMS idle task stack in bytes.  
-If this number is less than MINIMUM_STACK_SIZE, then the 
-idle task's stack will be MINIMUM_STACK_SIZE in bytes.
-When using the @code{rtems/confdefs.h} mechanism
-for configuring an RTEMS application, the value for this field
-corresponds to the setting of the macro
-@code{CONFIGURE_IDLE_TASK_STACK_SIZE}.
+is the size of the RTEMS idle task stack in bytes.  If this number is less
+than the configured minimum stack size, then the idle task's stack will
+be set to the minimum.  When using the @code{rtems/confdefs.h} mechanism
+for configuring an RTEMS application, the value for this field corresponds
+to the setting of the macro @code{CONFIGURE_IDLE_TASK_STACK_SIZE}.
 
 @item interrupt_stack_size
-is the size of the RTEMS interrupt stack in bytes.  
-If this number is less than MINIMUM_STACK_SIZE, then the 
-interrupt stack will be MINIMUM_STACK_SIZE in bytes.
-When using the @code{rtems/confdefs.h} mechanism
-for configuring an RTEMS application, the value for this field
-corresponds to the setting of the macro
-@code{CONFIGURE_INTERRUPT_STACK_SIZE}.
+is the size of the RTEMS interrupt stack in bytes.  If this number is less
+than configured minimum stack size, then the interrupt stack will be set
+to the minimum.  When using the @code{rtems/confdefs.h} mechanism for
+configuring an RTEMS application, the value for this field corresponds
+to the setting of the macro @code{CONFIGURE_INTERRUPT_STACK_SIZE}.
 
 @item stack_allocate_hook
 may point to a user provided routine to allocate task stacks.
@@ -1182,7 +1174,8 @@ to the task name of @code{"UI1 "} for User Initialization Task 1.
 
 @item @code{CONFIGURE_INIT_TASK_STACK_SIZE} - is the stack size
 of the single initialization task.  If this macro is not defined
-by the application, then this defaults to @code{RTEMS_MINIMUM_STACK_SIZE}.
+by the application, then this defaults to configured minimum
+stack size.
 
 @item @code{CONFIGURE_INIT_TASK_PRIORITY} - is the initial priority
 of the single initialization task.  If this macro is not defined
@@ -1333,8 +1326,8 @@ then this defaults to the C routine @code{POSIX_Init}.
 
 @item @code{CONFIGURE_POSIX_INIT_TASK_STACK_SIZE} - is the stack size
 of the single initialization thread.  If this macro is not defined
-by the application, then this defaults to
-@code{(RTEMS_MINIMUM_STACK_SIZE * 2)}.
+by the application, then this defaults to twice the configured
+minimum stack size.
 
 @end itemize
  
diff --git a/doc/user/task.t b/doc/user/task.t
index 8ab2ecdb2f..e8a3390665 100644
--- a/doc/user/task.t
+++ b/doc/user/task.t
@@ -744,11 +744,37 @@ This directive will not cause the calling task to be preempted.
 
 Valid task priorities range from a high of 1 to a low of 255.
 
-If the requested stack size is less than
-@code{@value{RPREFIX}MINIMUM_STACK_SIZE} bytes, then RTEMS
-will use @code{@value{RPREFIX}MINIMUM_STACK_SIZE} as the
-stack size.  The value of @code{@value{RPREFIX}MINIMUM_STACK_SIZE}
-is processor dependent. 
+If the requested stack size is less than the configured
+minimum stack size, then RTEMS will use the configured
+minimum as the stack size for this task.  In addition
+to being able to specify the task stack size as a integer,
+there are two constants which may be specified:
+
+@itemize @bullet
+@item @code{@value{RPREFIX}MINIMUM_STACK_SIZE} 
+is the minimum stack size @b{RECOMMENDED} for use on this processor.
+This value is selected by the RTEMS developers conservatively to
+minimize the risk of blown stacks for most user applications.
+Using this constant when specifying the task stack size, indicates
+that the stack size will be at least
+@code{@value{RPREFIX}MINIMUM_STACK_SIZE} bytes in size.  If the
+user configured minimum stack size is larger than the recommended
+minimum, then it will be used.
+
+@item @code{@value{RPREFIX}CONFIGURED_MINIMUM_STACK_SIZE} 
+indicates that this task is to be created with a stack size
+of the minimum stack size that was configured by the application.
+If not explicitly configured by the application, the default
+configured minimum stack size is the processor dependent value
+@code{@value{RPREFIX}MINIMUM_STACK_SIZE}.  Since this uses
+the configured minimum stack size value, you may get a stack
+size that is smaller or larger than the recommended minimum.  This
+can be used to provide large stacks for all tasks on complex
+applications or small stacks on applications that are trying
+to conserve memory.
+
+@end itemize
+
 Application developers should consider the stack usage of the
 device drivers when calculating the stack size required for
 tasks which utilize the driver.