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
|
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
|
