spec: Review configuration API

21 files changed, 57 insertions, 44 deletions

diff --git a/spec/rtems/config/if/api-table.yml b/spec/rtems/config/if/api-table.yml
index ff00330a..1dd49223 100644
--- a/spec/rtems/config/if/api-table.yml
+++ b/spec/rtems/config/if/api-table.yml
@@ -7,7 +7,7 @@ copyrights:
 definition:
 - default:
     brief: |
-      This field contains the maximum number of Classic API Tasks which are
+      This member contains the maximum number of Classic API Tasks which are
       configured for this application.
     definition: ${/c/if/uint32_t:/name} ${.:name}
     description: null
@@ -16,7 +16,7 @@ definition:
   variants: []
 - default:
     brief: |
-      This field indicates if Classic API Notepads are enabled or disabled for
+      This member indicates if Classic API Notepads are enabled or disabled for
       this application.
     definition: ${/c/if/bool:/name} ${.:name}
     description: null
@@ -25,7 +25,7 @@ definition:
   variants: []
 - default:
     brief: |
-      This field contains the maximum number of Classic API Timers which are
+      This member contains the maximum number of Classic API Timers which are
       configured for this application.
     definition: ${/c/if/uint32_t:/name} ${.:name}
     description: null
@@ -34,7 +34,7 @@ definition:
   variants: []
 - default:
     brief: |
-      This field contains the maximum number of Classic API Semaphores which
+      This member contains the maximum number of Classic API Semaphores which
       are configured for this application.
     definition: ${/c/if/uint32_t:/name} ${.:name}
     description: null
@@ -43,7 +43,7 @@ definition:
   variants: []
 - default:
     brief: |
-      This field contains the maximum number of Classic API Message Queues
+      This member contains the maximum number of Classic API Message Queues
       which are configured for this application.
     definition: ${/c/if/uint32_t:/name} ${.:name}
     description: null
@@ -52,7 +52,7 @@ definition:
   variants: []
 - default:
     brief: |
-      This field contains the maximum number of Classic API Partitions which
+      This member contains the maximum number of Classic API Partitions which
       are configured for this application.
     definition: ${/c/if/uint32_t:/name} ${.:name}
     description: null
@@ -61,7 +61,7 @@ definition:
   variants: []
 - default:
     brief: |
-      This field contains the maximum number of Classic API Regions which are
+      This member contains the maximum number of Classic API Regions which are
       configured for this application.
     definition: ${/c/if/uint32_t:/name} ${.:name}
     description: null
@@ -70,7 +70,7 @@ definition:
   variants: []
 - default:
     brief: |
-      This field contains the maximum number of Classic API Dual Ported Memory
+      This member contains the maximum number of Classic API Dual Ported Memory
       Areas which are configured for this application.
     definition: ${/c/if/uint32_t:/name} ${.:name}
     description: null
@@ -79,7 +79,7 @@ definition:
   variants: []
 - default:
     brief: |
-      This field contains the maximum number of Classic API Rate Monotonic
+      This member contains the maximum number of Classic API Rate Monotonic
       Periods which are configured for this application.
     definition: ${/c/if/uint32_t:/name} ${.:name}
     description: null
@@ -88,7 +88,7 @@ definition:
   variants: []
 - default:
     brief: |
-      This field contains the maximum number of Classic API Barriers which are
+      This member contains the maximum number of Classic API Barriers which are
       configured for this application.
     definition: ${/c/if/uint32_t:/name} ${.:name}
     description: null
@@ -97,7 +97,7 @@ definition:
   variants: []
 - default:
     brief: |
-      This field contains the number of Classic API Initialization
+      This member contains the number of Classic API Initialization
       Tasks which are configured for this application.
     definition: ${/c/if/uint32_t:/name} ${.:name}
     description: null
@@ -106,8 +106,8 @@ definition:
   variants: []
 - default:
     brief: |
-      This field contains the pointer to Classic API Initialization Tasks Table
-      of this application.
+      This member contains the pointer to Classic API Initialization Tasks
+      Table of this application.
     definition: const ${../../task/if/initialization-table:/name} *${.:name}
     description: null
     kind: member
diff --git a/spec/rtems/config/if/get-api-configuration.yml b/spec/rtems/config/if/get-api-configuration.yml
index c2fbc28a..3171fd85 100644
--- a/spec/rtems/config/if/get-api-configuration.yml
+++ b/spec/rtems/config/if/get-api-configuration.yml
@@ -1,6 +1,7 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns the pointer to the Classic API Configuration Table of this application.
+  Returns the pointer to the Classic API Configuration Table of this
+  application.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
diff --git a/spec/rtems/config/if/get-copyright-notice.yml b/spec/rtems/config/if/get-copyright-notice.yml
index debeaa70..e5df8f3c 100644
--- a/spec/rtems/config/if/get-copyright-notice.yml
+++ b/spec/rtems/config/if/get-copyright-notice.yml
@@ -1,8 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Returns the pointer to the RTEMS copyright notice.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
     body: null
diff --git a/spec/rtems/config/if/get-do-zero-of-workspace.yml b/spec/rtems/config/if/get-do-zero-of-workspace.yml
index de1dd018..cf3850ce 100644
--- a/spec/rtems/config/if/get-do-zero-of-workspace.yml
+++ b/spec/rtems/config/if/get-do-zero-of-workspace.yml
@@ -1,7 +1,7 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns true, if the workspace is zeroed during system initialization,
-  otherwise returns false.
+  Returns true, if the RTEMS Workspace is zeroed during system initialization
+  for this application, otherwise returns false.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
diff --git a/spec/rtems/config/if/get-idle-task-stack-size.yml b/spec/rtems/config/if/get-idle-task-stack-size.yml
index 7920a34d..13e243e4 100644
--- a/spec/rtems/config/if/get-idle-task-stack-size.yml
+++ b/spec/rtems/config/if/get-idle-task-stack-size.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns the configured IDLE task stack size in bytes of this application.
+  Returns the IDLE task stack size in bytes of this application.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
diff --git a/spec/rtems/config/if/get-idle-task.yml b/spec/rtems/config/if/get-idle-task.yml
index 7b14684d..0c23e173 100644
--- a/spec/rtems/config/if/get-idle-task.yml
+++ b/spec/rtems/config/if/get-idle-task.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns the configured IDLE task entry of this application.
+  Returns the IDLE task entry of this application.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
diff --git a/spec/rtems/config/if/get-interrupt-stack-size.yml b/spec/rtems/config/if/get-interrupt-stack-size.yml
index 78a94c02..2d0ece20 100644
--- a/spec/rtems/config/if/get-interrupt-stack-size.yml
+++ b/spec/rtems/config/if/get-interrupt-stack-size.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns the configured interrupt stack size in bytes of this application.
+  Returns the interrupt stack size in bytes of this application.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
diff --git a/spec/rtems/config/if/get-maximum-processors.yml b/spec/rtems/config/if/get-maximum-processors.yml
index 6fb3bfe0..3b6c3392 100644
--- a/spec/rtems/config/if/get-maximum-processors.yml
+++ b/spec/rtems/config/if/get-maximum-processors.yml
@@ -17,10 +17,11 @@ links:
   uid: group
 name: rtems_configuration_get_maximum_processors
 notes: |
-  The actual number of processors available for the application will be less
-  than or equal to the configured maximum number of processors.
+  The actual number of processors available to the application is returned by
+  ${../../scheduler/if/get-processor-maximum:/name}.  It will be less than or
+  equal to the configured maximum number of processors.
 
-  On uniprocessor configurations this macro is a compile time constant which
+  In uniprocessor configurations, this macro is a compile time constant which
   evaluates to one.
 params: []
 return:
diff --git a/spec/rtems/config/if/get-microseconds-per-tick.yml b/spec/rtems/config/if/get-microseconds-per-tick.yml
index 7c4d8765..aa64ce90 100644
--- a/spec/rtems/config/if/get-microseconds-per-tick.yml
+++ b/spec/rtems/config/if/get-microseconds-per-tick.yml
@@ -1,6 +1,7 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns the number of microseconds per tick configured for this application.
+  Returns the number of microseconds per clock tick configured for this
+  application.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
diff --git a/spec/rtems/config/if/get-milliseconds-per-tick.yml b/spec/rtems/config/if/get-milliseconds-per-tick.yml
index a0c4e42a..cbe0b31a 100644
--- a/spec/rtems/config/if/get-milliseconds-per-tick.yml
+++ b/spec/rtems/config/if/get-milliseconds-per-tick.yml
@@ -1,6 +1,7 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns the number of milliseconds per tick configured for this application.
+  Returns the number of milliseconds per clock tick configured for this
+  application.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
diff --git a/spec/rtems/config/if/get-nanoseconds-per-tick.yml b/spec/rtems/config/if/get-nanoseconds-per-tick.yml
index 2cd6d4b5..d88fc692 100644
--- a/spec/rtems/config/if/get-nanoseconds-per-tick.yml
+++ b/spec/rtems/config/if/get-nanoseconds-per-tick.yml
@@ -1,6 +1,7 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns the number of microseconds per tick configured for this application.
+  Returns the number of microseconds per clock tick configured for this
+  application.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
diff --git a/spec/rtems/config/if/get-stack-allocator-avoids-work-space.yml b/spec/rtems/config/if/get-stack-allocator-avoids-work-space.yml
index 106cca32..1c3b51b6 100644
--- a/spec/rtems/config/if/get-stack-allocator-avoids-work-space.yml
+++ b/spec/rtems/config/if/get-stack-allocator-avoids-work-space.yml
@@ -1,7 +1,7 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns true, if the thread stack allocator avoids the workspace, otherwise
-  returns false.
+  Returns true, if the thread stack allocator avoids the RTEMS Workspace,
+  otherwise returns false.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
diff --git a/spec/rtems/config/if/get-ticks-per-timeslice.yml b/spec/rtems/config/if/get-ticks-per-timeslice.yml
index 8011de74..0ae62ca7 100644
--- a/spec/rtems/config/if/get-ticks-per-timeslice.yml
+++ b/spec/rtems/config/if/get-ticks-per-timeslice.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns the ticks per timeslice configured for this application.
+  Returns the clock ticks per timeslice configured for this application.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
diff --git a/spec/rtems/config/if/get-version-string.yml b/spec/rtems/config/if/get-version-string.yml
index 2cca0f6a..87122860 100644
--- a/spec/rtems/config/if/get-version-string.yml
+++ b/spec/rtems/config/if/get-version-string.yml
@@ -1,8 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Returns the pointer to the RTEMS version string.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2009, 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default:
     body: null
diff --git a/spec/rtems/config/if/has-hardware-fp.yml b/spec/rtems/config/if/has-hardware-fp.yml
index b22d880c..f6a9e71d 100644
--- a/spec/rtems/config/if/has-hardware-fp.yml
+++ b/spec/rtems/config/if/has-hardware-fp.yml
@@ -1,8 +1,10 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  This constant evaluates to ${../../basedefs/if/true:/name}, if the this
+  processor variant has hardware floating point support, otherwise evaluates to
+  ${../../basedefs/if/false:/name}.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+- Copyright (C) 2009, 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default: ${/score/cpu/if/hardware-fp:/name}
   variants: []
diff --git a/spec/rtems/config/if/resource-is-unlimited.yml b/spec/rtems/config/if/resource-is-unlimited.yml
index 29c5448e..2f4550c9 100644
--- a/spec/rtems/config/if/resource-is-unlimited.yml
+++ b/spec/rtems/config/if/resource-is-unlimited.yml
@@ -15,7 +15,9 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_resource_is_unlimited
-notes: null
+notes: |
+  This function is implemented as a macro and can be used to define compile
+  time constants.
 params:
 - description: is the resource number.
   dir: null
diff --git a/spec/rtems/config/if/resource-maximum-per-allocation.yml b/spec/rtems/config/if/resource-maximum-per-allocation.yml
index 4fbbd13f..bc94d0d6 100644
--- a/spec/rtems/config/if/resource-maximum-per-allocation.yml
+++ b/spec/rtems/config/if/resource-maximum-per-allocation.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns the resource maximum number per allocation.
+  Returns the maximum number per allocation of a resource number.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
@@ -15,7 +15,9 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_resource_maximum_per_allocation
-notes: null
+notes: |
+  This function is implemented as a macro and can be used to define compile
+  time constants.
 params:
 - description: is the resource number.
   dir: null
diff --git a/spec/rtems/config/if/resource-unlimited.yml b/spec/rtems/config/if/resource-unlimited.yml
index 56661ec9..a25352f8 100644
--- a/spec/rtems/config/if/resource-unlimited.yml
+++ b/spec/rtems/config/if/resource-unlimited.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns the specified resource number configured for unlimited resources.
+  Returns the resource number configured for unlimited resources.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
@@ -15,7 +15,9 @@ links:
 - role: interface-ingroup
   uid: group
 name: rtems_resource_unlimited
-notes: null
+notes: |
+  This function is implemented as a macro and can be used to define compile
+  time constants.
 params:
 - description: is the resource number.
   dir: null
diff --git a/spec/rtems/config/if/stack-allocate-hook.yml b/spec/rtems/config/if/stack-allocate-hook.yml
index 697d7c2c..0e5ec36e 100644
--- a/spec/rtems/config/if/stack-allocate-hook.yml
+++ b/spec/rtems/config/if/stack-allocate-hook.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  The thread stack allocator allocate handler.
+  Thread stack allocator allocate handlers shall have this type.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
diff --git a/spec/rtems/config/if/stack-allocate-init-hook.yml b/spec/rtems/config/if/stack-allocate-init-hook.yml
index 15664afb..bc5a6cd1 100644
--- a/spec/rtems/config/if/stack-allocate-init-hook.yml
+++ b/spec/rtems/config/if/stack-allocate-init-hook.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  The thread stack allocator initialization handler.
+  Thread stack allocator initialization handlers shall have this type.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
diff --git a/spec/rtems/config/if/stack-free-hook.yml b/spec/rtems/config/if/stack-free-hook.yml
index 2156b9f4..de59be2d 100644
--- a/spec/rtems/config/if/stack-free-hook.yml
+++ b/spec/rtems/config/if/stack-free-hook.yml
@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  The thread stack allocator free handler.
+  Thread stack allocator free handlers shall have this type.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 definition: