diff options
Diffstat (limited to 'spec/rtems/sem')
-rw-r--r-- | spec/rtems/sem/if/create.yml | 183 | ||||
-rw-r--r-- | spec/rtems/sem/if/delete.yml | 30 | ||||
-rw-r--r-- | spec/rtems/sem/if/flush.yml | 30 | ||||
-rw-r--r-- | spec/rtems/sem/if/group.yml | 19 | ||||
-rw-r--r-- | spec/rtems/sem/if/header.yml | 12 | ||||
-rw-r--r-- | spec/rtems/sem/if/ident.yml | 86 | ||||
-rw-r--r-- | spec/rtems/sem/if/obtain.yml | 38 | ||||
-rw-r--r-- | spec/rtems/sem/if/release.yml | 30 | ||||
-rw-r--r-- | spec/rtems/sem/if/set-priority.yml | 42 | ||||
-rw-r--r-- | spec/rtems/sem/req/ident.yml | 15 | ||||
-rw-r--r-- | spec/rtems/sem/val/ident.yml | 49 |
11 files changed, 534 insertions, 0 deletions
diff --git a/spec/rtems/sem/if/create.yml b/spec/rtems/sem/if/create.yml new file mode 100644 index 00000000..e3a5e701 --- /dev/null +++ b/spec/rtems/sem/if/create.yml @@ -0,0 +1,183 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +brief: | + Creates a semaphore with the specified properties and returns its identifier. +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 + params: + - ${../../type/if/name:/name} ${.:/params[0]/name} + - ${/c/if/uint32_t:/name} ${.:/params[1]/name} + - ${../../attr/if/attribute:/name} ${.:/params[2]/name} + - ${../../task/if/priority:/name} ${.:/params[3]/name} + - ${../../type/if/id:/name} *${.:/params[4]/name} + return: ${../../status/if/code:/name} + variants: [] +description: | + This directive creates a semaphore which resides on the local node. The new + semaphore has the user-defined name specified in ``name`` and the initial + count specified in ``count``. For control and maintenance of the semaphore, + RTEMS allocates and initializes a ${/glossary/smcb:/term}. The + RTEMS-assigned semaphore identifier is returned in ``id``. This semaphore + identifier is used with other semaphore related directives to access the + semaphore. + + The attribute set specified in ``attribute_set`` defines + + * the scope of the semaphore (local or global), + + * the discipline of the task wait queue used by the semaphore (FIFO or + priority), + + * the class of the semaphore (counting, binary, or simple binary), and + + * the locking protocol of a binary semaphore (priority inheritance, priority + ceiling or MrsP). + + The attribute set is built through a *bitwise or* of the attribute constants + described below. Not all combinations of attributes are allowed. Some + attributes are mutually exclusive. If mutually exclusive attributes are + combined, the behaviour is undefined. + + The *scope of a semaphore* is either the local node only (local scope) or all + nodes in a multiprocessing network (global scope). The scope is selected by + the mutually exclusive ${../../attr/if/local:/name} and + ${../../attr/if/global:/name} attributes. + + * The local scope is the default and can be emphasized through use + of the ${../../attr/if/local:/name} attribute. + + * The global scope is selected by the ${../../attr/if/global:/name} attribute. In + a single node system and the local and global scope are identical. + + The *task wait queue discipline* is selected by the mutually exclusive + ${../../attr/if/fifo:/name} and ${../../attr/if/priority:/name} attributes. + + * The ${/glossary/fifo:/term} discipline is the default and can be emphasized + through use of the ${../../attr/if/fifo:/name} attribute. + + * The priority discipline is selected by the ${../../attr/if/priority:/name} + attribute. Some locking protocols require the priority discipline. + + The *semaphore class* is selected by the mutually exclusive + ${../../attr/if/counting-semaphore:/name}, + ${../../attr/if/binary-semaphore:/name}, and + ${../../attr/if/simple-binary-semaphore:/name} attributes. + + * Counting semaphores are the default and can be emphasized through use of + the ${../../attr/if/counting-semaphore:/name} attribute. + + * Binary semaphores are mutual exclusion (mutex) synchronization primitives + which may have an owner. The count of a binary semaphore is restricted to + 0 and 1. The binary semaphore class is selected by the + ${../../attr/if/binary-semaphore:/name} attribute. + + * Simple binary semaphores have no owner. The count of a simple binary + semaphore is restricted to 0 and 1. They may be used for task and + interrupt synchronization. The simple binary semaphore class is selected + by the ${../../attr/if/simple-binary-semaphore:/name} attribute. + + Binary semaphores may use a *locking protocol*. If a locking protocol is + selected, then the scope shall be local and the priority task wait queue + discipline shall be selected. The locking protocol is selected by the + mutually exclusive ${../../attr/if/inherit-priority:/name}, + ${../../attr/if/priority-ceiling:/name}, and + ${../../attr/if/multiprocessor-resource-sharing:/name} attributes. + + * The default is to use no locking protocol. + + * The ${../../attr/if/inherit-priority:/name} attribute selects the priority + inheritance locking protocol. + + * The ${../../attr/if/priority-ceiling:/name} attribute selects the priority + ceiling locking protocol. For this locking protocol a priority ceiling + shall be specified in ``priority_ceiling``. + + * The ${../../attr/if/multiprocessor-resource-sharing:/name} attribute selects the + MrsP locking protocol in SMP configurations, otherwise it selects the + priority ceiling protocol. For this locking protocol a priority ceiling + shall be specified in ``priority_ceiling``. This priority is used to set + the priority ceiling in all scheduler instances. This can be changed later + with the ${set-priority:/name} directive using the returned semaphore + identifier. +enabled-by: true +interface-type: function +links: +- role: interface-placement + uid: header +- role: interface-ingroup + uid: group +name: rtems_semaphore_create +notes: | + This directive may cause the calling task to be preempted due to an obtain + and release of the object allocator mutex. + + Semaphores should not be made global unless remote tasks must interact with + the new semaphore. This is to avoid the system overhead incurred by the + creation of a global semaphore. When a global semaphore is created, the + semaphore's name and identifier must be transmitted to every node in the + system for insertion in the local copy of the global object table. + + The total number of global objects, including semaphores, is limited by the + ${/acfg/if/mp-max-global-objects:/name} application configuration option. + + It is not allowed to create an initially locked MrsP semaphore and the + ${../../status/if/invalid-number:/name} status code will be returned in SMP + configurations in this case. This prevents lock order reversal problems + with the allocator mutex. +params: +- description: is the object name of the new semaphore. + dir: null + name: name +- description: | + is the initial count of the new semaphore. If the semaphore is a mutex, + then a count of 0 will make the calling task the owner of the new mutex and + a count of 1 will create a mutex without an owner. + dir: null + name: count +- description: | + is the attribute set which defines the properties of the new semaphore. + dir: null + name: attribute_set +- description: | + is the priority ceiling if the new semaphore is a binary semaphore with the + priority ceiling or MrsP semaphore locking protocol as defined by the + attribute set. + dir: null + name: priority_ceiling +- description: | + is the pointer to an object identifier variable. The object identifier of + the new semaphore will be stored in this variable, in case of a successful + operation. + dir: out + name: id +return: + return: null + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + The ${.:/params[3]/name} parameter was ${/c/if/null:/name}. + value: ${../../status/if/invalid-address:/name} + - description: | + The semaphore name was invalid. + value: ${../../status/if/invalid-name:/name} + - description: | + The priority ceiling was invalid. + value: ${../../status/if/invalid-priority:/name} + - description: | + The attribute set was invalid. + value: ${../../status/if/not-defined:/name} + - description: | + There was no inactive semaphore object available to create a new + semaphore. The semaphore object maximum is defined by the + ${/acfg/if/max-semaphores:/name} application configuration option. + value: ${../../status/if/too-many:/name} + - description: | + In multiprocessing configurations, there was no inactive global object + available to create a new global semaphore. + value: ${../../status/if/too-many:/name} +type: interface diff --git a/spec/rtems/sem/if/delete.yml b/spec/rtems/sem/if/delete.yml new file mode 100644 index 00000000..74f96cee --- /dev/null +++ b/spec/rtems/sem/if/delete.yml @@ -0,0 +1,30 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +brief: '%' +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 + params: + - ${../../type/if/id:/name} ${.:/params[0]/name} + return: ${../../status/if/code:/name} + variants: [] +description: null +enabled-by: true +interface-type: function +links: +- role: interface-placement + uid: header +- role: interface-ingroup + uid: group +name: rtems_semaphore_delete +notes: null +params: +- description: '%' + dir: null + name: id +return: + return: null + return-values: [] +type: interface diff --git a/spec/rtems/sem/if/flush.yml b/spec/rtems/sem/if/flush.yml new file mode 100644 index 00000000..c1f71a7b --- /dev/null +++ b/spec/rtems/sem/if/flush.yml @@ -0,0 +1,30 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +brief: '%' +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 + params: + - ${../../type/if/id:/name} ${.:/params[0]/name} + return: ${../../status/if/code:/name} + variants: [] +description: null +enabled-by: true +interface-type: function +links: +- role: interface-placement + uid: header +- role: interface-ingroup + uid: group +name: rtems_semaphore_flush +notes: null +params: +- description: '%' + dir: null + name: id +return: + return: null + return-values: [] +type: interface diff --git a/spec/rtems/sem/if/group.yml b/spec/rtems/sem/if/group.yml new file mode 100644 index 00000000..19e1e0f4 --- /dev/null +++ b/spec/rtems/sem/if/group.yml @@ -0,0 +1,19 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +brief: | + The Semaphore Manager utilizes standard Dijkstra counting semaphores to + provide synchronization and mutual exclusion capabilities. +copyrights: +- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +description: null +enabled-by: true +identifier: RTEMSAPIClassicSem +interface-type: group +links: +- role: interface-placement + uid: header +- role: interface-ingroup + uid: ../../if/group +name: Semaphore Manager +text: | + The Classic API shall provide an interface to the Semaphore Manager. +type: interface diff --git a/spec/rtems/sem/if/header.yml b/spec/rtems/sem/if/header.yml new file mode 100644 index 00000000..9c269fee --- /dev/null +++ b/spec/rtems/sem/if/header.yml @@ -0,0 +1,12 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +brief: This header file defines the Semaphore Manager API. +copyrights: +- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +interface-type: header-file +links: +- role: interface-placement + uid: /if/domain +path: rtems/rtems/sem.h +prefix: cpukit/include +type: interface diff --git a/spec/rtems/sem/if/ident.yml b/spec/rtems/sem/if/ident.yml new file mode 100644 index 00000000..e549d403 --- /dev/null +++ b/spec/rtems/sem/if/ident.yml @@ -0,0 +1,86 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +brief: | + Identifies a semaphore object by the specified object name. +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 + params: + - ${../../type/if/name:/name} ${.:/params[0]/name} + - ${/c/if/uint32_t:/name} ${.:/params[1]/name} + - ${../../type/if/id:/name} *${.:/params[2]/name} + return: ${../../status/if/code:/name} + variants: [] +description: | + This directive obtains the semaphore identifier associated with the semaphore + name specified in ``${.:/params[0]/name}``. + + The node to search is specified in ``${.:/params[1]/name}``. It shall be + + * a valid node number, + + * the constant ${../../object/if/search-all-nodes:/name} to search in all nodes, + + * the constant ${../../object/if/search-local-node:/name} to search in the local + node only, or + + * the constant ${../../object/if/search-other-nodes:/name} to search in all nodes + except the local node. +enabled-by: true +interface-type: function +links: +- role: interface-placement + uid: header +- role: interface-ingroup + uid: group +name: rtems_semaphore_ident +notes: | + If the semaphore name is not unique, then the semaphore identifier will match + the first semaphore with that name in the search order. However, this + semaphore identifier is not guaranteed to correspond to the desired + semaphore. The semaphore identifier is used with other semaphore related + directives to access the semaphore. + + If node is ${../../object/if/search-all-nodes:/name}, all nodes are searched with + the local node being searched first. All other nodes are searched with the + lowest numbered node searched first. + + If node is a valid node number which does not represent the local node, then + only the semaphores exported by the designated node are searched. + + This directive does not generate activity on remote nodes. It accesses only + the local copy of the global object table. +params: +- description: is the object name to look up. + dir: null + name: name +- description: is the node or node set to search for a matching object. + dir: null + name: node +- description: | + is the pointer to an object identifier variable. The object identifier of + an object with the specified name will be stored in this variable, in case + of a successful operation. + dir: out + name: id +return: + return: null + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + The ${.:/params[2]/name} parameter was ${/c/if/null:/name}. + value: ${../../status/if/invalid-address:/name} + - description: | + The ${.:/params[0]/name} parameter was 0. + value: ${../../status/if/invalid-name:/name} + - description: | + There was no object with the specified name on the specified nodes. + value: ${../../status/if/invalid-name:/name} + - description: | + In multiprocessing configurations, the specified node was invalid. + value: ${../../status/if/invalid-node:/name} +type: interface diff --git a/spec/rtems/sem/if/obtain.yml b/spec/rtems/sem/if/obtain.yml new file mode 100644 index 00000000..432908ef --- /dev/null +++ b/spec/rtems/sem/if/obtain.yml @@ -0,0 +1,38 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +brief: '%' +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 + params: + - ${../../type/if/id:/name} ${.:/params[0]/name} + - ${../../option/if/option:/name} ${.:/params[1]/name} + - ${../../type/if/interval:/name} ${.:/params[2]/name} + return: ${../../status/if/code:/name} + variants: [] +description: null +enabled-by: true +interface-type: function +links: +- role: interface-placement + uid: header +- role: interface-ingroup + uid: group +name: rtems_semaphore_obtain +notes: null +params: +- description: '%' + dir: null + name: id +- description: '%' + dir: null + name: option_set +- description: '%' + dir: null + name: timeout +return: + return: null + return-values: [] +type: interface diff --git a/spec/rtems/sem/if/release.yml b/spec/rtems/sem/if/release.yml new file mode 100644 index 00000000..9f063909 --- /dev/null +++ b/spec/rtems/sem/if/release.yml @@ -0,0 +1,30 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +brief: '%' +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 + params: + - ${../../type/if/id:/name} ${.:/params[0]/name} + return: ${../../status/if/code:/name} + variants: [] +description: null +enabled-by: true +interface-type: function +links: +- role: interface-placement + uid: header +- role: interface-ingroup + uid: group +name: rtems_semaphore_release +notes: null +params: +- description: '%' + dir: null + name: id +return: + return: null + return-values: [] +type: interface diff --git a/spec/rtems/sem/if/set-priority.yml b/spec/rtems/sem/if/set-priority.yml new file mode 100644 index 00000000..9e5b5916 --- /dev/null +++ b/spec/rtems/sem/if/set-priority.yml @@ -0,0 +1,42 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +brief: '%' +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 + params: + - ${../../type/if/id:/name} ${.:/params[0]/name} + - ${../../type/if/id:/name} ${.:/params[1]/name} + - ${../../task/if/priority:/name} ${.:/params[2]/name} + - ${../../task/if/priority:/name} *${.:/params[3]/name} + return: ${../../status/if/code:/name} + variants: [] +description: null +enabled-by: true +interface-type: function +links: +- role: interface-placement + uid: header +- role: interface-ingroup + uid: group +name: rtems_semaphore_set_priority +notes: null +params: +- description: '%' + dir: null + name: semaphore_id +- description: '%' + dir: null + name: scheduler_id +- description: '%' + dir: null + name: new_priority +- description: '%' + dir: null + name: old_priority +return: + return: null + return-values: [] +type: interface diff --git a/spec/rtems/sem/req/ident.yml b/spec/rtems/sem/req/ident.yml new file mode 100644 index 00000000..dde8d114 --- /dev/null +++ b/spec/rtems/sem/req/ident.yml @@ -0,0 +1,15 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 +copyrights: +- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +functional-type: function +links: +- role: interface-function + uid: ../if/ident +rationale: null +references: [] +requirement-type: functional +text: | + The ${../if/ident:/name} directive shall identify an Classic API + semaphore class object by its name as specified by ${../req/ident}. +type: requirement diff --git a/spec/rtems/sem/val/ident.yml b/spec/rtems/sem/val/ident.yml new file mode 100644 index 00000000..70068b7f --- /dev/null +++ b/spec/rtems/sem/val/ident.yml @@ -0,0 +1,49 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +links: +- role: validation + uid: ../req/ident +test-actions: +- action: | + ${../../req/ident:/test-run}( + id_local_object, + ClassicSemIdentAction + ); + checks: [] + description: | + Run the generic object identification tests for Classic API semaphore class + objects defined by ${../../req/ident}. + links: [] +test-brief: Test the ${../if/ident:/name} directive. +test-description: null +test-epilogue: null +test-fixture: null +test-header: null +test-includes: [] +test-local-includes: +- tr-object-ident.h +test-prologue: | + rtems_status_code sc; + rtems_id id_local_object; + + sc = rtems_semaphore_create( + ClassicObjectIdentName, + 0, + RTEMS_DEFAULT_ATTRIBUTES, + 0, + &id_local_object + ); + T_assert_rsc_success( sc ); +test-support: | + static rtems_status_code ClassicSemIdentAction( + rtems_name name, + uint32_t node, + rtems_id *id + ) + { + return rtems_semaphore_ident( name, node, id ); + } +test-target: testsuites/validation/tc-sem-ident.c +type: test-case |