source: rtems/cpukit/include/rtems/rtems/sem.h @ 55c6cb1d

Last change on this file since 55c6cb1d was 55c6cb1d, checked in by Sebastian Huber <sebastian.huber@…>, on Apr 22, 2021 at 1:57:19 PM

rtems: Clarify constraints in documentation

  • Property mode set to 100644
File size: 34.0 KB
Line 
1/* SPDX-License-Identifier: BSD-2-Clause */
2
3/**
4 * @file
5 *
6 * @brief This header file defines the Semaphore Manager API.
7 */
8
9/*
10 * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
11 * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
12 *
13 * Redistribution and use in source and binary forms, with or without
14 * modification, are permitted provided that the following conditions
15 * are met:
16 * 1. Redistributions of source code must retain the above copyright
17 *    notice, this list of conditions and the following disclaimer.
18 * 2. Redistributions in binary form must reproduce the above copyright
19 *    notice, this list of conditions and the following disclaimer in the
20 *    documentation and/or other materials provided with the distribution.
21 *
22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
26 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
27 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
28 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
29 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
30 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
31 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32 * POSSIBILITY OF SUCH DAMAGE.
33 */
34
35/*
36 * This file is part of the RTEMS quality process and was automatically
37 * generated.  If you find something that needs to be fixed or
38 * worded better please post a report or patch to an RTEMS mailing list
39 * or raise a bug report:
40 *
41 * https://www.rtems.org/bugs.html
42 *
43 * For information on updating and regenerating please refer to the How-To
44 * section in the Software Requirements Engineering chapter of the
45 * RTEMS Software Engineering manual.  The manual is provided as a part of
46 * a release.  For development sources please refer to the online
47 * documentation at:
48 *
49 * https://docs.rtems.org
50 */
51
52/* Generated from spec:/rtems/sem/if/header */
53
54#ifndef _RTEMS_RTEMS_SEM_H
55#define _RTEMS_RTEMS_SEM_H
56
57#include <stdint.h>
58#include <rtems/rtems/attr.h>
59#include <rtems/rtems/options.h>
60#include <rtems/rtems/status.h>
61#include <rtems/rtems/types.h>
62
63#ifdef __cplusplus
64extern "C" {
65#endif
66
67/* Generated from spec:/rtems/sem/if/group */
68
69/**
70 * @defgroup RTEMSAPIClassicSem Semaphore Manager
71 *
72 * @ingroup RTEMSAPIClassic
73 *
74 * @brief The Semaphore Manager utilizes standard Dijkstra counting semaphores
75 *   to provide synchronization and mutual exclusion capabilities.
76 */
77
78/* Generated from spec:/rtems/sem/if/create */
79
80/**
81 * @ingroup RTEMSAPIClassicSem
82 *
83 * @brief Creates a semaphore.
84 *
85 * @param name is the object name of the semaphore.
86 *
87 * @param count is the initial count of the semaphore.  If the semaphore is a
88 *   binary semaphore, then a count of 0 will make the calling task the owner
89 *   of the binary semaphore and a count of 1 will create a binary semaphore
90 *   without an owner.
91 *
92 * @param attribute_set is the attribute set of the semaphore.
93 *
94 * @param priority_ceiling is the priority ceiling if the semaphore is a binary
95 *   semaphore with the priority ceiling or MrsP locking protocol as defined by
96 *   the attribute set.
97 *
98 * @param[out] id is the pointer to an object identifier variable.  When the
99 *   directive call is successful, the identifier of the created semaphore will
100 *   be stored in this variable.
101 *
102 * This directive creates a semaphore which resides on the local node.  The
103 * semaphore has the user-defined object name specified in ``name`` and the
104 * initial count specified in ``count``.  The assigned object identifier is
105 * returned in ``id``.  This identifier is used to access the semaphore with
106 * other semaphore related directives.
107 *
108 * The **attribute set** specified in ``attribute_set`` is built through a
109 * *bitwise or* of the attribute constants described below.  Not all
110 * combinations of attributes are allowed.  Some attributes are mutually
111 * exclusive.  If mutually exclusive attributes are combined, the behaviour is
112 * undefined.  Attributes not mentioned below are not evaluated by this
113 * directive and have no effect.  Default attributes can be selected by using
114 * the #RTEMS_DEFAULT_ATTRIBUTES constant.  The attribute set defines
115 *
116 * * the scope of the semaphore: #RTEMS_LOCAL (default) or #RTEMS_GLOBAL,
117 *
118 * * the task wait queue discipline used by the semaphore: #RTEMS_FIFO
119 *   (default) or #RTEMS_PRIORITY,
120 *
121 * * the class of the semaphore: #RTEMS_COUNTING_SEMAPHORE (default),
122 *   #RTEMS_BINARY_SEMAPHORE, or #RTEMS_SIMPLE_BINARY_SEMAPHORE, and
123 *
124 * * the locking protocol of a binary semaphore: no locking protocol (default),
125 *   #RTEMS_INHERIT_PRIORITY, #RTEMS_PRIORITY_CEILING, or
126 *   #RTEMS_MULTIPROCESSOR_RESOURCE_SHARING.
127 *
128 * The semaphore has a local or global **scope** in a multiprocessing network
129 * (this attribute does not refer to SMP systems).  The scope is selected by
130 * the mutually exclusive #RTEMS_LOCAL and #RTEMS_GLOBAL attributes.
131 *
132 * * A **local scope** is the default and can be emphasized through the use of
133 *   the #RTEMS_LOCAL attribute.  A local semaphore can be only used by the
134 *   node which created it.
135 *
136 * * A **global scope** is established if the #RTEMS_GLOBAL attribute is set.
137 *   Setting the global attribute in a single node system has no effect.
138 *
139 * The **task wait queue discipline** is selected by the mutually exclusive
140 * #RTEMS_FIFO and #RTEMS_PRIORITY attributes.
141 *
142 * * The **FIFO discipline** is the default and can be emphasized through use
143 *   of the #RTEMS_FIFO attribute.
144 *
145 * * The **priority discipline** is selected by the #RTEMS_PRIORITY attribute.
146 *   The locking protocols require the priority discipline.
147 *
148 * The **semaphore class** is selected by the mutually exclusive
149 * #RTEMS_COUNTING_SEMAPHORE, #RTEMS_BINARY_SEMAPHORE, and
150 * #RTEMS_SIMPLE_BINARY_SEMAPHORE attributes.
151 *
152 * * The **counting semaphore class** is the default and can be emphasized
153 *   through use of the #RTEMS_COUNTING_SEMAPHORE attribute.
154 *
155 * * The **binary semaphore class** is selected by the #RTEMS_BINARY_SEMAPHORE
156 *   attribute.  Binary semaphores are mutual exclusion (mutex) synchronization
157 *   primitives which may have an owner.  The count of a binary semaphore is
158 *   restricted to 0 and 1 values.
159 *
160 * * The **simple binary semaphore class** is selected by the
161 *   #RTEMS_SIMPLE_BINARY_SEMAPHORE attribute.  Simple binary semaphores have
162 *   no owner.  They may be used for task and interrupt synchronization.  The
163 *   count of a simple binary semaphore is restricted to 0 and 1 values.
164 *
165 * Binary semaphores may use a **locking protocol**.  If a locking protocol is
166 * selected, then the scope shall be local and the priority task wait queue
167 * discipline shall be selected.  The locking protocol is selected by the
168 * mutually exclusive #RTEMS_INHERIT_PRIORITY, #RTEMS_PRIORITY_CEILING, and
169 * #RTEMS_MULTIPROCESSOR_RESOURCE_SHARING attributes.
170 *
171 * * The default is **no locking protocol**.  This can be emphasized through
172 *   use of the #RTEMS_NO_INHERIT_PRIORITY,
173 *   #RTEMS_NO_MULTIPROCESSOR_RESOURCE_SHARING, and #RTEMS_NO_PRIORITY_CEILING
174 *   attributes.
175 *
176 * * The **priority inheritance locking protocol** is selected by the
177 *   #RTEMS_INHERIT_PRIORITY attribute.
178 *
179 * * The **priority ceiling locking protocol** is selected by the
180 *   #RTEMS_PRIORITY_CEILING attribute.  For this locking protocol a priority
181 *   ceiling shall be specified in ``priority_ceiling``.
182 *
183 * * The **MrsP locking protocol** is selected by the
184 *   #RTEMS_MULTIPROCESSOR_RESOURCE_SHARING attribute in SMP configurations,
185 *   otherwise this attribute selects the **priority ceiling locking
186 *   protocol**.  For these locking protocols a priority ceiling shall be
187 *   specified in ``priority_ceiling``.  This priority is used to set the
188 *   priority ceiling for all schedulers.  This can be changed later with the
189 *   rtems_semaphore_set_priority() directive using the returned object
190 *   identifier.
191 *
192 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
193 *
194 * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid.
195 *
196 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
197 *
198 * @retval ::RTEMS_INVALID_NUMBER The ``count`` parameter was invalid.
199 *
200 * @retval ::RTEMS_NOT_DEFINED The ``attribute_set`` parameter was invalid.
201 *
202 * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a
203 *   semaphore.  The number of semaphores available to the application is
204 *   configured through the #CONFIGURE_MAXIMUM_SEMAPHORES application
205 *   configuration option.
206 *
207 * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no
208 *   inactive global object available to create a global semaphore.  The number
209 *   of global objects available to the application is configured through the
210 *   #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option.
211 *
212 * @retval ::RTEMS_INVALID_PRIORITY The ``priority_ceiling`` parameter was
213 *   invalid.
214 *
215 * @par Notes
216 * @parblock
217 * For control and maintenance of the semaphore, RTEMS allocates a SMCB from
218 * the local SMCB free pool and initializes it.
219 *
220 * The SMCB for a global semaphore is allocated on the local node.  Semaphores
221 * should not be made global unless remote tasks must interact with the
222 * semaphore.  This is to avoid the system overhead incurred by the creation of
223 * a global semaphore.  When a global semaphore is created, the semaphore's
224 * name and identifier must be transmitted to every node in the system for
225 * insertion in the local copy of the global object table.
226 * @endparblock
227 *
228 * @par Constraints
229 * @parblock
230 * The following constraints apply to this directive:
231 *
232 * * The directive may be called from within device driver initialization
233 *   context.
234 *
235 * * The directive may be called from within task context.
236 *
237 * * The directive may obtain and release the object allocator mutex.  This may
238 *   cause the calling task to be preempted.
239 *
240 * * When the directive operates on a global object, the directive sends a
241 *   message to remote nodes.  This may preempt the calling task.
242 *
243 * * The number of semaphores available to the application is configured
244 *   through the #CONFIGURE_MAXIMUM_SEMAPHORES application configuration
245 *   option.
246 *
247 * * Where the object class corresponding to the directive is configured to use
248 *   unlimited objects, the directive may allocate memory from the RTEMS
249 *   Workspace.
250 *
251 * * The number of global objects available to the application is configured
252 *   through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration
253 *   option.
254 * @endparblock
255 */
256rtems_status_code rtems_semaphore_create(
257  rtems_name          name,
258  uint32_t            count,
259  rtems_attribute     attribute_set,
260  rtems_task_priority priority_ceiling,
261  rtems_id           *id
262);
263
264/* Generated from spec:/rtems/sem/if/ident */
265
266/**
267 * @ingroup RTEMSAPIClassicSem
268 *
269 * @brief Identifies a semaphore by the object name.
270 *
271 * @param name is the object name to look up.
272 *
273 * @param node is the node or node set to search for a matching object.
274 *
275 * @param[out] id is the pointer to an object identifier variable.  When the
276 *   directive call is successful, the object identifier of an object with the
277 *   specified name will be stored in this variable.
278 *
279 * This directive obtains a semaphore identifier associated with the semaphore
280 * name specified in ``name``.
281 *
282 * The node to search is specified in ``node``.  It shall be
283 *
284 * * a valid node number,
285 *
286 * * the constant #RTEMS_SEARCH_ALL_NODES to search in all nodes,
287 *
288 * * the constant #RTEMS_SEARCH_LOCAL_NODE to search in the local node only, or
289 *
290 * * the constant #RTEMS_SEARCH_OTHER_NODES to search in all nodes except the
291 *   local node.
292 *
293 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
294 *
295 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
296 *
297 * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was 0.
298 *
299 * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
300 *   the specified nodes.
301 *
302 * @retval ::RTEMS_INVALID_NODE In multiprocessing configurations, the
303 *   specified node was invalid.
304 *
305 * @par Notes
306 * @parblock
307 * If the semaphore name is not unique, then the semaphore identifier will
308 * match the first semaphore with that name in the search order.  However, this
309 * semaphore identifier is not guaranteed to correspond to the desired
310 * semaphore.
311 *
312 * The objects are searched from lowest to the highest index.  If ``node`` is
313 * #RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local node being
314 * searched first.  All other nodes are searched from lowest to the highest
315 * node number.
316 *
317 * If node is a valid node number which does not represent the local node, then
318 * only the semaphores exported by the designated node are searched.
319 *
320 * This directive does not generate activity on remote nodes.  It accesses only
321 * the local copy of the global object table.
322 *
323 * The semaphore identifier is used with other semaphore related directives to
324 * access the semaphore.
325 * @endparblock
326 *
327 * @par Constraints
328 * @parblock
329 * The following constraints apply to this directive:
330 *
331 * * The directive may be called from within any runtime context.
332 *
333 * * The directive will not cause the calling task to be preempted.
334 * @endparblock
335 */
336rtems_status_code rtems_semaphore_ident(
337  rtems_name name,
338  uint32_t   node,
339  rtems_id  *id
340);
341
342/* Generated from spec:/rtems/sem/if/delete */
343
344/**
345 * @ingroup RTEMSAPIClassicSem
346 *
347 * @brief Deletes the semaphore.
348 *
349 * @param id is the semaphore identifier.
350 *
351 * This directive deletes the semaphore specified by ``id``.
352 *
353 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
354 *
355 * @retval ::RTEMS_INVALID_ID There was no semaphore associated with the
356 *   identifier specified by ``id``.
357 *
358 * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The semaphore resided on a remote
359 *   node.
360 *
361 * @retval ::RTEMS_RESOURCE_IN_USE The binary semaphore had an owner.
362 *
363 * @par Notes
364 * @parblock
365 * Binary semaphores with an owner cannot be deleted.
366 *
367 * When a semaphore is deleted, all tasks blocked waiting to obtain the
368 * semaphore will be readied and returned a status code which indicates that
369 * the semaphore was deleted.
370 *
371 * The SMCB for the deleted semaphore is reclaimed by RTEMS.
372 *
373 * When a global semaphore is deleted, the semaphore identifier must be
374 * transmitted to every node in the system for deletion from the local copy of
375 * the global object table.
376 *
377 * The semaphore must reside on the local node, even if the semaphore was
378 * created with the #RTEMS_GLOBAL attribute.
379 *
380 * Proxies, used to represent remote tasks, are reclaimed when the semaphore is
381 * deleted.
382 * @endparblock
383 *
384 * @par Constraints
385 * @parblock
386 * The following constraints apply to this directive:
387 *
388 * * The directive may be called from within device driver initialization
389 *   context.
390 *
391 * * The directive may be called from within task context.
392 *
393 * * The directive may obtain and release the object allocator mutex.  This may
394 *   cause the calling task to be preempted.
395 *
396 * * When the directive operates on a global object, the directive sends a
397 *   message to remote nodes.  This may preempt the calling task.
398 *
399 * * The calling task does not have to be the task that created the object.
400 *   Any local task that knows the object identifier can delete the object.
401 *
402 * * Where the object class corresponding to the directive is configured to use
403 *   unlimited objects, the directive may free memory to the RTEMS Workspace.
404 * @endparblock
405 */
406rtems_status_code rtems_semaphore_delete( rtems_id id );
407
408/* Generated from spec:/rtems/sem/if/obtain */
409
410/**
411 * @ingroup RTEMSAPIClassicSem
412 *
413 * @brief Obtains the semaphore.
414 *
415 * @param id is the semaphore identifier.
416 *
417 * @param option_set is the option set.
418 *
419 * @param timeout is the timeout in clock ticks if the #RTEMS_WAIT option is
420 *   set.  Use #RTEMS_NO_TIMEOUT to wait potentially forever.
421 *
422 * This directive obtains the semaphore specified by ``id``.
423 *
424 * The **option set** specified in ``option_set`` is built through a *bitwise
425 * or* of the option constants described below.  Not all combinations of
426 * options are allowed.  Some options are mutually exclusive.  If mutually
427 * exclusive options are combined, the behaviour is undefined.  Options not
428 * mentioned below are not evaluated by this directive and have no effect.
429 * Default options can be selected by using the #RTEMS_DEFAULT_OPTIONS
430 * constant.
431 *
432 * The calling task can **wait** or **try to obtain** the semaphore according
433 * to the mutually exclusive #RTEMS_WAIT and #RTEMS_NO_WAIT options.
434 *
435 * * **Waiting to obtain** the semaphore is the default and can be emphasized
436 *   through the use of the #RTEMS_WAIT option.  The ``timeout`` parameter
437 *   defines how long the calling task is willing to wait.  Use
438 *   #RTEMS_NO_TIMEOUT to wait potentially forever, otherwise set a timeout
439 *   interval in clock ticks.
440 *
441 * * **Trying to obtain** the semaphore is selected by the #RTEMS_NO_WAIT
442 *   option.  If this option is defined, then the ``timeout`` parameter is
443 *   ignored.  When the semaphore cannot be immediately obtained, then the
444 *   ::RTEMS_UNSATISFIED status is returned.
445 *
446 * With either #RTEMS_WAIT or #RTEMS_NO_WAIT if the current semaphore count is
447 * positive, then it is decremented by one and the semaphore is successfully
448 * obtained by returning immediately with the ::RTEMS_SUCCESSFUL status code.
449 *
450 * If the calling task chooses to return immediately and the current semaphore
451 * count is zero, then the ::RTEMS_UNSATISFIED status code is returned
452 * indicating that the semaphore is not available.
453 *
454 * If the calling task chooses to wait for a semaphore and the current
455 * semaphore count is zero, then the calling task is placed on the semaphore's
456 * wait queue and blocked.  If a local, binary semaphore was created with the
457 * #RTEMS_INHERIT_PRIORITY attribute, then the priority of the task currently
458 * holding the binary semaphore will inherit the current priority set of the
459 * blocking task.  The priority inheritance is carried out recursively.  This
460 * means, that if the task currently holding the binary semaphore is blocked on
461 * another local, binary semaphore using the priority inheritance locking
462 * protocol, then the owner of this semaphore will inherit the current priority
463 * sets of both tasks, and so on.  A task has a current priority for each
464 * scheduler.
465 *
466 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
467 *
468 * @retval ::RTEMS_INVALID_ID There was no semaphore associated with the
469 *   identifier specified by ``id``.
470 *
471 * @retval ::RTEMS_NOT_DEFINED The semaphore uses a priority ceiling and there
472 *   was no priority ceiling defined for the home scheduler of the calling
473 *   task.
474 *
475 * @retval ::RTEMS_UNSATISFIED The semaphore could not be obtained immediately.
476 *
477 * @retval ::RTEMS_INVALID_PRIORITY The semaphore uses a priority ceiling and
478 *   the calling task had a current priority less than the priority ceiling.
479 *
480 * @retval ::RTEMS_INCORRECT_STATE Acquiring of the local, binary semaphore by
481 *   the calling task would have cased a deadlock.
482 *
483 * @retval ::RTEMS_INCORRECT_STATE The calling task attempted to recursively
484 *   obtain a local, binary semaphore using the MrsP locking protocol.
485 *
486 * @retval ::RTEMS_UNSATISFIED The semaphore was flushed while the calling task
487 *   was waiting to obtain the semaphore.
488 *
489 * @retval ::RTEMS_TIMEOUT The timeout happened while the calling task was
490 *   waiting to obtain the semaphore.
491 *
492 * @retval ::RTEMS_OBJECT_WAS_DELETED The semaphore was deleted while the
493 *   calling task was waiting to obtain the semaphore.
494 *
495 * @par Notes
496 * @parblock
497 * If a local, binary semaphore was created with the #RTEMS_PRIORITY_CEILING or
498 * #RTEMS_MULTIPROCESSOR_RESOURCE_SHARING attribute, a task successfully
499 * obtains the semaphore, and the priority of that task is greater than the
500 * ceiling priority for this semaphore, then the priority of the task acquiring
501 * the semaphore is elevated to that of the ceiling.
502 *
503 * Deadlock situations are detected for local, binary semaphores.  If a
504 * deadlock is detected, then the directive immediately returns the
505 * ::RTEMS_INCORRECT_STATE status code.
506 *
507 * It is not allowed to recursively obtain (nested access) a local, binary
508 * semaphore using the MrsP locking protocol and any attempt to do this will
509 * just return the ::RTEMS_INCORRECT_STATE status code.  This error can only
510 * happen in SMP configurations.
511 *
512 * If the semaphore was created with the #RTEMS_PRIORITY attribute, then the
513 * calling task is inserted into the wait queue according to its priority.
514 * However, if the semaphore was created with the #RTEMS_FIFO attribute, then
515 * the calling task is placed at the rear of the wait queue.
516 *
517 * Attempting to obtain a global semaphore which does not reside on the local
518 * node will generate a request to the remote node to access the semaphore.  If
519 * the semaphore is not available and #RTEMS_NO_WAIT was not specified, then
520 * the task must be blocked until the semaphore is released.  A proxy is
521 * allocated on the remote node to represent the task until the semaphore is
522 * released.
523 * @endparblock
524 *
525 * @par Constraints
526 * @parblock
527 * The following constraints apply to this directive:
528 *
529 * * When a local, counting semaphore or a local, simple binary semaphore is
530 *   accessed and the #RTEMS_NO_WAIT option is set, the directive may be called
531 *   from within interrupt context.
532 *
533 * * When a local semaphore is accessed and the request can be immediately
534 *   satisfied, the directive may be called from within device driver
535 *   initialization context.
536 *
537 * * The directive may be called from within task context.
538 *
539 * * When the request cannot be immediately satisfied and the #RTEMS_WAIT
540 *   option is set, the calling task blocks at some point during the directive
541 *   call.
542 *
543 * * The timeout functionality of the directive requires a clock tick.
544 *
545 * * When the directive operates on a remote object, the directive sends a
546 *   message to the remote node and waits for a reply.  This will preempt the
547 *   calling task.
548 * @endparblock
549 */
550rtems_status_code rtems_semaphore_obtain(
551  rtems_id       id,
552  rtems_option   option_set,
553  rtems_interval timeout
554);
555
556/* Generated from spec:/rtems/sem/if/release */
557
558/**
559 * @ingroup RTEMSAPIClassicSem
560 *
561 * @brief Releases the semaphore.
562 *
563 * @param id is the semaphore identifier.
564 *
565 * This directive releases the semaphore specified by ``id``.  If the
566 * semaphore's wait queue is not empty, then
567 *
568 * * the first task on the wait queue is removed and unblocked, the semaphore's
569 *   count is not changed, otherwise
570 *
571 * * the semaphore's count is incremented by one for counting semaphores and
572 *   set to one for binary and simple binary semaphores.
573 *
574 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
575 *
576 * @retval ::RTEMS_INVALID_ID There was no semaphore associated with the
577 *   identifier specified by ``id``.
578 *
579 * @retval ::RTEMS_NOT_OWNER_OF_RESOURCE The calling task was not the owner of
580 *   the semaphore.
581 *
582 * @retval ::RTEMS_UNSATISFIED The semaphore's count already had the maximum
583 *   value of UINT32_MAX.
584 *
585 * @par Notes
586 * @parblock
587 * The calling task may be preempted if it causes a higher priority task to be
588 * made ready for execution.
589 *
590 * The outermost release of a local, binary semaphore using the priority
591 * inheritance, priority ceiling, or MrsP locking protocol may result in the
592 * calling task having its priority lowered.  This will occur if the highest
593 * priority of the calling task was available due to the ownership of the
594 * released semaphore.  If a task was on the semaphore's wait queue, then the
595 * priority associated with the semaphore will be transferred to the new owner.
596 *
597 * Releasing a global semaphore which does not reside on the local node will
598 * generate a request telling the remote node to release the semaphore.
599 *
600 * If the task to be unblocked resides on a different node from the semaphore,
601 * then the semaphore allocation is forwarded to the appropriate node, the
602 * waiting task is unblocked, and the proxy used to represent the task is
603 * reclaimed.
604 * @endparblock
605 *
606 * @par Constraints
607 * @parblock
608 * The following constraints apply to this directive:
609 *
610 * * When a local, counting semaphore or a local, simple binary semaphore is
611 *   accessed, the directive may be called from within interrupt context.
612 *
613 * * When a local semaphore is accessed, the directive may be called from
614 *   within device driver initialization context.
615 *
616 * * The directive may be called from within task context.
617 *
618 * * The directive may unblock a task.  This may cause the calling task to be
619 *   preempted.
620 *
621 * * When the directive operates on a remote object, the directive sends a
622 *   message to the remote node and waits for a reply.  This will preempt the
623 *   calling task.
624 * @endparblock
625 */
626rtems_status_code rtems_semaphore_release( rtems_id id );
627
628/* Generated from spec:/rtems/sem/if/flush */
629
630/**
631 * @ingroup RTEMSAPIClassicSem
632 *
633 * @brief Flushes the semaphore.
634 *
635 * @param id is the semaphore identifier.
636 *
637 * This directive unblocks all tasks waiting on the semaphore specified by
638 * ``id``.  The semaphore's count is not changed by this directive.  Tasks
639 * which are unblocked as the result of this directive will return from the
640 * rtems_semaphore_obtain() directive with a status code of ::RTEMS_UNSATISFIED
641 * to indicate that the semaphore was not obtained.
642 *
643 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
644 *
645 * @retval ::RTEMS_INVALID_ID There was no semaphore associated with the
646 *   identifier specified by ``id``.
647 *
648 * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The semaphore resided on a remote
649 *   node.
650 *
651 * @retval ::RTEMS_NOT_DEFINED Flushing a semaphore using the MrsP locking
652 *   protocol is undefined behaviour.
653 *
654 * @par Notes
655 * @parblock
656 * If the task to be unblocked resides on a different node from the semaphore,
657 * then the waiting task is unblocked, and the proxy used to represent the task
658 * is reclaimed.
659 *
660 * It is not allowed to flush a local, binary semaphore using the MrsP locking
661 * protocol and any attempt to do this will just return the ::RTEMS_NOT_DEFINED
662 * status code.  This error can only happen in SMP configurations.
663 *
664 * For barrier synchronization, the @ref RTEMSAPIClassicBarrier offers a
665 * cleaner alternative to using the semaphore flush directive.  Unlike POSIX
666 * barriers, they have a manual release option.
667 *
668 * Using the semaphore flush directive for condition synchronization in concert
669 * with another semaphore may be subject to the lost wake-up problem.  The
670 * following attempt to implement a condition variable is broken.
671 *
672 * @code
673 * #include <rtems.h>
674 * #include <assert.h>
675 *
676 * void cnd_wait( rtems_id cnd, rtems_id mtx )
677 * {
678 *   rtems_status_code sc;
679 *
680 *   sc = rtems_semaphore_release( mtx );
681 *   assert( sc == RTEMS_SUCCESSFUL );
682 *
683 *   // Here, a higher priority task may run and satisfy the condition.
684 *   // We may never wake up from the next semaphore obtain.
685 *
686 *   sc = rtems_semaphore_obtain( cnd, RTEMS_WAIT, RTEMS_NO_TIMEOUT );
687 *   assert( sc == RTEMS_UNSATISFIED );
688 *
689 *   sc = rtems_semaphore_obtain( mtx, RTEMS_WAIT, RTEMS_NO_TIMEOUT );
690 *   assert( sc == RTEMS_SUCCESSFUL );
691 * }
692 *
693 * void cnd_broadcast( rtems_id cnd )
694 * {
695 *   rtems_status_code sc;
696 *
697 *   sc = rtems_semaphore_flush( cnd );
698 *   assert( sc == RTEMS_SUCCESSFUL );
699 * }
700 * @endcode
701 * @endparblock
702 *
703 * @par Constraints
704 * @parblock
705 * The following constraints apply to this directive:
706 *
707 * * When a local, counting semaphore or a local, simple binary semaphore is
708 *   accessed, the directive may be called from within interrupt context.
709 *
710 * * When a local semaphore is accessed, the directive may be called from
711 *   within device driver initialization context.
712 *
713 * * The directive may be called from within task context.
714 *
715 * * The directive may unblock a task.  This may cause the calling task to be
716 *   preempted.
717 *
718 * * When the directive operates on a remote object, the directive sends a
719 *   message to the remote node and waits for a reply.  This will preempt the
720 *   calling task.
721 * @endparblock
722 */
723rtems_status_code rtems_semaphore_flush( rtems_id id );
724
725/* Generated from spec:/rtems/sem/if/set-priority */
726
727/**
728 * @ingroup RTEMSAPIClassicSem
729 *
730 * @brief Sets the priority by scheduler for the semaphore.
731 *
732 * @param semaphore_id is the semaphore identifier.
733 *
734 * @param scheduler_id is the identifier of the scheduler corresponding to the
735 *   new priority.
736 *
737 * @param new_priority is the new priority corresponding to the specified
738 *   scheduler.
739 *
740 * @param[out] old_priority is the pointer to a task priority variable.  When
741 *   the directive call is successful, the old priority of the semaphore
742 *   corresponding to the specified scheduler will be stored in this variable.
743 *
744 * This directive sets the priority of the semaphore specified by
745 * ``semaphore_id``.  The priority corresponds to the scheduler specified by
746 * ``scheduler_id``.
747 *
748 * The special priority value #RTEMS_CURRENT_PRIORITY can be used to get the
749 * current priority without changing it.
750 *
751 * The availability and use of a priority depends on the class and locking
752 * protocol of the semaphore:
753 *
754 * * For local, binary semaphores using the MrsP locking protocol, the ceiling
755 *   priority for each scheduler can be set by this directive.
756 *
757 * * For local, binary semaphores using the priority ceiling protocol, the
758 *   ceiling priority can be set by this directive.
759 *
760 * * For other semaphore classes and locking protocols, setting a priority is
761 *   undefined behaviour.
762 *
763 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
764 *
765 * @retval ::RTEMS_INVALID_ADDRESS The ``old_priority`` parameter was NULL.
766 *
767 * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the
768 *   identifier specified by ``scheduler_id``.
769 *
770 * @retval ::RTEMS_INVALID_ID There was no semaphore associated with the
771 *   identifier specified by ``semaphore_id``.
772 *
773 * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The semaphore resided on a remote
774 *   node.
775 *
776 * @retval ::RTEMS_INVALID_PRIORITY The ``new_priority`` parameter was invalid.
777 *
778 * @retval ::RTEMS_NOT_DEFINED Setting a priority for the class or locking
779 *   protocol of the semaphore is undefined behaviour.
780 *
781 * @par Notes
782 * @parblock
783 * Please have a look at the following example:
784 *
785 * @code
786 * #include <assert.h>
787 * #include <rtems.h>
788 *
789 * #define SCHED_A rtems_build_name( ' ', ' ', ' ', 'A' )
790 * #define SCHED_B rtems_build_name( ' ', ' ', ' ', 'B' )
791 *
792 * static void Init( rtems_task_argument arg )
793 * {
794 *   rtems_status_code   sc;
795 *   rtems_id            semaphore_id;
796 *   rtems_id            scheduler_a_id;
797 *   rtems_id            scheduler_b_id;
798 *   rtems_task_priority prio;
799 *
800 *   (void) arg;
801 *
802 *   // Get the scheduler identifiers
803 *   sc = rtems_scheduler_ident( SCHED_A, &scheduler_a_id );
804 *   assert( sc == RTEMS_SUCCESSFUL );
805 *   sc = rtems_scheduler_ident( SCHED_B, &scheduler_b_id );
806 *   assert( sc == RTEMS_SUCCESSFUL );
807 *
808 *   // Create a local, binary semaphore using the MrsP locking protocol
809 *   sc = rtems_semaphore_create(
810 *     rtems_build_name( 'M', 'R', 'S', 'P' ),
811 *     1,
812 *     RTEMS_BINARY_SEMAPHORE | RTEMS_PRIORITY |
813 *       RTEMS_MULTIPROCESSOR_RESOURCE_SHARING,
814 *     1,
815 *     &semaphore_id
816 *   );
817 *   assert( sc == RTEMS_SUCCESSFUL );
818 *
819 *   // The ceiling priority for each scheduler is equal to the priority
820 *   // specified for the semaphore creation.
821 *   prio = RTEMS_CURRENT_PRIORITY;
822 *   sc = rtems_semaphore_set_priority( semaphore_id, scheduler_a_id, prio, &prio );
823 *   assert( sc == RTEMS_SUCCESSFUL );
824 *   assert( prio == 1 );
825 *
826 *   // Check the old value and set a new ceiling priority for scheduler B
827 *   prio = 2;
828 *   sc = rtems_semaphore_set_priority( semaphore_id, scheduler_b_id, prio, &prio );
829 *   assert( sc == RTEMS_SUCCESSFUL );
830 *   assert( prio == 1 );
831 *
832 *   // Check the ceiling priority values
833 *   prio = RTEMS_CURRENT_PRIORITY;
834 *   sc = rtems_semaphore_set_priority( semaphore_id, scheduler_a_id, prio, &prio );
835 *   assert( sc == RTEMS_SUCCESSFUL );
836 *   assert( prio == 1 );
837 *   prio = RTEMS_CURRENT_PRIORITY;
838 *   sc = rtems_semaphore_set_priority( semaphore_id, scheduler_b_id, prio, &prio );
839 *   assert( sc == RTEMS_SUCCESSFUL );
840 *   assert( prio == 2 );
841 *
842 *   sc = rtems_semaphore_delete( semaphore_id );
843 *   assert( sc == RTEMS_SUCCESSFUL );
844 *
845 *   rtems_shutdown_executive( 0 );
846 * }
847 *
848 * #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
849 * #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
850 * #define CONFIGURE_MAXIMUM_TASKS 1
851 * #define CONFIGURE_MAXIMUM_SEMAPHORES 1
852 * #define CONFIGURE_MAXIMUM_PROCESSORS 2
853 *
854 * #define CONFIGURE_SCHEDULER_SIMPLE_SMP
855 *
856 * #include <rtems/scheduler.h>
857 *
858 * RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP( a );
859 * RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP( b );
860 *
861 * #define CONFIGURE_SCHEDULER_TABLE_ENTRIES \
862 *     RTEMS_SCHEDULER_TABLE_SIMPLE_SMP( a, SCHED_A ), \
863 *     RTEMS_SCHEDULER_TABLE_SIMPLE_SMP( b, SCHED_B )
864 *
865 * #define CONFIGURE_SCHEDULER_ASSIGNMENTS \
866 *     RTEMS_SCHEDULER_ASSIGN( 0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY ), \
867 *     RTEMS_SCHEDULER_ASSIGN( 1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY )
868 *
869 * #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
870 * #define CONFIGURE_INIT
871 *
872 * #include <rtems/confdefs.h>
873 * @endcode
874 * @endparblock
875 *
876 * @par Constraints
877 * @parblock
878 * The following constraints apply to this directive:
879 *
880 * * The directive may be called from within interrupt context.
881 *
882 * * The directive may be called from within device driver initialization
883 *   context.
884 *
885 * * The directive may be called from within task context.
886 *
887 * * The directive may change the priority of a task.  This may cause the
888 *   calling task to be preempted.
889 * @endparblock
890 */
891rtems_status_code rtems_semaphore_set_priority(
892  rtems_id             semaphore_id,
893  rtems_id             scheduler_id,
894  rtems_task_priority  new_priority,
895  rtems_task_priority *old_priority
896);
897
898#ifdef __cplusplus
899}
900#endif
901
902#endif /* _RTEMS_RTEMS_SEM_H */
Note: See TracBrowser for help on using the repository browser.