Changeset a526872 in rtems-docs


Ignore:
Timestamp:
Mar 8, 2020, 5:19:42 PM (4 months ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
5, master
Children:
ac9d49d
Parents:
c078afb
git-author:
Sebastian Huber <sebastian.huber@…> (03/08/20 17:19:42)
git-committer:
Sebastian Huber <sebastian.huber@…> (03/11/20 11:30:39)
Message:

c-user: Split up configuring_a_system.rst

Introduce an index file for this chapter. This helps to generate some
sections from the specification in the future. Start with moving
"Introduction" up to "Unlimited Objects" to a new file.

Update #3836.

Location:
c-user
Files:
1 added
1 edited
1 moved

Legend:

Unmodified
Added
Removed
  • c-user/config/index.rst

    rc078afb ra526872  
    1010********************
    1111
    12 Introduction
    13 ============
    14 
    15 RTEMS must be configured for an application.  This configuration encompasses a
    16 variety of information including the length of each clock tick, the maximum
    17 number of each information RTEMS object that can be created, the application
    18 initialization tasks, the task scheduling algorithm to be used, and the device
    19 drivers in the application.
    20 
    21 Although this information is contained in data structures that are used by
    22 RTEMS at system initialization time, the data structures themselves must not be
    23 generated by hand. RTEMS provides a set of macros system which provides a
    24 simple standard mechanism to automate the generation of these structures.
    25 
    26 .. index:: confdefs.h
    27 .. index:: <rtems/confdefs.h>
    28 
    29 The RTEMS header file ``<rtems/confdefs.h>`` is at the core of the automatic
    30 generation of system configuration. It is based on the idea of setting macros
    31 which define configuration parameters of interest to the application and
    32 defaulting or calculating all others. This variety of macros can automatically
    33 produce all of the configuration data required for an RTEMS application.
    34 
    35 .. sidebar: Trivia:
    36 
    37   The term ``confdefs`` is shorthand for a *Configuration Defaults*.
    38 
    39 As a general rule, application developers only specify values for the
    40 configuration parameters of interest to them. They define what resources or
    41 features they require. In most cases, when a parameter is not specified, it
    42 defaults to zero (0) instances, a standards compliant value, or disabled as
    43 appropriate. For example, by default there will be 256 task priority levels but
    44 this can be lowered by the application. This number of priority levels is
    45 required to be compliant with the RTEID/ORKID standards upon which the Classic
    46 API is based. There are similar cases where the default is selected to be
    47 compliant with the POSIX standard.
    48 
    49 For each configuration parameter in the configuration tables, the macro
    50 corresponding to that field is discussed. The RTEMS Maintainers expect that all
    51 systems can be easily configured using the ``<rtems/confdefs.h>`` mechanism and
    52 that using this mechanism will avoid internal RTEMS configuration changes
    53 impacting applications.
    54 
    55 Default Value Selection Philosophy
    56 ==================================
    57 
    58 The user should be aware that the defaults are intentionally set as low as
    59 possible.  By default, no application resources are configured.  The
    60 ``<rtems/confdefs.h>`` file ensures that at least one application task or
    61 thread is configured and that at least one of the initialization task/thread
    62 tables is configured.
    63 
    64 .. _Sizing the RTEMS Workspace:
    65 
    66 Sizing the RTEMS Workspace
    67 ==========================
    68 
    69 The RTEMS Workspace is a user-specified block of memory reserved for use by
    70 RTEMS.  The application should NOT modify this memory.  This area consists
    71 primarily of the RTEMS data structures whose exact size depends upon the values
    72 specified in the Configuration Table.  In addition, task stacks and floating
    73 point context areas are dynamically allocated from the RTEMS Workspace.
    74 
    75 The ``<rtems/confdefs.h>`` mechanism calculates the size of the RTEMS Workspace
    76 automatically.  It assumes that all tasks are floating point and that all will
    77 be allocated the minimum stack space.  This calculation includes the amount of
    78 memory that will be allocated for internal use by RTEMS. The automatic
    79 calculation may underestimate the workspace size truly needed by the
    80 application, in which case one can use the ``CONFIGURE_MEMORY_OVERHEAD`` macro
    81 to add a value to the estimate. See :ref:`Specify Memory Overhead` for more
    82 details.
    83 
    84 The memory area for the RTEMS Workspace is determined by the BSP.  In case the
    85 RTEMS Workspace is too large for the available memory, then a fatal run-time
    86 error occurs and the system terminates.
    87 
    88 The file ``<rtems/confdefs.h>`` will calculate the value of the
    89 ``work_space_size`` parameter of the Configuration Table. There are many
    90 parameters the application developer can specify to help ``<rtems/confdefs.h>``
    91 in its calculations.  Correctly specifying the application requirements via
    92 parameters such as ``CONFIGURE_EXTRA_TASK_STACKS`` and
    93 ``CONFIGURE_MAXIMUM_TASKS`` is critical for production software.
    94 
    95 For each class of objects, the allocation can operate in one of two ways.  The
    96 default way has an ceiling on the maximum number of object instances which can
    97 concurrently exist in the system. Memory for all instances of that object class
    98 is reserved at system initialization.  The second way allocates memory for an
    99 initial number of objects and increases the current allocation by a fixed
    100 increment when required. Both ways allocate space from inside the RTEMS
    101 Workspace.
    102 
    103 See :ref:`ConfigUnlimitedObjects` for more details about the second way, which
    104 allows for dynamic allocation of objects and therefore does not provide
    105 determinism.  This mode is useful mostly for when the number of objects cannot
    106 be determined ahead of time or when porting software for which you do not know
    107 the object requirements.
    108 
    109 The space needed for stacks and for RTEMS objects will vary from one version of
    110 RTEMS and from one target processor to another.  Therefore it is safest to use
    111 ``<rtems/confdefs.h>`` and specify your application's requirements in terms of
    112 the numbers of objects and multiples of ``RTEMS_MINIMUM_STACK_SIZE``, as far as
    113 is possible. The automatic estimates of space required will in general change
    114 when:
    115 
    116 - a configuration parameter is changed,
    117 
    118 - task or interrupt stack sizes change,
    119 
    120 - the floating point attribute of a task changes,
    121 
    122 - task floating point attribute is altered,
    123 
    124 - RTEMS is upgraded, or
    125 
    126 - the target processor is changed.
    127 
    128 Failure to provide enough space in the RTEMS Workspace may result in fatal
    129 run-time errors terminating the system.
    130 
    131 Potential Issues with RTEMS Workspace Size Estimation
    132 =====================================================
    133 
    134 The ``<rtems/confdefs.h>`` file estimates the amount of memory required for the
    135 RTEMS Workspace.  This estimate is only as accurate as the information given to
    136 ``<rtems/confdefs.h>`` and may be either too high or too low for a variety of
    137 reasons.  Some of the reasons that ``<rtems/confdefs.h>`` may reserve too much
    138 memory for RTEMS are:
    139 
    140 - All tasks/threads are assumed to be floating point.
    141 
    142 Conversely, there are many more reasons that the resource estimate could be too
    143 low:
    144 
    145 - Task/thread stacks greater than minimum size must be accounted for explicitly
    146   by developer.
    147 
    148 - Memory for messages is not included.
    149 
    150 - Device driver requirements are not included.
    151 
    152 - Network stack requirements are not included.
    153 
    154 - Requirements for add-on libraries are not included.
    155 
    156 In general, ``<rtems/confdefs.h>`` is very accurate when given enough
    157 information.  However, it is quite easy to use a library and forget to account
    158 for its resources.
    159 
    160 Format to be followed for making changes in this file
    161 =====================================================
    162 
    163 MACRO NAME:
    164   Should be alphanumeric. Can have '_' (underscore).
    165 
    166 DATA TYPE:
    167   Please refer to all existing formats.
    168 
    169 RANGE:
    170   The range depends on the Data Type of the macro.
    171 
    172   - If the data type is of type task priority, then its value should be an
    173     integer in the range of 1 to 255.
    174 
    175   - If the data type is an integer, then it can have numbers, characters (in
    176     case the value is defined using another macro) and arithmetic operations
    177     (+, -, \*, /).
    178 
    179   - If the data type is a function pointer the first character should be an
    180     alphabet or an underscore. The rest of the string can be alphanumeric.
    181 
    182   - If the data type is RTEMS Attributes or RTEMS Mode then the string should
    183     be alphanumeric.
    184 
    185   - If the data type is RTEMS NAME then the value should be an integer>=0 or
    186     ``RTEMS_BUILD_NAME( 'U', 'I', '1', ' ' )``
    187 
    188 DEFAULT VALUE:
    189   The default value should be in the following formats- Please note that the
    190   '.' (full stop) is necessary.
    191 
    192   - In case the value is not defined then: This is not defined by default.
    193 
    194   - If we know the default value then: The default value is XXX.
    195 
    196   - If the default value is BSP Specific then: This option is BSP specific.
    197 
    198 DESCRIPTION:
    199   The description of the macro. (No specific format)
    200 
    201 NOTES:
    202   Any further notes. (No specific format)
    203 
    204 Configuration Example
    205 =====================
    206 
    207 In the following example, the configuration information for a system with a
    208 single message queue, four (4) tasks, and a timeslice of fifty (50)
    209 milliseconds is as follows:
    210 
    211 .. code-block:: c
    212 
    213     #include <bsp.h>
    214     #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
    215     #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
    216     #define CONFIGURE_MICROSECONDS_PER_TICK   1000 /* 1 millisecond */
    217     #define CONFIGURE_TICKS_PER_TIMESLICE       50 /* 50 milliseconds */
    218     #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
    219     #define CONFIGURE_MAXIMUM_TASKS 4
    220     #define CONFIGURE_MAXIMUM_MESSAGE_QUEUES 1
    221     #define CONFIGURE_MESSAGE_BUFFER_MEMORY \
    222                CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(20, sizeof(struct USER_MESSAGE))
    223     #define CONFIGURE_INIT
    224     #include <rtems/confdefs.h>
    225 
    226 In this example, only a few configuration parameters are specified. The impact
    227 of these are as follows:
    228 
    229 - The example specified ``CONFIGURE_RTEMS_INIT_TASK_TABLE`` but did not specify
    230   any additional parameters. This results in a configuration of an application
    231   which will begin execution of a single initialization task named ``Init``
    232   which is non-preemptible and at priority one (1).
    233 
    234 - By specifying ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``, this application
    235   is configured to have a clock tick device driver. Without a clock tick device
    236   driver, RTEMS has no way to know that time is passing and will be unable to
    237   support delays and wall time. Further configuration details about time are
    238   provided. Per ``CONFIGURE_MICROSECONDS_PER_TICK`` and
    239   ``CONFIGURE_TICKS_PER_TIMESLICE``, the user specified they wanted a clock
    240   tick to occur each millisecond, and that the length of a timeslice would be
    241   fifty (50) milliseconds.
    242 
    243 - By specifying ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, the application
    244   will include a console device driver. Although the console device driver may
    245   support a combination of multiple serial ports and display and keyboard
    246   combinations, it is only required to provide a single device named
    247   ``/dev/console``. This device will be used for Standard Input, Output and
    248   Error I/O Streams. Thus when ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``
    249   is specified, implicitly three (3) file descriptors are reserved for the
    250   Standard I/O Streams and those file descriptors are associated with
    251   ``/dev/console`` during initialization. All console devices are expected to
    252   support the POSIX*termios* interface.
    253 
    254 - The example above specifies via ``CONFIGURE_MAXIMUM_TASKS`` that the
    255   application requires a maximum of four (4) simultaneously existing Classic
    256   API tasks. Similarly, by specifying ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``,
    257   there may be a maximum of only one (1) concurrently existent Classic API
    258   message queues.
    259 
    260 - The most surprising configuration parameter in this example is the use of
    261   ``CONFIGURE_MESSAGE_BUFFER_MEMORY``. Message buffer memory is allocated from
    262   the RTEMS Workspace and must be accounted for. In this example, the single
    263   message queue will have up to twenty (20) messages of type ``struct
    264   USER_MESSAGE``.
    265 
    266 - The ``CONFIGURE_INIT`` constant must be defined in order to make
    267   ``<rtems/confdefs.h>`` instantiate the configuration data structures.  This
    268   can only be defined in one source file per application that includes
    269   ``<rtems/confdefs.h>`` or the symbol table will be instantiated multiple
    270   times and linking errors produced.
    271 
    272 This example illustrates that parameters have default values. Among other
    273 things, the application implicitly used the following defaults:
    274 
    275 - All unspecified types of communications and synchronization objects in the
    276   Classic and POSIX Threads API have maximums of zero (0).
    277 
    278 - The filesystem will be the default filesystem which is the In-Memory File
    279   System (IMFS).
    280 
    281 - The application will have the default number of priority levels.
    282 
    283 - The minimum task stack size will be that recommended by RTEMS for the target
    284   architecture.
    285 
    286 .. _ConfigUnlimitedObjects:
    287 
    288 Unlimited Objects
    289 =================
    290 
    291 In real-time embedded systems the RAM is normally a limited, critical resource
    292 and dynamic allocation is avoided as much as possible to ensure predictable,
    293 deterministic execution times. For such cases, see :ref:`Sizing the RTEMS
    294 Workspace` for an overview of how to tune the size of the workspace.
    295 Frequently when users are porting software to RTEMS the precise resource
    296 requirements of the software is unknown. In these situations users do not need
    297 to control the size of the workspace very tightly because they just want to get
    298 the new software to run; later they can tune the workspace size as needed.
    299 
    300 The following object classes in the Classic API can be configured in unlimited
    301 mode:
    302 
    303 - Barriers
    304 
    305 - Message Queues
    306 
    307 - Partitions
    308 
    309 - Periods
    310 
    311 - Ports
    312 
    313 - Regions
    314 
    315 - Semaphores
    316 
    317 - Tasks
    318 
    319 - Timers
    320 
    321 Additionally, the following object classes from the POSIX API can be configured
    322 in unlimited mode:
    323 
    324 - Keys -- :c:func:`pthread_key_create`
    325 
    326 - Key Value Pairs -- :c:func:`pthread_setspecific`
    327 
    328 - Message Queues -- :c:func:`mq_open`
    329 
    330 - Named Semaphores -- :c:func:`sem_open`
    331 
    332 - Shared Memory -- :c:func:`shm_open`
    333 
    334 - Threads -- :c:func:`pthread_create`
    335 
    336 - Timers -- :c:func:`timer_create`
    337 
    338 .. warning::
    339 
    340     The following object classes can *not* be configured in unlimited mode:
    341 
    342     - Drivers
    343 
    344     - File Descriptors
    345 
    346     - POSIX Queued Signals
    347 
    348     - User Extensions
    349 
    350 Due to the memory requirements of unlimited objects it is strongly recommended
    351 to use them only in combination with the unified work areas. See :ref:`Separate
    352 or Unified Work Areas` for more information on unified work areas.
    353 
    354 The following example demonstrates how the two simple configuration defines for
    355 unlimited objects and unified works areas can replace many seperate
    356 configuration defines for supported object classes:
    357 
    358 .. code-block:: c
    359 
    360     #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
    361     #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
    362     #define CONFIGURE_UNIFIED_WORK_AREAS
    363     #define CONFIGURE_UNLIMITED_OBJECTS
    364     #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
    365     #define CONFIGURE_INIT
    366     #include <rtems/confdefs.h>
    367 
    368 Users are cautioned that using unlimited objects is not recommended for
    369 production software unless the dynamic growth is absolutely required. It is
    370 generally considered a safer embedded systems programming practice to know the
    371 system limits rather than experience an out of memory error at an arbitrary and
    372 largely unpredictable time in the field.
    373 
    374 .. index:: rtems_resource_unlimited
    375 
    376 .. _ConfigUnlimitedObjectsClass:
    377 
    378 Unlimited Objects by Class
    379 --------------------------
    380 
    381 When the number of objects is not known ahead of time, RTEMS provides an
    382 auto-extending mode that can be enabled individually for each object type by
    383 using the macro ``rtems_resource_unlimited``. This takes a value as a
    384 parameter, and is used to set the object maximum number field in an API
    385 Configuration table. The value is an allocation unit size. When RTEMS is
    386 required to grow the object table it is grown by this size. The kernel will
    387 return the object memory back to the RTEMS Workspace when an object is
    388 destroyed. The kernel will only return an allocated block of objects to the
    389 RTEMS Workspace if at least half the allocation size of free objects remain
    390 allocated. RTEMS always keeps one allocation block of objects allocated. Here
    391 is an example of using ``rtems_resource_unlimited``:
    392 
    393 .. code-block:: c
    394 
    395     #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5)
    396 
    397 .. index:: rtems_resource_is_unlimited
    398 .. index:: rtems_resource_maximum_per_allocation
    399 
    400 Object maximum specifications can be evaluated with the
    401 ``rtems_resource_is_unlimited`` and``rtems_resource_maximum_per_allocation``
    402 macros.
    403 
    404 .. _ConfigUnlimitedObjectsDefault:
    405 
    406 Unlimited Objects by Default
    407 ----------------------------
    408 
    409 To ease the burden of developers who are porting new software RTEMS also
    410 provides the capability to make all object classes listed above operate in
    411 unlimited mode in a simple manner. The application developer is only
    412 responsible for enabling unlimited objects
    413 (:ref:`CONFIGURE_UNLIMITED_OBJECTS`) and specifying the allocation size
    414 (:ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`).
    415 
    416 .. code-block:: c
    417 
    418     #define CONFIGURE_UNLIMITED_OBJECTS
    419     #define CONFIGURE_UNLIMITED_ALLOCATION_SIZE 5
     12.. toctree::
     13
     14    intro
    42015
    42116General System Configuration
  • c-user/index.rst

    rc078afb ra526872  
    4848        board_support_packages
    4949        user_extensions
    50         configuring_a_system
     50        config/index
    5151        self_contained_objects
    5252        multiprocessing
Note: See TracChangeset for help on using the changeset viewer.