From b912f9573787439a919c3afd4930d2d2a4b68527 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Fri, 13 Jun 2008 15:06:56 +0000 Subject: 2008-06-13 Joel Sherrill * 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. --- doc/ChangeLog | 7 +++++++ doc/user/bsp.t | 11 ++++++++--- doc/user/conf.t | 61 +++++++++++++++++++++++++-------------------------------- doc/user/task.t | 36 +++++++++++++++++++++++++++++----- 4 files changed, 73 insertions(+), 42 deletions(-) (limited to 'doc') 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 + + * 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 * 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. -- cgit v1.2.3