summaryrefslogtreecommitdiffstats
path: root/cpukit/include/rtems/rtems/sem.h
blob: 2cf3ba232bf2c955a3711fd3d56d35183f60aba6 (plain)
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
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
/* SPDX-License-Identifier: BSD-2-Clause */

/**
 * @file
 *
 * @brief This header file defines the Semaphore Manager API.
 */

/*
 * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

/*
 * This file is part of the RTEMS quality process and was automatically
 * generated.  If you find something that needs to be fixed or
 * worded better please post a report or patch to an RTEMS mailing list
 * or raise a bug report:
 *
 * https://www.rtems.org/bugs.html
 *
 * For information on updating and regenerating please refer to the How-To
 * section in the Software Requirements Engineering chapter of the
 * RTEMS Software Engineering manual.  The manual is provided as a part of
 * a release.  For development sources please refer to the online
 * documentation at:
 *
 * https://docs.rtems.org
 */

/* Generated from spec:/rtems/sem/if/header */

#ifndef _RTEMS_RTEMS_SEM_H
#define _RTEMS_RTEMS_SEM_H

#include <stdint.h>
#include <rtems/rtems/attr.h>
#include <rtems/rtems/options.h>
#include <rtems/rtems/status.h>
#include <rtems/rtems/types.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Generated from spec:/rtems/sem/if/group */

/**
 * @defgroup RTEMSAPIClassicSem Semaphore Manager
 *
 * @ingroup RTEMSAPIClassic
 *
 * @brief The Semaphore Manager utilizes standard Dijkstra counting semaphores
 *   to provide synchronization and mutual exclusion capabilities.
 */

/* Generated from spec:/rtems/sem/if/create */

/**
 * @ingroup RTEMSAPIClassicSem
 *
 * @brief Creates a semaphore.
 *
 * @param name is the object name of the semaphore.
 *
 * @param count 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.
 *
 * @param attribute_set is the attribute set of the semaphore.
 *
 * @param priority_ceiling 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.
 *
 * @param[out] id is the pointer to an ::rtems_id object.  When the directive
 *   call is successful, the identifier of the created semaphore will be stored
 *   in this object.
 *
 * This directive creates a semaphore which resides on the local node.  The
 * semaphore has the user-defined object name specified in ``name`` and the
 * initial count specified in ``count``.  The assigned object identifier is
 * returned in ``id``.  This identifier is used to access the semaphore with
 * other semaphore related directives.
 *
 * The **attribute set** specified in ``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.  Attributes not mentioned below are not evaluated by this
 * directive and have no effect.  Default attributes can be selected by using
 * the #RTEMS_DEFAULT_ATTRIBUTES constant.  The attribute set defines
 *
 * * the scope of the semaphore: #RTEMS_LOCAL (default) or #RTEMS_GLOBAL,
 *
 * * the task wait queue discipline used by the semaphore: #RTEMS_FIFO
 *   (default) or #RTEMS_PRIORITY,
 *
 * * the class of the semaphore: #RTEMS_COUNTING_SEMAPHORE (default),
 *   #RTEMS_BINARY_SEMAPHORE, or #RTEMS_SIMPLE_BINARY_SEMAPHORE, and
 *
 * * the locking protocol of a binary semaphore: no locking protocol (default),
 *   #RTEMS_INHERIT_PRIORITY, #RTEMS_PRIORITY_CEILING, or
 *   #RTEMS_MULTIPROCESSOR_RESOURCE_SHARING.
 *
 * 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 #RTEMS_LOCAL and #RTEMS_GLOBAL attributes.
 *
 * * A **local scope** is the default and can be emphasized through the use of
 *   the #RTEMS_LOCAL attribute.  A local semaphore can be only used by the
 *   node which created it.
 *
 * * A **global scope** is established if the #RTEMS_GLOBAL 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
 * #RTEMS_FIFO and #RTEMS_PRIORITY attributes.
 *
 * * The **FIFO discipline** is the default and can be emphasized through use
 *   of the #RTEMS_FIFO attribute.
 *
 * * The **priority discipline** is selected by the #RTEMS_PRIORITY attribute.
 *   The locking protocols require the priority discipline.
 *
 * The **semaphore class** is selected by the mutually exclusive
 * #RTEMS_COUNTING_SEMAPHORE, #RTEMS_BINARY_SEMAPHORE, and
 * #RTEMS_SIMPLE_BINARY_SEMAPHORE attributes.
 *
 * * The **counting semaphore class** is the default and can be emphasized
 *   through use of the #RTEMS_COUNTING_SEMAPHORE attribute.
 *
 * * The **binary semaphore class** is selected by the #RTEMS_BINARY_SEMAPHORE
 *   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
 *   #RTEMS_SIMPLE_BINARY_SEMAPHORE 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 #RTEMS_INHERIT_PRIORITY, #RTEMS_PRIORITY_CEILING, and
 * #RTEMS_MULTIPROCESSOR_RESOURCE_SHARING attributes.
 *
 * * The default is **no locking protocol**.  This can be emphasized through
 *   use of the #RTEMS_NO_INHERIT_PRIORITY,
 *   #RTEMS_NO_MULTIPROCESSOR_RESOURCE_SHARING, and #RTEMS_NO_PRIORITY_CEILING
 *   attributes.
 *
 * * The **priority inheritance locking protocol** is selected by the
 *   #RTEMS_INHERIT_PRIORITY attribute.
 *
 * * The **priority ceiling locking protocol** is selected by the
 *   #RTEMS_PRIORITY_CEILING attribute.  For this locking protocol a priority
 *   ceiling shall be specified in ``priority_ceiling``.
 *
 * * The **MrsP locking protocol** is selected by the
 *   #RTEMS_MULTIPROCESSOR_RESOURCE_SHARING attribute in SMP configurations,
 *   otherwise this attribute selects the **priority ceiling locking
 *   protocol**.  For these locking protocols a priority ceiling shall be
 *   specified in ``priority_ceiling``.  This priority is used to set the
 *   priority ceiling for all schedulers.  This can be changed later with the
 *   rtems_semaphore_set_priority() directive using the returned object
 *   identifier.
 *
 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
 *
 * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid.
 *
 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
 *
 * @retval ::RTEMS_INVALID_NUMBER The ``count`` parameter was invalid.
 *
 * @retval ::RTEMS_NOT_DEFINED The ``attribute_set`` parameter was invalid.
 *
 * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a
 *   semaphore.  The number of semaphores available to the application is
 *   configured through the #CONFIGURE_MAXIMUM_SEMAPHORES application
 *   configuration option.
 *
 * @retval ::RTEMS_TOO_MANY 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
 *   #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option.
 *
 * @retval ::RTEMS_INVALID_PRIORITY The ``priority_ceiling`` parameter was
 *   invalid.
 *
 * @par Notes
 * @parblock
 * For control and maintenance of the semaphore, RTEMS allocates a SMCB 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.
 * @endparblock
 *
 * @par Constraints
 * @parblock
 * The following constraints apply to this directive:
 *
 * * The directive may be called from within device driver initialization
 *   context.
 *
 * * The directive may be called from within task context.
 *
 * * The directive may obtain and release the object allocator mutex.  This may
 *   cause the calling task to be preempted.
 *
 * * When the directive operates on a global object, the directive sends a
 *   message to remote nodes.  This may preempt the calling task.
 *
 * * The number of semaphores available to the application is configured
 *   through the #CONFIGURE_MAXIMUM_SEMAPHORES application configuration
 *   option.
 *
 * * Where the object class corresponding to the directive is configured to use
 *   unlimited objects, the directive may allocate memory from the RTEMS
 *   Workspace.
 *
 * * The number of global objects available to the application is configured
 *   through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration
 *   option.
 * @endparblock
 */
rtems_status_code rtems_semaphore_create(
  rtems_name          name,
  uint32_t            count,
  rtems_attribute     attribute_set,
  rtems_task_priority priority_ceiling,
  rtems_id           *id
);

/* Generated from spec:/rtems/sem/if/ident */

/**
 * @ingroup RTEMSAPIClassicSem
 *
 * @brief Identifies a semaphore by the object name.
 *
 * @param name is the object name to look up.
 *
 * @param node is the node or node set to search for a matching object.
 *
 * @param[out] id is the pointer to an ::rtems_id object.  When the directive
 *   call is successful, the object identifier of an object with the specified
 *   name will be stored in this object.
 *
 * This directive obtains a semaphore identifier associated with the semaphore
 * name specified in ``name``.
 *
 * The node to search is specified in ``node``.  It shall be
 *
 * * a valid node number,
 *
 * * the constant #RTEMS_SEARCH_ALL_NODES to search in all nodes,
 *
 * * the constant #RTEMS_SEARCH_LOCAL_NODE to search in the local node only, or
 *
 * * the constant #RTEMS_SEARCH_OTHER_NODES to search in all nodes except the
 *   local node.
 *
 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
 *
 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
 *
 * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was 0.
 *
 * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
 *   the specified nodes.
 *
 * @retval ::RTEMS_INVALID_NODE In multiprocessing configurations, the
 *   specified node was invalid.
 *
 * @par Notes
 * @parblock
 * If the semaphore name is not unique, then the semaphore identifier will
 * match the first semaphore with that name in the search order.  However, this
 * semaphore identifier is not guaranteed to correspond to the desired
 * semaphore.
 *
 * The objects are searched from lowest to the highest index.  If ``node`` is
 * #RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local node being
 * searched first.  All other nodes are searched from lowest to the highest
 * node number.
 *
 * If node is a valid node number which does not represent the local node, then
 * only the semaphores exported by the designated node are searched.
 *
 * This directive does not generate activity on remote nodes.  It accesses only
 * the local copy of the global object table.
 *
 * The semaphore identifier is used with other semaphore related directives to
 * access the semaphore.
 * @endparblock
 *
 * @par Constraints
 * @parblock
 * The following constraints apply to this directive:
 *
 * * The directive may be called from within any runtime context.
 *
 * * The directive will not cause the calling task to be preempted.
 * @endparblock
 */
rtems_status_code rtems_semaphore_ident(
  rtems_name name,
  uint32_t   node,
  rtems_id  *id
);

/* Generated from spec:/rtems/sem/if/delete */

/**
 * @ingroup RTEMSAPIClassicSem
 *
 * @brief Deletes the semaphore.
 *
 * @param id is the semaphore identifier.
 *
 * This directive deletes the semaphore specified by ``id``.
 *
 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
 *
 * @retval ::RTEMS_INVALID_ID There was no semaphore associated with the
 *   identifier specified by ``id``.
 *
 * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The semaphore resided on a remote
 *   node.
 *
 * @retval ::RTEMS_RESOURCE_IN_USE The binary semaphore had an owner.
 *
 * @par Notes
 * @parblock
 * Binary semaphores with an owner cannot be deleted.
 *
 * When a semaphore is deleted, all tasks blocked waiting to obtain the
 * semaphore will be readied and returned a status code which indicates that
 * the semaphore was deleted.
 *
 * The SMCB for the deleted semaphore is reclaimed by RTEMS.
 *
 * When a global semaphore is deleted, the semaphore identifier must be
 * transmitted to every node in the system for deletion from the local copy of
 * the global object table.
 *
 * The semaphore must reside on the local node, even if the semaphore was
 * created with the #RTEMS_GLOBAL attribute.
 *
 * Proxies, used to represent remote tasks, are reclaimed when the semaphore is
 * deleted.
 * @endparblock
 *
 * @par Constraints
 * @parblock
 * The following constraints apply to this directive:
 *
 * * The directive may be called from within device driver initialization
 *   context.
 *
 * * The directive may be called from within task context.
 *
 * * The directive may obtain and release the object allocator mutex.  This may
 *   cause the calling task to be preempted.
 *
 * * When the directive operates on a global object, the directive sends a
 *   message to remote nodes.  This may preempt the calling task.
 *
 * * The calling task does not have to be the task that created the object.
 *   Any local task that knows the object identifier can delete the object.
 *
 * * Where the object class corresponding to the directive is configured to use
 *   unlimited objects, the directive may free memory to the RTEMS Workspace.
 * @endparblock
 */
rtems_status_code rtems_semaphore_delete( rtems_id id );

/* Generated from spec:/rtems/sem/if/obtain */

/**
 * @ingroup RTEMSAPIClassicSem
 *
 * @brief Obtains the semaphore.
 *
 * @param id is the semaphore identifier.
 *
 * @param option_set is the option set.
 *
 * @param timeout is the timeout in clock ticks if the #RTEMS_WAIT option is
 *   set.  Use #RTEMS_NO_TIMEOUT to wait potentially forever.
 *
 * This directive obtains the semaphore specified by ``id``.
 *
 * The **option set** specified in ``option_set`` is built through a *bitwise
 * or* of the option constants described below.  Not all combinations of
 * options are allowed.  Some options are mutually exclusive.  If mutually
 * exclusive options are combined, the behaviour is undefined.  Options not
 * mentioned below are not evaluated by this directive and have no effect.
 * Default options can be selected by using the #RTEMS_DEFAULT_OPTIONS
 * constant.
 *
 * The calling task can **wait** or **try to obtain** the semaphore according
 * to the mutually exclusive #RTEMS_WAIT and #RTEMS_NO_WAIT options.
 *
 * * **Waiting to obtain** the semaphore is the default and can be emphasized
 *   through the use of the #RTEMS_WAIT option.  The ``timeout`` parameter
 *   defines how long the calling task is willing to wait.  Use
 *   #RTEMS_NO_TIMEOUT to wait potentially forever, otherwise set a timeout
 *   interval in clock ticks.
 *
 * * **Trying to obtain** the semaphore is selected by the #RTEMS_NO_WAIT
 *   option.  If this option is defined, then the ``timeout`` parameter is
 *   ignored.  When the semaphore cannot be immediately obtained, then the
 *   ::RTEMS_UNSATISFIED status is returned.
 *
 * With either #RTEMS_WAIT or #RTEMS_NO_WAIT if the current semaphore count is
 * positive, then it is decremented by one and the semaphore is successfully
 * obtained by returning immediately with the ::RTEMS_SUCCESSFUL status code.
 *
 * If the calling task chooses to return immediately and the current semaphore
 * count is zero, then the ::RTEMS_UNSATISFIED status code is returned
 * indicating that the semaphore is not available.
 *
 * If the calling task chooses to wait for a semaphore and the current
 * semaphore count is zero, then the calling task is placed on the semaphore's
 * wait queue and blocked.  If a local, binary semaphore was created with the
 * #RTEMS_INHERIT_PRIORITY attribute, then the priority of the task currently
 * holding the binary semaphore will inherit the current priority set of the
 * blocking task.  The priority inheritance is carried out recursively.  This
 * means, that if the task currently holding the binary semaphore is blocked on
 * another local, binary semaphore using the priority inheritance locking
 * protocol, then the owner of this semaphore will inherit the current priority
 * sets of both tasks, and so on.  A task has a current priority for each
 * scheduler.
 *
 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
 *
 * @retval ::RTEMS_INVALID_ID There was no semaphore associated with the
 *   identifier specified by ``id``.
 *
 * @retval ::RTEMS_NOT_DEFINED The semaphore uses a priority ceiling and there
 *   was no priority ceiling defined for the home scheduler of the calling
 *   task.
 *
 * @retval ::RTEMS_UNSATISFIED The semaphore could not be obtained immediately.
 *
 * @retval ::RTEMS_INVALID_PRIORITY The semaphore uses a priority ceiling and
 *   the calling task had a current priority less than the priority ceiling.
 *
 * @retval ::RTEMS_INCORRECT_STATE Acquiring of the local, binary semaphore by
 *   the calling task would have cased a deadlock.
 *
 * @retval ::RTEMS_INCORRECT_STATE The calling task attempted to recursively
 *   obtain a local, binary semaphore using the MrsP locking protocol.
 *
 * @retval ::RTEMS_UNSATISFIED The semaphore was flushed while the calling task
 *   was waiting to obtain the semaphore.
 *
 * @retval ::RTEMS_TIMEOUT The timeout happened while the calling task was
 *   waiting to obtain the semaphore.
 *
 * @retval ::RTEMS_OBJECT_WAS_DELETED The semaphore was deleted while the
 *   calling task was waiting to obtain the semaphore.
 *
 * @par Notes
 * @parblock
 * If a local, binary semaphore was created with the #RTEMS_PRIORITY_CEILING or
 * #RTEMS_MULTIPROCESSOR_RESOURCE_SHARING attribute, a task successfully
 * obtains the semaphore, and the priority of that task is greater than the
 * ceiling priority for this semaphore, then the priority of the task acquiring
 * the semaphore is elevated to that of the ceiling.
 *
 * Deadlock situations are detected for local, binary semaphores.  If a
 * deadlock is detected, then the directive immediately returns the
 * ::RTEMS_INCORRECT_STATE status code.
 *
 * It is not allowed to recursively obtain (nested access) a local, binary
 * semaphore using the MrsP locking protocol and any attempt to do this will
 * just return the ::RTEMS_INCORRECT_STATE status code.  This error can only
 * happen in SMP configurations.
 *
 * If the semaphore was created with the #RTEMS_PRIORITY attribute, then the
 * calling task is inserted into the wait queue according to its priority.
 * However, if the semaphore was created with the #RTEMS_FIFO attribute, then
 * the calling task is placed at the rear of the wait queue.
 *
 * Attempting to obtain a global semaphore which does not reside on the local
 * node will generate a request to the remote node to access the semaphore.  If
 * the semaphore is not available and #RTEMS_NO_WAIT was not specified, then
 * the task must be blocked until the semaphore is released.  A proxy is
 * allocated on the remote node to represent the task until the semaphore is
 * released.
 * @endparblock
 *
 * @par Constraints
 * @parblock
 * The following constraints apply to this directive:
 *
 * * When a local, counting semaphore or a local, simple binary semaphore is
 *   accessed and the #RTEMS_NO_WAIT option is set, the directive may be called
 *   from within interrupt context.
 *
 * * When a local semaphore is accessed and the request can be immediately
 *   satisfied, the directive may be called from within device driver
 *   initialization context.
 *
 * * The directive may be called from within task context.
 *
 * * When the request cannot be immediately satisfied and the #RTEMS_WAIT
 *   option is set, the calling task blocks at some point during the directive
 *   call.
 *
 * * The timeout functionality of the directive requires a clock tick.
 *
 * * When the directive operates on a remote object, the directive sends a
 *   message to the remote node and waits for a reply.  This will preempt the
 *   calling task.
 * @endparblock
 */
rtems_status_code rtems_semaphore_obtain(
  rtems_id       id,
  rtems_option   option_set,
  rtems_interval timeout
);

/* Generated from spec:/rtems/sem/if/release */

/**
 * @ingroup RTEMSAPIClassicSem
 *
 * @brief Releases the semaphore.
 *
 * @param id is the semaphore identifier.
 *
 * This directive releases the semaphore specified by ``id``.  If the
 * semaphore's wait queue is not empty, then
 *
 * * the first task on the wait queue is removed and unblocked, the semaphore's
 *   count is not changed, otherwise
 *
 * * the semaphore's count is incremented by one for counting semaphores and
 *   set to one for binary and simple binary semaphores.
 *
 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
 *
 * @retval ::RTEMS_INVALID_ID There was no semaphore associated with the
 *   identifier specified by ``id``.
 *
 * @retval ::RTEMS_NOT_OWNER_OF_RESOURCE The calling task was not the owner of
 *   the semaphore.
 *
 * @retval ::RTEMS_UNSATISFIED The semaphore's count already had the maximum
 *   value of UINT32_MAX.
 *
 * @par Notes
 * @parblock
 * The calling task may be preempted if it causes a higher priority task to be
 * made ready for execution.
 *
 * The outermost release of a local, binary semaphore using the priority
 * inheritance, priority ceiling, or MrsP locking protocol may result in the
 * calling task having its priority lowered.  This will occur if the highest
 * priority of the calling task was available due to the ownership of the
 * released semaphore.  If a task was on the semaphore's wait queue, then the
 * priority associated with the semaphore will be transferred to the new owner.
 *
 * Releasing a global semaphore which does not reside on the local node will
 * generate a request telling the remote node to release the semaphore.
 *
 * If the task to be unblocked resides on a different node from the semaphore,
 * then the semaphore allocation is forwarded to the appropriate node, the
 * waiting task is unblocked, and the proxy used to represent the task is
 * reclaimed.
 * @endparblock
 *
 * @par Constraints
 * @parblock
 * The following constraints apply to this directive:
 *
 * * When a local, counting semaphore or a local, simple binary semaphore is
 *   accessed, the directive may be called from within interrupt context.
 *
 * * When a local semaphore is accessed, the directive may be called from
 *   within device driver initialization context.
 *
 * * The directive may be called from within task context.
 *
 * * The directive may unblock a task.  This may cause the calling task to be
 *   preempted.
 *
 * * When the directive operates on a remote object, the directive sends a
 *   message to the remote node and waits for a reply.  This will preempt the
 *   calling task.
 * @endparblock
 */
rtems_status_code rtems_semaphore_release( rtems_id id );

/* Generated from spec:/rtems/sem/if/flush */

/**
 * @ingroup RTEMSAPIClassicSem
 *
 * @brief Flushes the semaphore.
 *
 * @param id is the semaphore identifier.
 *
 * This directive unblocks all tasks waiting on the semaphore specified by
 * ``id``.  The semaphore's count is not changed by this directive.  Tasks
 * which are unblocked as the result of this directive will return from the
 * rtems_semaphore_obtain() directive with a status code of ::RTEMS_UNSATISFIED
 * to indicate that the semaphore was not obtained.
 *
 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
 *
 * @retval ::RTEMS_INVALID_ID There was no semaphore associated with the
 *   identifier specified by ``id``.
 *
 * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The semaphore resided on a remote
 *   node.
 *
 * @retval ::RTEMS_NOT_DEFINED Flushing a semaphore using the MrsP locking
 *   protocol is undefined behaviour.
 *
 * @par Notes
 * @parblock
 * If the task to be unblocked resides on a different node from the semaphore,
 * then the waiting task is unblocked, and the proxy used to represent the task
 * is reclaimed.
 *
 * It is not allowed to flush a local, binary semaphore using the MrsP locking
 * protocol and any attempt to do this will just return the ::RTEMS_NOT_DEFINED
 * status code.  This error can only happen in SMP configurations.
 *
 * For barrier synchronization, the @ref RTEMSAPIClassicBarrier offers a
 * cleaner alternative to using the semaphore flush directive.  Unlike POSIX
 * barriers, they have a manual release option.
 *
 * Using the semaphore flush directive for condition synchronization in concert
 * with another semaphore may be subject to the lost wake-up problem.  The
 * following attempt to implement a condition variable is broken.
 *
 * @code
 * #include <rtems.h>
 * #include <assert.h>
 *
 * void cnd_wait( rtems_id cnd, rtems_id mtx )
 * {
 *   rtems_status_code sc;
 *
 *   sc = rtems_semaphore_release( mtx );
 *   assert( sc == RTEMS_SUCCESSFUL );
 *
 *   // Here, a higher priority task may run and satisfy the condition.
 *   // We may never wake up from the next semaphore obtain.
 *
 *   sc = rtems_semaphore_obtain( cnd, RTEMS_WAIT, RTEMS_NO_TIMEOUT );
 *   assert( sc == RTEMS_UNSATISFIED );
 *
 *   sc = rtems_semaphore_obtain( mtx, RTEMS_WAIT, RTEMS_NO_TIMEOUT );
 *   assert( sc == RTEMS_SUCCESSFUL );
 * }
 *
 * void cnd_broadcast( rtems_id cnd )
 * {
 *   rtems_status_code sc;
 *
 *   sc = rtems_semaphore_flush( cnd );
 *   assert( sc == RTEMS_SUCCESSFUL );
 * }
 * @endcode
 * @endparblock
 *
 * @par Constraints
 * @parblock
 * The following constraints apply to this directive:
 *
 * * When a local, counting semaphore or a local, simple binary semaphore is
 *   accessed, the directive may be called from within interrupt context.
 *
 * * When a local semaphore is accessed, the directive may be called from
 *   within device driver initialization context.
 *
 * * The directive may be called from within task context.
 *
 * * The directive may unblock a task.  This may cause the calling task to be
 *   preempted.
 *
 * * When the directive operates on a remote object, the directive sends a
 *   message to the remote node and waits for a reply.  This will preempt the
 *   calling task.
 * @endparblock
 */
rtems_status_code rtems_semaphore_flush( rtems_id id );

/* Generated from spec:/rtems/sem/if/set-priority */

/**
 * @ingroup RTEMSAPIClassicSem
 *
 * @brief Sets the priority by scheduler for the semaphore.
 *
 * @param semaphore_id is the semaphore identifier.
 *
 * @param scheduler_id is the identifier of the scheduler corresponding to the
 *   new priority.
 *
 * @param new_priority is the new priority corresponding to the specified
 *   scheduler.
 *
 * @param[out] old_priority is the pointer to an ::rtems_task_priority object.
 *   When the directive call is successful, the old priority of the semaphore
 *   corresponding to the specified scheduler will be stored in this object.
 *
 * This directive sets the priority of the semaphore specified by
 * ``semaphore_id``.  The priority corresponds to the scheduler specified by
 * ``scheduler_id``.
 *
 * The special priority value #RTEMS_CURRENT_PRIORITY can be used to get the
 * current priority without changing it.
 *
 * The availability and use of a priority depends on the class and locking
 * protocol of the semaphore:
 *
 * * For local, binary semaphores using the MrsP locking protocol, the ceiling
 *   priority for each scheduler can be set by this directive.
 *
 * * For local, binary semaphores using the priority ceiling protocol, the
 *   ceiling priority can be set by this directive.
 *
 * * For other semaphore classes and locking protocols, setting a priority is
 *   undefined behaviour.
 *
 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
 *
 * @retval ::RTEMS_INVALID_ADDRESS The ``old_priority`` parameter was NULL.
 *
 * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the
 *   identifier specified by ``scheduler_id``.
 *
 * @retval ::RTEMS_INVALID_ID There was no semaphore associated with the
 *   identifier specified by ``semaphore_id``.
 *
 * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The semaphore resided on a remote
 *   node.
 *
 * @retval ::RTEMS_INVALID_PRIORITY The ``new_priority`` parameter was invalid.
 *
 * @retval ::RTEMS_NOT_DEFINED Setting a priority for the class or locking
 *   protocol of the semaphore is undefined behaviour.
 *
 * @par Notes
 * @parblock
 * Please have a look at the following example:
 *
 * @code
 * #include <assert.h>
 * #include <rtems.h>
 *
 * #define SCHED_A rtems_build_name( ' ', ' ', ' ', 'A' )
 * #define SCHED_B rtems_build_name( ' ', ' ', ' ', 'B' )
 *
 * static void Init( rtems_task_argument arg )
 * {
 *   rtems_status_code   sc;
 *   rtems_id            semaphore_id;
 *   rtems_id            scheduler_a_id;
 *   rtems_id            scheduler_b_id;
 *   rtems_task_priority prio;
 *
 *   (void) arg;
 *
 *   // Get the scheduler identifiers
 *   sc = rtems_scheduler_ident( SCHED_A, &scheduler_a_id );
 *   assert( sc == RTEMS_SUCCESSFUL );
 *   sc = rtems_scheduler_ident( SCHED_B, &scheduler_b_id );
 *   assert( sc == RTEMS_SUCCESSFUL );
 *
 *   // Create a local, binary semaphore using the MrsP locking protocol
 *   sc = rtems_semaphore_create(
 *     rtems_build_name( 'M', 'R', 'S', 'P' ),
 *     1,
 *     RTEMS_BINARY_SEMAPHORE | RTEMS_PRIORITY |
 *       RTEMS_MULTIPROCESSOR_RESOURCE_SHARING,
 *     1,
 *     &semaphore_id
 *   );
 *   assert( sc == RTEMS_SUCCESSFUL );
 *
 *   // The ceiling priority for each scheduler is equal to the priority
 *   // specified for the semaphore creation.
 *   prio = RTEMS_CURRENT_PRIORITY;
 *   sc = rtems_semaphore_set_priority( semaphore_id, scheduler_a_id, prio, &prio );
 *   assert( sc == RTEMS_SUCCESSFUL );
 *   assert( prio == 1 );
 *
 *   // Check the old value and set a new ceiling priority for scheduler B
 *   prio = 2;
 *   sc = rtems_semaphore_set_priority( semaphore_id, scheduler_b_id, prio, &prio );
 *   assert( sc == RTEMS_SUCCESSFUL );
 *   assert( prio == 1 );
 *
 *   // Check the ceiling priority values
 *   prio = RTEMS_CURRENT_PRIORITY;
 *   sc = rtems_semaphore_set_priority( semaphore_id, scheduler_a_id, prio, &prio );
 *   assert( sc == RTEMS_SUCCESSFUL );
 *   assert( prio == 1 );
 *   prio = RTEMS_CURRENT_PRIORITY;
 *   sc = rtems_semaphore_set_priority( semaphore_id, scheduler_b_id, prio, &prio );
 *   assert( sc == RTEMS_SUCCESSFUL );
 *   assert( prio == 2 );
 *
 *   sc = rtems_semaphore_delete( semaphore_id );
 *   assert( sc == RTEMS_SUCCESSFUL );
 *
 *   rtems_shutdown_executive( 0 );
 * }
 *
 * #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
 * #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
 * #define CONFIGURE_MAXIMUM_TASKS 1
 * #define CONFIGURE_MAXIMUM_SEMAPHORES 1
 * #define CONFIGURE_MAXIMUM_PROCESSORS 2
 *
 * #define CONFIGURE_SCHEDULER_SIMPLE_SMP
 *
 * #include <rtems/scheduler.h>
 *
 * RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP( a );
 * RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP( b );
 *
 * #define CONFIGURE_SCHEDULER_TABLE_ENTRIES \
 *     RTEMS_SCHEDULER_TABLE_SIMPLE_SMP( a, SCHED_A ), \
 *     RTEMS_SCHEDULER_TABLE_SIMPLE_SMP( b, SCHED_B )
 *
 * #define CONFIGURE_SCHEDULER_ASSIGNMENTS \
 *     RTEMS_SCHEDULER_ASSIGN( 0, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY ), \
 *     RTEMS_SCHEDULER_ASSIGN( 1, RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY )
 *
 * #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
 * #define CONFIGURE_INIT
 *
 * #include <rtems/confdefs.h>
 * @endcode
 * @endparblock
 *
 * @par Constraints
 * @parblock
 * The following constraints apply to this directive:
 *
 * * The directive may be called from within interrupt context.
 *
 * * The directive may be called from within device driver initialization
 *   context.
 *
 * * The directive may be called from within task context.
 *
 * * The directive may change the priority of a task.  This may cause the
 *   calling task to be preempted.
 * @endparblock
 */
rtems_status_code rtems_semaphore_set_priority(
  rtems_id             semaphore_id,
  rtems_id             scheduler_id,
  rtems_task_priority  new_priority,
  rtems_task_priority *old_priority
);

#ifdef __cplusplus
}
#endif

#endif /* _RTEMS_RTEMS_SEM_H */