diff options
Diffstat (limited to 'spec/if/rtems/sem/create.yml')
| -rw-r--r-- | spec/if/rtems/sem/create.yml | 182 |
1 files changed, 0 insertions, 182 deletions
diff --git a/spec/if/rtems/sem/create.yml b/spec/if/rtems/sem/create.yml deleted file mode 100644 index 98aace39..00000000 --- a/spec/if/rtems/sem/create.yml +++ /dev/null @@ -1,182 +0,0 @@ -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: - - ${../types/name:/name} ${.:/params[0]/name} - - ${/if/c/uint32_t:/name} ${.:/params[1]/name} - - ${../attr/attribute:/name} ${.:/params[2]/name} - - ${../tasks/priority:/name} ${.:/params[3]/name} - - ${../types/id:/name} *${.:/params[4]/name} - return: ${../status/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/local:/name} and ${../attr/global:/name} - attributes. - - * The local scope is the default and can be emphasized through use - of the ${../attr/local:/name} attribute. - - * The global scope is selected by the ${../attr/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/fifo:/name} and ${../attr/priority:/name} attributes. - - * The ${/glossary/fifo:/term} discipline is the default and can be emphasized - through use of the ${../attr/fifo:/name} attribute. - - * The priority discipline is selected by the ${../attr/priority:/name} - attribute. Some locking protocols require the priority discipline. - - The *semaphore class* is selected by the mutually exclusive - ${../attr/counting-semaphore:/name}, ${../attr/binary-semaphore:/name}, and - ${../attr/simple-binary-semaphore:/name} attributes. - - * Counting semaphores are the default and can be emphasized through use of - the ${../attr/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/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/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/inherit-priority:/name}, - ${../attr/priority-ceiling:/name}, and - ${../attr/multiprocessor-resource-sharing:/name} attributes. - - * The default is to use no locking protocol. - - * The ${../attr/inherit-priority:/name} attribute selects the priority - inheritance locking protocol. - - * The ${../attr/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/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 - ${/if/acfg/mp-max-global-objects:/name} application configuration option. - - It is not allowed to create an initially locked MrsP semaphore and the - ${../status/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/successful:/name} - - description: | - The ${.:/params[3]/name} parameter was ${/if/c/null:/name}. - value: ${../status/invalid-address:/name} - - description: | - The semaphore name was invalid. - value: ${../status/invalid-name:/name} - - description: | - The priority ceiling was invalid. - value: ${../status/invalid-priority:/name} - - description: | - The attribute set was invalid. - value: ${../status/not-defined:/name} - - description: | - There was no inactive semaphore object available to create a new - semaphore. The semaphore object maximum is defined by the - ${/if/acfg/max-semaphores:/name} application configuration option. - value: ${../status/too-many:/name} - - description: | - In multiprocessing configurations, there was no inactive global object - available to create a new global semaphore. - value: ${../status/too-many:/name} -type: interface |