spec: Add constraints to semaphore manager

13 files changed, 123 insertions, 9 deletions

diff --git a/spec/constraint/priority-may-preempt.yml b/spec/constraint/priority-may-preempt.yml
new file mode 100644
index 00000000..317181f6
--- /dev/null
+++ b/spec/constraint/priority-may-preempt.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links: []
+rationale: null
+scope: user
+text: |
+  The directive may change the priority of another task which may preempt the
+  calling task.
+type: constraint
diff --git a/spec/rtems/constraint/directive-ctx-isr-no-wait.yml b/spec/rtems/constraint/directive-ctx-isr-no-wait.yml
index d34ad688..d3b5bb3b 100644
--- a/spec/rtems/constraint/directive-ctx-isr-no-wait.yml
+++ b/spec/rtems/constraint/directive-ctx-isr-no-wait.yml
@@ -6,6 +6,6 @@ links: []
 rationale: null
 scope: user
 text: |
-  The directive may be called from within interrupt context if the
-  ${../option/if/no-wait:/name} option is set.
+  When the ${../option/if/no-wait:/name} option is set, the directive may be
+  called from within interrupt context.
 type: constraint
diff --git a/spec/rtems/constraint/request-may-block.yml b/spec/rtems/constraint/request-may-block.yml
new file mode 100644
index 00000000..a4b51726
--- /dev/null
+++ b/spec/rtems/constraint/request-may-block.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links: []
+rationale: null
+scope: user
+text: |
+  When the request cannot be immediately satisfied and the
+  ${../option/if/wait:/name} option is set, the calling task blocks at some
+  point during the directive call.
+type: constraint
diff --git a/spec/rtems/sem/constraint/create-mrsp-not-locked.yml b/spec/rtems/sem/constraint/create-mrsp-not-locked.yml
new file mode 100644
index 00000000..b582aa2c
--- /dev/null
+++ b/spec/rtems/sem/constraint/create-mrsp-not-locked.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links: []
+rationale: null
+scope: user
+text: |
+  When a semaphore using the MrsP locking protocol is created, the initial
+  count shall be exactly one.
+type: constraint
diff --git a/spec/rtems/sem/constraint/obtain-devinit.yml b/spec/rtems/sem/constraint/obtain-devinit.yml
new file mode 100644
index 00000000..46a099ad
--- /dev/null
+++ b/spec/rtems/sem/constraint/obtain-devinit.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links: []
+rationale: null
+scope: user
+text: |
+  When a local semaphore is accessed and the request can be immediately
+  satisfied, the directive may be called from within device driver
+  initialization context.
+type: constraint
diff --git a/spec/rtems/sem/constraint/obtain-isr.yml b/spec/rtems/sem/constraint/obtain-isr.yml
new file mode 100644
index 00000000..e69be163
--- /dev/null
+++ b/spec/rtems/sem/constraint/obtain-isr.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links: []
+rationale: null
+scope: user
+text: |
+  When a local, counting semaphore or a local, simple binary semaphore is
+  accessed and the ${../../option/if/no-wait:/name} option is set, the
+  directive may be called from within interrupt context.
+type: constraint
diff --git a/spec/rtems/sem/constraint/release-devinit.yml b/spec/rtems/sem/constraint/release-devinit.yml
new file mode 100644
index 00000000..d926265c
--- /dev/null
+++ b/spec/rtems/sem/constraint/release-devinit.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links: []
+rationale: null
+scope: user
+text: |
+  When a local semaphore is accessed, the directive may be called from within
+  device driver initialization context.
+type: constraint
diff --git a/spec/rtems/sem/constraint/release-isr.yml b/spec/rtems/sem/constraint/release-isr.yml
new file mode 100644
index 00000000..9dc47cd8
--- /dev/null
+++ b/spec/rtems/sem/constraint/release-isr.yml
@@ -0,0 +1,11 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links: []
+rationale: null
+scope: user
+text: |
+  When a local, counting semaphore or a local, simple binary semaphore is
+  accessed, the directive may be called from within interrupt context.
+type: constraint
diff --git a/spec/rtems/sem/if/create.yml b/spec/rtems/sem/if/create.yml
index d9ba2392..805860ff 100644
--- a/spec/rtems/sem/if/create.yml
+++ b/spec/rtems/sem/if/create.yml
@@ -130,6 +130,8 @@ links:
 - role: constraint
   uid: /constraint/object-allocator
 - role: constraint
+  uid: ../constraint/create-mrsp-not-locked
+- role: constraint
   uid: ../constraint/max
 - role: constraint
   uid: /constraint/obj-unlimited-alloc
diff --git a/spec/rtems/sem/if/flush.yml b/spec/rtems/sem/if/flush.yml
index 6665a1e2..376c5b18 100644
--- a/spec/rtems/sem/if/flush.yml
+++ b/spec/rtems/sem/if/flush.yml
@@ -18,7 +18,7 @@ description: |
   directive.  Tasks which are unblocked as the result of this directive will
   return from the ${obtain:/name} directive with a status code of
   ${../../status/if/unsatisfied:/name} to indicate that the semaphore was not
-  acquired.
+  obtained.
 enabled-by: true
 index-entries:
 - flush a semaphore
@@ -29,12 +29,18 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: ../constraint/release-isr
+- role: constraint
+  uid: ../constraint/release-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/unblock-may-preempt
+- role: constraint
+  uid: /constraint/directive-remote
 name: rtems_semaphore_flush
 notes: |
-  This directive may unblock any number of tasks.  Any of the unblocked tasks
-  may preempt the calling task if the calling task's preemption mode is
-  enabled and an unblocked task has a higher priority than the calling task.
-
   If the task to be unblocked resides on a different node from the semaphore,
   then the waiting task is unblocked, and the proxy used to represent the
   task is reclaimed.
@@ -45,10 +51,10 @@ notes: |
   in SMP configurations.
 
   For barrier synchronization, the ${../../barrier/if/group:/name} offers a
-  cleaner alternative to using the ${flush:/name} directive.  Unlike POSIX
+  cleaner alternative to using the semaphore flush directive.  Unlike POSIX
   barriers, they have a manual release option.
 
-  Using the ${flush:/name} directive for condition synchronization in concert
+  Using the semaphore flush directive for condition synchronization in concert
   with another semaphore may be subject to the lost wake-up problem.  The
   following attempt to implement a condition variable is broken.
 
diff --git a/spec/rtems/sem/if/obtain.yml b/spec/rtems/sem/if/obtain.yml
index b7deb371..84e3abac 100644
--- a/spec/rtems/sem/if/obtain.yml
+++ b/spec/rtems/sem/if/obtain.yml
@@ -72,9 +72,17 @@ links:
 - role: interface-ingroup
   uid: group
 - role: constraint
+  uid: ../constraint/obtain-isr
+- role: constraint
+  uid: ../constraint/obtain-devinit
+- role: constraint
   uid: /constraint/directive-ctx-task
 - role: constraint
+  uid: ../../constraint/request-may-block
+- role: constraint
   uid: /constraint/clock-tick
+- role: constraint
+  uid: /constraint/directive-remote
 name: rtems_semaphore_obtain
 notes: |
   If a local, binary semaphore was created with the
diff --git a/spec/rtems/sem/if/release.yml b/spec/rtems/sem/if/release.yml
index 0861cfc3..f53cfc17 100644
--- a/spec/rtems/sem/if/release.yml
+++ b/spec/rtems/sem/if/release.yml
@@ -31,6 +31,16 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: ../constraint/release-isr
+- role: constraint
+  uid: ../constraint/release-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/unblock-may-preempt
+- role: constraint
+  uid: /constraint/directive-remote
 name: rtems_semaphore_release
 notes: |
   The calling task may be preempted if it causes a higher priority task to be
diff --git a/spec/rtems/sem/if/set-priority.yml b/spec/rtems/sem/if/set-priority.yml
index f7532a56..874353d9 100644
--- a/spec/rtems/sem/if/set-priority.yml
+++ b/spec/rtems/sem/if/set-priority.yml
@@ -43,6 +43,14 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-isr
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/priority-may-preempt
 name: rtems_semaphore_set_priority
 notes: |
   Please have a look at the following example: