source: rtems/doc/user/sem.t @ 61389eac

@c
@c  COPYRIGHT (c) 1996.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved.
@c

@ifinfo
@node Semaphore Manager, Semaphore Manager Introduction, TIMER_RESET - Reset an interval timer, Top
@end ifinfo
@chapter Semaphore Manager
@ifinfo
@menu
* Semaphore Manager Introduction::
* Semaphore Manager Background::
* Semaphore Manager Operations::
* Semaphore Manager Directives::
@end menu
@end ifinfo

@ifinfo
@node Semaphore Manager Introduction, Semaphore Manager Background, Semaphore Manager, Semaphore Manager
@end ifinfo
@section Introduction

The semaphore manager utilizes standard Dijkstra
counting semaphores to provide synchronization and mutual
exclusion capabilities.  The directives provided by the
semaphore manager are:

@itemize @bullet
@item @code{semaphore_create} -  Create a semaphore
@item @code{semaphore_ident} - Get ID of a semaphore
@item @code{semaphore_delete} - Delete a semaphore
@item @code{semaphore_obtain} - Acquire a semaphore
@item @code{semaphore_release} - Release a semaphore
@end itemize

@ifinfo
@node Semaphore Manager Background, Nested Resource Access, Semaphore Manager Introduction, Semaphore Manager
@end ifinfo
@section Background
@ifinfo
@menu
* Nested Resource Access::
* Priority Inversion::
* Priority Inheritance::
* Priority Ceiling::
* Building a Semaphore's Attribute Set::
* Building a SEMAPHORE_OBTAIN Option Set::
@end menu
@end ifinfo

A semaphore can be viewed as a protected variable
whose value can be modified only with the semaphore_create,
semaphore_obtain, and semaphore_release directives.  RTEMS
supports both binary and counting semaphores. A binary semaphore
is restricted to values of zero or one, while a counting
semaphore can assume any non-negative integer value.

A binary semaphore can be used to control access to a
single resource.  In particular, it can be used to enforce
mutual exclusion for a critical section in user code.  In this
instance, the semaphore would be created with an initial count
of one to indicate that no task is executing the critical
section of code.  Upon entry to the critical section, a task
must issue the semaphore_obtain directive to prevent other tasks
from entering the critical section.  Upon exit from the critical
section, the task must issue the semaphore_release directive to
allow another task to execute the critical section.

A counting semaphore can be used to control access to
a pool of two or more resources.  For example, access to three
printers could be administered by a semaphore created with an
initial count of three.  When a task requires access to one of
the printers, it issues the semaphore_obtain directive to obtain
access to a printer.  If a printer is not currently available,
the task can wait for a printer to become available or return
immediately.  When the task has completed printing, it should
issue the semaphore_release directive to allow other tasks
access to the printer.

Task synchronization may be achieved by creating a
semaphore with an initial count of zero.  One task waits for the
arrival of another task by issuing a semaphore_obtain directive
when it reaches a synchronization point.  The other task
performs a corresponding semaphore_release operation when it
reaches its synchronization point, thus unblocking the pending
task.

@ifinfo
@node Nested Resource Access, Priority Inversion, Semaphore Manager Background, Semaphore Manager Background
@end ifinfo
@subsection Nested Resource Access

Deadlock occurs when a task owning a binary semaphore
attempts to acquire that same semaphore and blocks as result.
Since the semaphore is allocated to a task, it cannot be
deleted.  Therefore, the task that currently holds the semaphore
and is also blocked waiting for that semaphore will never
execute again.

RTEMS addresses this problem by allowing the task
holding the binary semaphore to obtain the same binary semaphore
multiple times in a nested manner.  Each semaphore_obtain must
be accompanied with a semaphore_release.  The semaphore will
only be made available for acquisition by other tasks when the
outermost semaphore_obtain is matched with a semaphore_release.


@ifinfo
@node Priority Inversion, Priority Inheritance, Nested Resource Access, Semaphore Manager Background
@end ifinfo
@subsection Priority Inversion

Priority inversion is a form of indefinite
postponement which is common in multitasking, preemptive
executives with shared resources.  Priority inversion occurs
when a high priority tasks requests access to shared resource
which is currently allocated to low priority task.  The high
priority task must block until the low priority task releases
the resource.  This problem is exacerbated when the low priority
task is prevented from executing by one or more medium priority
tasks.  Because the low priority task is not executing, it
cannot complete its interaction with the resource and release
that resource.  The high priority task is effectively prevented
from executing by lower priority tasks.

@ifinfo
@node Priority Inheritance, Priority Ceiling, Priority Inversion, Semaphore Manager Background
@end ifinfo
@subsection Priority Inheritance

Priority inheritance is an algorithm that calls for
the lower priority task holding a resource to have its priority
increased to that of the highest priority task blocked waiting
for that resource.  Each time a task blocks attempting to obtain
the resource, the task holding the resource may have its
priority increased.

RTEMS supports priority inheritance for local, binary
semaphores that use the priority task wait queue blocking
discipline.   When a task of higher priority than the task
holding the semaphore blocks, the priority of the task holding
the semaphore is increased to that of the blocking task.  When
the task holding the task completely releases the binary
semaphore (i.e. not for a nested release), the holder's priority
is restored to the value it had before any higher priority was
inherited.

The RTEMS implementation of the priority inheritance
algorithm takes into account the scenario in which a task holds
more than one binary semaphore.  The holding task will execute
at the priority of the higher of the highest ceiling priority or
at the priority of the highest priority task blocked waiting for
any of the semaphores the task holds.  Only when the task
releases ALL of the binary semaphores it holds will its priority
be restored to the normal value.

@ifinfo
@node Priority Ceiling, Building a Semaphore's Attribute Set, Priority Inheritance, Semaphore Manager Background
@end ifinfo
@subsection Priority Ceiling

Priority ceiling is an algorithm that calls for the
lower priority task holding a resource to have its priority
increased to that of the highest priority task which will EVER
block waiting for that resource.  This algorithm addresses the
problem of priority inversion although it avoids the possibility
of changing the priority of the task holding the resource
multiple times.  The priority ceiling algorithm will only change
the priority of the task holding the resource a maximum of one
time.  The ceiling priority is set at creation time and must be
the priority of the highest priority task which will ever
attempt to acquire that semaphore.

RTEMS supports priority ceiling for local, binary
semaphores that use the priority task wait queue blocking
discipline.   When a task of lower priority than the ceiling
priority successfully obtains the semaphore, its priority is
raised to the ceiling priority.  When the task holding the task
completely releases the binary semaphore (i.e. not for a nested
release), the holder's priority is restored to the value it had
before any higher priority was put into effect.

The need to identify the highest priority task which
will attempt to obtain a particular semaphore can be a difficult
task in a large, complicated system.  Although the priority
ceiling algorithm is more efficient than the priority
inheritance algorithm with respect to the maximum number of task
priority changes which may occur while a task holds a particular
semaphore, the priority inheritance algorithm is more forgiving
in that it does not require this apriori information.

The RTEMS implementation of the priority ceiling
algorithm takes into account the scenario in which a task holds
more than one binary semaphore.  The holding task will execute
at the priority of the higher of the highest ceiling priority or
at the priority of the highest priority task blocked waiting for
any of the semaphores the task holds.  Only when the task
releases ALL of the binary semaphores it holds will its priority
be restored to the normal value.

@ifinfo
@node Building a Semaphore's Attribute Set, Building a SEMAPHORE_OBTAIN Option Set, Priority Ceiling, Semaphore Manager Background
@end ifinfo
@subsection Building a Semaphore's Attribute Set

In general, an attribute set is built by a bitwise OR
of the desired attribute components.  The following table lists
the set of valid semaphore attributes:

@itemize @bullet
@item FIFO - tasks wait by FIFO (default)
@item PRIORITY - tasks wait by priority
@item BINARY_SEMAPHORE - restrict values to 0 and 1 (default)
@item COUNTING_SEMAPHORE - no restriction on values
@item NO_INHERIT_PRIORITY - do not use priority inheritance (default)
@item INHERIT_PRIORITY - use priority inheritance
@item PRIORITY_CEILING - use priority ceiling
@item NO_PRIORITY_CEILING - do not use priority ceiling (default)
@item LOCAL - local task (default)
@item GLOBAL - global task
@end itemize

Attribute values are specifically designed to be
mutually exclusive, therefore bitwise OR and addition operations
are equivalent as long as each attribute appears exactly once in
the component list.  An attribute listed as a default is not
required to appear in the attribute list, although it is a good
programming practice to specify default attributes.  If all
defaults are desired, the attribute DEFAULT_ATTRIBUTES should be
specified on this call.

This example demonstrates the attribute_set parameter
needed to create a local semaphore with the task priority
waiting queue discipline.  The attribute_set parameter passed to
the semaphore_create directive could be either PRIORITY or LOCAL
| PRIORITY.  The attribute_set parameter can be set to PRIORITY
because LOCAL is the default for all created tasks.  If a
similar semaphore were to be known globally, then the
attribute_set parameter would be GLOBAL | PRIORITY.

@ifinfo
@node Building a SEMAPHORE_OBTAIN Option Set, Semaphore Manager Operations, Building a Semaphore's Attribute Set, Semaphore Manager Background
@end ifinfo
@subsection Building a SEMAPHORE_OBTAIN Option Set

In general, an option is built by a bitwise OR of the
desired option components.  The set of valid options for the
semaphore_obtain directive are listed in the following table:

@itemize @bullet
@item WAIT - task will wait for semaphore (default)
@item NO_WAIT - task should not wait
@end itemize

Option values are specifically designed to be
mutually exclusive, therefore bitwise OR and addition operations
are equivalent as long as each attribute appears exactly once in
the component list.  An option listed as a default is not
required to appear in the list, although it is a good
programming practice to specify default options.  If all
defaults are desired, the option DEFAULT_OPTIONS should be
specified on this call.

This example demonstrates the option parameter needed
to poll for a semaphore.  The option parameter passed to the
semaphore_obtain directive should be NO_WAIT.

@ifinfo
@node Semaphore Manager Operations, Creating a Semaphore, Building a SEMAPHORE_OBTAIN Option Set, Semaphore Manager
@end ifinfo
@section Operations
@ifinfo
@menu
* Creating a Semaphore::
* Obtaining Semaphore IDs::
* Acquiring a Semaphore::
* Releasing a Semaphore::
* Deleting a Semaphore::
@end menu
@end ifinfo

@ifinfo
@node Creating a Semaphore, Obtaining Semaphore IDs, Semaphore Manager Operations, Semaphore Manager Operations
@end ifinfo
@subsection Creating a Semaphore

The semaphore_create directive creates a binary or
counting semaphore with a user-specified name as well as an
initial count.  If a binary semaphore is created with a count of
zero (0) to indicate that it has been allocated, then the task
creating the semaphore is considered the current holder of the
semaphore.  At create time the method for ordering waiting tasks
in the semaphore's task wait queue (by FIFO or task priority) is
specified.  Additionally, the priority inheritance or priority
ceiling algorithm may be selected for local, binary semaphores
that use the priority task wait queue blocking discipline.  If
the priority ceiling algorithm is selected, then the highest
priority of any task which will attempt to obtain this semaphore
must be specified.  RTEMS allocates a Semaphore Control Block
(SMCB) from the SMCB free list.  This data structure is used by
RTEMS to manage the newly created semaphore.  Also, a unique
semaphore ID is generated and returned to the calling task.

@ifinfo
@node Obtaining Semaphore IDs, Acquiring a Semaphore, Creating a Semaphore, Semaphore Manager Operations
@end ifinfo
@subsection Obtaining Semaphore IDs

When a semaphore is created, RTEMS generates a unique
semaphore ID and assigns it to the created semaphore until it is
deleted.  The semaphore ID may be obtained by either of two
methods.  First, as the result of an invocation of the
semaphore_create directive, the semaphore ID is stored in a user
provided location.  Second, the semaphore ID may be obtained
later using the semaphore_ident directive.  The semaphore ID is
used by other semaphore manager directives to access this
semaphore.

@ifinfo
@node Acquiring a Semaphore, Releasing a Semaphore, Obtaining Semaphore IDs, Semaphore Manager Operations
@end ifinfo
@subsection Acquiring a Semaphore

The semaphore_obtain directive is used to acquire the
specified semaphore.  A simplified version of the
semaphore_obtain directive can be described as follows:

@example
if semaphore's count is greater than zero
   then decrement semaphore's count
   else wait for release of semaphore

return SUCCESSFUL
@end example

When the semaphore cannot be immediately acquired,
one of the following situations applies:

@itemize @bullet
@item By default, the calling task will wait forever to
acquire the semaphore.

@item Specifying NO_WAIT forces an immediate return with an
error status code.

@item Specifying a timeout limits the interval the task will
wait before returning with an error status code.
@end itemize

If the task waits to acquire the semaphore, then it
is placed in the semaphore's task wait queue in either FIFO or
task priority order.  If the task blocked waiting for a binary
semaphore using priority inheritance and the task's priority is
greater than that of the task currently holding the semaphore,
then the holding task will inherit the priority of the blocking
task.  All tasks waiting on a semaphore are returned an error
code when the semaphore is deleted.

When a task successfully obtains a semaphore using
priority ceiling and the priority ceiling for this semaphore is
greater than that of the holder, then the holder's priority will
be elevated.

@ifinfo
@node Releasing a Semaphore, Deleting a Semaphore, Acquiring a Semaphore, Semaphore Manager Operations
@end ifinfo
@subsection Releasing a Semaphore

The semaphore_release directive is used to release
the specified semaphore.  A simplified version of the
semaphore_release directive can be described as follows:

@example
if no tasks are waiting on this semaphore
   then increment semaphore's count
   else assign semaphore to a waiting task

return SUCCESSFUL
@end example

If this is the outermost release of a binary
semaphore that uses priority inheritance or priority ceiling and
the task does not currently hold any other binary semaphores,
then the task performing the semaphore_release will have its
priority restored to its normal value.

@ifinfo
@node Deleting a Semaphore, Semaphore Manager Directives, Releasing a Semaphore, Semaphore Manager Operations
@end ifinfo
@subsection Deleting a Semaphore

The semaphore_delete directive removes a semaphore
from the system and frees its control block.  A semaphore can be
deleted by any local task that knows the semaphore's ID.  As a
result of this directive, all tasks blocked waiting to acquire
the semaphore will be readied and returned a status code which
indicates that the semaphore was deleted.  Any subsequent
references to the semaphore's name and ID are invalid.

@ifinfo
@node Semaphore Manager Directives, SEMAPHORE_CREATE - Create a semaphore, Deleting a Semaphore, Semaphore Manager
@end ifinfo
@section Directives
@ifinfo
@menu
* SEMAPHORE_CREATE - Create a semaphore::
* SEMAPHORE_IDENT - Get ID of a semaphore::
* SEMAPHORE_DELETE - Delete a semaphore::
* SEMAPHORE_OBTAIN - Acquire a semaphore::
* SEMAPHORE_RELEASE - Release a semaphore::
@end menu
@end ifinfo

This section details the semaphore manager's
directives.  A subsection is dedicated to each of this manager's
directives and describes the calling sequence, related
constants, usage, and status codes.

@page
@ifinfo
@node SEMAPHORE_CREATE - Create a semaphore, SEMAPHORE_IDENT - Get ID of a semaphore, Semaphore Manager Directives, Semaphore Manager Directives
@end ifinfo
@subsection SEMAPHORE_CREATE - Create a semaphore

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_semaphore_create(
  rtems_name           name,
  rtems_unsigned32     count,
  rtems_attribute      attribute_set,
  rtems_task_priority  priority_ceiling,
  rtems_id            *id
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Semaphore_Create (
   Name          : in     RTEMS.Name;
   Count         : in     RTEMS.Unsigned32;
   Attribute_Set : in     RTEMS.Attribute;
   ID            :    out RTEMS.ID;
   Result        :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{SUCCESSFUL} - semaphore created successfully@*
@code{INVALID_NAME} - invalid task name@*
@code{TOO_MANY} - too many semaphores created@*
@code{NOT_DEFINED} - invalid attribute set@*
@code{INVALID_NUMBER} - invalid starting count for binary semaphore@*
@code{MP_NOT_CONFIGURED} - multiprocessing not configured@*
@code{TOO_MANY} - too many global objects

@subheading DESCRIPTION:

This directive creates a semaphore which resides on
the local node. The created 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 SMCB.  The RTEMS-assigned semaphore id is returned
in id.  This semaphore id is used with other semaphore related
directives to access the semaphore.

Specifying PRIORITY in attribute_set causes tasks
waiting for a semaphore to be serviced according to task
priority.  When FIFO is selected, tasks are serviced in First
In-First Out order.

@subheading NOTES:

This directive will not cause the calling task to be
preempted.

The priority inheritance and priority ceiling
algorithms are only supported for local, binary semaphores that
use the priority task wait queue blocking discipline.

The following semaphore attribute constants are
defined by RTEMS:

@itemize @bullet
@item FIFO - tasks wait by FIFO (default)
@item PRIORITY - tasks wait by priority
@item BINARY_SEMAPHORE - restrict values to 0 and 1 (default)
@item COUNTING_SEMAPHORE - no restriction on values
@item NO_INHERIT_PRIORITY - do not use priority inheritance (default)
@item INHERIT_PRIORITY - use priority inheritance
@item PRIORITY_CEILING - use priority ceiling
@item NO_PRIORITY_CEILING - do not use priority ceiling (default)
@item LOCAL - local task (default)
@item GLOBAL - global task
@end itemize



Semaphores should not be made global unless remote
tasks must interact with the created 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 id 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 maximum_global_objects field in
the Configuration Table.

@page
@ifinfo
@node SEMAPHORE_IDENT - Get ID of a semaphore, SEMAPHORE_DELETE - Delete a semaphore, SEMAPHORE_CREATE - Create a semaphore, Semaphore Manager Directives
@end ifinfo
@subsection SEMAPHORE_IDENT - Get ID of a semaphore

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_semaphore_ident(
  rtems_name        name,
  rtems_unsigned32  node,
  rtems_id         *id
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Semaphore_Ident (
   Name   : in     RTEMS.Name;
   Node   : in     RTEMS.Unsigned32;
   ID     :    out RTEMS.ID;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{SUCCESSFUL} - semaphore identified successfully@*
@code{INVALID_NAME} - semaphore name not found@*
@code{INVALID_NODE} - invalid node id

@subheading DESCRIPTION:

This directive obtains the semaphore id associated
with the semaphore name.  If the semaphore name is not unique,
then the semaphore id will match one of the semaphores with that
name.  However, this semaphore id is not guaranteed to
correspond to the desired semaphore.  The semaphore id is used
by other semaphore related directives to access the semaphore.

@subheading NOTES:

This directive will not cause the running task to be
preempted.

If node is SEARCH_ALL_NODES, all nodes are searched
with the local node being searched first.  All other nodes are
searched with the lowest numbered node searched first.

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.

@page
@ifinfo
@node SEMAPHORE_DELETE - Delete a semaphore, SEMAPHORE_OBTAIN - Acquire a semaphore, SEMAPHORE_IDENT - Get ID of a semaphore, Semaphore Manager Directives
@end ifinfo
@subsection SEMAPHORE_DELETE - Delete a semaphore

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_semaphore_delete(
  rtems_id id
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Semaphore_Delete (
   ID     : in     RTEMS.ID;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{SUCCESSFUL} -  semaphore deleted successfully@*
@code{INVALID_ID} - invalid semaphore id@*
@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote semaphore@*
@code{RESOURCE_IN_USE} - binary semaphore is in use

@subheading DESCRIPTION:

This directive deletes the semaphore specified by id.
All tasks blocked waiting to acquire the semaphore will be
readied and returned a status code which indicates that the
semaphore was deleted.  The SMCB for this semaphore is reclaimed
by RTEMS.

@subheading NOTES:

The calling task will be preempted if it is enabled
by the task's execution mode and a higher priority local task is
waiting on the deleted semaphore.  The calling task will NOT be
preempted if all of the tasks that are waiting on the semaphore
are remote tasks.

The calling task does not have to be the task that
created the semaphore.  Any local task that knows the semaphore
id can delete the semaphore.

When a global semaphore is deleted, the semaphore id
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 GLOBAL option.

Proxies, used to represent remote tasks, are
reclaimed when the semaphore is deleted.

@page
@ifinfo
@node SEMAPHORE_OBTAIN - Acquire a semaphore, SEMAPHORE_RELEASE - Release a semaphore, SEMAPHORE_DELETE - Delete a semaphore, Semaphore Manager Directives
@end ifinfo
@subsection SEMAPHORE_OBTAIN - Acquire a semaphore

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_semaphore_obtain(
  rtems_id         id,
  rtems_unsigned32 option_set,
  rtems_interval   timeout
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Semaphore_Obtain (
   ID         : in     RTEMS.ID;
   Option_Set : in     RTEMS.Option;
   Timeout    : in     RTEMS.Interval;
   Result     :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{SUCCESSFUL} - semaphore obtained successfully@*
@code{UNSATISFIED} - semaphore not available@*
@code{TIMEOUT} - timed out waiting for semaphore@*
@code{OBJECT_WAS_DELETED} - semaphore deleted while waiting@*
@code{INVALID_ID} - invalid semaphore id

@subheading DESCRIPTION:

This directive acquires the semaphore specified by
id.  The WAIT and NO_WAIT components of the options parameter
indicate whether the calling task wants to wait for the
semaphore to become available or return immediately if the
semaphore is not currently available.  With either WAIT or
NO_WAIT, if the current semaphore count is positive, then it is
decremented by one and the semaphore is successfully acquired by
returning immediately with a successful return code.

If the calling task chooses to return immediately and
the current semaphore count is zero or negative, then a 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 or negative, then it is
decremented by one and the calling task is placed on the
semaphore's wait queue and blocked.  If the semaphore was
created with the PRIORITY attribute, then the calling task is
inserted into the queue according to its priority.  However, if
the semaphore was created with the FIFO attribute, then the
calling task is placed at the rear of the wait queue.  If the
binary semaphore was created with the INHERIT_PRIORITY
attribute, then the priority of the task currently holding the
binary semaphore is guaranteed to be greater than or equal to
that of the blocking task.  If the binary semaphore was created
with the PRIORITY_CEILING 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 obtaining the semaphore is elevated to that of the ceiling.

The timeout parameter specifies the maximum interval
the calling task is willing to be blocked waiting for the
semaphore.  If it is set to NO_TIMEOUT, then the calling task
will wait forever.  If the semaphore is available or the NO_WAIT
option component is set, then timeout is ignored.

@subheading NOTES:
The following semaphore acquisition option constants
are defined by RTEMS:

@itemize @bullet
@item WAIT - task will wait for semaphore (default)
@item NO_WAIT - task should not wait
@end itemize

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

@page
@ifinfo
@node SEMAPHORE_RELEASE - Release a semaphore, Message Manager, SEMAPHORE_OBTAIN - Acquire a semaphore, Semaphore Manager Directives
@end ifinfo
@subsection SEMAPHORE_RELEASE - Release a semaphore

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_semaphore_release(
  rtems_id id
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Semaphore_Release (
   ID     : in     RTEMS.ID;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{SUCCESSFUL} - semaphore released successfully@*
@code{INVALID_ID} - invalid semaphore id@*
@code{NOT_OWNER_OF_RESOURCE} - calling task does not own semaphore

@subheading DESCRIPTION:

This directive releases the semaphore specified by
id.  The semaphore count is incremented by one.  If the count is
zero or negative, then the first task on this semaphore's wait
queue is removed and unblocked.  The unblocked task may preempt
the running task if the running task's preemption mode is
enabled and the unblocked task has a higher priority than the
running task.

@subheading NOTES:

The calling task may be preempted if it causes a
higher priority task to be made ready for execution.

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.

The outermost release of a local, binary, priority
inheritance or priority ceiling semaphore may result in the
calling task having its priority lowered.  This will occur if
the calling task holds no other binary semaphores and it has
inherited a higher priority.