michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Edit nanokernel_timers for proper ReST syntax, grammar, etc.

Browse source 
Minor edits to clarify wording, readability of rendered documentation

Change-Id: I4144cfb8e191234d5fb3b6aa0fc3324b85cd286a
Signed-off-by: L.S. Cook <leonax.cook@intel.com>
This commit is contained in:
L.S. Cook 2016-03-16 11:57:42 -07:00 • committed by Gerrit Code Review
commit a1b9254697
1 changed files with 28 additions and 28 deletions
Download patch file Download diff file Expand all files Collapse all files

56
doc/kernel/nanokernel/nanokernel_timers.rst
View file

@ -6,57 +6,57 @@ Timer Services
Concepts Concepts
******** ********
The nanokernel's timer object type uses the kernel's system clock to monitor The nanokernel's :dfn:`timer` object type uses the kernel's system clock to
the passage of time, as measured in ticks. It is mainly intended for use monitor the passage of time, as measured in ticks. It is mainly intended for use
by fibers. by fibers.
A nanokernel timer allows a fiber or task to determine if a specified time A *nanokernel timer* allows a fiber or task to determine whether or not a
limit has been reached while the thread itself is busy performing other work. specified time limit has been reached while the thread itself is busy performing
A thread can use more than one timer when it needs to monitor multiple time other work. A thread can use more than one timer when it needs to monitor multiple
intervals simultaneously. time intervals simultaneously.
A nanokernel timer points to a *user data structure* that is supplied by the A nanokernel timer points to a *user data structure* that is supplied by the
thread that uses it; this pointer is returned when the timer expires. thread that uses it; this pointer is returned when the timer expires. The user
The user data structure must be at least 4 bytes long and aligned on a 4-byte data structure must be at least 4 bytes long and aligned on a 4-byte boundary,
boundary, as the kernel reserves the first 32 bits of this area for its own use. as the kernel reserves the first 32 bits of this area for its own use. Any
Any remaining bytes of this area can be used to hold data that is helpful remaining bytes of this area can be used to hold data that is helpful to the
to the thread that uses the timer. thread that uses the timer.
Any number of nanokernel timers can be defined. Each timer is a distinct Any number of nanokernel timers can be defined. Each timer is a distinct
variable of type :cpp:type:`struct nano_timer`, and is referenced using a pointer variable of type :cpp:type:`struct nano_timer`, and is referenced using a pointer
to that variable. A timer must be initialized with its user data structure to that variable. A timer must be initialized with its user data structure
before it can be used. before it can be used.
A nanokernel timer is started by specifying a duration, which is the number A nanokernel timer is started by specifying a *duration*, which is the number
of ticks the timer counts before it expires. of ticks the timer counts before it expires.
.. note:: .. note::
Care must be taken when specifying the duration of a nanokernel timer, Care must be taken when specifying the duration of a nanokernel timer,
since the first tick measured by the timer after it is started will be since the first tick measured by the timer after it is started will be
less than a full tick interval. For example, when the system clock period less than a full tick interval. For example, when the system clock period
is 10 milliseconds starting a timer than expires after 1 tick will result is 10 milliseconds, starting a timer than expires after 1 tick will result
in the timer expiring anywhere from a fraction of a millisecond in the timer expiring anywhere from a fraction of a millisecond
later to just slightly less than 10 milliseconds later. To ensure that later to just slightly less than 10 milliseconds later. To ensure that
a timer doesn't expire for at least N ticks it is necessary to specify a timer doesn't expire for at least ``N`` ticks it is necessary to specify
a duration of N+1 ticks. a duration of ``N+1`` ticks.
Once started, a nanokernel timer can be tested in either a non-blocking or Once started, a nanokernel timer can be tested in either a non-blocking or
blocking manner to allow a thread to determine if the timer has expired. blocking manner to allow a thread to determine if the timer has expired.
If the timer has expired the kernel returns the pointer to the user data If the timer has expired, the kernel returns the pointer to the user data
structure. If the timer has not expired the kernel either returns structure. If the timer has not expired, the kernel either returns
:c:macro:`NULL` (for a non-blocking test) or waits for the timer to expire :c:macro:`NULL` (for a non-blocking test), or it waits for the timer to expire
(for a blocking test). (for a blocking test).
.. note:: .. note::
The nanokernel does not allow more than one thread to wait on a nanokernel The nanokernel does not allow more than one thread to wait on a nanokernel
timer at any given time. If a second thread starts waiting only the first timer at any given time. If a second thread starts waiting, only the first
waiting thread wakes up when the timer expires and the second thread waiting thread wakes up when the timer expires. The second thread continues
continues waiting. waiting.
A task that waits on a nanokernel timer does a busy wait. This is A task that waits on a nanokernel timer does a ``busy wait``. This is
not an issue for a nanokernel application's background task; however, in not an issue for a nanokernel application's background task; however, in
a microkernel application a task that waits on a nanokernel timer remains a microkernel application, a task that waits on a nanokernel timer remains
the current task, which prevents other tasks of equal or lower priority the *current task* and prevents other tasks of equal or lower priority
from doing useful work. from doing useful work.
A nanokernel timer can be cancelled after it has been started. Cancelling A nanokernel timer can be cancelled after it has been started. Cancelling
@ -78,7 +78,7 @@ other work.
.. note:: .. note::
If a fiber or task has no other work to perform while waiting If a fiber or task has no other work to perform while waiting
for time to pass it can simply call :cpp:func:`fiber_sleep()` for time to pass, it can simply call :cpp:func:`fiber_sleep()`
or :cpp:func:`task_sleep()`, respectively. or :cpp:func:`task_sleep()`, respectively.
.. note:: .. note::
@ -152,11 +152,11 @@ This code illustrates how an active nanokernel timer can be stopped prematurely.
APIs APIs
**** ****
The following APIs for a nanokernel timer are provided APIs for a nanokernel timer provided by :file:`nanokernel.h`
by :file:`nanokernel.h`: ============================================================
:cpp:func:`nano_timer_init()` :cpp:func:`nano_timer_init()`
Initializes a timer. Initialize a timer.
:cpp:func:`nano_task_timer_start()`, :cpp:func:`nano_fiber_timer_start()`, :cpp:func:`nano_task_timer_start()`, :cpp:func:`nano_fiber_timer_start()`,
:cpp:func:`nano_isr_timer_start()`, :cpp:func:`nano_timer_start()` :cpp:func:`nano_isr_timer_start()`, :cpp:func:`nano_timer_start()`