[rtems-docs commit] c-user: Split up configuring_a_system.rst
Sebastian Huber
sebh at rtems.org
Thu Mar 12 09:32:36 UTC 2020
Module: rtems-docs
Branch: master
Commit: a526872600d6df878fc55a7ac2d5d6bb079d095e
Changeset: http://git.rtems.org/rtems-docs/commit/?id=a526872600d6df878fc55a7ac2d5d6bb079d095e
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Sun Mar 8 18:19:42 2020 +0100
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.
---
.../{configuring_a_system.rst => config/index.rst} | 409 +-------------------
c-user/config/intro.rst | 412 +++++++++++++++++++++
c-user/index.rst | 2 +-
3 files changed, 415 insertions(+), 408 deletions(-)
diff --git a/c-user/configuring_a_system.rst b/c-user/config/index.rst
similarity index 88%
rename from c-user/configuring_a_system.rst
rename to c-user/config/index.rst
index 75b1c7b..982a258 100644
--- a/c-user/configuring_a_system.rst
+++ b/c-user/config/index.rst
@@ -9,414 +9,9 @@
Configuring a System
********************
-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
+.. toctree::
- #define CONFIGURE_UNLIMITED_OBJECTS
- #define CONFIGURE_UNLIMITED_ALLOCATION_SIZE 5
+ intro
General System Configuration
============================
diff --git a/c-user/config/intro.rst b/c-user/config/intro.rst
new file mode 100644
index 0000000..636a7b8
--- /dev/null
+++ b/c-user/config/intro.rst
@@ -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
diff --git a/c-user/index.rst b/c-user/index.rst
index 30cd165..e958481 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -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
More information about the vc
mailing list