[rtems-central commit] spec: Document barrier directives

[Sebastian Huber]

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

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Tue Feb  2 07:54:26 2021 +0100

spec: Document barrier directives

---

 spec/rtems/barrier/if/group.yml   | 10 ++++++++
 spec/rtems/barrier/if/release.yml | 38 +++++++++++++++++++++++------
 spec/rtems/barrier/if/wait.yml    | 51 +++++++++++++++++++++++++++++++++------
 3 files changed, 84 insertions(+), 15 deletions(-)

diff --git a/spec/rtems/barrier/if/group.yml b/spec/rtems/barrier/if/group.yml
index 254b180..dba5034 100644
--- a/spec/rtems/barrier/if/group.yml
+++ b/spec/rtems/barrier/if/group.yml
@@ -15,6 +15,16 @@ links:
   uid: header
 - role: interface-ingroup
   uid: ../../if/group
+- role: placement-order
+  uid: create
+- role: placement-order
+  uid: ident
+- role: placement-order
+  uid: delete
+- role: placement-order
+  uid: wait
+- role: placement-order
+  uid: release
 name: Barrier Manager
 text: |
   The Classic API shall provide an interface to the Barrier Manager.
diff --git a/spec/rtems/barrier/if/release.yml b/spec/rtems/barrier/if/release.yml
index 1ff96d6..6310d18 100644
--- a/spec/rtems/barrier/if/release.yml
+++ b/spec/rtems/barrier/if/release.yml
@@ -1,5 +1,6 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Releases the barrier.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -12,25 +13,48 @@ definition:
     - ${/c/if/uint32_t:/name} *${.:/params[1]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive releases the barrier specified by ${.:/params[0]/name}.  All
+  tasks waiting at the barrier will be unblocked.  The number of released tasks
+  will be returned in ${.:/params[1]/name}.
 enabled-by: true
-index-entries: []
+index-entries:
+- release a barrier
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-isr
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/directive-may-preempt
 name: rtems_barrier_release
 notes: null
 params:
-- description: '%'
+- description: |
+    is the barrier identifier.
   dir: null
   name: id
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to an integer variable.  The number of released tasks will
+    be stored in this variable, in case of a successful operation.
+  dir: out
   name: released
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      There was no barrier associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
 type: interface
diff --git a/spec/rtems/barrier/if/wait.yml b/spec/rtems/barrier/if/wait.yml
index 532a149..ceac80e 100644
--- a/spec/rtems/barrier/if/wait.yml
+++ b/spec/rtems/barrier/if/wait.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Waits at the barrier.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -12,25 +13,59 @@ definition:
     - ${../../type/if/interval:/name} ${.:/params[1]/name}
     return: ${../../status/if/code:/name}
   variants: []
-description: null
+description: |
+  This directive waits at the barrier specified by ${.:/params[0]/name}.  The
+  ${.:/params[1]/name} parameter defines how long the calling task is willing
+  to wait.  Use ${../../type/if/no-timeout:/name} to wait potentially forever,
+  otherwise set a timeout interval in clock ticks.
+
+  Conceptually, the calling task should always be thought of as blocking when
+  it makes this call and being unblocked when the barrier is released.  If the
+  barrier is configured for manual release, this rule of thumb will always be
+  valid.  If the barrier is configured for automatic release, all callers will
+  block except for the one which trips the automatic release condition.
 enabled-by: true
-index-entries: []
+index-entries:
+- wait at a barrier
 interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/clock-tick
 name: rtems_barrier_wait
-notes: null
+notes: |
+  For automatic release barriers, the maximum count of waiting tasks is defined
+  during barrier creation, see ${create:/name}.
 params:
-- description: '%'
+- description: |
+    is the barrier identifier.
   dir: null
   name: id
-- description: '%'
+- description: |
+    is the timeout in clock ticks.  Use ${../../type/if/no-timeout:/name} to
+    wait potentially forever.
   dir: null
   name: timeout
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      There was no barrier associated with the identifier specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
+  - description: |
+      The timeout happened while the calling task was waiting at the barrier.
+    value: ${../../status/if/timeout:/name}
+  - description: |
+      The barrier was deleted while the calling task was waiting at the
+      barrier.
+    value: ${../../status/if/object-was-deleted:/name}
 type: interface