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

Last change on this file since d3edaca was d3edaca, checked in by Sebastian Huber <sebastian.huber@…>, on Oct 12, 2020 at 1:07:38 PM

spec: Add function attributes

  • Property mode set to 100644
File size: 7.9 KB
Line 
1SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
2brief: |
3  Creates a semaphore with the specified properties and returns its identifier.
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 new
21  semaphore has the user-defined name specified in ``name`` and the initial
22  count specified in ``count``.  For control and maintenance of the semaphore,
23  RTEMS allocates and initializes a ${/glossary/smcb:/term}.  The
24  RTEMS-assigned semaphore identifier is returned in ``id``.  This semaphore
25  identifier is used with other semaphore related directives to access the
26  semaphore.
27
28  The attribute set specified in ``attribute_set`` defines
29
30  * the scope of the semaphore (local or global),
31
32  * the discipline of the task wait queue used by the semaphore (FIFO or
33    priority),
34
35  * the class of the semaphore (counting, binary, or simple binary), and
36
37  * the locking protocol of a binary semaphore (priority inheritance, priority
38    ceiling or MrsP).
39
40  The attribute set is built through a *bitwise or* of the attribute constants
41  described below.  Not all combinations of attributes are allowed.  Some
42  attributes are mutually exclusive.  If mutually exclusive attributes are
43  combined, the behaviour is undefined.
44
45  The *scope of a semaphore* is either the local node only (local scope) or all
46  nodes in a multiprocessing network (global scope).  The scope is selected by
47  the mutually exclusive ${../../attr/if/local:/name} and
48  ${../../attr/if/global:/name} attributes.
49
50  * The local scope is the default and can be emphasized through use
51    of the ${../../attr/if/local:/name} attribute.
52
53  * The global scope is selected by the ${../../attr/if/global:/name} attribute.  In
54    a single node system and the local and global scope are identical.
55
56  The *task wait queue discipline* is selected by the mutually exclusive
57  ${../../attr/if/fifo:/name} and ${../../attr/if/priority:/name} attributes.
58
59  * The ${/glossary/fifo:/term} discipline is the default and can be emphasized
60    through use of the ${../../attr/if/fifo:/name} attribute.
61
62  * The priority discipline is selected by the ${../../attr/if/priority:/name}
63    attribute.  Some locking protocols require the priority discipline.
64
65  The *semaphore class* is selected by the mutually exclusive
66  ${../../attr/if/counting-semaphore:/name},
67  ${../../attr/if/binary-semaphore:/name}, and
68  ${../../attr/if/simple-binary-semaphore:/name} attributes.
69
70  * Counting semaphores are the default and can be emphasized through use of
71    the ${../../attr/if/counting-semaphore:/name} attribute.
72
73  * Binary semaphores are mutual exclusion (mutex) synchronization primitives
74    which may have an owner.  The count of a binary semaphore is restricted to
75    0 and 1.  The binary semaphore class is selected by the
76    ${../../attr/if/binary-semaphore:/name} attribute.
77
78  * Simple binary semaphores have no owner.  The count of a simple binary
79    semaphore is restricted to 0 and 1.  They may be used for task and
80    interrupt synchronization.  The simple binary semaphore class is selected
81    by the ${../../attr/if/simple-binary-semaphore:/name} attribute.
82
83  Binary semaphores may use a *locking protocol*.  If a locking protocol is
84  selected, then the scope shall be local and the priority task wait queue
85  discipline shall be selected.  The locking protocol is selected by the
86  mutually exclusive ${../../attr/if/inherit-priority:/name},
87  ${../../attr/if/priority-ceiling:/name}, and
88  ${../../attr/if/multiprocessor-resource-sharing:/name} attributes.
89
90  * The default is to use no locking protocol.
91
92  * The ${../../attr/if/inherit-priority:/name} attribute selects the priority
93    inheritance locking protocol.
94
95  * The ${../../attr/if/priority-ceiling:/name} attribute selects the priority
96    ceiling locking protocol.  For this locking protocol a priority ceiling
97    shall be specified in ``priority_ceiling``.
98
99  * The ${../../attr/if/multiprocessor-resource-sharing:/name} attribute selects the
100    MrsP locking protocol in SMP configurations, otherwise it selects the
101    priority ceiling protocol.  For this locking protocol a priority ceiling
102    shall be specified in ``priority_ceiling``.  This priority is used to set
103    the priority ceiling in all scheduler instances.  This can be changed later
104    with the ${set-priority:/name} directive using the returned semaphore
105    identifier.
106enabled-by: true
107index-entries: []
108interface-type: function
109links:
110- role: interface-placement
111  uid: header
112- role: interface-ingroup
113  uid: group
114name: rtems_semaphore_create
115notes: |
116  This directive may cause the calling task to be preempted due to an obtain
117  and release of the object allocator mutex.
118
119  Semaphores should not be made global unless remote tasks must interact with
120  the new semaphore.  This is to avoid the system overhead incurred by the
121  creation of a global semaphore.  When a global semaphore is created, the
122  semaphore's name and identifier must be transmitted to every node in the
123  system for insertion in the local copy of the global object table.
124
125  The total number of global objects, including semaphores, is limited by the
126  ${/acfg/if/mp-max-global-objects:/name} application configuration option.
127
128  It is not allowed to create an initially locked MrsP semaphore and the
129  ${../../status/if/invalid-number:/name} status code will be returned in SMP
130  configurations in this case.  This prevents lock order reversal problems
131  with the allocator mutex.
132params:
133- description: is the object name of the new semaphore.
134  dir: null
135  name: name
136- description: |
137    is the initial count of the new semaphore.  If the semaphore is a mutex,
138    then a count of 0 will make the calling task the owner of the new mutex and
139    a count of 1 will create a mutex without an owner.
140  dir: null
141  name: count
142- description: |
143    is the attribute set which defines the properties of the new semaphore.
144  dir: null
145  name: attribute_set
146- description: |
147    is the priority ceiling if the new semaphore is a binary semaphore with the
148    priority ceiling or MrsP semaphore locking protocol as defined by the
149    attribute set.
150  dir: null
151  name: priority_ceiling
152- description: |
153    is the pointer to an object identifier variable.  The object identifier of
154    the new semaphore will be stored in this variable, in case of a successful
155    operation.
156  dir: out
157  name: id
158return:
159  return: null
160  return-values:
161  - description: |
162      The requested operation was successful.
163    value: ${../../status/if/successful:/name}
164  - description: |
165      The ${.:/params[3]/name} parameter was ${/c/if/null:/name}.
166    value: ${../../status/if/invalid-address:/name}
167  - description: |
168      The semaphore name was invalid.
169    value: ${../../status/if/invalid-name:/name}
170  - description: |
171      The priority ceiling was invalid.
172    value: ${../../status/if/invalid-priority:/name}
173  - description: |
174      The attribute set was invalid.
175    value: ${../../status/if/not-defined:/name}
176  - description: |
177      There was no inactive semaphore object available to create a new
178      semaphore.  The semaphore object maximum is defined by the
179      ${/acfg/if/max-semaphores:/name} application configuration option.
180    value: ${../../status/if/too-many:/name}
181  - description: |
182      In multiprocessing configurations, there was no inactive global object
183      available to create a new global semaphore.
184    value: ${../../status/if/too-many:/name}
185type: interface
Note: See TracBrowser for help on using the repository browser.