diff options
Diffstat (limited to 'c-user/config/intro.rst')
| -rw-r--r-- | c-user/config/intro.rst | 123 |
1 files changed, 38 insertions, 85 deletions
diff --git a/c-user/config/intro.rst b/c-user/config/intro.rst index 4c2f715..eb9c4c1 100644 --- a/c-user/config/intro.rst +++ b/c-user/config/intro.rst @@ -3,49 +3,6 @@ .. Copyright (C) 2012 Gedare Bloom .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -Introduction -============ - -RTEMS must be configured for an application. This configuration encompasses a -variety of information including the length of each clock tick, the maximum -number of each information RTEMS object that can be created, the application -initialization tasks, the task scheduling algorithm to be used, and the device -drivers in the application. - -Although this information is contained in data structures that are used by -RTEMS at system initialization time, the data structures themselves must not be -generated by hand. RTEMS provides a set of macros system which provides a -simple standard mechanism to automate the generation of these structures. - -.. index:: confdefs.h -.. index:: <rtems/confdefs.h> - -The RTEMS header file ``<rtems/confdefs.h>`` is at the core of the automatic -generation of system configuration. It is based on the idea of setting macros -which define configuration parameters of interest to the application and -defaulting or calculating all others. This variety of macros can automatically -produce all of the configuration data required for an RTEMS application. - -.. sidebar: Trivia: - - The term ``confdefs`` is shorthand for a *Configuration Defaults*. - -As a general rule, application developers only specify values for the -configuration parameters of interest to them. They define what resources or -features they require. In most cases, when a parameter is not specified, it -defaults to zero (0) instances, a standards compliant value, or disabled as -appropriate. For example, by default there will be 256 task priority levels but -this can be lowered by the application. This number of priority levels is -required to be compliant with the RTEID/ORKID standards upon which the Classic -API is based. There are similar cases where the default is selected to be -compliant with the POSIX standard. - -For each configuration parameter in the configuration tables, the macro -corresponding to that field is discussed. The RTEMS Maintainers expect that all -systems can be easily configured using the ``<rtems/confdefs.h>`` mechanism and -that using this mechanism will avoid internal RTEMS configuration changes -impacting applications. - Default Value Selection Philosophy ================================== @@ -71,9 +28,9 @@ automatically. It assumes that all tasks are floating point and that all will be allocated the minimum stack space. This calculation includes the amount of memory that will be allocated for internal use by RTEMS. The automatic calculation may underestimate the workspace size truly needed by the -application, in which case one can use the ``CONFIGURE_MEMORY_OVERHEAD`` macro -to add a value to the estimate. See :ref:`Specify Memory Overhead` for more -details. +application, in which case one can use the :ref:`CONFIGURE_MEMORY_OVERHEAD` +macro to add a value to the estimate. See :ref:`Specify Memory Overhead` for +more details. The memory area for the RTEMS Workspace is determined by the BSP. In case the RTEMS Workspace is too large for the available memory, then a fatal run-time @@ -83,8 +40,8 @@ The file ``<rtems/confdefs.h>`` will calculate the value of the ``work_space_size`` parameter of the Configuration Table. There are many parameters the application developer can specify to help ``<rtems/confdefs.h>`` in its calculations. Correctly specifying the application requirements via -parameters such as ``CONFIGURE_EXTRA_TASK_STACKS`` and -``CONFIGURE_MAXIMUM_TASKS`` is critical for production software. +parameters such as :ref:`CONFIGURE_EXTRA_TASK_STACKS` and +:ref:`CONFIGURE_MAXIMUM_TASKS` is critical for production software. For each class of objects, the allocation can operate in one of two ways. The default way has an ceiling on the maximum number of object instances which can @@ -176,44 +133,45 @@ milliseconds is as follows: In this example, only a few configuration parameters are specified. The impact of these are as follows: -- The example specified ``CONFIGURE_RTEMS_INIT_TASK_TABLE`` but did not specify - any additional parameters. This results in a configuration of an application - which will begin execution of a single initialization task named ``Init`` - which is non-preemptible and at priority one (1). - -- By specifying ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``, this application - is configured to have a clock tick device driver. Without a clock tick device - driver, RTEMS has no way to know that time is passing and will be unable to - support delays and wall time. Further configuration details about time are - provided. Per ``CONFIGURE_MICROSECONDS_PER_TICK`` and - ``CONFIGURE_TICKS_PER_TIMESLICE``, the user specified they wanted a clock +- The example specified :ref:`CONFIGURE_RTEMS_INIT_TASKS_TABLE` but did not + specify any additional parameters. This results in a configuration of an + application which will begin execution of a single initialization task named + ``Init`` which is non-preemptible and at priority one (1). + +- By specifying :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER`, this + application is configured to have a clock tick device driver. Without a clock + tick device driver, RTEMS has no way to know that time is passing and will be + unable to support delays and wall time. Further configuration details about + time are provided. Per :ref:`CONFIGURE_MICROSECONDS_PER_TICK` and + :ref:`CONFIGURE_TICKS_PER_TIMESLICE`, the user specified they wanted a clock tick to occur each millisecond, and that the length of a timeslice would be fifty (50) milliseconds. -- By specifying ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER``, the application - will include a console device driver. Although the console device driver may - support a combination of multiple serial ports and display and keyboard - combinations, it is only required to provide a single device named +- By specifying :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`, the + application will include a console device driver. Although the console device + driver may support a combination of multiple serial ports and display and + keyboard combinations, it is only required to provide a single device named ``/dev/console``. This device will be used for Standard Input, Output and - Error I/O Streams. Thus when ``CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER`` - is specified, implicitly three (3) file descriptors are reserved for the - Standard I/O Streams and those file descriptors are associated with - ``/dev/console`` during initialization. All console devices are expected to - support the POSIX*termios* interface. - -- The example above specifies via ``CONFIGURE_MAXIMUM_TASKS`` that the + Error I/O Streams. Thus when + :ref:`CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER` is specified, implicitly + three (3) file descriptors are reserved for the Standard I/O Streams and + those file descriptors are associated with ``/dev/console`` during + initialization. All console devices are expected to support the + POSIX*termios* interface. + +- The example above specifies via :ref:`CONFIGURE_MAXIMUM_TASKS` that the application requires a maximum of four (4) simultaneously existing Classic - API tasks. Similarly, by specifying ``CONFIGURE_MAXIMUM_MESSAGE_QUEUES``, + API tasks. Similarly, by specifying :ref:`CONFIGURE_MAXIMUM_MESSAGE_QUEUES`, there may be a maximum of only one (1) concurrently existent Classic API message queues. - The most surprising configuration parameter in this example is the use of - ``CONFIGURE_MESSAGE_BUFFER_MEMORY``. Message buffer memory is allocated from - the RTEMS Workspace and must be accounted for. In this example, the single - message queue will have up to twenty (20) messages of type ``struct + :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`. Message buffer memory is allocated + from the RTEMS Workspace and must be accounted for. In this example, the + single message queue will have up to twenty (20) messages of type ``struct USER_MESSAGE``. -- The ``CONFIGURE_INIT`` constant must be defined in order to make +- The :ref:`CONFIGURE_INIT` constant must be defined in order to make ``<rtems/confdefs.h>`` instantiate the configuration data structures. This can only be defined in one source file per application that includes ``<rtems/confdefs.h>`` or the symbol table will be instantiated multiple @@ -321,8 +279,6 @@ generally considered a safer embedded systems programming practice to know the system limits rather than experience an out of memory error at an arbitrary and largely unpredictable time in the field. -.. index:: rtems_resource_unlimited - .. _ConfigUnlimitedObjectsClass: Unlimited Objects by Class @@ -330,7 +286,7 @@ Unlimited Objects by Class When the number of objects is not known ahead of time, RTEMS provides an auto-extending mode that can be enabled individually for each object type by -using the macro ``rtems_resource_unlimited``. This takes a value as a +using the macro :ref:`InterfaceRtemsResourceUnlimited`. This takes a value as a parameter, and is used to set the object maximum number field in an API Configuration table. The value is an allocation unit size. When RTEMS is required to grow the object table it is grown by this size. The kernel will @@ -338,18 +294,15 @@ return the object memory back to the RTEMS Workspace when an object is destroyed. The kernel will only return an allocated block of objects to the RTEMS Workspace if at least half the allocation size of free objects remain allocated. RTEMS always keeps one allocation block of objects allocated. Here -is an example of using ``rtems_resource_unlimited``: +is an example of using :c:func:`rtems_resource_unlimited`: .. code-block:: c - #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5) - -.. index:: rtems_resource_is_unlimited -.. index:: rtems_resource_maximum_per_allocation + #define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited( 5 ) Object maximum specifications can be evaluated with the -``rtems_resource_is_unlimited`` and``rtems_resource_maximum_per_allocation`` -macros. +:ref:`InterfaceRtemsResourceIsUnlimited` and +:ref:`InterfaceRtemsResourceMaximumPerAllocation` macros. .. _ConfigUnlimitedObjectsDefault: |