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