michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Edit microkernel_timers.rst with better ReST syntax to enhance readability.

Browse source 
Added ReST syntax dfns, added bold and lists.  Reworded a couple sentences
that could be stated more clearly.

Change-Id: I997b54e1dcbc44d683919008770dd90857a96e47
Signed-off-by: L.S. Cook <leonax.cook@intel.com>
This commit is contained in:
L.S. Cook 2016-02-24 10:53:28 -08:00 • committed by Gerrit Code Review
commit 023e1281e6
1 changed files with 51 additions and 49 deletions
Download patch file Download diff file Expand all files Collapse all files

100
doc/kernel/microkernel/microkernel_timers.rst
View file

@ -6,10 +6,10 @@ Timer Services
Concepts Concepts
******** ********
A microkernel timer allows a task to determine whether or not a specified A :dfn:`microkernel timer` allows a task to determine whether or not a
time limit has been reached while the task is busy performing other work. specified time limit has been reached while the task is busy performing
The timer uses the kernel's system clock to monitor the passage of time, other work. The timer uses the kernel's system clock, measured in
as measured in ticks. ticks, to monitor the passage of time.
Any number of microkernel timers can be defined in a microkernel system. Any number of microkernel timers can be defined in a microkernel system.
Each timer has a unique identifier, which allows it to be distinguished Each timer has a unique identifier, which allows it to be distinguished
@ -19,48 +19,50 @@ A task that wants to use a timer must first allocate an unused timer
from the set of microkernel timers. A task can allocate more than one timer from the set of microkernel timers. A task can allocate more than one timer
when it needs to monitor multiple time intervals simultaneously. when it needs to monitor multiple time intervals simultaneously.
A timer is started by specifying a duration, a period, and an associated A timer is started by specifying:
microkernel semaphore identifier. Duration is the number of ticks
the timer counts before it expires for the first time, and period is the
number of ticks the timer counts before it expires each time thereafter.
Each time the timer expires the timer gives the semaphore.
The semaphore's state can be examined by the task at any time
to allow the task to determine if a given time limit has been reached or not.
When the timer's period is set to zero the timer stops automatically * A :dfn:`duration` is the number of ticks the timer counts before it
once the duration is reached and the semaphore is given. When the period expires for the first time.
is non-zero the timer restarts automatically using a new duration equal * A :dfn:`period` is the number of ticks the timer counts before it expires
to its period; when this new duration has elapsed the timer gives the each time thereafter.
semaphore again and restarts. For example, a timer can be set to expire * The :dfn:`microkernel semaphore identifier` is what the timer gives each
after 5 ticks, and then re-expire every 20 ticks thereafter, time the semaphore expires.
resulting in the semaphore being given 3 times after 50 ticks have elapsed.
The semaphore's state can be examined by the task any time the task needs to
determine whether or not the given time limit has been reached.
When the timer's period is set to zero, the timer stops automatically
after reaching the duration and giving the semaphore. When the period is set to
any number of ticks other than zero, the timer restarts automatically with
a new duration that is equal to its period. When this new duration has elapsed,
the timer gives the semaphore again and restarts. For example, a timer can be
set to expire after 5 ticks, and to then re-expire every 20 ticks thereafter,
resulting in the semaphore being given 3 times after 45 ticks have elapsed.
.. note:: .. note::
Care must be taken when specifying the duration of a microkernel timer, Care must be taken when specifying the duration of a microkernel timer.
since the first tick measured by the timer after it is started will be 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 that expires after 1 tick will result
in the semaphore being given anywhere from a fraction of a millisecond in the semaphore being given 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
a timer doesn't expire for at least N ticks it is necessary to specify timer doesn't expire for at least ``N`` ticks, it is necessary to specify
a duration of N+1 ticks. This adjustment is not required when specifying a duration of ``N+1`` ticks. This adjustment is not required when specifying
the period of a timer, which always corresponds to full tick intervals. the period of a timer, which always corresponds to full-tick intervals.
A running microkernel timer can be cancelled or restarted by a task prior A running microkernel timer can be cancelled or restarted by a task prior to
to its expiration. Cancelling a timer that has already expired does not its expiration. Cancelling a timer that has already expired does not affect
affect the state of the associated semaphore. Likewise, restarting a the state of the associated semaphore. Likewise, restarting a timer that has
timer that has already expired is equivalent to stopping the timer and already expired is equivalent to stopping the timer and starting it afresh.
then starting it afresh.
When a task no longer needs a timer it should free the timer. When a task no longer needs a timer it should free the timer. This makes
This makes the timer available for reallocation. the timer available for reallocation.
Purpose Purpose
******* *******
Use a microkernel timer to determine whether or not a specified number Use a microkernel timer to determine whether or not a specified number of
of system clock ticks have elapsed while the task is busy performing system clock ticks have elapsed while the task is busy performing other work.
other work.
.. note:: .. note::
If a task has no other work to perform while waiting for time to pass If a task has no other work to perform while waiting for time to pass
@ -68,8 +70,8 @@ other work.
.. note:: .. note::
The microkernel provides additional APIs that allow a task to monitor The microkernel provides additional APIs that allow a task to monitor
the system clock, as well as the higher precision hardware clock, both the system clock and the higher-precision hardware clock, without
without using a microkernel timer. using a microkernel timer.
Usage Usage
***** *****
@ -77,18 +79,18 @@ Usage
Configuring Microkernel Timers Configuring Microkernel Timers
============================== ==============================
Set the :option:`NUM_TIMER_PACKETS` configuration option Set the :option:`NUM_TIMER_PACKETS` configuration option to specify the
to specify the number of timer-related command packets available number of timer-related command packets available in the application. This
in the application. This value should be equal to or greater than value should be **equal to** or **greater than** the sum of the following
the sum of the following quantities: quantities:
* The number of microkernel timers. * The number of microkernel timers.
* The number of tasks. * The number of tasks.
.. note:: .. note::
Unlike most other microkernel object types, microkernel timers are defined Unlike most other microkernel object types, microkernel timers are defined
as a group using a configuration option, rather than as individual as a group using a configuration option, rather than as individual public
public objects in an MDEF or private objects in a source file. objects in an MDEF or private objects in a source file.
Example: Allocating a Microkernel Timer Example: Allocating a Microkernel Timer
======================================= =======================================
@ -103,10 +105,10 @@ This code allocates an unused timer.
Example: Starting a One Shot Microkernel Timer Example: Starting a One Shot Microkernel Timer
============================================== ==============================================
This code uses a timer to limit the amount of time a task This code uses a timer to limit the amount of time a task spends on gathering
spends gathering data by monitoring the status of a microkernel semaphore data. It works by monitoring the status of a microkernel semaphore that is set
that is set when the timer expires. Since the timer is started with when the timer expires. Since the timer is started with a period of zero, it
a period of zero, it stops automatically once it expires. stops automatically once it expires.
.. code-block:: c .. code-block:: c
@ -180,7 +182,7 @@ This code illustrates how an active timer can be stopped prematurely.
Example: Freeing a Microkernel Timer Example: Freeing a Microkernel Timer
==================================== ====================================
This code allows a task to relinquish a previously allocated timer This code allows a task to relinquish a previously-allocated timer
so it can be used by other tasks. so it can be used by other tasks.
.. code-block:: c .. code-block:: c