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.

1 files changed, 2 insertions, 407 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
 ============================