mirror of
https://git.rtems.org/rtems-docs/
synced 2025-05-14 00:51:36 +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
|
||||
********************
|
||||
|
||||
Introduction
|
||||
============
|
||||
.. toctree::
|
||||
|
||||
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
|
||||
intro
|
||||
|
||||
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
|
||||
board_support_packages
|
||||
user_extensions
|
||||
configuring_a_system
|
||||
config/index
|
||||
self_contained_objects
|
||||
multiprocessing
|
||||
symmetric_multiprocessing_services
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user