michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Edit nanokernel_synchronization section

Browse source 
Fix for imperative API descriptions, note needs work (see comment).

Change-Id: I300ff03ee5c6b6cb50cf2b1614f22940a0b10213
Signed-off-by: L.S. Cook <leonax.cook@intel.com>
This commit is contained in:
L.S. Cook 2016-03-18 06:59:04 -07:00 • committed by Gerrit Code Review
commit fb4b8d2933
1 changed files with 19 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

38
doc/kernel/nanokernel/nanokernel_synchronization.rst
View file

@ -3,7 +3,7 @@
Synchronization Services
########################
This section describes the synchronization services provided by the nanokernel.
This section describes synchronization services provided by the nanokernel.
Currently, only a single service is provided.
.. _nanokernel_semaphores:
@ -14,8 +14,8 @@ Nanokernel Semaphores
Concepts
========
The nanokernel's semaphore object type is an implementation of a traditional
counting semaphore. It is mainly intended for use by fibers.
The nanokernel's :dfn:`semaphore` object type is an implementation of a
traditional counting semaphore. It is mainly intended for use by fibers.
Any number of nanokernel semaphores can be defined. Each semaphore is a
distinct variable of type :cpp:type:`struct nano_sem`, and is referenced
@ -25,32 +25,32 @@ it can be used.
A nanokernel semaphore's count is set to zero when the semaphore is initialized.
This count is incremented each time the semaphore is given, and is decremented
each time the semaphore is taken. However, a semaphore cannot be taken if it is
unavailable (i.e. has a count of zero).
unavailable; that is, when it has a count of zero.
A nanokernel semaphore may be given by any context type (i.e. ISR, fiber,
or task).
A nanokernel semaphore may be **given** by any context type: ISRs, fibers,
or tasks.
A nanokernel semaphore may be taken in a non-blocking manner by any
A nanokernel semaphore may be **taken in a non-blocking manner** by any
context type; a special return code indicates if the semaphore is unavailable.
A semaphore can also be taken in a blocking manner by a fiber or task;
if the semaphore is unavailable the thread waits for it to be given.
A semaphore can also be **taken in a blocking manner** by a fiber or task;
if the semaphore is unavailable, the thread waits for it to be given.
Any number of threads may wait on an unavailable nanokernel semaphore
simultaneously. When the semaphore is signalled it is given to the fiber
that has waited longest, or to a waiting task if no fiber is waiting.
simultaneously. When the semaphore is signaled, it is given to the fiber
that has waited longest, or to a waiting task when no fiber is waiting.
.. note::
A task that waits on an unavailable nanokernel FIFO semaphore a busy wait.
A task that waits on an unavailable nanokernel FIFO semaphore busy-waits.
This is not an issue for a nanokernel application's background task;
however, in a microkernel application a task that waits on a nanokernel
semaphore remains the current task. In contrast, a microkernel task that
waits on a microkernel synchronization object ceases to be the current task,
allowing other tasks of equal or lower priority to do useful work.
If multiple tasks in a microkernel application wait on the same nanokernel
semaphore, higher priority tasks are given the semaphore in preference to
lower priority tasks. However, the order in which equal priority tasks
are given the semaphore is unpredictable.
When multiple tasks in a microkernel application are waiting on the same nanokernel
semaphore, higher priority tasks are given the semaphore in preference to
lower priority tasks. However, the order in which equal priority tasks are given
the semaphore is unpredictable.
Purpose
=======
@ -58,8 +58,8 @@ Purpose
Use a nanokernel semaphore to control access to a set of resources by multiple
fibers.
Use a nanokernel semaphore to synchronize processing between a producing task,
fiber, or ISR and one or more consuming fibers.
Use a nanokernel semaphore to synchronize processing between a producing task and
fiber, or among an ISR and one or more consuming fibers.
Usage
=====
@ -119,7 +119,7 @@ The following APIs for a nanokernel semaphore are provided
by :file:`nanokernel.h`:
:cpp:func:`nano_sem_init()`
Initializes a semaphore.
Initialize a semaphore.
:cpp:func:`nano_task_sem_give()`, :cpp:func:`nano_fiber_sem_give()`,
:cpp:func:`nano_isr_sem_give()`, :cpp:func:`nano_sem_give()`