spec: Polish configuration API

21 files changed, 159 insertions, 53 deletions

diff --git a/spec/acfg/val/acfg.yml b/spec/acfg/val/acfg.yml
index 00f78750..be11a7af 100644
--- a/spec/acfg/val/acfg.yml
+++ b/spec/acfg/val/acfg.yml
@@ -206,6 +206,54 @@ test-actions:
     - role: validation
       uid: /rtems/config/if/get-stack-free-hook
   - brief: |
+      Check the configured ${/acfg/if/task-stack-allocator-for-idle:/name} hook.
+    code: |
+      T_eq_ptr(
+        rtems_configuration_get_stack_allocate_for_idle_hook(),
+        test_idle_task_stack_allocate
+      );
+    links:
+    - role: validation
+      uid: ../if/task-stack-allocator-for-idle
+    - role: validation
+      uid: /rtems/config/if/get-stack-allocate-for-idle-hook
+  - brief: |
+      Check the configured ${/acfg/if/idle-task-stack-size:/name} value.
+    code: |
+      T_eq_sz(
+        rtems_configuration_get_idle_task_stack_size(),
+        TEST_IDLE_STACK_SIZE
+      );
+    links:
+    - role: validation
+      uid: ../if/idle-task-stack-size
+    - role: validation
+      uid: /rtems/config/if/get-idle-task-stack-size
+  - brief: |
+      Check the configured ${/acfg/if/idle-task-body:/name}.
+    code: |
+      T_eq_ptr(
+        rtems_configuration_get_idle_task(),
+        test_idle_task_body
+      );
+    links:
+    - role: validation
+      uid: ../if/idle-task-body
+    - role: validation
+      uid: /rtems/config/if/get-idle-task
+  - brief: |
+      Check the configured ${/acfg/if/interrupt-stack-size:/name} value.
+    code: |
+      T_eq_sz(
+        rtems_configuration_get_interrupt_stack_size(),
+        TEST_INTERRUPT_STACK_SIZE
+      );
+    links:
+    - role: validation
+      uid: ../if/interrupt-stack-size
+    - role: validation
+      uid: /rtems/config/if/get-interrupt-stack-size
+  - brief: |
       Check the configured ${/acfg/if/ticks-per-time-slice:/name} value.
     code: |
       T_eq_u32(
diff --git a/spec/rtems/config/req/get-idle-task-stack-size.yml b/spec/rtems/config/req/get-idle-task-stack-size.yml
index 8502a444..425c3643 100644
--- a/spec/rtems/config/req/get-idle-task-stack-size.yml
+++ b/spec/rtems/config/req/get-idle-task-stack-size.yml
@@ -6,10 +6,12 @@ links:
 - role: interface-function
   uid: ../if/get-idle-task-stack-size
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/idle-task-stack-size:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
-  The ${../if/get-idle-task-stack-size:/name} directive shall return the IDLE
-  task stack size configured by ${/acfg/if/idle-task-stack-size:/name}.
+  The ${../if/get-idle-task-stack-size:/name} directive shall return the
+  task stack size of each ${/glossary/idletask:/term}.
 type: requirement
diff --git a/spec/rtems/config/req/get-idle-task.yml b/spec/rtems/config/req/get-idle-task.yml
index 88208c87..04471e86 100644
--- a/spec/rtems/config/req/get-idle-task.yml
+++ b/spec/rtems/config/req/get-idle-task.yml
@@ -6,10 +6,12 @@ links:
 - role: interface-function
   uid: ../if/get-idle-task
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/idle-task-body:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
-  The ${../if/get-idle-task:/name} directive shall return the IDLE task body
-  configured by ${/acfg/if/idle-task-body:/name}.
+  The ${../if/get-idle-task:/name} directive shall return the address of task
+  body executed by each ${/glossary/idletask:/term}.
 type: requirement
diff --git a/spec/rtems/config/req/get-interrupt-stack-size.yml b/spec/rtems/config/req/get-interrupt-stack-size.yml
index 01915570..06d84538 100644
--- a/spec/rtems/config/req/get-interrupt-stack-size.yml
+++ b/spec/rtems/config/req/get-interrupt-stack-size.yml
@@ -6,10 +6,12 @@ links:
 - role: interface-function
   uid: ../if/get-interrupt-stack-size
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/interrupt-stack-size:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
   The ${../if/get-interrupt-stack-size:/name} directive shall return the
-  interrupt stack size configured by ${/acfg/if/interrupt-stack-size:/name}.
+  interrupt stack size.
 type: requirement
diff --git a/spec/rtems/config/req/get-maximum-barriers.yml b/spec/rtems/config/req/get-maximum-barriers.yml
index 09cd7993..22b3125b 100644
--- a/spec/rtems/config/req/get-maximum-barriers.yml
+++ b/spec/rtems/config/req/get-maximum-barriers.yml
@@ -6,11 +6,13 @@ links:
 - role: interface-function
   uid: ../if/get-maximum-barriers
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/max-barriers:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
   The ${../if/get-maximum-barriers:/name} directive shall return the maximum
-  number of Classic API Barriers that can be concurrently active configured by
-  ${/acfg/if/max-barriers:/name}.
+  number of objects managed by the ${../../barrier/if/group:/name} that can be
+  concurrently active.
 type: requirement
diff --git a/spec/rtems/config/req/get-maximum-extensions.yml b/spec/rtems/config/req/get-maximum-extensions.yml
index d9aac20a..09030fef 100644
--- a/spec/rtems/config/req/get-maximum-extensions.yml
+++ b/spec/rtems/config/req/get-maximum-extensions.yml
@@ -6,11 +6,13 @@ links:
 - role: interface-function
   uid: ../if/get-maximum-extensions
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/max-user-extensions:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
   The ${../if/get-maximum-extensions:/name} directive shall return the maximum
-  number of Classic API User Extensions that can be concurrently active
-  configured by ${/acfg/if/max-user-extensions:/name}.
+  number of objects managed by the ${../../userext/if/group:/name} that can be
+  concurrently active.
 type: requirement
diff --git a/spec/rtems/config/req/get-maximum-message-queues.yml b/spec/rtems/config/req/get-maximum-message-queues.yml
index ea87d2ea..bc4190d6 100644
--- a/spec/rtems/config/req/get-maximum-message-queues.yml
+++ b/spec/rtems/config/req/get-maximum-message-queues.yml
@@ -6,11 +6,13 @@ links:
 - role: interface-function
   uid: ../if/get-maximum-message-queues
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/max-message-queues:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
   The ${../if/get-maximum-message-queues:/name} directive shall return the
-  maximum number of Classic API Message Queues that can be concurrently active
-  configured by ${/acfg/if/max-message-queues:/name}.
+  maximum number of objects managed by the ${../../message/if/group:/name} that
+  can be concurrently active.
 type: requirement
diff --git a/spec/rtems/config/req/get-maximum-partitions.yml b/spec/rtems/config/req/get-maximum-partitions.yml
index 8a99e006..f8984ff8 100644
--- a/spec/rtems/config/req/get-maximum-partitions.yml
+++ b/spec/rtems/config/req/get-maximum-partitions.yml
@@ -6,11 +6,13 @@ links:
 - role: interface-function
   uid: ../if/get-maximum-partitions
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/max-partitions:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
   The ${../if/get-maximum-partitions:/name} directive shall return the maximum
-  number of Classic API Partitions that can be concurrently active configured
-  by ${/acfg/if/max-partitions:/name}.
+  number of objects managed by the ${../../part/if/group:/name} that can be
+  concurrently active.
 type: requirement
diff --git a/spec/rtems/config/req/get-maximum-periods.yml b/spec/rtems/config/req/get-maximum-periods.yml
index fca759cf..8d54e6cf 100644
--- a/spec/rtems/config/req/get-maximum-periods.yml
+++ b/spec/rtems/config/req/get-maximum-periods.yml
@@ -6,11 +6,13 @@ links:
 - role: interface-function
   uid: ../if/get-maximum-periods
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/max-periods:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
   The ${../if/get-maximum-periods:/name} directive shall return the maximum
-  number of Classic API Periods that can be concurrently active configured by
-  ${/acfg/if/max-periods:/name}.
+  number of objects managed by the ${../../ratemon/if/group:/name} that can be
+  concurrently active.
 type: requirement
diff --git a/spec/rtems/config/req/get-maximum-processors.yml b/spec/rtems/config/req/get-maximum-processors.yml
index 00ac633c..30ba56d4 100644
--- a/spec/rtems/config/req/get-maximum-processors.yml
+++ b/spec/rtems/config/req/get-maximum-processors.yml
@@ -6,10 +6,15 @@ links:
 - role: interface-function
   uid: ../if/get-maximum-processors
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/max-processors:/name} application configuration option.  The
+  maximum number of processors which are actually available for use by the
+  application is returned by
+  ${../../scheduler/if/get-processor-maximum:/name}.
 references: []
 requirement-type: functional
 text: |
   The ${../if/get-maximum-processors:/name} directive shall return the maximum
-  number of processors configured by ${/acfg/if/max-processors:/name}.
+  number of processors which can be managed by the system.
 type: requirement
diff --git a/spec/rtems/config/req/get-maximum-semaphores.yml b/spec/rtems/config/req/get-maximum-semaphores.yml
index d8dd775e..325ce6da 100644
--- a/spec/rtems/config/req/get-maximum-semaphores.yml
+++ b/spec/rtems/config/req/get-maximum-semaphores.yml
@@ -6,11 +6,13 @@ links:
 - role: interface-function
   uid: ../if/get-maximum-semaphores
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/max-semaphores:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
   The ${../if/get-maximum-semaphores:/name} directive shall return the maximum
-  number of Classic API Semaphores that can be concurrently active configured
-  by ${/acfg/if/max-semaphores:/name}.
+  number of objects managed by the ${../../sem/if/group:/name} that can be
+  concurrently active.
 type: requirement
diff --git a/spec/rtems/config/req/get-maximum-tasks.yml b/spec/rtems/config/req/get-maximum-tasks.yml
index 82159919..f3850687 100644
--- a/spec/rtems/config/req/get-maximum-tasks.yml
+++ b/spec/rtems/config/req/get-maximum-tasks.yml
@@ -6,11 +6,13 @@ links:
 - role: interface-function
   uid: ../if/get-maximum-tasks
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/max-tasks:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
   The ${../if/get-maximum-tasks:/name} directive shall return the maximum
-  number of Classic API Tasks that can be concurrently active configured by
-  ${/acfg/if/max-tasks:/name}.
+  number of objects managed by the ${../../task/if/group:/name} that can be
+  concurrently active.
 type: requirement
diff --git a/spec/rtems/config/req/get-maximum-timers.yml b/spec/rtems/config/req/get-maximum-timers.yml
index 71e89017..c5483c3b 100644
--- a/spec/rtems/config/req/get-maximum-timers.yml
+++ b/spec/rtems/config/req/get-maximum-timers.yml
@@ -6,11 +6,13 @@ links:
 - role: interface-function
   uid: ../if/get-maximum-timers
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/max-timers:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
   The ${../if/get-maximum-timers:/name} directive shall return the maximum
-  number of Classic API Timers that can be concurrently active configured by
-  ${/acfg/if/max-timers:/name}.
+  number of objects managed by the ${../../timer/if/group:/name} that can be
+  concurrently active.
 type: requirement
diff --git a/spec/rtems/config/req/get-microseconds-per-tick.yml b/spec/rtems/config/req/get-microseconds-per-tick.yml
index 8d36b75b..365bfe9a 100644
--- a/spec/rtems/config/req/get-microseconds-per-tick.yml
+++ b/spec/rtems/config/req/get-microseconds-per-tick.yml
@@ -6,11 +6,12 @@ links:
 - role: interface-function
   uid: ../if/get-microseconds-per-tick
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/microseconds-per-tick:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
   The ${../if/get-microseconds-per-tick:/name} directive shall return the
-  ${/glossary/clock-tick:/term} interval in microseconds configured by
-  ${/acfg/if/microseconds-per-tick:/name}.
+  ${/glossary/clock-tick:/term} interval in microseconds.
 type: requirement
diff --git a/spec/rtems/config/req/get-milliseconds-per-tick.yml b/spec/rtems/config/req/get-milliseconds-per-tick.yml
index 34bb8a5a..2ad765af 100644
--- a/spec/rtems/config/req/get-milliseconds-per-tick.yml
+++ b/spec/rtems/config/req/get-milliseconds-per-tick.yml
@@ -6,11 +6,12 @@ links:
 - role: interface-function
   uid: ../if/get-milliseconds-per-tick
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/microseconds-per-tick:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
   The ${../if/get-milliseconds-per-tick:/name} directive shall return the
-  ${/glossary/clock-tick:/term} interval in milliseconds configured by
-  ${/acfg/if/microseconds-per-tick:/name}.
+  ${/glossary/clock-tick:/term} interval in milliseconds.
 type: requirement
diff --git a/spec/rtems/config/req/get-nanoseconds-per-tick.yml b/spec/rtems/config/req/get-nanoseconds-per-tick.yml
index ad82916f..bca1ed85 100644
--- a/spec/rtems/config/req/get-nanoseconds-per-tick.yml
+++ b/spec/rtems/config/req/get-nanoseconds-per-tick.yml
@@ -6,11 +6,12 @@ links:
 - role: interface-function
   uid: ../if/get-nanoseconds-per-tick
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/microseconds-per-tick:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
   The ${../if/get-nanoseconds-per-tick:/name} directive shall return the
-  ${/glossary/clock-tick:/term} interval in nanoseconds configured by
-  ${/acfg/if/microseconds-per-tick:/name}.
+  ${/glossary/clock-tick:/term} interval in nanoseconds.
 type: requirement
diff --git a/spec/rtems/config/req/get-stack-allocate-for-idle-hook.yml b/spec/rtems/config/req/get-stack-allocate-for-idle-hook.yml
new file mode 100644
index 00000000..28897f95
--- /dev/null
+++ b/spec/rtems/config/req/get-stack-allocate-for-idle-hook.yml
@@ -0,0 +1,19 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: interface-function
+  uid: ../if/get-stack-allocate-for-idle-hook
+functional-type: function
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/task-stack-allocator-for-idle:/name} application configuration
+  option.
+references: []
+requirement-type: functional
+text: |
+  The ${../if/get-stack-allocate-for-idle-hook:/name} directive shall return
+  the stack allocator allocate handler used to allocate the task stack of each
+  ${/glossary/idletask:/term}.
+type: requirement
diff --git a/spec/rtems/config/req/get-stack-allocate-hook.yml b/spec/rtems/config/req/get-stack-allocate-hook.yml
index f3cc9644..2509533a 100644
--- a/spec/rtems/config/req/get-stack-allocate-hook.yml
+++ b/spec/rtems/config/req/get-stack-allocate-hook.yml
@@ -6,10 +6,13 @@ links:
 - role: interface-function
   uid: ../if/get-stack-allocate-hook
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/task-stack-allocator:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
-  The ${../if/get-stack-allocate-hook:/name} directive shall return the task
-  stack allocator hook configured by ${/acfg/if/task-stack-allocator:/name}.
+  The ${../if/get-stack-allocate-hook:/name} directive shall return the address
+  of the task stack allocator which is used to allocate the stack for a task
+  which is not an ${/glossary/idletask:/term}.
 type: requirement
diff --git a/spec/rtems/config/req/get-stack-allocator-avoids-work-space.yml b/spec/rtems/config/req/get-stack-allocator-avoids-work-space.yml
index dd5916a0..762b6b2b 100644
--- a/spec/rtems/config/req/get-stack-allocator-avoids-work-space.yml
+++ b/spec/rtems/config/req/get-stack-allocator-avoids-work-space.yml
@@ -6,7 +6,9 @@ links:
 - role: interface-function
   uid: ../if/get-stack-allocator-avoids-work-space
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/task-stack-no-workspace:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
diff --git a/spec/rtems/config/req/get-stack-free-hook.yml b/spec/rtems/config/req/get-stack-free-hook.yml
index c2824e78..1beaa8b7 100644
--- a/spec/rtems/config/req/get-stack-free-hook.yml
+++ b/spec/rtems/config/req/get-stack-free-hook.yml
@@ -6,10 +6,13 @@ links:
 - role: interface-function
   uid: ../if/get-stack-free-hook
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/task-stack-deallocator:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
-  The ${../if/get-stack-free-hook:/name} directive shall return the task stack
-  free hook configured by ${/acfg/if/task-stack-deallocator:/name}.
+  The ${../if/get-stack-free-hook:/name} directive shall return the address of
+  the task stack deallocator which is used to free the stack of a task which
+  was allocated by the task stack allocator.
 type: requirement
diff --git a/spec/rtems/config/req/get-ticks-per-timeslice.yml b/spec/rtems/config/req/get-ticks-per-timeslice.yml
index df2716f4..b93cbd5f 100644
--- a/spec/rtems/config/req/get-ticks-per-timeslice.yml
+++ b/spec/rtems/config/req/get-ticks-per-timeslice.yml
@@ -6,11 +6,12 @@ links:
 - role: interface-function
   uid: ../if/get-ticks-per-timeslice
 functional-type: function
-rationale: null
+rationale: |
+  The directive may be used to check the setting of the
+  ${/acfg/if/ticks-per-time-slice:/name} application configuration option.
 references: []
 requirement-type: functional
 text: |
   The ${../if/get-ticks-per-timeslice:/name} directive shall return the number
-  of ${/glossary/clock-tick:/plural} per timeslice configured by
-  ${/acfg/if/ticks-per-time-slice:/name}.
+  of ${/glossary/clock-tick:/plural} per timeslice.
 type: requirement