spec: Specify <sys/lock.h> mutexes

27 files changed, 832 insertions, 0 deletions

diff --git a/spec/c/if/ebusy.yml b/spec/c/if/ebusy.yml
new file mode 100644
index 00000000..7aaed3d2
--- /dev/null
+++ b/spec/c/if/ebusy.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
+index-entries: []
+interface-type: unspecified-define
+links:
+- role: interface-placement
+  uid: errno-header
+name: EBUSY
+references: []
+type: interface
diff --git a/spec/c/if/etimedout.yml b/spec/c/if/etimedout.yml
new file mode 100644
index 00000000..82401d66
--- /dev/null
+++ b/spec/c/if/etimedout.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
+index-entries: []
+interface-type: unspecified-define
+links:
+- role: interface-placement
+  uid: errno-header
+name: ETIMEDOUT
+references: []
+type: interface
diff --git a/spec/newlib/if/sys-lock-mutex-acquire-timed.yml b/spec/newlib/if/sys-lock-mutex-acquire-timed.yml
new file mode 100644
index 00000000..bad252f4
--- /dev/null
+++ b/spec/newlib/if/sys-lock-mutex-acquire-timed.yml
@@ -0,0 +1,14 @@
+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
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: sys-lock
+- role: interface-ingroup
+  uid: group
+name: _Mutex_Acquire_timed
+references: []
+type: interface
diff --git a/spec/newlib/if/sys-lock-mutex-acquire.yml b/spec/newlib/if/sys-lock-mutex-acquire.yml
new file mode 100644
index 00000000..14901e2e
--- /dev/null
+++ b/spec/newlib/if/sys-lock-mutex-acquire.yml
@@ -0,0 +1,14 @@
+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
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: sys-lock
+- role: interface-ingroup
+  uid: group
+name: _Mutex_Acquire
+references: []
+type: interface
diff --git a/spec/newlib/if/sys-lock-mutex-recursive-acquire-timed.yml b/spec/newlib/if/sys-lock-mutex-recursive-acquire-timed.yml
new file mode 100644
index 00000000..1d1faa22
--- /dev/null
+++ b/spec/newlib/if/sys-lock-mutex-recursive-acquire-timed.yml
@@ -0,0 +1,14 @@
+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
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: sys-lock
+- role: interface-ingroup
+  uid: group
+name: _Mutex_recursive_Acquire_timed
+references: []
+type: interface
diff --git a/spec/newlib/if/sys-lock-mutex-recursive-acquire.yml b/spec/newlib/if/sys-lock-mutex-recursive-acquire.yml
new file mode 100644
index 00000000..2f9a9bed
--- /dev/null
+++ b/spec/newlib/if/sys-lock-mutex-recursive-acquire.yml
@@ -0,0 +1,14 @@
+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
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: sys-lock
+- role: interface-ingroup
+  uid: group
+name: _Mutex_recursive_Acquire
+references: []
+type: interface
diff --git a/spec/newlib/if/sys-lock-mutex-recursive-release.yml b/spec/newlib/if/sys-lock-mutex-recursive-release.yml
new file mode 100644
index 00000000..33607d66
--- /dev/null
+++ b/spec/newlib/if/sys-lock-mutex-recursive-release.yml
@@ -0,0 +1,14 @@
+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
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: sys-lock
+- role: interface-ingroup
+  uid: group
+name: _Mutex_recursive_Release
+references: []
+type: interface
diff --git a/spec/newlib/if/sys-lock-mutex-recursive-try-acquire.yml b/spec/newlib/if/sys-lock-mutex-recursive-try-acquire.yml
new file mode 100644
index 00000000..453c6e89
--- /dev/null
+++ b/spec/newlib/if/sys-lock-mutex-recursive-try-acquire.yml
@@ -0,0 +1,14 @@
+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
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: sys-lock
+- role: interface-ingroup
+  uid: group
+name: _Mutex_recursive_Try_acquire
+references: []
+type: interface
diff --git a/spec/newlib/if/sys-lock-mutex-release.yml b/spec/newlib/if/sys-lock-mutex-release.yml
new file mode 100644
index 00000000..3d22df69
--- /dev/null
+++ b/spec/newlib/if/sys-lock-mutex-release.yml
@@ -0,0 +1,14 @@
+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
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: sys-lock
+- role: interface-ingroup
+  uid: group
+name: _Mutex_Release
+references: []
+type: interface
diff --git a/spec/newlib/if/sys-lock-mutex-try-acquire.yml b/spec/newlib/if/sys-lock-mutex-try-acquire.yml
new file mode 100644
index 00000000..e1d28f24
--- /dev/null
+++ b/spec/newlib/if/sys-lock-mutex-try-acquire.yml
@@ -0,0 +1,14 @@
+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
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: sys-lock
+- role: interface-ingroup
+  uid: group
+name: _Mutex_Try_acquire
+references: []
+type: interface
diff --git a/spec/newlib/req/sys-lock-mutex-acquire-timed.yml b/spec/newlib/req/sys-lock-mutex-acquire-timed.yml
new file mode 100644
index 00000000..08f5e49c
--- /dev/null
+++ b/spec/newlib/req/sys-lock-mutex-acquire-timed.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/sys-lock-mutex-acquire-timed
+- role: function-implementation
+  uid: /score/mtx/req/seize-wait
+- role: requirement-refinement
+  uid: sys-lock
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  The ${../if/sys-lock-mutex-acquire-timed:/name} directive shall seize the
+  mutex as specified by ${/score/mtx/req/seize-wait}.
+type: requirement
diff --git a/spec/newlib/req/sys-lock-mutex-acquire.yml b/spec/newlib/req/sys-lock-mutex-acquire.yml
new file mode 100644
index 00000000..1538c67b
--- /dev/null
+++ b/spec/newlib/req/sys-lock-mutex-acquire.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/sys-lock-mutex-acquire
+- role: function-implementation
+  uid: /score/mtx/req/seize-wait
+- role: requirement-refinement
+  uid: sys-lock
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  The ${../if/sys-lock-mutex-acquire:/name} directive shall seize the mutex as
+  specified by ${/score/mtx/req/seize-wait}.
+type: requirement
diff --git a/spec/newlib/req/sys-lock-mutex-clock-realtime.yml b/spec/newlib/req/sys-lock-mutex-clock-realtime.yml
new file mode 100644
index 00000000..8bbd8e79
--- /dev/null
+++ b/spec/newlib/req/sys-lock-mutex-clock-realtime.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: requirement-refinement
+  uid: sys-lock-mutex-acquire-timed
+- role: requirement-refinement
+  uid: sys-lock-mutex-recursive-acquire-timed
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  While the timeout parameter specifies a valid absolute
+  ${/glossary/clock-realtime:/term} time point, while the mutex is not avaiable
+  at the specified time point, the directive shall return with a status code of
+  ${/c/if/etimedout:/name}.
+type: requirement
diff --git a/spec/newlib/req/sys-lock-mutex-invalid-timeout.yml b/spec/newlib/req/sys-lock-mutex-invalid-timeout.yml
new file mode 100644
index 00000000..2e3c55e8
--- /dev/null
+++ b/spec/newlib/req/sys-lock-mutex-invalid-timeout.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: requirement-refinement
+  uid: sys-lock-mutex-acquire-timed
+- role: interface-function
+  uid: sys-lock-mutex-recursive-acquire-timed
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  While the mutex is not available, while the timeout parameter does not
+  specify a valid absolute ${/glossary/clock-realtime:/term} time point, if an
+  attempt to acquire the mutex is made, then the directive shall immediately
+  return with a status code of ${/c/if/einval:/name}.
+type: requirement
diff --git a/spec/newlib/req/sys-lock-mutex-omip.yml b/spec/newlib/req/sys-lock-mutex-omip.yml
new file mode 100644
index 00000000..fd4677c9
--- /dev/null
+++ b/spec/newlib/req/sys-lock-mutex-omip.yml
@@ -0,0 +1,24 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: RTEMS_SMP
+links:
+- role: requirement-refinement
+  uid: sys-lock-mutex-acquire
+- role: requirement-refinement
+  uid: sys-lock-mutex-acquire-timed
+- role: requirement-refinement
+  uid: sys-lock-mutex-release
+- role: requirement-refinement
+  uid: sys-lock-mutex-recursive-acquire
+- role: requirement-refinement
+  uid: sys-lock-mutex-recursive-acquire-timed
+- role: requirement-refinement
+  uid: sys-lock-mutex-recursive-release
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  The mutex operations shall use the ${/glossary/omip:/term} locking protocol.
+type: requirement
diff --git a/spec/newlib/req/sys-lock-mutex-priority-inherit.yml b/spec/newlib/req/sys-lock-mutex-priority-inherit.yml
new file mode 100644
index 00000000..229a1cf5
--- /dev/null
+++ b/spec/newlib/req/sys-lock-mutex-priority-inherit.yml
@@ -0,0 +1,26 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by:
+  not: RTEMS_SMP
+links:
+- role: requirement-refinement
+  uid: sys-lock-mutex-acquire
+- role: requirement-refinement
+  uid: sys-lock-mutex-acquire-timed
+- role: requirement-refinement
+  uid: sys-lock-mutex-release
+- role: requirement-refinement
+  uid: sys-lock-mutex-recursive-acquire
+- role: requirement-refinement
+  uid: sys-lock-mutex-recursive-acquire-timed
+- role: requirement-refinement
+  uid: sys-lock-mutex-recursive-release
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  The mutex operations shall use the ${/glossary/priorityinheritance:/term}
+  locking protocol.
+type: requirement
diff --git a/spec/newlib/req/sys-lock-mutex-recursive-acquire-timed.yml b/spec/newlib/req/sys-lock-mutex-recursive-acquire-timed.yml
new file mode 100644
index 00000000..fccce451
--- /dev/null
+++ b/spec/newlib/req/sys-lock-mutex-recursive-acquire-timed.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/sys-lock-mutex-recursive-acquire-timed
+- role: function-implementation
+  uid: /score/mtx/req/seize-wait
+- role: requirement-refinement
+  uid: sys-lock
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  The ${../if/sys-lock-mutex-recursive-acquire-timed:/name} directive shall
+  seize the mutex as specified by ${/score/mtx/req/seize-wait}.
+type: requirement
diff --git a/spec/newlib/req/sys-lock-mutex-recursive-acquire.yml b/spec/newlib/req/sys-lock-mutex-recursive-acquire.yml
new file mode 100644
index 00000000..afc5137c
--- /dev/null
+++ b/spec/newlib/req/sys-lock-mutex-recursive-acquire.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/sys-lock-mutex-recursive-acquire
+- role: function-implementation
+  uid: /score/mtx/req/seize-wait
+- role: requirement-refinement
+  uid: sys-lock
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  The ${../if/sys-lock-mutex-recursive-acquire:/name} directive shall seize the
+  mutex as specified by ${/score/mtx/req/seize-wait}.
+type: requirement
diff --git a/spec/newlib/req/sys-lock-mutex-recursive-allowed.yml b/spec/newlib/req/sys-lock-mutex-recursive-allowed.yml
new file mode 100644
index 00000000..83498c33
--- /dev/null
+++ b/spec/newlib/req/sys-lock-mutex-recursive-allowed.yml
@@ -0,0 +1,20 @@
+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: requirement-refinement
+  uid: sys-lock-mutex-recursive-acquire
+- role: requirement-refinement
+  uid: sys-lock-mutex-recursive-acquire-timed
+- role: requirement-refinement
+  uid: sys-lock-mutex-recursive-release
+- role: requirement-refinement
+  uid: sys-lock-mutex-recursive-try-acquire
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  The mutex may be acquired recursively.
+type: requirement
diff --git a/spec/newlib/req/sys-lock-mutex-recursive-busy.yml b/spec/newlib/req/sys-lock-mutex-recursive-busy.yml
new file mode 100644
index 00000000..4ec2f930
--- /dev/null
+++ b/spec/newlib/req/sys-lock-mutex-recursive-busy.yml
@@ -0,0 +1,15 @@
+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: requirement-refinement
+  uid: sys-lock-mutex-try-acquire
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  When an attempt to recursively acquire the mutex is made, the directive shall
+  immediately return with a status code of ${/c/if/ebusy:/name}.
+type: requirement
diff --git a/spec/newlib/req/sys-lock-mutex-recursive-fatal.yml b/spec/newlib/req/sys-lock-mutex-recursive-fatal.yml
new file mode 100644
index 00000000..3d970eba
--- /dev/null
+++ b/spec/newlib/req/sys-lock-mutex-recursive-fatal.yml
@@ -0,0 +1,18 @@
+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: requirement-refinement
+  uid: sys-lock-mutex-acquire
+- role: requirement-refinement
+  uid: sys-lock-mutex-acquire-timed
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  When an attempt to recursively acquire the mutex is made, the system shall
+  terminate with the ${/score/interr/if/internal-error-core:/name} fatal source
+  and the ${/score/interr/if/thread-queue-deadlock:/name} fatal code.
+type: requirement
diff --git a/spec/newlib/req/sys-lock-mutex-recursive-release.yml b/spec/newlib/req/sys-lock-mutex-recursive-release.yml
new file mode 100644
index 00000000..85be154f
--- /dev/null
+++ b/spec/newlib/req/sys-lock-mutex-recursive-release.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/sys-lock-mutex-recursive-release
+- role: function-implementation
+  uid: /score/mtx/req/surrender
+- role: requirement-refinement
+  uid: sys-lock
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  The ${../if/sys-lock-mutex-release:/name} directive shall surrender the mutex
+  as specified by ${/score/mtx/req/surrender}.
+type: requirement
diff --git a/spec/newlib/req/sys-lock-mutex-recursive-try-acquire.yml b/spec/newlib/req/sys-lock-mutex-recursive-try-acquire.yml
new file mode 100644
index 00000000..a0f4011b
--- /dev/null
+++ b/spec/newlib/req/sys-lock-mutex-recursive-try-acquire.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/sys-lock-mutex-recursive-try-acquire
+- role: function-implementation
+  uid: /score/mtx/req/seize-try
+- role: requirement-refinement
+  uid: sys-lock
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  The ${../if/sys-lock-mutex-recursive-try-acquire:/name} directive shall seize
+  the mutex as specified by ${/score/mtx/req/seize-try}.
+type: requirement
diff --git a/spec/newlib/req/sys-lock-mutex-release.yml b/spec/newlib/req/sys-lock-mutex-release.yml
new file mode 100644
index 00000000..e3e97fc4
--- /dev/null
+++ b/spec/newlib/req/sys-lock-mutex-release.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/sys-lock-mutex-release
+- role: function-implementation
+  uid: /score/mtx/req/surrender
+- role: requirement-refinement
+  uid: sys-lock
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  The ${../if/sys-lock-mutex-release:/name} directive shall surrender the mutex
+  as specified by ${/score/mtx/req/surrender}.
+type: requirement
diff --git a/spec/newlib/req/sys-lock-mutex-try-acquire.yml b/spec/newlib/req/sys-lock-mutex-try-acquire.yml
new file mode 100644
index 00000000..28cb56c5
--- /dev/null
+++ b/spec/newlib/req/sys-lock-mutex-try-acquire.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/sys-lock-mutex-try-acquire
+- role: function-implementation
+  uid: /score/mtx/req/seize-try
+- role: requirement-refinement
+  uid: sys-lock
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  The ${../if/sys-lock-mutex-try-acquire:/name} directive shall seize the mutex
+  as specified by ${/score/mtx/req/seize-try}.
+type: requirement
diff --git a/spec/newlib/req/sys-lock.yml b/spec/newlib/req/sys-lock.yml
new file mode 100644
index 00000000..98184464
--- /dev/null
+++ b/spec/newlib/req/sys-lock.yml
@@ -0,0 +1,21 @@
+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
+identifier: RTEMSScoreSysLockMutex
+links:
+- role: interface-ingroup
+  uid: /score/if/group
+non-functional-type: design-group
+rationale: |
+  The system lock mutexes are used for Newlib internal locking, the C++
+  standard library provided by ${/glossary/gcc:/term}, the OpenMP support
+  provided by GCC, the self-contained objects ${/glossary/api:/term} provided
+  by RTEMS, and the super core internal mutexes such as the objects allocator
+  lock.
+references: []
+requirement-type: non-functional
+text: |
+  The super core shall have a component containing the system lock mutex
+  implementation those interfaces are defined by Newlib.
+type: requirement
diff --git a/spec/newlib/val/sys-lock.yml b/spec/newlib/val/sys-lock.yml
new file mode 100644
index 00000000..c6358b26
--- /dev/null
+++ b/spec/newlib/val/sys-lock.yml
@@ -0,0 +1,382 @@
+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: []
+test-actions:
+- action-brief: |
+    Create a mutex and validate the mutex directives.
+  action-code: |
+    const struct timespec invalid_abstime = {
+      .tv_sec = -1,
+      .tv_nsec = -1
+    };
+    int                   eno;
+    struct _Mutex_Control mutex;
+
+    _Mutex_Initialize( &mutex );
+
+    ctx->tq_mtx_ctx.base.thread_queue_object = &mutex;
+    ctx->tq_mtx_ctx.base.enqueue_prepare = TQEnqueuePrepareDefault;
+    ctx->tq_mtx_ctx.base.enqueue_done = TQEnqueueDoneDefault;
+    ctx->tq_mtx_ctx.base.enqueue = Enqueue;
+    ctx->tq_mtx_ctx.base.surrender = Surrender;
+    ctx->tq_mtx_ctx.base.get_owner = GetOwner;
+  checks:
+  - brief: |
+      Validate the ${../if/sys-lock-mutex-try-acquire:/name} directive.
+    code: |
+      ctx->tq_mtx_ctx.base.wait = TQ_NO_WAIT;
+      ctx->tq_mtx_ctx.recursive = TQ_MTX_RECURSIVE_UNAVAILABLE;
+      ${/score/mtx/req/seize-try:/test-run}( &ctx->tq_mtx_ctx );
+    links:
+    - role: validation
+      uid: ../req/sys-lock-mutex-try-acquire
+    - role: validation
+      uid: ../req/sys-lock-mutex-recursive-busy
+  - brief: |
+      Validate the ${../if/sys-lock-mutex-acquire-timed:/name} directive for
+      valid timeout parameters.
+    code: |
+      ctx->tq_mtx_ctx.base.wait = TQ_WAIT_TIMED;
+      ctx->tq_mtx_ctx.recursive = TQ_MTX_RECURSIVE_DEADLOCK;
+      ${/score/mtx/req/seize-wait:/test-run}( &ctx->tq_mtx_ctx );
+    links:
+    - role: validation
+      uid: ../req/sys-lock-mutex-acquire-timed
+    - role: validation
+      uid: ../req/sys-lock-mutex-clock-realtime
+    - role: validation
+      uid: ../req/sys-lock-mutex-omip
+    - role: validation
+      uid: ../req/sys-lock-mutex-priority-inherit
+    - role: validation
+      uid: ../req/sys-lock-mutex-recursive-fatal
+  - brief: |
+      Validate the ${../if/sys-lock-mutex-acquire-timed:/name} directive for
+      an invalid timeout parameter.
+    code: |
+      TQSetScheduler(
+        &ctx->tq_mtx_ctx.base,
+        TQ_HELPER_A,
+        SCHEDULER_A_ID,
+        PRIO_HIGH
+      );
+      TQSend( &ctx->tq_mtx_ctx.base, TQ_HELPER_A, TQ_EVENT_ENQUEUE );
+      eno = _Mutex_Acquire_timed( &mutex, &invalid_abstime );
+      T_eq_int( eno, EINVAL );
+      TQSend( &ctx->tq_mtx_ctx.base, TQ_HELPER_A, TQ_EVENT_SURRENDER );
+    links:
+    - role: validation
+      uid: ../req/sys-lock-mutex-acquire-timed
+    - role: validation
+      uid: ../req/sys-lock-mutex-clock-realtime
+    - role: validation
+      uid: ../req/sys-lock-mutex-invalid-timeout
+  - brief: |
+      Validate the ${../if/sys-lock-mutex-acquire-timed:/name} timeout
+      behaviour.
+    code: |
+      ctx->tq_mtx_ctx.base.wait = TQ_WAIT_TIMED;
+      ctx->tq_mtx_ctx.recursive = TQ_MTX_RECURSIVE_DEADLOCK;
+      ${/score/tq/req/timeout-priority-inherit:/test-run}(
+        &ctx->tq_mtx_ctx.base
+      );
+    links:
+    - role: validation
+      uid: ../req/sys-lock-mutex-acquire-timed
+    - role: validation
+      uid: ../req/sys-lock-mutex-clock-realtime
+    - role: validation
+      uid: ../req/sys-lock-mutex-omip
+    - role: validation
+      uid: ../req/sys-lock-mutex-priority-inherit
+  - brief: |
+      Validate the ${../if/sys-lock-mutex-acquire:/name} directive.
+    code: |
+      ctx->tq_mtx_ctx.base.wait = TQ_WAIT_FOREVER;
+      ctx->tq_mtx_ctx.recursive = TQ_MTX_RECURSIVE_DEADLOCK;
+      ${/score/mtx/req/seize-wait:/test-run}( &ctx->tq_mtx_ctx );
+    links:
+    - role: validation
+      uid: ../req/sys-lock-mutex-acquire
+    - role: validation
+      uid: ../req/sys-lock-mutex-omip
+    - role: validation
+      uid: ../req/sys-lock-mutex-priority-inherit
+    - role: validation
+      uid: ../req/sys-lock-mutex-recursive-fatal
+  - brief: |
+      Validate the ${../if/sys-lock-mutex-try-acquire:/name} directive.
+    code: |
+      ctx->tq_mtx_ctx.base.wait = TQ_WAIT_FOREVER;
+      ctx->tq_mtx_ctx.recursive = TQ_MTX_RECURSIVE_DEADLOCK;
+      ${/score/mtx/req/surrender:/test-run}( &ctx->tq_mtx_ctx );
+    links:
+    - role: validation
+      uid: ../req/sys-lock-mutex-release
+    - role: validation
+      uid: ../req/sys-lock-mutex-omip
+    - role: validation
+      uid: ../req/sys-lock-mutex-priority-inherit
+  - brief: |
+      Destroy the mutex.
+    code: |
+      _Mutex_Destroy( &mutex );
+    links: []
+  links: []
+- action-brief: |
+    Create a recursive mutex and validate the mutex directives.
+  action-code: |
+    const struct timespec invalid_abstime = {
+      .tv_sec = -1,
+      .tv_nsec = -1
+    };
+    int                             eno;
+    struct _Mutex_recursive_Control mutex;
+
+    _Mutex_recursive_Initialize( &mutex );
+
+    ctx->tq_mtx_ctx.base.thread_queue_object = &mutex;
+    ctx->tq_mtx_ctx.base.enqueue_prepare = TQEnqueuePrepareDefault;
+    ctx->tq_mtx_ctx.base.enqueue_done = TQEnqueueDoneDefault;
+    ctx->tq_mtx_ctx.base.enqueue = RecursiveEnqueue;
+    ctx->tq_mtx_ctx.base.surrender = RecursiveSurrender;
+    ctx->tq_mtx_ctx.base.get_owner = RecursiveGetOwner;
+  checks:
+  - brief: |
+      Validate the ${../if/sys-lock-mutex-recursive-try-acquire:/name}
+      directive.
+    code: |
+      ctx->tq_mtx_ctx.base.wait = TQ_NO_WAIT;
+      ctx->tq_mtx_ctx.recursive = TQ_MTX_RECURSIVE_ALLOWED;
+      ${/score/mtx/req/seize-try:/test-run}( &ctx->tq_mtx_ctx );
+    links:
+    - role: validation
+      uid: ../req/sys-lock-mutex-recursive-try-acquire
+    - role: validation
+      uid: ../req/sys-lock-mutex-recursive-allowed
+  - brief: |
+      Validate the ${../if/sys-lock-mutex-recursive-acquire-timed:/name}
+      directive for valid timeout parameters.
+    code: |
+      ctx->tq_mtx_ctx.base.wait = TQ_WAIT_TIMED;
+      ctx->tq_mtx_ctx.recursive = TQ_MTX_RECURSIVE_ALLOWED;
+      ${/score/mtx/req/seize-wait:/test-run}( &ctx->tq_mtx_ctx );
+    links:
+    - role: validation
+      uid: ../req/sys-lock-mutex-recursive-acquire-timed
+    - role: validation
+      uid: ../req/sys-lock-mutex-clock-realtime
+    - role: validation
+      uid: ../req/sys-lock-mutex-omip
+    - role: validation
+      uid: ../req/sys-lock-mutex-priority-inherit
+    - role: validation
+      uid: ../req/sys-lock-mutex-recursive-allowed
+  - brief: |
+      Validate the ${../if/sys-lock-mutex-recursive-acquire-timed:/name}
+      directive for an invalid timeout parameter.
+    code: |
+      TQSetScheduler(
+        &ctx->tq_mtx_ctx.base,
+        TQ_HELPER_A,
+        SCHEDULER_A_ID,
+        PRIO_HIGH
+      );
+      TQSend( &ctx->tq_mtx_ctx.base, TQ_HELPER_A, TQ_EVENT_ENQUEUE );
+      eno = _Mutex_recursive_Acquire_timed( &mutex, &invalid_abstime );
+      T_eq_int( eno, EINVAL );
+      TQSend( &ctx->tq_mtx_ctx.base, TQ_HELPER_A, TQ_EVENT_SURRENDER );
+    links:
+    - role: validation
+      uid: ../req/sys-lock-mutex-recursive-acquire-timed
+    - role: validation
+      uid: ../req/sys-lock-mutex-clock-realtime
+    - role: validation
+      uid: ../req/sys-lock-mutex-invalid-timeout
+  - brief: |
+      Validate the ${../if/sys-lock-mutex-recursive-acquire-timed:/name}
+      timeout behaviour.
+    code: |
+      ctx->tq_mtx_ctx.base.wait = TQ_WAIT_TIMED;
+      ctx->tq_mtx_ctx.recursive = TQ_MTX_RECURSIVE_ALLOWED;
+      ${/score/tq/req/timeout-priority-inherit:/test-run}(
+        &ctx->tq_mtx_ctx.base
+      );
+    links:
+    - role: validation
+      uid: ../req/sys-lock-mutex-recursive-acquire-timed
+    - role: validation
+      uid: ../req/sys-lock-mutex-clock-realtime
+    - role: validation
+      uid: ../req/sys-lock-mutex-omip
+    - role: validation
+      uid: ../req/sys-lock-mutex-priority-inherit
+  - brief: |
+      Validate the ${../if/sys-lock-mutex-recursive-acquire:/name} directive.
+    code: |
+      ctx->tq_mtx_ctx.base.wait = TQ_WAIT_FOREVER;
+      ctx->tq_mtx_ctx.recursive = TQ_MTX_RECURSIVE_ALLOWED;
+      ${/score/mtx/req/seize-wait:/test-run}( &ctx->tq_mtx_ctx );
+    links:
+    - role: validation
+      uid: ../req/sys-lock-mutex-recursive-acquire
+    - role: validation
+      uid: ../req/sys-lock-mutex-omip
+    - role: validation
+      uid: ../req/sys-lock-mutex-priority-inherit
+    - role: validation
+      uid: ../req/sys-lock-mutex-recursive-allowed
+  - brief: |
+      Validate the ${../if/sys-lock-mutex-recursive-try-acquire:/name}
+      directive.
+    code: |
+      ctx->tq_mtx_ctx.base.wait = TQ_WAIT_FOREVER;
+      ctx->tq_mtx_ctx.recursive = TQ_MTX_RECURSIVE_ALLOWED;
+      ${/score/mtx/req/surrender:/test-run}( &ctx->tq_mtx_ctx );
+    links:
+    - role: validation
+      uid: ../req/sys-lock-mutex-recursive-release
+    - role: validation
+      uid: ../req/sys-lock-mutex-omip
+    - role: validation
+      uid: ../req/sys-lock-mutex-priority-inherit
+  - brief: |
+      Destroy the mutex.
+    code: |
+      _Mutex_recursive_Destroy( &mutex );
+    links: []
+  links: []
+test-brief: |
+  Tests the <sys/lock.h> mutex directives.
+test-context:
+- brief: |
+    This member contains the thread queue test context.
+  description: null
+  member: |
+    TQMtxContext tq_mtx_ctx
+test-context-support: null
+test-description: null
+test-header: null
+test-includes:
+- errno.h
+- string.h
+- sys/lock.h
+test-local-includes:
+- tr-mtx-seize-try.h
+- tr-mtx-seize-wait.h
+- tr-mtx-surrender.h
+- tr-tq-timeout-priority-inherit.h
+- tx-thread-queue.h
+test-setup:
+  brief: null
+  code: |
+    memset( ctx, 0, sizeof( *ctx ) );
+    ctx->tq_mtx_ctx.base.enqueue_variant = TQ_ENQUEUE_BLOCKS;
+    ctx->tq_mtx_ctx.base.discipline = TQ_PRIORITY;
+    ctx->tq_mtx_ctx.base.deadlock = TQ_DEADLOCK_FATAL;
+    ctx->tq_mtx_ctx.base.convert_status = TQConvertStatusPOSIX;
+    ctx->tq_mtx_ctx.protocol = TQ_MTX_PRIORITY_INHERIT;
+    ctx->tq_mtx_ctx.owner_check = TQ_MTX_NO_OWNER_CHECK;
+    ctx->tq_mtx_ctx.priority_ceiling = PRIO_INVALID;
+    TQInitialize( &ctx->tq_mtx_ctx.base );
+  description: null
+test-stop: null
+test-support: |
+  static Status_Control Enqueue( TQContext *ctx, TQWait wait )
+  {
+    const struct timespec abstime = {
+      .tv_sec = INT64_MAX,
+      .tv_nsec = 0
+    };
+    int                   eno;
+
+    switch ( wait ) {
+      case TQ_NO_WAIT:
+        eno = _Mutex_Try_acquire( ctx->thread_queue_object );
+        break;
+      case TQ_WAIT_FOREVER:
+        _Mutex_Acquire( ctx->thread_queue_object );
+        eno = 0;
+        break;
+      case TQ_WAIT_TIMED:
+        eno = _Mutex_Acquire_timed( ctx->thread_queue_object, &abstime );
+        break;
+      default:
+        T_unreachable();
+        break;
+    }
+
+    return STATUS_BUILD( 0, eno );
+  }
+
+  static Status_Control Surrender( TQContext *ctx )
+  {
+    _Mutex_Release( ctx->thread_queue_object );
+
+    return STATUS_SUCCESSFUL;
+  }
+
+  static rtems_tcb *GetOwner( TQContext *ctx )
+  {
+    const struct _Mutex_Control *mutex;
+
+    mutex = ctx->thread_queue_object;
+
+    return mutex->_Queue._owner;
+  }
+
+  static Status_Control RecursiveEnqueue( TQContext *ctx, TQWait wait )
+  {
+    const struct timespec abstime = {
+      .tv_sec = INT64_MAX,
+      .tv_nsec = 0
+    };
+    int                   eno;
+
+    switch ( wait ) {
+      case TQ_NO_WAIT:
+        eno = _Mutex_recursive_Try_acquire( ctx->thread_queue_object );
+        break;
+      case TQ_WAIT_FOREVER:
+        _Mutex_recursive_Acquire( ctx->thread_queue_object );
+        eno = 0;
+        break;
+      case TQ_WAIT_TIMED:
+        eno = _Mutex_recursive_Acquire_timed(
+          ctx->thread_queue_object,
+          &abstime
+        );
+        break;
+      default:
+        T_unreachable();
+        break;
+    }
+
+    return STATUS_BUILD( 0, eno );
+  }
+
+  static Status_Control RecursiveSurrender( TQContext *ctx )
+  {
+    _Mutex_recursive_Release( ctx->thread_queue_object );
+
+    return STATUS_SUCCESSFUL;
+  }
+
+  static rtems_tcb *RecursiveGetOwner( TQContext *ctx )
+  {
+    const struct _Mutex_recursive_Control *mutex;
+
+    mutex = ctx->thread_queue_object;
+
+    return mutex->_Mutex._Queue._owner;
+  }
+test-target: testsuites/validation/tc-sys-lock.c
+test-teardown:
+  brief: null
+  code: |
+    TQDestroy( &ctx->tq_mtx_ctx.base );
+    RestoreRunnerPriority();
+  description: null
+type: test-case