c-user: Use new template for integer config opts

Try to bring all descriptions up to date.  Add cross-references to
several options.  Clarify configuration value constraints.

Use this template also for initializer type options.

Close #3901.

1 files changed, 189 insertions, 72 deletions

diff --git a/c-user/config/posix-api.rst b/c-user/config/posix-api.rst
index 13ac18d..54e8d99 100644
--- a/c-user/config/posix-api.rst
+++ b/c-user/config/posix-api.rst
@@ -1,5 +1,6 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
+.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 
 POSIX API Configuration
@@ -20,21 +21,36 @@ CONFIGURE_MAXIMUM_POSIX_KEYS
 CONSTANT:
     ``CONFIGURE_MAXIMUM_POSIX_KEYS``
 
-DATA TYPE:
-    Unsigned integer (``uint32_t``).
-
-RANGE:
-    Zero or positive.
+OPTION TYPE:
+    This configuration option is an integer define.
 
 DEFAULT VALUE:
     The default value is 0.
 
+VALUE CONSTRAINTS:
+    The value of this configuration option shall satisfy all of the following
+    constraints:
+
+    * It shall be greater than or equal to 0.
+
+    * It shall be less than or equal to 65535.
+
+    * It shall be less than or equal to a
+      BSP-specific and application-specific value which depends on the size of the
+      memory available to the application.
+
+    * It may be defined through
+      :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
+      object class, if the value passed to :c:func:`rtems_resource_unlimited`
+      satisfies all other constraints of this configuration option.
+
 DESCRIPTION:
-    ``CONFIGURE_MAXIMUM_POSIX_KEYS`` is the maximum number of POSIX API Keys
-    that can be concurrently active.
+    The value of this configuration option defines the maximum number of POSIX
+    API Keys that can be concurrently active.
 
 NOTES:
-    This object class can be configured in unlimited allocation mode.
+    This object class can be configured in unlimited allocation mode, see
+    :ref:`ConfigUnlimitedObjects`.
 
 .. index:: CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS
 
@@ -46,24 +62,39 @@ CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS
 CONSTANT:
     ``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS``
 
-DATA TYPE:
-    Unsigned integer (``uint32_t``).
-
-RANGE:
-    Zero or positive.
+OPTION TYPE:
+    This configuration option is an integer define.
 
 DEFAULT VALUE:
     The default value is
-    :ref:`CONFIGURE_MAXIMUM_POSIX_KEYS <CONFIGURE_MAXIMUM_POSIX_KEYS>` *
-    :ref:`CONFIGURE_MAXIMUM_TASKS <CONFIGURE_MAXIMUM_TASKS>` +
-    :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS <CONFIGURE_MAXIMUM_POSIX_THREADS>`.
+    :ref:`CONFIGURE_MAXIMUM_POSIX_KEYS` *
+    :ref:`CONFIGURE_MAXIMUM_TASKS` +
+    :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS`.
+
+VALUE CONSTRAINTS:
+    The value of this configuration option shall satisfy all of the following
+    constraints:
+
+    * It shall be greater than or equal to 0.
+
+    * It shall be less than or equal to 65535.
+
+    * It shall be less than or equal to a
+      BSP-specific and application-specific value which depends on the size of the
+      memory available to the application.
+
+    * It may be defined through
+      :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
+      object class, if the value passed to :c:func:`rtems_resource_unlimited`
+      satisfies all other constraints of this configuration option.
 
 DESCRIPTION:
-    ``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS`` is the maximum number of key
+    The value of this configuration option defines the maximum number of key
     value pairs used by POSIX API Keys that can be concurrently active.
 
 NOTES:
-    This object class can be configured in unlimited allocation mode.
+    This object class can be configured in unlimited allocation mode, see
+    :ref:`ConfigUnlimitedObjects`.
 
     A key value pair is created by :c:func:`pthread_setspecific` if the value
     is not :c:macro:`NULL`, otherwise it is deleted.
@@ -78,23 +109,42 @@ CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES
 CONSTANT:
     ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES``
 
-DATA TYPE:
-    Unsigned integer (``uint32_t``).
-
-RANGE:
-    Zero or positive.
+OPTION TYPE:
+    This configuration option is an integer define.
 
 DEFAULT VALUE:
     The default value is 0.
 
+VALUE CONSTRAINTS:
+    The value of this configuration option shall satisfy all of the following
+    constraints:
+
+    * It shall be greater than or equal to 0.
+
+    * It shall be less than or equal to 65535.
+
+    * It shall be less than or equal to a
+      BSP-specific and application-specific value which depends on the size of the
+      memory available to the application.
+
+    * It shall be small enough so that the
+      RTEMS Workspace size calculation carried out by ``<rtems/confdefs.h>`` does
+      not overflow an integer of type ``uintptr_t``.
+
+    * It may be defined through
+      :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
+      object class, if the value passed to :c:func:`rtems_resource_unlimited`
+      satisfies all other constraints of this configuration option.
+
 DESCRIPTION:
-    ``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES`` is the maximum number of POSIX
+    The value of this configuration option defines the maximum number of POSIX
     API Message Queues that can be concurrently active.
 
 NOTES:
-    This object class can be configured in unlimited allocation mode.  You have
-    to account for the memory used to store the messages of each message queue,
-    see :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`.
+    This object class can be configured in unlimited allocation mode, see
+    :ref:`ConfigUnlimitedObjects`.  You have to account for the memory used to
+    store the messages of each message queue, see
+    :ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`.
 
 .. index:: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS
 
@@ -106,17 +156,28 @@ CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS
 CONSTANT:
     ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS``
 
-DATA TYPE:
-    Unsigned integer (``uint32_t``).
-
-RANGE:
-    Zero or positive.
+OPTION TYPE:
+    This configuration option is an integer define.
 
 DEFAULT VALUE:
     The default value is 0.
 
+VALUE CONSTRAINTS:
+    The value of this configuration option shall satisfy all of the following
+    constraints:
+
+    * It shall be greater than or equal to 0.
+
+    * It shall be less than or equal to a
+      BSP-specific and application-specific value which depends on the size of the
+      memory available to the application.
+
+    * It shall be small enough so that the
+      RTEMS Workspace size calculation carried out by ``<rtems/confdefs.h>`` does
+      not overflow an integer of type ``uintptr_t``.
+
 DESCRIPTION:
-    ``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS`` is the maximum number of POSIX
+    The value of this configuration option defines the maximum number of POSIX
     API Queued Signals that can be concurrently active.
 
 NOTES:
@@ -135,25 +196,44 @@ CONFIGURE_MAXIMUM_POSIX_SEMAPHORES
 CONSTANT:
     ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES``
 
-DATA TYPE:
-    Unsigned integer (``uint32_t``).
-
-RANGE:
-    Zero or positive.
+OPTION TYPE:
+    This configuration option is an integer define.
 
 DEFAULT VALUE:
     The default value is 0.
 
+VALUE CONSTRAINTS:
+    The value of this configuration option shall satisfy all of the following
+    constraints:
+
+    * It shall be greater than or equal to 0.
+
+    * It shall be less than or equal to 65535.
+
+    * It shall be less than or equal to a
+      BSP-specific and application-specific value which depends on the size of the
+      memory available to the application.
+
+    * It shall be small enough so that the
+      RTEMS Workspace size calculation carried out by ``<rtems/confdefs.h>`` does
+      not overflow an integer of type ``uintptr_t``.
+
+    * It may be defined through
+      :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
+      object class, if the value passed to :c:func:`rtems_resource_unlimited`
+      satisfies all other constraints of this configuration option.
+
 DESCRIPTION:
-    ``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES`` is the maximum number of POSIX API
-    Named Semaphores that can be concurrently active.
+    The value of this configuration option defines the maximum number of POSIX
+    API Named Semaphores that can be concurrently active.
 
 NOTES:
-    This object class can be configured in unlimited allocation mode.
+    This object class can be configured in unlimited allocation mode, see
+    :ref:`ConfigUnlimitedObjects`.
 
-    Named semaphores are created with ``sem_open()``.  Semaphores initialized
-    with ``sem_init()`` are not affected by this configuration option since the
-    storage space for these semaphores is user-provided.
+    Named semaphores are created with :c:func:`sem_open()`.  Semaphores
+    initialized with :c:func:`sem_init()` are not affected by this configuration
+    option since the storage space for these semaphores is user-provided.
 
 .. index:: CONFIGURE_MAXIMUM_POSIX_THREADS
 
@@ -165,32 +245,46 @@ CONFIGURE_MAXIMUM_POSIX_THREADS
 CONSTANT:
     ``CONFIGURE_MAXIMUM_POSIX_THREADS``
 
-DATA TYPE:
-    Unsigned integer (``uint32_t``).
-
-RANGE:
-    Zero or positive.
+OPTION TYPE:
+    This configuration option is an integer define.
 
 DEFAULT VALUE:
     The default value is 0.
 
+VALUE CONSTRAINTS:
+    The value of this configuration option shall satisfy all of the following
+    constraints:
+
+    * It shall be greater than or equal to 0.
+
+    * It shall be less than or equal to 65535.
+
+    * It shall be less than or equal to a
+      BSP-specific and application-specific value which depends on the size of the
+      memory available to the application.
+
+    * It shall be small enough so that the task
+      stack space calculation carried out by ``<rtems/confdefs.h>`` does not
+      overflow an integer of type ``uintptr_t``.
+
 DESCRIPTION:
-    ``CONFIGURE_MAXIMUM_POSIX_THREADS`` is the maximum number of POSIX API
-    Threads that can be concurrently active.
+    The value of this configuration option defines the maximum number of POSIX
+    API Threads that can be concurrently active.
 
 NOTES:
-    This object class can be configured in unlimited allocation mode.
+    This object class can be configured in unlimited allocation mode, see
+    :ref:`ConfigUnlimitedObjects`.
 
     This calculations for the required memory in the RTEMS Workspace for
     threads assume that each thread has a minimum stack size and has floating
-    point support enabled.  The configuration parameter
-    ``CONFIGURE_EXTRA_TASK_STACKS`` is used to specify thread stack
-    requirements *ABOVE* the minimum size required.  See :ref:`Reserve
+    point support enabled.  The configuration option
+    :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used to specify thread stack
+    requirements **above** the minimum size required.  See :ref:`Reserve
     Task/Thread Stack Memory Above Minimum` for more information about
     ``CONFIGURE_EXTRA_TASK_STACKS``.
 
     The maximum number of Classic API Tasks is specified by
-    :ref:`CONFIGURE_MAXIMUM_TASKS <CONFIGURE_MAXIMUM_TASKS>`.
+    :ref:`CONFIGURE_MAXIMUM_TASKS`.
 
     All POSIX threads have floating point enabled.
 
@@ -204,21 +298,36 @@ CONFIGURE_MAXIMUM_POSIX_TIMERS
 CONSTANT:
     ``CONFIGURE_MAXIMUM_POSIX_TIMERS``
 
-DATA TYPE:
-    Unsigned integer (``uint32_t``).
-
-RANGE:
-    Zero or positive.
+OPTION TYPE:
+    This configuration option is an integer define.
 
 DEFAULT VALUE:
     The default value is 0.
 
+VALUE CONSTRAINTS:
+    The value of this configuration option shall satisfy all of the following
+    constraints:
+
+    * It shall be greater than or equal to 0.
+
+    * It shall be less than or equal to 65535.
+
+    * It shall be less than or equal to a
+      BSP-specific and application-specific value which depends on the size of the
+      memory available to the application.
+
+    * It may be defined through
+      :c:func:`rtems_resource_unlimited` the enable unlimited objects for this
+      object class, if the value passed to :c:func:`rtems_resource_unlimited`
+      satisfies all other constraints of this configuration option.
+
 DESCRIPTION:
-    ``CONFIGURE_MAXIMUM_POSIX_TIMERS`` is the maximum number of POSIX API
-    Timers that can be concurrently active.
+    The value of this configuration option defines the maximum number of POSIX
+    API Timers that can be concurrently active.
 
 NOTES:
-    This object class can be configured in unlimited allocation mode.
+    This object class can be configured in unlimited allocation mode, see
+    :ref:`ConfigUnlimitedObjects`.
 
     Timers are only available if RTEMS was built with the
     ``--enable-posix`` build configuration option.
@@ -234,19 +343,27 @@ CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE
 CONSTANT:
     ``CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE``
 
-DATA TYPE:
-    Unsigned integer (``size_t``).
-
-RANGE:
-    Positive.
+OPTION TYPE:
+    This configuration option is an integer define.
 
 DEFAULT VALUE:
     The default value is two times the value of
-    :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE <CONFIGURE_MINIMUM_TASK_STACK_SIZE>`.
+    :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`.
+
+VALUE CONSTRAINTS:
+    The value of this configuration option shall satisfy all of the following
+    constraints:
+
+    * It shall be small enough so that the task
+      stack space calculation carried out by ``<rtems/confdefs.h>`` does not
+      overflow an integer of type ``uintptr_t``.
+
+    * It shall be greater than or equal to a
+      BSP-specific and application-specific minimum value.
 
 DESCRIPTION:
-    This configuration parameter defines the minimum stack size in bytes for
-    every POSIX thread in the system.
+    The value of this configuration option defines the minimum stack size in
+    bytes for every POSIX thread in the system.
 
 NOTES:
     None.