From 023e1281e6c72fad18d84bbe05f82854d2adf31b Mon Sep 17 00:00:00 2001 From: "L.S. Cook" Date: Wed, 24 Feb 2016 10:53:28 -0800 Subject: doc: Edit microkernel_timers.rst with better ReST syntax to enhance readability. 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 --- doc/kernel/microkernel/microkernel_timers.rst | 102 +++++++++++++------------- 1 file changed, 52 insertions(+), 50 deletions(-) diff --git a/doc/kernel/microkernel/microkernel_timers.rst b/doc/kernel/microkernel/microkernel_timers.rst index 213503f18..75e199ea5 100644 --- a/doc/kernel/microkernel/microkernel_timers.rst +++ b/doc/kernel/microkernel/microkernel_timers.rst @@ -6,10 +6,10 @@ Timer Services Concepts ******** -A microkernel timer allows a task to determine whether or not a specified -time limit has been reached while the task is busy performing other work. -The timer uses the kernel's system clock to monitor the passage of time, -as measured in ticks. +A :dfn:`microkernel timer` allows a task to determine whether or not a +specified time limit has been reached while the task is busy performing +other work. The timer uses the kernel's system clock, measured in +ticks, to monitor the passage of time. Any number of microkernel timers can be defined in a microkernel system. 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 when it needs to monitor multiple time intervals simultaneously. -A timer is started by specifying a duration, a period, and an associated -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 -once the duration is reached and the semaphore is given. When the period -is non-zero the timer restarts automatically using a new duration 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 then re-expire every 20 ticks thereafter, -resulting in the semaphore being given 3 times after 50 ticks have elapsed. +A timer is started by specifying: + +* A :dfn:`duration` is the number of ticks the timer counts before it + expires for the first time. +* A :dfn:`period` is the number of ticks the timer counts before it expires + each time thereafter. +* The :dfn:`microkernel semaphore identifier` is what the timer gives each + time the semaphore expires. + +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:: - 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 - 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 + Care must be taken when specifying the duration of a microkernel timer. + 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 + 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 - 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 duration of N+1 ticks. This adjustment is not required when specifying - the period of a timer, which always corresponds to full tick intervals. + 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 duration of ``N+1`` ticks. This adjustment is not required when specifying + 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 -to its expiration. Cancelling a timer that has already expired does not -affect the state of the associated semaphore. Likewise, restarting a -timer that has already expired is equivalent to stopping the timer and -then starting it afresh. +A running microkernel timer can be cancelled or restarted by a task prior to +its expiration. Cancelling a timer that has already expired does not affect +the state of the associated semaphore. Likewise, restarting a timer that has +already expired is equivalent to stopping the timer and starting it afresh. -When a task no longer needs a timer it should free the timer. -This makes the timer available for reallocation. +When a task no longer needs a timer it should free the timer. This makes +the timer available for reallocation. Purpose ******* -Use a microkernel timer to determine whether or not a specified number -of system clock ticks have elapsed while the task is busy performing -other work. +Use a microkernel timer to determine whether or not a specified number of +system clock ticks have elapsed while the task is busy performing other work. .. note:: If a task has no other work to perform while waiting for time to pass @@ -68,8 +70,8 @@ other work. .. note:: The microkernel provides additional APIs that allow a task to monitor - the system clock, as well as the higher precision hardware clock, - without using a microkernel timer. + both the system clock and the higher-precision hardware clock, without + using a microkernel timer. Usage ***** @@ -77,18 +79,18 @@ Usage Configuring Microkernel Timers ============================== -Set the :option:`NUM_TIMER_PACKETS` configuration option -to specify the number of timer-related command packets available -in the application. This value should be equal to or greater than -the sum of the following quantities: +Set the :option:`NUM_TIMER_PACKETS` configuration option to specify the +number of timer-related command packets available in the application. This +value should be **equal to** or **greater than** the sum of the following +quantities: * The number of microkernel timers. * The number of tasks. .. note:: Unlike most other microkernel object types, microkernel timers are defined - as a group using a configuration option, rather than as individual - public objects in an MDEF or private objects in a source file. + as a group using a configuration option, rather than as individual public + objects in an MDEF or private objects in a source file. Example: Allocating a Microkernel Timer ======================================= @@ -103,10 +105,10 @@ This code allocates an unused timer. Example: Starting a One Shot Microkernel Timer ============================================== -This code uses a timer to limit the amount of time a task -spends gathering data by monitoring the status of a microkernel semaphore -that is set when the timer expires. Since the timer is started with -a period of zero, it stops automatically once it expires. +This code uses a timer to limit the amount of time a task spends on gathering +data. It works by monitoring the status of a microkernel semaphore that is set +when the timer expires. Since the timer is started with a period of zero, it +stops automatically once it expires. .. code-block:: c @@ -180,7 +182,7 @@ This code illustrates how an active timer can be stopped prematurely. 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. .. code-block:: c -- cgit v1.2.3