diff --git a/doc/kernel/nanokernel/nanokernel_timers.rst b/doc/kernel/nanokernel/nanokernel_timers.rst index acc1ac7e769..165df93bb81 100644 --- a/doc/kernel/nanokernel/nanokernel_timers.rst +++ b/doc/kernel/nanokernel/nanokernel_timers.rst @@ -6,57 +6,57 @@ Timer Services Concepts ******** -The nanokernel's timer object type uses the kernel's system clock to monitor -the passage of time, as measured in ticks. It is mainly intended for use +The nanokernel's :dfn:`timer` object type uses the kernel's system clock to +monitor the passage of time, as measured in ticks. It is mainly intended for use by fibers. -A nanokernel timer allows a fiber or task to determine if a specified time -limit has been reached while the thread itself is busy performing other work. -A thread can use more than one timer when it needs to monitor multiple time -intervals simultaneously. +A *nanokernel timer* allows a fiber or task to determine whether or not a +specified time limit has been reached while the thread itself is busy performing +other work. A thread can use more than one timer when it needs to monitor multiple +time intervals simultaneously. 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. -The user data structure must be at least 4 bytes long and aligned on a 4-byte -boundary, as the kernel reserves the first 32 bits of this area for its own use. -Any remaining bytes of this area can be used to hold data that is helpful -to the thread that uses the timer. +thread that uses it; this pointer is returned when the timer expires. The user +data structure must be at least 4 bytes long and aligned on a 4-byte boundary, +as the kernel reserves the first 32 bits of this area for its own use. Any +remaining bytes of this area can be used to hold data that is helpful to the +thread that uses the timer. 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 to that variable. A timer must be initialized with its user data structure 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. .. note:: 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 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 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. + a timer doesn't expire for at least ``N`` ticks it is necessary to specify + a duration of ``N+1`` ticks. 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. -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 -:c:macro:`NULL` (for a non-blocking test) or waits for the timer to expire +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 +:c:macro:`NULL` (for a non-blocking test), or it waits for the timer to expire (for a blocking test). .. note:: 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 - waiting thread wakes up when the timer expires and the second thread - continues waiting. + timer at any given time. If a second thread starts waiting, only the first + waiting thread wakes up when the timer expires. The second thread continues + 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 - a microkernel application a task that waits on a nanokernel timer remains - the current task, which prevents other tasks of equal or lower priority + a microkernel application, a task that waits on a nanokernel timer remains + the *current task* and prevents other tasks of equal or lower priority from doing useful work. A nanokernel timer can be cancelled after it has been started. Cancelling @@ -78,7 +78,7 @@ other work. .. note:: 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. .. note:: @@ -152,11 +152,11 @@ This code illustrates how an active nanokernel timer can be stopped prematurely. APIs **** -The following APIs for a nanokernel timer are provided -by :file:`nanokernel.h`: +APIs for a nanokernel timer provided by :file:`nanokernel.h` +============================================================ :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_isr_timer_start()`, :cpp:func:`nano_timer_start()`