Ticket #1924: doc-conf.patch

File doc-conf.patch, 15.1 KB (added by Sebastian Huber, on 12/14/11 at 15:21:03)

Documentation changes.

  • doc/user/conf.t 

    RCS file: /usr1/CVS/rtems/doc/user/conf.t,v
retrieving revision 1.77
diff -u -r1.77 conf.t
     
    218218if the application is providing their own complete set of configuration
    219219tables.
    220220
    221 @findex CONFIGURE_EXECUTIVE_RAM_WORK_AREA
    222 @item @code{CONFIGURE_EXECUTIVE_RAM_WORK_AREA} is the base
    223 address of the RTEMS RAM Workspace.  By default, this value
    224 is NULL indicating that the BSP is to determine the location
    225 of the RTEMS RAM Workspace.
    226 
    227221@findex CONFIGURE_UNIFIED_WORK_AREAS
    228222@item @code{CONFIGURE_UNIFIED_WORK_AREAS} configures RTEMS to use a
    229223single memory pool for the RTEMS Workspace and C Program Heap.  If not
    … …  
    280274will be of minimum size.  The default value is the configured
    281275minimum stack size.
    282276
    283 @findex CONFIGURE_TASK_STACK_ALLOCATOR
    284 @item @code{CONFIGURE_TASK_STACK_ALLOCATOR}
    285 may point to a user provided routine to allocate task stacks.
    286 The default value for this field is NULL which indicates that
    287 task stacks will be allocated from the RTEMS Workspace.
    288 
    289 @findex CONFIGURE_TASK_STACK_DEALLOCATOR
    290 @item @code{CONFIGURE_TASK_STACK_DEALLOCATOR}
    291 may point to a user provided routine to free task stacks.
    292 The default value for this field is NULL which indicates that
    293 task stacks will be allocated from the RTEMS Workspace.
    294 
    295277@findex CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY
    296278@item @code{CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY}
    297279indicates whether RTEMS should zero the RTEMS Workspace and
    298280C Program Heap as part of its initialization.  If set to
    299 TRUE, the Workspace is zeroed.  Otherwise, it is not.
     281@code{true}, the Workspace is zeroed.  Otherwise, it is not.
    300282Unless overridden by the BSP, the default value for this
    301 field is FALSE.
     283field is @code{false}.
    302284
    303285@findex CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE
    304286@item @code{CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE} is a helper macro
    … …  
    395377@c
    396378@c
    397379@c
     380@subsection Task Stack Allocator Configuration
     381
     382This section defines the task stack allocator configuration parameters
     383supported by @code{rtems/confdefs.h}.
     384
     385@itemize @bullet
     386
     387@findex CONFIGURE_TASK_STACK_ALLOCATOR_INIT
     388@item @code{CONFIGURE_TASK_STACK_ALLOCATOR_INIT}
     389may be defined to point to a user provided routine to initialize the task stack allocator.
     390This pointer may be @code{NULL}.  The default value is @code{NULL}.
     391
     392@findex CONFIGURE_TASK_STACK_ALLOCATOR
     393@item @code{CONFIGURE_TASK_STACK_ALLOCATOR}
     394may be defined to point to a user provided routine to allocate a task stack.
     395This pointer must be not @code{NULL}.  If this define is not set, then the task
     396stack allocation will use the RTEMS Workspace.
     397
     398@findex CONFIGURE_TASK_STACK_DEALLOCATOR
     399@item @code{CONFIGURE_TASK_STACK_DEALLOCATOR}
     400may be defined to point to a user provided routine to free a task stack.  This
     401pointer must be not @code{NULL}.  If this define is not set, then the task
     402stack allocation will use the RTEMS Workspace.
     403
     404@findex CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE
     405@item @code{CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE}
     406indicates whether the stack allocator avoids the RTEMS Workspace and uses its
     407own memory area.  If this is defined, then the task stack allocator must use
     408its own memory area.  Otherwise, it may use the RTEMS Workspace.
     409
     410@findex CONFIGURE_TASK_STACK_FROM_ALLOCATOR
     411@item @code{CONFIGURE_TASK_STACK_FROM_ALLOCATOR}
     412this optional macro can provide the size estimate for one allocation of a
     413specified quantity of bytes.  It should take the worst case per allocation
     414overhead into account.  In case this macro is undefined the allocation estimate
     415of the standard RTEMS heap will be used.
     416
     417@end itemize
     418
     419@c
     420@c
     421@c
    398422@subsection Scheduler Algorithm Configuration
    399423
    400424This section defines the configuration parameters related to selecting
    … …  
    958982The RTEMS Configuration Table is used to tailor an
    959983application for its specific needs.  For example, the user can
    960984configure the number of device drivers or which APIs may be used.
    961 THe address of the user-defined Configuration Table is passed as an
    962 argument to the @code{rtems_initialize_executive}
    963 directive, which MUST be the first RTEMS directive called. 
    964985The RTEMS Configuration Table is defined in the following C structure:
    965986
    966987@findex rtems_configuration_table
    967988@example
    968989@group
    969990typedef struct @{
    970   void                           *work_space_start;
    971   uintptr_t                       work_space_size;
    972   uint32_t                        maximum_extensions;
    973   uint32_t                        microseconds_per_tick;
    974   uint32_t                        ticks_per_timeslice;
    975   uint32_t                        scheduler_policy;
    976   void                          (*idle_task)( void );
    977   uint32_t                        idle_task_stack_size;
    978   uint32_t                        interrupt_stack_size;
    979   void *                        (*stack_allocate_hook)( size_t );
    980   void                          (*stack_free_hook)( void * );
    981   bool                            do_zero_of_workspace;
    982   uint32_t                        maximum_drivers;
    983   uint32_t                        number_of_device_drivers;
    984   rtems_driver_address_table     *Device_driver_table;
    985   uint32_t                        number_of_initial_extensions;
    986   rtems_extensions_table         *User_extension_table;
    987 #if defined(RTEMS_MULTIPROCESSING)
    988   rtems_multiprocessing_table    *User_multiprocessing_table;
    989 #endif
    990   rtems_api_configuration_table  *RTEMS_api_configuration;
    991   posix_api_configuration_table  *POSIX_api_configuration;
     991  void                          *work_space_start;
     992  uintptr_t                      work_space_size;
     993  uintptr_t                      stack_space_size;
     994  uint32_t                       maximum_extensions;
     995  uint32_t                       microseconds_per_tick;
     996  uint32_t                       ticks_per_timeslice;
     997  Thread                       (*idle_task)( uintptr_t );
     998  uint32_t                       idle_task_stack_size;
     999  uint32_t                       interrupt_stack_size;
     1000  rtems_stack_allocate_init_hook stack_allocate_init_hook;
     1001  rtems_stack_allocate_hook      stack_allocate_hook;
     1002  rtems_stack_free_hook          stack_free_hook;
     1003  bool                           do_zero_of_workspace;
     1004  bool                           unified_work_area;
     1005  bool                           stack_allocator_avoids_work_space;
     1006  uint32_t                       maximum_drivers;
     1007  uint32_t                       number_of_device_drivers;
     1008  rtems_driver_address_table    *Device_driver_table;
     1009  uint32_t                       number_of_initial_extensions;
     1010  rtems_extensions_table        *User_extension_table;
     1011  #if defined(RTEMS_MULTIPROCESSING)
     1012    rtems_multiprocessing_table *User_multiprocessing_table;
     1013  #endif
    9921014@} rtems_configuration_table;
    9931015@end group
    9941016@end example
    9951017
    9961018@table @b
    9971019@item work_space_start
    998 is the address of the RTEMS RAM Workspace. 
    999 This area contains items such as the
    1000 various object control blocks (TCBs, QCBs, ...) and task stacks.
    1001 If the address is not aligned on a four-word boundary, then
    1002 RTEMS will invoke the fatal error handler during
    1003 @code{rtems_initialize_executive}.
    1004 When using the @code{rtems/confdefs.h} mechanism for configuring
    1005 an RTEMS application, the value for this field corresponds
    1006 to the setting of the macro @code{CONFIGURE_EXECUTIVE_RAM_WORK_AREA}
    1007 which defaults to @code{NULL}.  Normally, this field should be
    1008 configured as @code{NULL} as BSPs will assign memory for the
    1009 RTEMS RAM Workspace as part of system initialization.
     1020is the address of the RTEMS RAM Workspace.  This area contains items such as
     1021the various object control blocks (TCBs, QCBs, ...) and by default the task
     1022stacks.  Normally, this field should be configured as @code{NULL} as BSPs will
     1023assign memory for the RTEMS RAM Workspace as part of system initialization.
    10101024
    10111025@item work_space_size
    10121026is the calculated size of the
    … …  
    10171031to the setting of the macro @code{CONFIGURE_EXECUTIVE_RAM_SIZE}
    10181032and is calculated based on the other system configuration settings.
    10191033
     1034@item stack_space_size
     1035is the size reserved for the task stack space in bytes.  When using the
     1036@code{rtems/confdefs.h} mechanism for configuring an RTEMS application, the
     1037value for this field corresponds to the setting of the macro
     1038@code{CONFIGURE_STACK_SPACE_SIZE} and is calculated based on the other system
     1039configuration settings.
     1040
     1041@item maximum_extensions;
     1042is the maximum number of user extensions that can be registered.  When using
     1043the @code{rtems/confdefs.h} mechanism for configuring an RTEMS application, the
     1044value for this field corresponds to the setting of the macro
     1045@code{CONFIGURE_MAXIMUM_USER_EXTENSIONS}.
     1046
    10201047@item microseconds_per_tick
    10211048is number of microseconds per clock tick.
    10221049When using the @code{rtems/confdefs.h} mechanism for configuring
    … …  
    10321059an RTEMS application, the value for this field corresponds
    10331060to the setting of the macro @code{CONFIGURE_TICKS_PER_TIMESLICE}.
    10341061
    1035 @item scheduler_policy
    1036 is the algorithm to use for task scheduling.
    1037 When using the @code{rtems/confdefs.h} mechanism for configuring
    1038 an RTEMS application, the value for this field corresponds
    1039 to the setting of the macro @code{CONFIGURE_SCHEDULER_POLICY}.
    1040 
    10411062@item idle_task
    10421063is the address of the optional user
    10431064provided routine which is used as the system's IDLE task.  If
    … …  
    10611082configuring an RTEMS application, the value for this field corresponds
    10621083to the setting of the macro @code{CONFIGURE_INTERRUPT_STACK_SIZE}.
    10631084
    1064 @item stack_allocate_hook
    1065 may point to a user provided routine to allocate task stacks.
    1066 The default is to allocate task stacks from the RTEMS Workspace.
    1067 When using the @code{rtems/confdefs.h} mechanism
    1068 for configuring an RTEMS application, the value for this field
     1085@item stack_allocate_init_hook
     1086may point to a user provided routine to initialize the task stack allocator.
     1087This pointer may be @code{NULL}.  When using the @code{rtems/confdefs.h}
     1088mechanism for configuring an RTEMS application, the value for this field
    10691089corresponds to the setting of the macro
    1070 @code{CONFIGURE_TASK_STACK_ALLOCATOR}.
     1090@code{CONFIGURE_TASK_STACK_ALLOCATOR_INIT}.
     1091
     1092@item stack_allocate_hook
     1093must point to a routine to allocate a task stack.  This pointer must be not
     1094@code{NULL}.  When using the @code{rtems/confdefs.h} mechanism for configuring
     1095an RTEMS application, the value for this field corresponds to the setting of
     1096the macro @code{CONFIGURE_TASK_STACK_ALLOCATOR}.  If this define is not set,
     1097then the default is allocation from the RTEMS Workspace.
    10711098
    10721099@item stack_free_hook
    1073 may point to a user provided routine to free task stacks.
    1074 The default is to allocate task stacks from the RTEMS Workspace.
    1075 When using the @code{rtems/confdefs.h} mechanism
    1076 for configuring an RTEMS application, the value for this field
    1077 corresponds to the setting of the macro
    1078 @code{CONFIGURE_TASK_STACK_DEALLOCATOR}.
     1100must point to a routine to free a task stack.  This pointer must be not
     1101@code{NULL}.  When using the @code{rtems/confdefs.h} mechanism for configuring
     1102an RTEMS application, the value for this field corresponds to the setting of
     1103the macro @code{CONFIGURE_TASK_STACK_DEALLOCATOR}.  If this define is not set,
     1104then the default is allocation from the RTEMS Workspace.
    10791105
    10801106@item do_zero_of_workspace
    1081 indicates whether RTEMS should zero the RTEMS Workspace and
    1082 C Program Heap as part of its initialization.  If set to
    1083 TRUE, the Workspace is zeroed.  Otherwise, it is not.
    1084 When using the @code{rtems/confdefs.h} mechanism
    1085 for configuring an RTEMS application, the value for this field
     1107indicates whether RTEMS should zero the RTEMS Workspace and C Program Heap as
     1108part of its initialization.  If set to @code{true}, the RTEMS Workspace is
     1109zeroed.  Otherwise, it is not.  When using the @code{rtems/confdefs.h}
     1110mechanism for configuring an RTEMS application, the value for this field
    10861111corresponds to the setting of the macro
    10871112@code{CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY}.
    10881113
     1114@item unified_work_area
     1115indicates whether the RTEMS Workspace and C Program Heap use the same heap.  If
     1116set to @code{true}, the RTEMS Workspace and C Program Heap use the same heap.
     1117Otherwise, they use separate heaps.  When using the @code{rtems/confdefs.h}
     1118mechanism for configuring an RTEMS application, the value for this field
     1119corresponds to the setting of the macro @code{CONFIGURE_UNIFIED_WORK_AREAS}.  A
     1120unified work area is useful in combination with unlimited objects.
     1121
     1122@item stack_allocator_avoids_work_space
     1123indicates whether the stack allocator avoids the RTEMS Workspace and uses its
     1124own memory area.  If set to @code{true}, the task stack allocator uses its own
     1125memory area.  Otherwise, it uses the RTEMS Workspace.  When using the
     1126@code{rtems/confdefs.h} mechanism for configuring an RTEMS application, the
     1127value for this field corresponds to the setting of the macro
     1128@code{CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE}.
     1129
    10891130@item maximum_drivers
    10901131is the maximum number of device drivers that can be registered.
    10911132When using the @code{rtems/confdefs.h} mechanism for configuring
    … …  
    11121153@item @code{CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER}
    11131154@item @code{CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER}
    11141155@item @code{CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER}
     1156@item @code{CONFIGURE_APPLICATION_NEEDS_ZERO_DRIVER}
    11151157
    11161158@end itemize
    11171159
    … …  
    11551197@itemize @bullet
    11561198
    11571199@item @code{CONFIGURE_INITIAL_EXTENSIONS}
    1158 @item @code{STACK_CHECKER_EXTENSION}
     1200@item @code{CONFIGURE_STACK_CHECKER_ENABLED}
     1201@item @code{CONFIGURE_DISABLE_NEWLIB_REENTRANCY}
    11591202
    11601203@end itemize
    11611204
    … …  
    11771220entry is set to NULL.  The generated table has the name
    11781221@code{Multiprocessing_configuration}.
    11791222
    1180 @item RTEMS_api_configuration
    1181 is the address of the RTEMS API Configuration Table.  This table
    1182 contains information needed by the RTEMS API.  This field should be
    1183 NULL if the RTEMS API is not used.  [NOTE: Currently the RTEMS API
    1184 is required to support support components such as BSPs and libraries
    1185 which use this API.]  This table is built automatically and this
    1186 entry filled in, if using the @code{rtems/confdefs.h} application
    1187 configuration mechanism.  The generated table has the name
    1188 @code{Configuration_RTEMS_API}.
    1189 
    1190 @item POSIX_api_configuration
    1191 is the address of the POSIX API Configuration Table.  This table
    1192 contains information needed by the POSIX API.  This field should be
    1193 NULL if the POSIX API is not used.  This table is built automatically
    1194 and this entry filled in, if using the @code{rtems/confdefs.h} application
    1195 configuration mechanism.  The @code{rtems/confdefs.h} application
    1196 mechanism will fill this field in with the address of the
    1197 @code{Configuration_POSIX_API} table of POSIX API is configured
    1198 and NULL if the POSIX API is not configured.
    1199 
    12001223@end table
    12011224
    12021225@subsection RTEMS API Configuration Table
    … …  
    13501373is the address of the Initialization Task Table. This table contains the
    13511374information needed to create and start each of the
    13521375initialization tasks.  The format of this table will be discussed below.
    1353 When using the @code{rtems/confdefs.h} mechanism for configuring
    1354 an RTEMS application, the value for this field corresponds
    1355 to the setting of the macro @code{CONFIGURE_EXECUTIVE_RAM_WORK_AREA}.
    13561376
    13571377@end table
    13581378