[rtems-central commit] spec: Review configuration API

Sebastian Huber sebh at rtems.org
Fri Sep 25 11:43:12 UTC 2020


Module:    rtems-central
Branch:    master
Commit:    084bbeccd81212f40c92f5d4fa542946197a19f5
Changeset: http://git.rtems.org/rtems-central/commit/?id=084bbeccd81212f40c92f5d4fa542946197a19f5

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Fri Sep 25 13:26:28 2020 +0200

spec: Review configuration API

---

 spec/rtems/config/if/api-table.yml                 | 26 +++++++++++-----------
 spec/rtems/config/if/get-api-configuration.yml     |  3 ++-
 spec/rtems/config/if/get-copyright-notice.yml      |  4 ++--
 spec/rtems/config/if/get-do-zero-of-workspace.yml  |  4 ++--
 spec/rtems/config/if/get-idle-task-stack-size.yml  |  2 +-
 spec/rtems/config/if/get-idle-task.yml             |  2 +-
 spec/rtems/config/if/get-interrupt-stack-size.yml  |  2 +-
 spec/rtems/config/if/get-maximum-processors.yml    |  7 +++---
 spec/rtems/config/if/get-microseconds-per-tick.yml |  3 ++-
 spec/rtems/config/if/get-milliseconds-per-tick.yml |  3 ++-
 spec/rtems/config/if/get-nanoseconds-per-tick.yml  |  3 ++-
 .../if/get-stack-allocator-avoids-work-space.yml   |  4 ++--
 spec/rtems/config/if/get-ticks-per-timeslice.yml   |  2 +-
 spec/rtems/config/if/get-version-string.yml        |  6 ++---
 spec/rtems/config/if/has-hardware-fp.yml           |  8 ++++---
 spec/rtems/config/if/resource-is-unlimited.yml     |  4 +++-
 .../config/if/resource-maximum-per-allocation.yml  |  6 +++--
 spec/rtems/config/if/resource-unlimited.yml        |  6 +++--
 spec/rtems/config/if/stack-allocate-hook.yml       |  2 +-
 spec/rtems/config/if/stack-allocate-init-hook.yml  |  2 +-
 spec/rtems/config/if/stack-free-hook.yml           |  2 +-
 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 ff00330..1dd4922 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 c2fbc28..3171fd8 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 debeaa7..e5df8f3 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 de1dd01..cf3850c 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 7920a34..13e243e 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 7b14684..0c23e17 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 78a94c0..2d0ece2 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 6fb3bfe..3b6c339 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 7c4d876..aa64ce9 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 a0c4e42..cbe0b31 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 2cd6d4b..d88fc69 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 106cca3..1c3b51b 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 8011de7..0ae62ca 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 2cca0f6..8712286 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 b22d880..f6a9e71 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 29c5448..2f4550c 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 4fbbd13..bc94d0d 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 56661ec..a25352f 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 697d7c2..0e5ec36 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 15664af..bc5a6cd 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 2156b9f..de59be2 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:



More information about the vc mailing list