1 files changed, 105 insertions, 0 deletions
diff --git a/c-user/semaphore/operations.rst b/c-user/semaphore/operations.rst
new file mode 100644
index 0000000..19c4be2
--- /dev/null
+++ b/c-user/semaphore/operations.rst
@@ -0,0 +1,105 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Operations
+==========
+
+.. _Creating a Semaphore:
+
+Creating a Semaphore
+--------------------
+
+The ``rtems_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.
+
+.. _Obtaining Semaphore IDs:
+
+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 ``rtems_semaphore_create`` directive, the semaphore ID is stored in a user
+provided location.  Second, the semaphore ID may be obtained later using the
+``rtems_semaphore_ident`` directive.  The semaphore ID is used by other
+semaphore manager directives to access this semaphore.
+
+.. _Acquiring a Semaphore:
+
+Acquiring a Semaphore
+---------------------
+
+The ``rtems_semaphore_obtain`` directive is used to acquire the
+specified semaphore.  A simplified version of the ``rtems_semaphore_obtain``
+directive can be described as follows:
+
+    If the semaphore's count is greater than zero then decrement the
+    semaphore's count else wait for release of semaphore then return
+    SUCCESSFUL.
+
+When the semaphore cannot be immediately acquired, one of the following
+situations applies:
+
+- By default, the calling task will wait forever to acquire the semaphore.
+
+- Specifying ``RTEMS_NO_WAIT`` forces an immediate return with an error status
+  code.
+
+- Specifying a timeout limits the interval the task will wait before returning
+  with an error status code.
+
+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.
+
+.. _Releasing a Semaphore:
+
+Releasing a Semaphore
+---------------------
+
+The ``rtems_semaphore_release`` directive is used to release the specified
+semaphore.  A simplified version of the ``rtems_semaphore_release`` directive
+can be described as follows:
+
+    If there are no tasks are waiting on this semaphore then increment the
+    semaphore's count else assign semaphore to a waiting task and return
+    SUCCESSFUL.
+
+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 ``rtems_semaphore_release``
+will have its priority restored to its normal value.
+
+.. _Deleting a Semaphore:
+
+Deleting a Semaphore
+--------------------
+
+The ``rtems_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.