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.

3 files changed, 415 insertions, 408 deletions

diff --git a/c-user/configuring_a_system.rst b/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