spec: Convert initializer options

11 files changed, 119 insertions, 103 deletions

diff --git a/spec/acfg/opt/RTEMS-ACFG-OPT-APPLEXTRADRIVERS.yml b/spec/acfg/opt/RTEMS-ACFG-OPT-APPLEXTRADRIVERS.yml
index b66f2074..85df8c60 100644
--- a/spec/acfg/opt/RTEMS-ACFG-OPT-APPLEXTRADRIVERS.yml
+++ b/spec/acfg/opt/RTEMS-ACFG-OPT-APPLEXTRADRIVERS.yml
@@ -1,20 +1,24 @@
 SPDX-License-Identifier: CC-BY-SA-4.0
 active: true
-appl-config-option-data-type: |
-  device driver entry structures
+appl-config-option-type: initializer
 appl-config-option-default-value: |
-  This is not defined by default.
+  The default value is the empty list.
 appl-config-option-description: |
-  ``CONFIGURE_APPLICATION_EXTRA_DRIVERS`` is defined if the application has
-  device drivers it needs to include in the Device Driver Table.  This should
-  be defined to the set of device driver entries that will be placed in the
-  table at the *END* of the Device Driver Table.
+  The value of this configuration option is used to initialize the Device
+  Driver Table.
 appl-config-option-index: []
 appl-config-option-name: CONFIGURE_APPLICATION_EXTRA_DRIVERS
 appl-config-option-notes: |
-  None.
-appl-config-option-range: |
-  Undefined or set of device driver entry structures
+  The value of this configuration option is placed after the entries of other
+  device driver configuration options.
+
+  See :ref:`CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS` for an alternative
+  placement of application device driver initializers.
+appl-config-option-constraint:
+  custom:
+  - |
+    The value of this configuration option must be a list of initializers for
+    structures of type :c:type:`rtems_driver_address_table`.
 copyrights:
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 derived: false
diff --git a/spec/acfg/opt/RTEMS-ACFG-OPT-APPLPREREQUISITEDRIVERS.yml b/spec/acfg/opt/RTEMS-ACFG-OPT-APPLPREREQUISITEDRIVERS.yml
index c987960d..e3f118ad 100644
--- a/spec/acfg/opt/RTEMS-ACFG-OPT-APPLPREREQUISITEDRIVERS.yml
+++ b/spec/acfg/opt/RTEMS-ACFG-OPT-APPLPREREQUISITEDRIVERS.yml
@@ -1,25 +1,25 @@
 SPDX-License-Identifier: CC-BY-SA-4.0
 active: true
-appl-config-option-data-type: |
-  device driver entry structures
+appl-config-option-type: initializer
 appl-config-option-default-value: |
-  This is not defined by default.
+  The default value is the empty list.
 appl-config-option-description: |
-  ``CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS`` is defined if the
-  application has device drivers it needs to include in the Device Driver
-  Table.  This should be defined to the set of device driver entries that
-  will be placed in the table at the *FRONT* of the Device Driver Table and
-  initialized before any other drivers *EXCEPT* any BSP prerequisite drivers.
+  The value of this configuration option is used to initialize the Device
+  Driver Table.
 appl-config-option-index: []
 appl-config-option-name: CONFIGURE_APPLICATION_PREREQUISITE_DRIVERS
 appl-config-option-notes: |
-  In some cases, it is used by System On Chip BSPs to support peripheral
-  buses beyond those normally found on the System On Chip. For example, this
-  is used by one RTEMS system which has implemented a SPARC/ERC32 based board
-  with VMEBus. The VMEBus Controller initialization is performed by a device
-  driver configured via this configuration parameter.
-appl-config-option-range: |
-  Undefined or set of device driver entry structures
+  The value of this configuration option is placed after the entries defined by
+  :ref:`CONFIGURE_BSP_PREREQUISITE_DRIVERS` and before all other device driver
+  configuration options.
+
+  See :ref:`CONFIGURE_APPLICATION_EXTRA_DRIVERS` for an alternative placement
+  of application device driver initializers.
+appl-config-option-constraint:
+  custom:
+  - |
+    The value of this configuration option must be a list of initializers for
+    structures of type :c:type:`rtems_driver_address_table`.
 copyrights:
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 derived: false
diff --git a/spec/acfg/opt/RTEMS-ACFG-OPT-IDLETASKBODY.yml b/spec/acfg/opt/RTEMS-ACFG-OPT-IDLETASKBODY.yml
index ac0640f9..4ceca122 100644
--- a/spec/acfg/opt/RTEMS-ACFG-OPT-IDLETASKBODY.yml
+++ b/spec/acfg/opt/RTEMS-ACFG-OPT-IDLETASKBODY.yml
@@ -1,19 +1,25 @@
 SPDX-License-Identifier: CC-BY-SA-4.0
 active: true
-appl-config-option-data-type: |
-  Function pointer.
+appl-config-option-type: initializer
 appl-config-option-default-value: |
-  This is not defined by default.
+  If :ref:`BSP_IDLE_TASK_BODY` is defined, then this will be the default value,
+  otherwise the default value is ``_CPU_Thread_Idle_body``.
 appl-config-option-description: |
-  ``CONFIGURE_IDLE_TASK_BODY`` is set to the function name corresponding to
-  the application specific IDLE thread body.  If not specified, the BSP or
-  RTEMS default IDLE thread body will be used.
+  The value of this configuration option initializes the IDLE thread body.
 appl-config-option-index: []
 appl-config-option-name: CONFIGURE_IDLE_TASK_BODY
 appl-config-option-notes: |
-  None.
-appl-config-option-range: |
-  Undefined or valid function pointer.
+  IDLE threads must not block.  A blocking IDLE thread results in undefined
+  system behaviour because the scheduler assume that at least one ready thread
+  exists.
+
+  IDLE threads can be used to initialize the application, see configuration
+  option :ref:`CONFIGURE_IDLE_TASK_INITIALIZES_APPLICATION`.
+appl-config-option-constraint:
+  custom:
+  - |
+    The value of this configuration option must be defined to a valid function
+    pointer of the type ``void *( *idle_body )( uintptr_t )``.
 copyrights:
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 derived: false
diff --git a/spec/acfg/opt/RTEMS-ACFG-OPT-INITIALEXTENSIONS.yml b/spec/acfg/opt/RTEMS-ACFG-OPT-INITIALEXTENSIONS.yml
index 1ee5818a..5268cd7f 100644
--- a/spec/acfg/opt/RTEMS-ACFG-OPT-INITIALEXTENSIONS.yml
+++ b/spec/acfg/opt/RTEMS-ACFG-OPT-INITIALEXTENSIONS.yml
@@ -1,19 +1,22 @@
 SPDX-License-Identifier: CC-BY-SA-4.0
 active: true
-appl-config-option-data-type: |
-  List of user extension initializers (``rtems_extensions_table``).
+appl-config-option-type: initializer
 appl-config-option-default-value: |
-  This is not defined by default.
+  The default value is the empty list.
 appl-config-option-description: |
-  If ``CONFIGURE_INITIAL_EXTENSIONS`` is defined by the application, then
-  this application specific set of initial extensions will be placed in the
-  initial extension table.
+  The value of this configuration option is used to initialize the table of
+  initial user extensions.
 appl-config-option-index: []
 appl-config-option-name: CONFIGURE_INITIAL_EXTENSIONS
 appl-config-option-notes: |
-  None.
-appl-config-option-range: |
-  Undefined or a list of one or more user extensions.
+  The value of this configuration option is placed before the entries of
+  :ref:`BSP_INITIAL_EXTENSION` and after the entries of all other initial
+  user extensions.
+appl-config-option-constraint:
+  custom:
+  - |
+    The value of this configuration option must be a list of initializers for
+    structures of type :c:type:`rtems_extensions_table`.
 copyrights:
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 derived: false
diff --git a/spec/acfg/opt/RTEMS-ACFG-OPT-INITTASKENTRYPOINT.yml b/spec/acfg/opt/RTEMS-ACFG-OPT-INITTASKENTRYPOINT.yml
index 5c6b7a16..4b434ba4 100644
--- a/spec/acfg/opt/RTEMS-ACFG-OPT-INITTASKENTRYPOINT.yml
+++ b/spec/acfg/opt/RTEMS-ACFG-OPT-INITTASKENTRYPOINT.yml
@@ -1,20 +1,20 @@
 SPDX-License-Identifier: CC-BY-SA-4.0
 active: true
-appl-config-option-data-type: |
-  Task entry function pointer (``rtems_task_entry``).
+appl-config-option-type: initializer
 appl-config-option-default-value: |
   The default value is ``Init``.
 appl-config-option-description: |
-  ``CONFIGURE_INIT_TASK_ENTRY_POINT`` is the entry point (a.k.a. function
-  name) of the single initialization task defined by the Classic API
-  Initialization Tasks Table.
+  The value of this configuration option initializes the entry point of the
+  Classic API initialization task.
 appl-config-option-index: []
 appl-config-option-name: CONFIGURE_INIT_TASK_ENTRY_POINT
 appl-config-option-notes: |
-  The user must implement the function ``Init`` or the function name provided
-  in this configuration parameter.
-appl-config-option-range: |
-  Valid task entry function pointer.
+  The user must implement the function referenced by this configuration option.
+appl-config-option-constraint:
+  custom:
+  - |
+    The value of this configuration option must be defined to a valid function
+    pointer of the type ``void ( *entry_point )( rtems_task_argument )``.
 copyrights:
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 derived: false
diff --git a/spec/acfg/opt/RTEMS-ACFG-OPT-MPMPCITABLEPOINTER.yml b/spec/acfg/opt/RTEMS-ACFG-OPT-MPMPCITABLEPOINTER.yml
index 69ef8498..1900d536 100644
--- a/spec/acfg/opt/RTEMS-ACFG-OPT-MPMPCITABLEPOINTER.yml
+++ b/spec/acfg/opt/RTEMS-ACFG-OPT-MPMPCITABLEPOINTER.yml
@@ -1,20 +1,21 @@
 SPDX-License-Identifier: CC-BY-SA-4.0
 active: true
-appl-config-option-data-type: |
-  pointer to ``rtems_mpci_table``
-appl-config-option-default-value: |
-  This is not defined by default.
+appl-config-option-type: initializer
+appl-config-option-default-value: '``&MPCI_table``'
 appl-config-option-description: |
-  ``CONFIGURE_MP_MPCI_TABLE_POINTER`` is the pointer to the MPCI
-  Configuration Table.  The default value of this field is``&MPCI_table``.
+  The value of this configuration option initializes the MPCI Configuration
+  Table.
 appl-config-option-index: []
 appl-config-option-name: CONFIGURE_MP_MPCI_TABLE_POINTER
 appl-config-option-notes: |
   RTEMS provides a Shared Memory MPCI Device Driver which can be used on any
   Multiprocessor System assuming the BSP provides the proper set of
   supporting methods.
-appl-config-option-range: |
-  undefined or valid pointer
+appl-config-option-constraint:
+  custom:
+  - |
+    The value of this configuration option must be a pointer to
+    :c:type:`rtems_mpci_table`.
 copyrights:
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 derived: false
diff --git a/spec/acfg/opt/RTEMS-ACFG-OPT-POSIXINITTHREADENTRYPOINT.yml b/spec/acfg/opt/RTEMS-ACFG-OPT-POSIXINITTHREADENTRYPOINT.yml
index ae37deeb..aa602c0f 100644
--- a/spec/acfg/opt/RTEMS-ACFG-OPT-POSIXINITTHREADENTRYPOINT.yml
+++ b/spec/acfg/opt/RTEMS-ACFG-OPT-POSIXINITTHREADENTRYPOINT.yml
@@ -1,20 +1,19 @@
 SPDX-License-Identifier: CC-BY-SA-4.0
 active: true
-appl-config-option-data-type: |
-  POSIX thread function pointer (``void *(*entry_point)(void *)``).
-appl-config-option-default-value: |
-  The default value is ``POSIX_Init``.
+appl-config-option-type: initializer
+appl-config-option-default-value: '``POSIX_Init``'
 appl-config-option-description: |
-  ``CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT`` is the entry point
-  (a.k.a. function name) of the single initialization thread defined by the
-  POSIX API Initialization Threads Table.
+  The value of this configuration option initializes the entry point of the
+  POSIX API initialization thread.
 appl-config-option-index: []
 appl-config-option-name: CONFIGURE_POSIX_INIT_THREAD_ENTRY_POINT
 appl-config-option-notes: |
-  The user must implement the function ``POSIX_Init`` or the function name
-  provided in this configuration parameter.
-appl-config-option-range: |
-  Undefined or a valid POSIX thread function pointer.
+  The user must implement the function referenced by this configuration option.
+appl-config-option-constraint:
+  custom:
+  - |
+    The value of this configuration option must be defined to a valid function
+    pointer of the type ``void *( *entry_point )( void * )``.
 copyrights:
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 derived: false
diff --git a/spec/acfg/opt/RTEMS-ACFG-OPT-POSIXINITTHREADSTACKSIZE.yml b/spec/acfg/opt/RTEMS-ACFG-OPT-POSIXINITTHREADSTACKSIZE.yml
index 9a6ca421..6cf8424d 100644
--- a/spec/acfg/opt/RTEMS-ACFG-OPT-POSIXINITTHREADSTACKSIZE.yml
+++ b/spec/acfg/opt/RTEMS-ACFG-OPT-POSIXINITTHREADSTACKSIZE.yml
@@ -4,7 +4,7 @@ appl-config-option-type: integer
 appl-config-option-default-value: ':ref:`CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE`'
 appl-config-option-description: |
   The value of this configuration option defines the thread stack size of the
-  POSIX API initialization threads.
+  POSIX API initialization thread.
 appl-config-option-index: []
 appl-config-option-name: CONFIGURE_POSIX_INIT_THREAD_STACK_SIZE
 appl-config-option-notes: |
diff --git a/spec/acfg/opt/RTEMS-ACFG-OPT-TASKSTACKALLOCATOR.yml b/spec/acfg/opt/RTEMS-ACFG-OPT-TASKSTACKALLOCATOR.yml
index 91945453..c6dcd5b4 100644
--- a/spec/acfg/opt/RTEMS-ACFG-OPT-TASKSTACKALLOCATOR.yml
+++ b/spec/acfg/opt/RTEMS-ACFG-OPT-TASKSTACKALLOCATOR.yml
@@ -1,26 +1,28 @@
 SPDX-License-Identifier: CC-BY-SA-4.0
 active: true
-appl-config-option-data-type: |
-  Function pointer.
+appl-config-option-type: initializer
 appl-config-option-default-value: |
   The default value is ``_Workspace_Allocate``, which indicates that task
   stacks will be allocated from the RTEMS Workspace.
 appl-config-option-description: |
-  ``CONFIGURE_TASK_STACK_ALLOCATOR`` may point to a user provided routine to
-  allocate task stacks.
+  The value of this configuration option initializes the stack allocator
+  allocate handler.
 appl-config-option-index:
 - task stack allocator
 appl-config-option-name: CONFIGURE_TASK_STACK_ALLOCATOR
 appl-config-option-notes: |
   A correctly configured system must configure the following to be consistent:
 
-  - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT``
+  - :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT`
 
-  - ``CONFIGURE_TASK_STACK_ALLOCATOR``
+  - `CONFIGURE_TASK_STACK_ALLOCATOR`
 
-  - ``CONFIGURE_TASK_STACK_DEALLOCATOR``
-appl-config-option-range: |
-  Undefined or valid function pointer.
+  - :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR`
+appl-config-option-constraint:
+  custom:
+  - |
+    The value of this configuration option must be defined to a valid function
+    pointer of the type ``void *( *allocate )( size_t )``.
 copyrights:
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 derived: false
diff --git a/spec/acfg/opt/RTEMS-ACFG-OPT-TASKSTACKALLOCATORINIT.yml b/spec/acfg/opt/RTEMS-ACFG-OPT-TASKSTACKALLOCATORINIT.yml
index 071e1f8d..fee5437c 100644
--- a/spec/acfg/opt/RTEMS-ACFG-OPT-TASKSTACKALLOCATORINIT.yml
+++ b/spec/acfg/opt/RTEMS-ACFG-OPT-TASKSTACKALLOCATORINIT.yml
@@ -1,26 +1,25 @@
 SPDX-License-Identifier: CC-BY-SA-4.0
 active: true
-appl-config-option-data-type: |
-  Function pointer.
-appl-config-option-default-value: |
-  The default value is NULL, which indicates that task stacks will be
-  allocated from the RTEMS Workspace.
+appl-config-option-type: initializer
+appl-config-option-default-value: '``NULL``'
 appl-config-option-description: |
-  ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT`` configures the initialization
-  method for an application or BSP specific task stack allocation
-  implementation.
+  The value of this configuration option initializes the stack allocator
+  initialization handler.
 appl-config-option-index: []
 appl-config-option-name: CONFIGURE_TASK_STACK_ALLOCATOR_INIT
 appl-config-option-notes: |
   A correctly configured system must configure the following to be consistent:
 
-  - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT``
+  - `CONFIGURE_TASK_STACK_ALLOCATOR_INIT`
 
-  - ``CONFIGURE_TASK_STACK_ALLOCATOR``
+  - :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`
 
-  - ``CONFIGURE_TASK_STACK_DEALLOCATOR``
-appl-config-option-range: |
-  Undefined, NULL or valid function pointer.
+  - :ref:`CONFIGURE_TASK_STACK_DEALLOCATOR`
+appl-config-option-constraint:
+  custom:
+  - |
+    The value of this configuration option must be defined to a valid function
+    pointer of the type ``void ( *initialize )( size_t )`` or to ``NULL``.
 copyrights:
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 derived: false
diff --git a/spec/acfg/opt/RTEMS-ACFG-OPT-TASKSTACKDEALLOCATOR.yml b/spec/acfg/opt/RTEMS-ACFG-OPT-TASKSTACKDEALLOCATOR.yml
index bef3d41c..ddf1bef7 100644
--- a/spec/acfg/opt/RTEMS-ACFG-OPT-TASKSTACKDEALLOCATOR.yml
+++ b/spec/acfg/opt/RTEMS-ACFG-OPT-TASKSTACKDEALLOCATOR.yml
@@ -1,26 +1,28 @@
 SPDX-License-Identifier: CC-BY-SA-4.0
 active: true
-appl-config-option-data-type: |
-  Function pointer.
+appl-config-option-type: initializer
 appl-config-option-default-value: |
   The default value is ``_Workspace_Free``, which indicates that task stacks
   will be allocated from the RTEMS Workspace.
 appl-config-option-description: |
-  ``CONFIGURE_TASK_STACK_DEALLOCATOR`` may point to a user provided routine
-  to free task stacks.
+  The value of this configuration option initializes the stack allocator
+  deallocate handler.
 appl-config-option-index:
 - task stack deallocator
 appl-config-option-name: CONFIGURE_TASK_STACK_DEALLOCATOR
 appl-config-option-notes: |
   A correctly configured system must configure the following to be consistent:
 
-  - ``CONFIGURE_TASK_STACK_ALLOCATOR_INIT``
+  - :ref:`CONFIGURE_TASK_STACK_ALLOCATOR_INIT`
 
-  - ``CONFIGURE_TASK_STACK_ALLOCATOR``
+  - :ref:`CONFIGURE_TASK_STACK_ALLOCATOR`
 
-  - ``CONFIGURE_TASK_STACK_DEALLOCATOR``
-appl-config-option-range: |
-  Undefined or valid function pointer.
+  - `CONFIGURE_TASK_STACK_DEALLOCATOR`
+appl-config-option-constraint:
+  custom:
+  - |
+    The value of this configuration option must be defined to a valid function
+    pointer of the type ``void ( *deallocate )( void * )``.
 copyrights:
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 derived: false