mirror of
https://git.rtems.org/rtems-docs/
synced 2025-05-14 20:49:18 +08:00
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.
This commit is contained in:
Sebastian Huber
parent
c078afb637
commit
a526872600
@ -9,414 +9,9 @@
|
|||||||
Configuring a System
|
Configuring a System
|
||||||
********************
|
********************
|
||||||
|
|
||||||
Introduction
|
.. toctree::
|
||||||
============
|
|
||||||
|
|
||||||
RTEMS must be configured for an application. This configuration encompasses a
|
intro
|
||||||
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
|
|
||||||
==================================
|
|
||||||
|
|
||||||
The user should be aware that the defaults are intentionally set as low as
|
|
||||||
possible. By default, no application resources are configured. The
|
|
||||||
``<rtems/confdefs.h>`` file ensures that at least one application task or
|
|
||||||
thread is configured and that at least one of the initialization task/thread
|
|
||||||
tables is configured.
|
|
||||||
|
|
||||||
.. _Sizing the RTEMS Workspace:
|
|
||||||
|
|
||||||
Sizing the RTEMS Workspace
|
|
||||||
==========================
|
|
||||||
|
|
||||||
The RTEMS Workspace is a user-specified block of memory reserved for use by
|
|
||||||
RTEMS. The application should NOT modify this memory. This area consists
|
|
||||||
primarily of the RTEMS data structures whose exact size depends upon the values
|
|
||||||
specified in the Configuration Table. In addition, task stacks and floating
|
|
||||||
point context areas are dynamically allocated from the RTEMS Workspace.
|
|
||||||
|
|
||||||
The ``<rtems/confdefs.h>`` mechanism calculates the size of the RTEMS Workspace
|
|
||||||
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.
|
|
||||||
|
|
||||||
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
|
|
||||||
error occurs and the system terminates.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
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
|
|
||||||
concurrently exist in the system. Memory for all instances of that object class
|
|
||||||
is reserved at system initialization. The second way allocates memory for an
|
|
||||||
initial number of objects and increases the current allocation by a fixed
|
|
||||||
increment when required. Both ways allocate space from inside the RTEMS
|
|
||||||
Workspace.
|
|
||||||
|
|
||||||
See :ref:`ConfigUnlimitedObjects` for more details about the second way, which
|
|
||||||
allows for dynamic allocation of objects and therefore does not provide
|
|
||||||
determinism. This mode is useful mostly for when the number of objects cannot
|
|
||||||
be determined ahead of time or when porting software for which you do not know
|
|
||||||
the object requirements.
|
|
||||||
|
|
||||||
The space needed for stacks and for RTEMS objects will vary from one version of
|
|
||||||
RTEMS and from one target processor to another. Therefore it is safest to use
|
|
||||||
``<rtems/confdefs.h>`` and specify your application's requirements in terms of
|
|
||||||
the numbers of objects and multiples of ``RTEMS_MINIMUM_STACK_SIZE``, as far as
|
|
||||||
is possible. The automatic estimates of space required will in general change
|
|
||||||
when:
|
|
||||||
|
|
||||||
- a configuration parameter is changed,
|
|
||||||
|
|
||||||
- task or interrupt stack sizes change,
|
|
||||||
|
|
||||||
- the floating point attribute of a task changes,
|
|
||||||
|
|
||||||
- task floating point attribute is altered,
|
|
||||||
|
|
||||||
- RTEMS is upgraded, or
|
|
||||||
|
|
||||||
- the target processor is changed.
|
|
||||||
|
|
||||||
Failure to provide enough space in the RTEMS Workspace may result in fatal
|
|
||||||
run-time errors terminating the system.
|
|
||||||
|
|
||||||
Potential Issues with RTEMS Workspace Size Estimation
|
|
||||||
=====================================================
|
|
||||||
|
|
||||||
The ``<rtems/confdefs.h>`` file estimates the amount of memory required for the
|
|
||||||
RTEMS Workspace. This estimate is only as accurate as the information given to
|
|
||||||
``<rtems/confdefs.h>`` and may be either too high or too low for a variety of
|
|
||||||
reasons. Some of the reasons that ``<rtems/confdefs.h>`` may reserve too much
|
|
||||||
memory for RTEMS are:
|
|
||||||
|
|
||||||
- All tasks/threads are assumed to be floating point.
|
|
||||||
|
|
||||||
Conversely, there are many more reasons that the resource estimate could be too
|
|
||||||
low:
|
|
||||||
|
|
||||||
- Task/thread stacks greater than minimum size must be accounted for explicitly
|
|
||||||
by developer.
|
|
||||||
|
|
||||||
- Memory for messages is not included.
|
|
||||||
|
|
||||||
- Device driver requirements are not included.
|
|
||||||
|
|
||||||
- Network stack requirements are not included.
|
|
||||||
|
|
||||||
- Requirements for add-on libraries are not included.
|
|
||||||
|
|
||||||
In general, ``<rtems/confdefs.h>`` is very accurate when given enough
|
|
||||||
information. However, it is quite easy to use a library and forget to account
|
|
||||||
for its resources.
|
|
||||||
|
|
||||||
Format to be followed for making changes in this file
|
|
||||||
=====================================================
|
|
||||||
|
|
||||||
MACRO NAME:
|
|
||||||
Should be alphanumeric. Can have '_' (underscore).
|
|
||||||
|
|
||||||
DATA TYPE:
|
|
||||||
Please refer to all existing formats.
|
|
||||||
|
|
||||||
RANGE:
|
|
||||||
The range depends on the Data Type of the macro.
|
|
||||||
|
|
||||||
- If the data type is of type task priority, then its value should be an
|
|
||||||
integer in the range of 1 to 255.
|
|
||||||
|
|
||||||
- If the data type is an integer, then it can have numbers, characters (in
|
|
||||||
case the value is defined using another macro) and arithmetic operations
|
|
||||||
(+, -, \*, /).
|
|
||||||
|
|
||||||
- If the data type is a function pointer the first character should be an
|
|
||||||
alphabet or an underscore. The rest of the string can be alphanumeric.
|
|
||||||
|
|
||||||
- If the data type is RTEMS Attributes or RTEMS Mode then the string should
|
|
||||||
be alphanumeric.
|
|
||||||
|
|
||||||
- If the data type is RTEMS NAME then the value should be an integer>=0 or
|
|
||||||
``RTEMS_BUILD_NAME( 'U', 'I', '1', ' ' )``
|
|
||||||
|
|
||||||
DEFAULT VALUE:
|
|
||||||
The default value should be in the following formats- Please note that the
|
|
||||||
'.' (full stop) is necessary.
|
|
||||||
|
|
||||||
- In case the value is not defined then: This is not defined by default.
|
|
||||||
|
|
||||||
- If we know the default value then: The default value is XXX.
|
|
||||||
|
|
||||||
- If the default value is BSP Specific then: This option is BSP specific.
|
|
||||||
|
|
||||||
DESCRIPTION:
|
|
||||||
The description of the macro. (No specific format)
|
|
||||||
|
|
||||||
NOTES:
|
|
||||||
Any further notes. (No specific format)
|
|
||||||
|
|
||||||
Configuration Example
|
|
||||||
=====================
|
|
||||||
|
|
||||||
In the following example, the configuration information for a system with a
|
|
||||||
single message queue, four (4) tasks, and a timeslice of fifty (50)
|
|
||||||
milliseconds is as follows:
|
|
||||||
|
|
||||||
.. code-block:: c
|
|
||||||
|
|
||||||
#include <bsp.h>
|
|
||||||
#define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
|
|
||||||
#define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
|
|
||||||
#define CONFIGURE_MICROSECONDS_PER_TICK 1000 /* 1 millisecond */
|
|
||||||
#define CONFIGURE_TICKS_PER_TIMESLICE 50 /* 50 milliseconds */
|
|
||||||
#define CONFIGURE_RTEMS_INIT_TASKS_TABLE
|
|
||||||
#define CONFIGURE_MAXIMUM_TASKS 4
|
|
||||||
#define CONFIGURE_MAXIMUM_MESSAGE_QUEUES 1
|
|
||||||
#define CONFIGURE_MESSAGE_BUFFER_MEMORY \
|
|
||||||
CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(20, sizeof(struct USER_MESSAGE))
|
|
||||||
#define CONFIGURE_INIT
|
|
||||||
#include <rtems/confdefs.h>
|
|
||||||
|
|
||||||
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
|
|
||||||
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
|
|
||||||
``/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
|
|
||||||
application requires a maximum of four (4) simultaneously existing Classic
|
|
||||||
API tasks. Similarly, by specifying ``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
|
|
||||||
USER_MESSAGE``.
|
|
||||||
|
|
||||||
- The ``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
|
|
||||||
times and linking errors produced.
|
|
||||||
|
|
||||||
This example illustrates that parameters have default values. Among other
|
|
||||||
things, the application implicitly used the following defaults:
|
|
||||||
|
|
||||||
- All unspecified types of communications and synchronization objects in the
|
|
||||||
Classic and POSIX Threads API have maximums of zero (0).
|
|
||||||
|
|
||||||
- The filesystem will be the default filesystem which is the In-Memory File
|
|
||||||
System (IMFS).
|
|
||||||
|
|
||||||
- The application will have the default number of priority levels.
|
|
||||||
|
|
||||||
- The minimum task stack size will be that recommended by RTEMS for the target
|
|
||||||
architecture.
|
|
||||||
|
|
||||||
.. _ConfigUnlimitedObjects:
|
|
||||||
|
|
||||||
Unlimited Objects
|
|
||||||
=================
|
|
||||||
|
|
||||||
In real-time embedded systems the RAM is normally a limited, critical resource
|
|
||||||
and dynamic allocation is avoided as much as possible to ensure predictable,
|
|
||||||
deterministic execution times. For such cases, see :ref:`Sizing the RTEMS
|
|
||||||
Workspace` for an overview of how to tune the size of the workspace.
|
|
||||||
Frequently when users are porting software to RTEMS the precise resource
|
|
||||||
requirements of the software is unknown. In these situations users do not need
|
|
||||||
to control the size of the workspace very tightly because they just want to get
|
|
||||||
the new software to run; later they can tune the workspace size as needed.
|
|
||||||
|
|
||||||
The following object classes in the Classic API can be configured in unlimited
|
|
||||||
mode:
|
|
||||||
|
|
||||||
- Barriers
|
|
||||||
|
|
||||||
- Message Queues
|
|
||||||
|
|
||||||
- Partitions
|
|
||||||
|
|
||||||
- Periods
|
|
||||||
|
|
||||||
- Ports
|
|
||||||
|
|
||||||
- Regions
|
|
||||||
|
|
||||||
- Semaphores
|
|
||||||
|
|
||||||
- Tasks
|
|
||||||
|
|
||||||
- Timers
|
|
||||||
|
|
||||||
Additionally, the following object classes from the POSIX API can be configured
|
|
||||||
in unlimited mode:
|
|
||||||
|
|
||||||
- Keys -- :c:func:`pthread_key_create`
|
|
||||||
|
|
||||||
- Key Value Pairs -- :c:func:`pthread_setspecific`
|
|
||||||
|
|
||||||
- Message Queues -- :c:func:`mq_open`
|
|
||||||
|
|
||||||
- Named Semaphores -- :c:func:`sem_open`
|
|
||||||
|
|
||||||
- Shared Memory -- :c:func:`shm_open`
|
|
||||||
|
|
||||||
- Threads -- :c:func:`pthread_create`
|
|
||||||
|
|
||||||
- Timers -- :c:func:`timer_create`
|
|
||||||
|
|
||||||
.. warning::
|
|
||||||
|
|
||||||
The following object classes can *not* be configured in unlimited mode:
|
|
||||||
|
|
||||||
- Drivers
|
|
||||||
|
|
||||||
- File Descriptors
|
|
||||||
|
|
||||||
- POSIX Queued Signals
|
|
||||||
|
|
||||||
- User Extensions
|
|
||||||
|
|
||||||
Due to the memory requirements of unlimited objects it is strongly recommended
|
|
||||||
to use them only in combination with the unified work areas. See :ref:`Separate
|
|
||||||
or Unified Work Areas` for more information on unified work areas.
|
|
||||||
|
|
||||||
The following example demonstrates how the two simple configuration defines for
|
|
||||||
unlimited objects and unified works areas can replace many seperate
|
|
||||||
configuration defines for supported object classes:
|
|
||||||
|
|
||||||
.. code-block:: c
|
|
||||||
|
|
||||||
#define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
|
|
||||||
#define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
|
|
||||||
#define CONFIGURE_UNIFIED_WORK_AREAS
|
|
||||||
#define CONFIGURE_UNLIMITED_OBJECTS
|
|
||||||
#define CONFIGURE_RTEMS_INIT_TASKS_TABLE
|
|
||||||
#define CONFIGURE_INIT
|
|
||||||
#include <rtems/confdefs.h>
|
|
||||||
|
|
||||||
Users are cautioned that using unlimited objects is not recommended for
|
|
||||||
production software unless the dynamic growth is absolutely required. It is
|
|
||||||
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
|
|
||||||
--------------------------
|
|
||||||
|
|
||||||
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
|
|
||||||
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
|
|
||||||
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``:
|
|
||||||
|
|
||||||
.. code-block:: c
|
|
||||||
|
|
||||||
#define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5)
|
|
||||||
|
|
||||||
.. index:: rtems_resource_is_unlimited
|
|
||||||
.. index:: rtems_resource_maximum_per_allocation
|
|
||||||
|
|
||||||
Object maximum specifications can be evaluated with the
|
|
||||||
``rtems_resource_is_unlimited`` and``rtems_resource_maximum_per_allocation``
|
|
||||||
macros.
|
|
||||||
|
|
||||||
.. _ConfigUnlimitedObjectsDefault:
|
|
||||||
|
|
||||||
Unlimited Objects by Default
|
|
||||||
----------------------------
|
|
||||||
|
|
||||||
To ease the burden of developers who are porting new software RTEMS also
|
|
||||||
provides the capability to make all object classes listed above operate in
|
|
||||||
unlimited mode in a simple manner. The application developer is only
|
|
||||||
responsible for enabling unlimited objects
|
|
||||||
(:ref:`CONFIGURE_UNLIMITED_OBJECTS`) and specifying the allocation size
|
|
||||||
(:ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`).
|
|
||||||
|
|
||||||
.. code-block:: c
|
|
||||||
|
|
||||||
#define CONFIGURE_UNLIMITED_OBJECTS
|
|
||||||
#define CONFIGURE_UNLIMITED_ALLOCATION_SIZE 5
|
|
||||||
|
|
||||||
General System Configuration
|
General System Configuration
|
||||||
============================
|
============================
|
||||||
412
c-user/config/intro.rst
Normal file
412
c-user/config/intro.rst
Normal file
@ -0,0 +1,412 @@
|
|||||||
|
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
||||||
|
|
||||||
|
.. 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
|
||||||
|
==================================
|
||||||
|
|
||||||
|
The user should be aware that the defaults are intentionally set as low as
|
||||||
|
possible. By default, no application resources are configured. The
|
||||||
|
``<rtems/confdefs.h>`` file ensures that at least one application task or
|
||||||
|
thread is configured and that at least one of the initialization task/thread
|
||||||
|
tables is configured.
|
||||||
|
|
||||||
|
.. _Sizing the RTEMS Workspace:
|
||||||
|
|
||||||
|
Sizing the RTEMS Workspace
|
||||||
|
==========================
|
||||||
|
|
||||||
|
The RTEMS Workspace is a user-specified block of memory reserved for use by
|
||||||
|
RTEMS. The application should NOT modify this memory. This area consists
|
||||||
|
primarily of the RTEMS data structures whose exact size depends upon the values
|
||||||
|
specified in the Configuration Table. In addition, task stacks and floating
|
||||||
|
point context areas are dynamically allocated from the RTEMS Workspace.
|
||||||
|
|
||||||
|
The ``<rtems/confdefs.h>`` mechanism calculates the size of the RTEMS Workspace
|
||||||
|
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.
|
||||||
|
|
||||||
|
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
|
||||||
|
error occurs and the system terminates.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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
|
||||||
|
concurrently exist in the system. Memory for all instances of that object class
|
||||||
|
is reserved at system initialization. The second way allocates memory for an
|
||||||
|
initial number of objects and increases the current allocation by a fixed
|
||||||
|
increment when required. Both ways allocate space from inside the RTEMS
|
||||||
|
Workspace.
|
||||||
|
|
||||||
|
See :ref:`ConfigUnlimitedObjects` for more details about the second way, which
|
||||||
|
allows for dynamic allocation of objects and therefore does not provide
|
||||||
|
determinism. This mode is useful mostly for when the number of objects cannot
|
||||||
|
be determined ahead of time or when porting software for which you do not know
|
||||||
|
the object requirements.
|
||||||
|
|
||||||
|
The space needed for stacks and for RTEMS objects will vary from one version of
|
||||||
|
RTEMS and from one target processor to another. Therefore it is safest to use
|
||||||
|
``<rtems/confdefs.h>`` and specify your application's requirements in terms of
|
||||||
|
the numbers of objects and multiples of ``RTEMS_MINIMUM_STACK_SIZE``, as far as
|
||||||
|
is possible. The automatic estimates of space required will in general change
|
||||||
|
when:
|
||||||
|
|
||||||
|
- a configuration parameter is changed,
|
||||||
|
|
||||||
|
- task or interrupt stack sizes change,
|
||||||
|
|
||||||
|
- the floating point attribute of a task changes,
|
||||||
|
|
||||||
|
- task floating point attribute is altered,
|
||||||
|
|
||||||
|
- RTEMS is upgraded, or
|
||||||
|
|
||||||
|
- the target processor is changed.
|
||||||
|
|
||||||
|
Failure to provide enough space in the RTEMS Workspace may result in fatal
|
||||||
|
run-time errors terminating the system.
|
||||||
|
|
||||||
|
Potential Issues with RTEMS Workspace Size Estimation
|
||||||
|
=====================================================
|
||||||
|
|
||||||
|
The ``<rtems/confdefs.h>`` file estimates the amount of memory required for the
|
||||||
|
RTEMS Workspace. This estimate is only as accurate as the information given to
|
||||||
|
``<rtems/confdefs.h>`` and may be either too high or too low for a variety of
|
||||||
|
reasons. Some of the reasons that ``<rtems/confdefs.h>`` may reserve too much
|
||||||
|
memory for RTEMS are:
|
||||||
|
|
||||||
|
- All tasks/threads are assumed to be floating point.
|
||||||
|
|
||||||
|
Conversely, there are many more reasons that the resource estimate could be too
|
||||||
|
low:
|
||||||
|
|
||||||
|
- Task/thread stacks greater than minimum size must be accounted for explicitly
|
||||||
|
by developer.
|
||||||
|
|
||||||
|
- Memory for messages is not included.
|
||||||
|
|
||||||
|
- Device driver requirements are not included.
|
||||||
|
|
||||||
|
- Network stack requirements are not included.
|
||||||
|
|
||||||
|
- Requirements for add-on libraries are not included.
|
||||||
|
|
||||||
|
In general, ``<rtems/confdefs.h>`` is very accurate when given enough
|
||||||
|
information. However, it is quite easy to use a library and forget to account
|
||||||
|
for its resources.
|
||||||
|
|
||||||
|
Format to be followed for making changes in this file
|
||||||
|
=====================================================
|
||||||
|
|
||||||
|
MACRO NAME:
|
||||||
|
Should be alphanumeric. Can have '_' (underscore).
|
||||||
|
|
||||||
|
DATA TYPE:
|
||||||
|
Please refer to all existing formats.
|
||||||
|
|
||||||
|
RANGE:
|
||||||
|
The range depends on the Data Type of the macro.
|
||||||
|
|
||||||
|
- If the data type is of type task priority, then its value should be an
|
||||||
|
integer in the range of 1 to 255.
|
||||||
|
|
||||||
|
- If the data type is an integer, then it can have numbers, characters (in
|
||||||
|
case the value is defined using another macro) and arithmetic operations
|
||||||
|
(+, -, \*, /).
|
||||||
|
|
||||||
|
- If the data type is a function pointer the first character should be an
|
||||||
|
alphabet or an underscore. The rest of the string can be alphanumeric.
|
||||||
|
|
||||||
|
- If the data type is RTEMS Attributes or RTEMS Mode then the string should
|
||||||
|
be alphanumeric.
|
||||||
|
|
||||||
|
- If the data type is RTEMS NAME then the value should be an integer>=0 or
|
||||||
|
``RTEMS_BUILD_NAME( 'U', 'I', '1', ' ' )``
|
||||||
|
|
||||||
|
DEFAULT VALUE:
|
||||||
|
The default value should be in the following formats- Please note that the
|
||||||
|
'.' (full stop) is necessary.
|
||||||
|
|
||||||
|
- In case the value is not defined then: This is not defined by default.
|
||||||
|
|
||||||
|
- If we know the default value then: The default value is XXX.
|
||||||
|
|
||||||
|
- If the default value is BSP Specific then: This option is BSP specific.
|
||||||
|
|
||||||
|
DESCRIPTION:
|
||||||
|
The description of the macro. (No specific format)
|
||||||
|
|
||||||
|
NOTES:
|
||||||
|
Any further notes. (No specific format)
|
||||||
|
|
||||||
|
Configuration Example
|
||||||
|
=====================
|
||||||
|
|
||||||
|
In the following example, the configuration information for a system with a
|
||||||
|
single message queue, four (4) tasks, and a timeslice of fifty (50)
|
||||||
|
milliseconds is as follows:
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
#include <bsp.h>
|
||||||
|
#define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
|
||||||
|
#define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
|
||||||
|
#define CONFIGURE_MICROSECONDS_PER_TICK 1000 /* 1 millisecond */
|
||||||
|
#define CONFIGURE_TICKS_PER_TIMESLICE 50 /* 50 milliseconds */
|
||||||
|
#define CONFIGURE_RTEMS_INIT_TASKS_TABLE
|
||||||
|
#define CONFIGURE_MAXIMUM_TASKS 4
|
||||||
|
#define CONFIGURE_MAXIMUM_MESSAGE_QUEUES 1
|
||||||
|
#define CONFIGURE_MESSAGE_BUFFER_MEMORY \
|
||||||
|
CONFIGURE_MESSAGE_BUFFERS_FOR_QUEUE(20, sizeof(struct USER_MESSAGE))
|
||||||
|
#define CONFIGURE_INIT
|
||||||
|
#include <rtems/confdefs.h>
|
||||||
|
|
||||||
|
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
|
||||||
|
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
|
||||||
|
``/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
|
||||||
|
application requires a maximum of four (4) simultaneously existing Classic
|
||||||
|
API tasks. Similarly, by specifying ``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
|
||||||
|
USER_MESSAGE``.
|
||||||
|
|
||||||
|
- The ``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
|
||||||
|
times and linking errors produced.
|
||||||
|
|
||||||
|
This example illustrates that parameters have default values. Among other
|
||||||
|
things, the application implicitly used the following defaults:
|
||||||
|
|
||||||
|
- All unspecified types of communications and synchronization objects in the
|
||||||
|
Classic and POSIX Threads API have maximums of zero (0).
|
||||||
|
|
||||||
|
- The filesystem will be the default filesystem which is the In-Memory File
|
||||||
|
System (IMFS).
|
||||||
|
|
||||||
|
- The application will have the default number of priority levels.
|
||||||
|
|
||||||
|
- The minimum task stack size will be that recommended by RTEMS for the target
|
||||||
|
architecture.
|
||||||
|
|
||||||
|
.. _ConfigUnlimitedObjects:
|
||||||
|
|
||||||
|
Unlimited Objects
|
||||||
|
=================
|
||||||
|
|
||||||
|
In real-time embedded systems the RAM is normally a limited, critical resource
|
||||||
|
and dynamic allocation is avoided as much as possible to ensure predictable,
|
||||||
|
deterministic execution times. For such cases, see :ref:`Sizing the RTEMS
|
||||||
|
Workspace` for an overview of how to tune the size of the workspace.
|
||||||
|
Frequently when users are porting software to RTEMS the precise resource
|
||||||
|
requirements of the software is unknown. In these situations users do not need
|
||||||
|
to control the size of the workspace very tightly because they just want to get
|
||||||
|
the new software to run; later they can tune the workspace size as needed.
|
||||||
|
|
||||||
|
The following object classes in the Classic API can be configured in unlimited
|
||||||
|
mode:
|
||||||
|
|
||||||
|
- Barriers
|
||||||
|
|
||||||
|
- Message Queues
|
||||||
|
|
||||||
|
- Partitions
|
||||||
|
|
||||||
|
- Periods
|
||||||
|
|
||||||
|
- Ports
|
||||||
|
|
||||||
|
- Regions
|
||||||
|
|
||||||
|
- Semaphores
|
||||||
|
|
||||||
|
- Tasks
|
||||||
|
|
||||||
|
- Timers
|
||||||
|
|
||||||
|
Additionally, the following object classes from the POSIX API can be configured
|
||||||
|
in unlimited mode:
|
||||||
|
|
||||||
|
- Keys -- :c:func:`pthread_key_create`
|
||||||
|
|
||||||
|
- Key Value Pairs -- :c:func:`pthread_setspecific`
|
||||||
|
|
||||||
|
- Message Queues -- :c:func:`mq_open`
|
||||||
|
|
||||||
|
- Named Semaphores -- :c:func:`sem_open`
|
||||||
|
|
||||||
|
- Shared Memory -- :c:func:`shm_open`
|
||||||
|
|
||||||
|
- Threads -- :c:func:`pthread_create`
|
||||||
|
|
||||||
|
- Timers -- :c:func:`timer_create`
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
The following object classes can *not* be configured in unlimited mode:
|
||||||
|
|
||||||
|
- Drivers
|
||||||
|
|
||||||
|
- File Descriptors
|
||||||
|
|
||||||
|
- POSIX Queued Signals
|
||||||
|
|
||||||
|
- User Extensions
|
||||||
|
|
||||||
|
Due to the memory requirements of unlimited objects it is strongly recommended
|
||||||
|
to use them only in combination with the unified work areas. See :ref:`Separate
|
||||||
|
or Unified Work Areas` for more information on unified work areas.
|
||||||
|
|
||||||
|
The following example demonstrates how the two simple configuration defines for
|
||||||
|
unlimited objects and unified works areas can replace many seperate
|
||||||
|
configuration defines for supported object classes:
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
#define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
|
||||||
|
#define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
|
||||||
|
#define CONFIGURE_UNIFIED_WORK_AREAS
|
||||||
|
#define CONFIGURE_UNLIMITED_OBJECTS
|
||||||
|
#define CONFIGURE_RTEMS_INIT_TASKS_TABLE
|
||||||
|
#define CONFIGURE_INIT
|
||||||
|
#include <rtems/confdefs.h>
|
||||||
|
|
||||||
|
Users are cautioned that using unlimited objects is not recommended for
|
||||||
|
production software unless the dynamic growth is absolutely required. It is
|
||||||
|
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
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
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
|
||||||
|
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
|
||||||
|
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``:
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
#define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5)
|
||||||
|
|
||||||
|
.. index:: rtems_resource_is_unlimited
|
||||||
|
.. index:: rtems_resource_maximum_per_allocation
|
||||||
|
|
||||||
|
Object maximum specifications can be evaluated with the
|
||||||
|
``rtems_resource_is_unlimited`` and``rtems_resource_maximum_per_allocation``
|
||||||
|
macros.
|
||||||
|
|
||||||
|
.. _ConfigUnlimitedObjectsDefault:
|
||||||
|
|
||||||
|
Unlimited Objects by Default
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
To ease the burden of developers who are porting new software RTEMS also
|
||||||
|
provides the capability to make all object classes listed above operate in
|
||||||
|
unlimited mode in a simple manner. The application developer is only
|
||||||
|
responsible for enabling unlimited objects
|
||||||
|
(:ref:`CONFIGURE_UNLIMITED_OBJECTS`) and specifying the allocation size
|
||||||
|
(:ref:`CONFIGURE_UNLIMITED_ALLOCATION_SIZE`).
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
#define CONFIGURE_UNLIMITED_OBJECTS
|
||||||
|
#define CONFIGURE_UNLIMITED_ALLOCATION_SIZE 5
|
||||||
@ -47,7 +47,7 @@ RTEMS Classic API Guide (|version|).
|
|||||||
fatal_error
|
fatal_error
|
||||||
board_support_packages
|
board_support_packages
|
||||||
user_extensions
|
user_extensions
|
||||||
configuring_a_system
|
config/index
|
||||||
self_contained_objects
|
self_contained_objects
|
||||||
multiprocessing
|
multiprocessing
|
||||||
symmetric_multiprocessing_services
|
symmetric_multiprocessing_services
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user