source: rtems-central/spec/rtems/sem/if/create.yml @ 45b6997

Last change on this file since 45b6997 was 45b6997, checked in by Sebastian Huber <sebastian.huber@…>, on Jan 13, 2021 at 1:05:42 PM

spec: Document all create directives

  • Property mode set to 100644
File size: 9.0 KB
Line 
1SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
2brief: |
3  Creates a semaphore.
4copyrights:
5- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
6- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
7definition:
8  default:
9    attributes: null
10    body: null
11    params:
12    - ${../../type/if/name:/name} ${.:/params[0]/name}
13    - ${/c/if/uint32_t:/name} ${.:/params[1]/name}
14    - ${../../attr/if/attribute:/name} ${.:/params[2]/name}
15    - ${../../task/if/priority:/name} ${.:/params[3]/name}
16    - ${../../type/if/id:/name} *${.:/params[4]/name}
17    return: ${../../status/if/code:/name}
18  variants: []
19description: |
20  This directive creates a semaphore which resides on the local node.  The
21  semaphore has the user-defined object name specified in ${.:/params[0]/name}
22  and the initial count specified in ${.:/params[1]/name}.  The assigned object
23  identifier is returned in ${.:/params[4]/name}.  This identifier is used to
24  access the semaphore with other semaphore related directives.
25
26  The **attribute set** specified in ${.:/params[2]/name} is built through a
27  *bitwise or* of the attribute constants described below.  Not all
28  combinations of attributes are allowed.  Some attributes are mutually
29  exclusive.  If mutually exclusive attributes are combined, the behaviour is
30  undefined.  Attributes not mentioned below are not evaluated by this
31  directive and have no effect.  Default attributes can be selected by using
32  the ${../../attr/if/default:/name} constant.  The attribute set defines
33
34  * the scope of the semaphore: ${../../attr/if/local:/name} (default) or
35    ${../../attr/if/global:/name},
36
37  * the task wait queue discipline used by the semaphore:
38    ${../../attr/if/fifo:/name} (default) or ${../../attr/if/priority:/name},
39
40  * the class of the semaphore: ${../../attr/if/counting-semaphore:/name}
41    (default), ${../../attr/if/binary-semaphore:/name}, or
42    ${../../attr/if/simple-binary-semaphore:/name}, and
43
44  * the locking protocol of a binary semaphore: no locking protocol (default),
45    ${../../attr/if/inherit-priority:/name},
46    ${../../attr/if/priority-ceiling:/name}, or
47    ${../../attr/if/multiprocessor-resource-sharing:/name}.
48
49  The semaphore has a local or global **scope** in a multiprocessing network
50  (this attribute does not refer to SMP systems).  The scope is selected by the
51  mutually exclusive ${../../attr/if/local:/name} and
52  ${../../attr/if/global:/name} attributes.
53
54  * A **local scope** is the default and can be emphasized through the use of
55    the ${../../attr/if/local:/name} attribute.  A local semaphore can be only
56    used by the node which created it.
57
58  * A **global scope** is established if the ${../../attr/if/global:/name}
59    attribute is set.  Setting the global attribute in a single node system has
60    no effect.
61
62  The **task wait queue discipline** is selected by the mutually exclusive
63  ${../../attr/if/fifo:/name} and ${../../attr/if/priority:/name} attributes.
64
65  * The **FIFO discipline** is the default and can be emphasized
66    through use of the ${../../attr/if/fifo:/name} attribute.
67
68  * The **priority discipline** is selected by the
69    ${../../attr/if/priority:/name} attribute.  The locking protocols require
70    the priority discipline.
71
72  The **semaphore class** is selected by the mutually exclusive
73  ${../../attr/if/counting-semaphore:/name},
74  ${../../attr/if/binary-semaphore:/name}, and
75  ${../../attr/if/simple-binary-semaphore:/name} attributes.
76
77  * The **counting semaphore class** is the default and can be emphasized
78    through use of the ${../../attr/if/counting-semaphore:/name} attribute.
79
80  * The **binary semaphore class** is selected by the
81    ${../../attr/if/binary-semaphore:/name} attribute.  Binary semaphores are
82    mutual exclusion (mutex) synchronization primitives which may have an
83    owner.  The count of a binary semaphore is restricted to 0 and 1 values.
84
85  * The **simple binary semaphore class** is selected by the
86    ${../../attr/if/simple-binary-semaphore:/name} attribute.  Simple binary
87    semaphores have no owner.  They may be used for task and interrupt
88    synchronization.  The count of a simple binary semaphore is restricted to 0
89    and 1 values.
90
91  Binary semaphores may use a **locking protocol**.  If a locking protocol is
92  selected, then the scope shall be local and the priority task wait queue
93  discipline shall be selected.  The locking protocol is selected by the
94  mutually exclusive ${../../attr/if/inherit-priority:/name},
95  ${../../attr/if/priority-ceiling:/name}, and
96  ${../../attr/if/multiprocessor-resource-sharing:/name} attributes.
97
98  * The default is **no locking protocol**.  This can be emphasized
99    through use of the ${../../attr/if/no-inherit-priority:/name},
100    ${../../attr/if/no-multiprocessor-resource-sharing:/name}, and
101    ${../../attr/if/no-priority-ceiling:/name} attributes.
102
103  * The **priority inheritance locking protocol** is selected by the
104    ${../../attr/if/inherit-priority:/name} attribute.
105
106  * The **priority ceiling locking protocol** is selected by the
107    ${../../attr/if/priority-ceiling:/name} attribute.  For this locking protocol
108    a priority ceiling shall be specified in ${.:/params[3]/name}.
109
110  * The **MrsP locking protocol** is selected by the
111    ${../../attr/if/multiprocessor-resource-sharing:/name} attribute in SMP
112    configurations, otherwise this attribute selects the **priority ceiling
113    locking protocol**.  For these locking protocols a priority ceiling shall be
114    specified in ${.:/params[3]/name}.  This priority is used to set the
115    priority ceiling for all schedulers.  This can be changed later with the
116    ${set-priority:/name} directive using the returned object identifier.
117enabled-by: true
118index-entries:
119- create a semaphore
120interface-type: function
121links:
122- role: interface-placement
123  uid: header
124- role: interface-ingroup
125  uid: group
126- role: constraint
127  uid: /constraint/directive-ctx-devinit
128- role: constraint
129  uid: /constraint/directive-ctx-task
130- role: constraint
131  uid: /constraint/object-allocator
132- role: constraint
133  uid: ../constraint/max
134- role: constraint
135  uid: /constraint/obj-unlimited-alloc
136- role: constraint
137  uid: ../../constraint/mp-max-global-objects
138name: rtems_semaphore_create
139notes: |
140  For control and maintenance of the semaphore, RTEMS allocates a
141  ${/glossary/smcb:/term} from the local SMCB free pool and initializes it.
142
143  The SMCB for a global semaphore is allocated on the local node.  Semaphores
144  should not be made global unless remote tasks must interact with the
145  semaphore.  This is to avoid the system overhead incurred by the creation of
146  a global semaphore.  When a global semaphore is created, the semaphore's name
147  and identifier must be transmitted to every node in the system for insertion
148  in the local copy of the global object table.
149params:
150- description: |
151    is the object name of the semaphore.
152  dir: null
153  name: name
154- description: |
155    is the initial count of the semaphore.  If the semaphore is a binary semaphore,
156    then a count of 0 will make the calling task the owner of the binary semaphore and
157    a count of 1 will create a binary semaphore without an owner.
158  dir: null
159  name: count
160- description: |
161    is the attribute set of the semaphore.
162  dir: null
163  name: attribute_set
164- description: |
165    is the priority ceiling if the semaphore is a binary semaphore with the
166    priority ceiling or MrsP locking protocol as defined by the attribute set.
167  dir: null
168  name: priority_ceiling
169- description: |
170    is the pointer to an object identifier variable.  The identifier of the
171    created semaphore will be stored in this variable, in case of a successful
172    operation.
173  dir: out
174  name: id
175return:
176  return: null
177  return-values:
178  - description: |
179      The requested operation was successful.
180    value: ${../../status/if/successful:/name}
181  - description: |
182      The ${.:/params[0]/name} parameter was invalid.
183    value: ${../../status/if/invalid-name:/name}
184  - description: |
185      The ${.:/params[4]/name} parameter was ${/c/if/null:/name}.
186    value: ${../../status/if/invalid-address:/name}
187  - description: |
188      The ${.:/params[1]/name} parameter was invalid.
189    value: ${../../status/if/invalid-number:/name}
190  - description: |
191      The ${.:/params[2]/name} parameter was invalid.
192    value: ${../../status/if/not-defined:/name}
193  - description: |
194      There was no inactive object available to create a semaphore.  The number
195      of semaphores available to the application is configured through the
196      ${/acfg/if/max-semaphores:/name} application configuration option.
197    value: ${../../status/if/too-many:/name}
198  - description: |
199      In multiprocessing configurations, there was no inactive global object
200      available to create a global semaphore.  The number of global objects
201      available to the application is configured through the
202      ${/acfg/if/mp-max-global-objects:/name} application configuration option.
203    value: ${../../status/if/too-many:/name}
204  - description: |
205      The ${.:/params[3]/name} parameter was invalid.
206    value: ${../../status/if/invalid-priority:/name}
207type: interface
Note: See TracBrowser for help on using the repository browser.