[PATCH 1/6] c-user: Clarify BSP related configuration options

[Sebastian Huber]

Sort options alphabetically.

Update #3836.
---
 c-user/configuring_a_system.rst | 127 ++++++++++++++++++++--------------------
 1 file changed, 63 insertions(+), 64 deletions(-)

diff --git a/c-user/configuring_a_system.rst b/c-user/configuring_a_system.rst
index 4c7bae6..e45af77 100644
--- a/c-user/configuring_a_system.rst
+++ b/c-user/configuring_a_system.rst
@@ -3002,69 +3002,13 @@ DESCRIPTION:
 NOTES:
     None.
 
-BSP Specific Settings
-=====================
-
-This section describes BSP specific configuration settings used by
-``<rtems/confdefs.h>``.  The BSP specific configuration settings are defined in
-``<bsp.h>``.
-
-.. index:: CONFIGURE_DISABLE_BSP_SETTINGS
-
-.. _CONFIGURE_DISABLE_BSP_SETTINGS:
-
-CONFIGURE_DISABLE_BSP_SETTINGS
-------------------------------
-
-CONSTANT:
-    ``CONFIGURE_DISABLE_BSP_SETTINGS``
-
-DATA TYPE:
-    Boolean feature macro.
-
-RANGE:
-    Defined or undefined.
-
-DEFAULT VALUE:
-    This is not defined by default.
-
-DESCRIPTION:
-    All BSP specific configuration settings can be disabled by the application
-    with the ``CONFIGURE_DISABLE_BSP_SETTINGS`` option.
-
-NOTES:
-    None.
-
-.. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
-
-.. _CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK:
-
-CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
-----------------------------------
-
-CONSTANT:
-    ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK``
-
-DATA TYPE:
-    Boolean feature macro.
-
-RANGE:
-    Defined or undefined.
-
-DEFAULT VALUE:
-    This option is BSP specific.
-
-DESCRIPTION:
-    This configuration parameter is defined by a BSP to indicate that it does
-    not allocate all available memory to the C Program Heap used by the Malloc
-    Family of routines.
-
-    If defined, when ``malloc()`` is unable to allocate memory, it will call
-    the BSP supplied ``sbrk()`` to obtain more memory.
+BSP Related Configuration Options
+=================================
 
-NOTES:
-    This parameter should not be defined by the application. Only the BSP knows
-    how it allocates memory to the C Program Heap.
+This section describes configuration options related to the BSP.  Some
+configuration options may have a BSP-specific setting which is defined by
+``<bsp.h>``.  The BSP-specific settings can be disabled by the
+:ref:`CONFIGURE_DISABLE_BSP_SETTINGS` configuration option.
 
 .. index:: BSP_IDLE_TASK_BODY
 
@@ -3130,8 +3074,6 @@ NOTES:
 
     - If defined, then the application specified ``CONFIGURE_IDLE_TASK_SIZE``.
 
-.. COMMENT: XXX - add cross references to other related values.
-
 .. index:: BSP_INITIAL_EXTENSION
 
 .. _BSP_INITIAL_EXTENSION:
@@ -3247,6 +3189,63 @@ NOTES:
     configure common infrastructure such as bus controllers or probe for
     devices.
 
+.. index:: CONFIGURE_DISABLE_BSP_SETTINGS
+
+.. _CONFIGURE_DISABLE_BSP_SETTINGS:
+
+CONFIGURE_DISABLE_BSP_SETTINGS
+------------------------------
+
+CONSTANT:
+    ``CONFIGURE_DISABLE_BSP_SETTINGS``
+
+DATA TYPE:
+    Boolean feature macro.
+
+RANGE:
+    Defined or undefined.
+
+DEFAULT VALUE:
+    This is not defined by default.
+
+DESCRIPTION:
+    All BSP specific configuration settings can be disabled by the application
+    with the ``CONFIGURE_DISABLE_BSP_SETTINGS`` option.
+
+NOTES:
+    None.
+
+.. index:: CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
+
+.. _CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK:
+
+CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK
+----------------------------------
+
+CONSTANT:
+    ``CONFIGURE_MALLOC_BSP_SUPPORTS_SBRK``
+
+DATA TYPE:
+    Boolean feature macro.
+
+RANGE:
+    Defined or undefined.
+
+DEFAULT VALUE:
+    This option is BSP specific.
+
+DESCRIPTION:
+    This configuration parameter is defined by a BSP to indicate that it does
+    not allocate all available memory to the C Program Heap used by the Malloc
+    Family of routines.
+
+    If defined, when ``malloc()`` is unable to allocate memory, it will call
+    the BSP supplied ``sbrk()`` to obtain more memory.
+
+NOTES:
+    This parameter should not be defined by the application. Only the BSP knows
+    how it allocates memory to the C Program Heap.
+
 Idle Task Configuration
 =======================
 
-- 
2.16.4