Changeset b2cf295f in rtems


Ignore:
Timestamp:
Apr 9, 2013, 4:56:11 PM (6 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.11, master
Children:
a6a88f4
Parents:
6784547
git-author:
Joel Sherrill <joel.sherrill@…> (04/09/13 16:56:11)
git-committer:
Joel Sherrill <joel.sherrill@…> (04/09/13 18:15:40)
Message:

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

Stephen Tether <tether@…> posted to the users list:

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

I tried to make the requested changes.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/user/conf.t

    r6784547 rb2cf295f  
    2121
    2222RTEMS must be configured for an application.  This configuration
    23 information encompasses a variety of information including
    24 the length of each clock tick, the maximum number of each RTEMS
    25 object that can be created, the application initialization tasks,
    26 the task scheduling algorithm to be used, and the device drivers in
    27 the application.
     23encompasses a variety of information including the length of each clock
     24tick, the maximum number of each information RTEMS object that can
     25be created, the application initialization tasks, the task scheduling
     26algorithm to be used, and the device drivers in the application.
    2827
    2928Although this information is contained in data structures that are used
    30 to RTEMS at system initialization time, the data structures themselves
    31 should only rarely to be generated by hand. RTEMS provides a macro based
    32 system which provides the standard and simple mechanism to automate the
    33 generation of these structures.
     29by RTEMS at system initialization time, the data structures themselves
     30should only rarely to be generated by hand. RTEMS provides a set of
     31macros system which provides a simple standard mechanism to automate
     32the generation of these structures.
    3433
    3534@ifset is-Ada
     
    4746@findex <rtems/confdefs.h>
    4847
    49 The RTEMS header file @code{<rtems/confdefs.h>} is the core of the
     48The RTEMS header file @code{<rtems/confdefs.h>} is at the core of the
    5049automatic generation of system configuration. It is based on the idea
    5150of setting macros which define configuration parameters of interest to
     
    5655Trivia: @code{confdefs} is shorthand for a @b{Configuration Defaults}.
    5756
    58 As a general rule, the application developer only specifies values
     57As a general rule, application developers only specify values
    5958for the configuration parameters of interest to them. They define what
    6059resources or features they require. In most cases, when a parameter is
     
    6261value, or disabled as appropriate. For example, by default there will be
    6362256 task priority levels but this can be lowered by the application. This
    64 number of priority levels is required to be standards compliant.
     63number of priority levels is required to be compliant with the RTEID/ORKID
     64standards upon which the Classic API is based. There are similar cases
     65where the default is selected to be compliant with with the POSIX standard.
    6566
    6667For each configuration parameter in the configuration tables, the macro
    67 corresponding to that field is discussed. It is expected that all systems
    68 can be easily configured using the @code{<rtems/confdefs.h>} mechanism. It
    69 is also expected that using this mechanism will avoid internal RTEMS
    70 configuration changes impacting applications.
     68corresponding to that field is discussed. The RTEMS Maintainers
     69expect that all systems can be easily configured using the
     70@code{<rtems/confdefs.h>} mechanism and that using this mechanism will
     71avoid internal RTEMS configuration changes impacting applications.
    7172
    7273@c
     
    7879low as possible.  By default, no application resources are configured.
    7980The @code{<rtems/confdefs.h>} file ensures that at least one application
    80 tasks or thread is configured and that at least one of the initialization
     81task or thread is configured and that at least one of the initialization
    8182task/thread tables is configured.
    8283
     
    9596The @code{<rtems/confdefs.h>} mechanism calculates the size of the RTEMS
    9697Workspace automatically.  It assumes that all tasks are floating point and
    97 that all will be allocated the mininum stack space.  This calculation also
    98 automatically includes the memory that will be allocated for internal
    99 use by RTEMS. In the event, there is an under-estimation of the amount
    100 of memoryy required, the @code{CONFIGURE_MEMORY_OVERHEAD} is provided
    101 as a work-around.
    102 
    103 The starting address of the RTEMS Workspace is determined
    104 by the BSP must be aligned on at least a four-byte boundary.
    105 Failure to properly align the workspace area will result in the
    106 @code{@value{DIRPREFIX}fatal_error_occurred} directive being invoked
    107 with the @code{@value{RPREFIX}INVALID_ADDRESS} error code.
    108 
    109 The file @code{<rtems/confdefs.h>} will calculate the value that is
    110 specified as the @code{work_space_size} parameter of the Configuration
    111 Table. There are many parameters the application developer can
    112 specify to help @code{<rtems/confdefs.h>} in its calculations.
    113 Correctly specifying the application requirements via parameters such
    114 as @code{CONFIGURE_EXTRA_TASK_STACKS} and @code{CONFIGURE_MAXIMUM_TASKS}
     98that all will be allocated the mininum stack space.  This calculation
     99includes the amount of memory that will be allocated for internal use
     100by RTEMS. The automatic calculation may underestimate the workspace
     101size truly needed by the application, in which case one can use the
     102@code{CONFIGURE_MEMORY_OVERHEAD} macro to add a value to the estimate. See
     103@ref{Configuring a System Specify Memory Overhead} for more details.
     104
     105@c XXX - ************* REMOVE ME *************
     106@c The starting address of the RTEMS Workspace is determined
     107@c by the BSP and must be aligned on at least a four-byte boundary.
     108@c Failure to properly align the workspace will result in the
     109@c @code{@value{DIRPREFIX}fatal_error_occurred} directive being invoked
     110@c with the @code{@value{RPREFIX}INVALID_ADDRESS} error code.
     111
     112The file @code{<rtems/confdefs.h>} will calculate the value of the
     113@code{work_space_size} parameter of the Configuration Table. There
     114are many parameters the application developer can specify to
     115help @code{<rtems/confdefs.h>} in its calculations.  Correctly
     116specifying the application requirements via parameters such as
     117@code{CONFIGURE_EXTRA_TASK_STACKS} and @code{CONFIGURE_MAXIMUM_TASKS}
    115118is critical for production software.
    116119
    117 The allocation of objects can operate in two modes. The default mode
    118 has an object number ceiling. No more than the specified number of
    119 objects can be allocated from the RTEMS Workspace. The number of objects
    120 specified in the particular API Configuration table fields are
    121 allocated at initialisation. The second mode allows the number of
    122 objects to grow to use the available free memory in the RTEMS Workspace.
     120For each class of objects, the allocation can operate in one of two ways.
     121The default way has an ceiling on the maximum number of object instances
     122which can concurrently exist in the system. Memory for all instances of
     123that object class is reserved at system initialization.  The second
     124way allocates memory for an initial number of objects and increases the
     125current allocation by a fixed increment when required. Both ways allocate
     126space from inside the RTEMS Workspace.
    123127
    124128See @ref{Configuring a System Unlimited Objects} for more details about
    125 the second mode, which allows for dynamic allocation of objects and
     129the second way, which allows for dynamic allocation of objects and
    126130therefore does not provide determinism.  This mode is useful mostly for
    127131when the number of objects cannot be determined ahead of time or when
    128132porting software for which you do not know the object requirements.
    129133
    130 Note that future versions of RTEMS may not have the same memory
    131 requirements per object. Although the value calculated is sufficient
    132 for a particular target processor and release of RTEMS, memory usage
    133 is subject to change across versions and target processors.  To avoid
    134 problems, users should accurately specify each configuration parameter and
    135 allow @code{<rtems/confdefs.h>} to calculate the memory requirements.
    136 The memory requirements are likely to change each time one of the
    137 following events occurs:
     134The space needed for stacks and for RTEMS objects will vary from
     135one version of RTEMS and from one target processor to another.
     136Therefore it is safest to use @code{<rtems/confdefs.h>} and specify
     137your application's requirements in terms of the numbers of objects and
     138multiples of @code{RTEMS_MINIMUM_STACK_SIZE}, as far as is possible. The
     139automatic estimates of space required will in general change when:
    138140
    139141@itemize @bullet
    140 @item a configuration parameter is modified,
    141 @item task or interrupt stack requirements change,
     142@item a configuration parameter is changed,
     143@item task or interrupt stack sizes change,
     144@item the floating point attribute of a task changes,
    142145@item task floating point attribute is altered,
    143146@item RTEMS is upgraded, or
     
    152155@c === Potential Issues ===
    153156@c
    154 @section Potential Issues with RTEMS Workspace Estimation
     157@section Potential Issues with RTEMS Workspace Size Estimation
    155158
    156159The @code{<rtems/confdefs.h>} file estimates the amount of memory
     
    164167@end itemize
    165168
    166 Conversely, there are many more reasons, the resource estimate could be
     169Conversely, there are many more reasons that the resource estimate could be
    167170too low:
    168171
     
    190193
    191194In the following example, the configuration information for a system
    192 with a single message queue, four (4) tasks, and a time slice
     195with a single message queue, four (4) tasks, and a timeslice of
    193196fifty (50) milliseconds is as follows:
    194197
     
    223226@item The example specified @code{CONFIGURE_RTEMS_INIT_TASK_TABLE}
    224227but did not specify any additional parameters. This results in a
    225 configuration which will begin execution at  single initialization task
    226 named @code{Init} which is non-preemptible and at priority one (1).
     228configuration of an application which will begin execution of a single
     229initialization task named @code{Init} which is non-preemptible and at
     230priority one (1).
    227231
    228232@item By specifying @code{CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER},
    229233this application is configured to have a clock tick device
    230 driver. This is required for the passage of time including
    231 delays and wall time. Further configuration details about time
    232 are provided. Per @code{CONFIGURE_MICROSECONDS_PER_TICK} and
     234driver. Without a clock tick device driver, RTEMS has no way to know
     235that time is passing and will be unable to support delays and wall
     236time. Further configuration details about time are
     237provided. Per @code{CONFIGURE_MICROSECONDS_PER_TICK} and
    233238@code{CONFIGURE_TICKS_PER_TIMESLICE}, the user specified they wanted a
    234239clock tick to occur each millisecond, and that the length of a timeslice
     
    236241
    237242@item By specifying @code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER},
    238 the application will include a console device driver. This provides
    239 for standard I/O) on at least @code{/dev/console}. Implicitly, the
    240 Configuration Defaults header file configures enough resources for three
    241 (3) file descriptors to be used for standard in, out, and error on a
    242 device that supports the POSIX @i{termios} interface.
    243 
    244 @item The example above specifies via @code{CONFIGURE_MAXIMUM_TASKS},
     243the application will include a console device driver. Although the
     244console device driver may support a combination of multiple serial
     245ports and display and keyboard combinations, it is only required to
     246provide a single device named @code{/dev/console}. This device will
     247be used for Standard Input, Output and Error I/O Streams. Thus when
     248@code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER} is specified, implicitly
     249three (3) file descriptors are reserved for the Standard I/O Streams and
     250those file descriptors are associated with @code{/dev/console} during
     251initialization. All console devices are expected to support the POSIX
     252@i{termios} interface.
     253
     254@item The example above specifies via @code{CONFIGURE_MAXIMUM_TASKS}
    245255that the application requires a maximum of four (4)
    246 concurrently existent Classic API tasks. Similarly, by specifying
     256simultaneously existing Classic API tasks. Similarly, by specifying
    247257@code{CONFIGURE_MAXIMUM_MESSAGE_QUEUES}, there may be a maximum of only
    248258one (1) concurrently existent Classic API message queues.
Note: See TracChangeset for help on using the changeset viewer.