[PATCH rtems-docs] c-user: Update references to rtems_task_wake_after

[Chris Johns]

On 28/6/2023 7:37 am, Kinsey Moore wrote:
> 
> On Tue, Jun 27, 2023 at 4:05 PM Sebastian Huber
> <sebastian.huber at embedded-brains.de <mailto:sebastian.huber at embedded-brains.de>>
> wrote:
> 
>     On 27.06.23 22:18, Kinsey Moore wrote:
>     > diff --git a/c-user/task/directives.rst b/c-user/task/directives.rst
>     > index c082b51..3334679 100644
>     > --- a/c-user/task/directives.rst
>     > +++ b/c-user/task/directives.rst
>     > @@ -1475,15 +1475,15 @@ The following constraints apply to this directive:
>     >       \clearpage
>     >   
>     >   .. index:: rtems_task_wake_after()
>     > -.. index:: delay a task for an interval
>     > -.. index:: wake up after an interval
>     > +.. index:: delay a task for a number of ticks
>     > +.. index:: wake up after a number of ticks
>     >   
>     >   .. _InterfaceRtemsTaskWakeAfter:
>     >   
>     >   rtems_task_wake_after()
>     >   -----------------------
>     >   
>     > -Wakes up after an interval in :term:`clock ticks <clock tick>` or yields the
>     > +Wakes up after a number of :term:`clock ticks <clock tick>` or yields the
>     >   processor.
>     >   
>     >   .. rubric:: CALLING SEQUENCE:
>     > @@ -1502,10 +1502,12 @@ processor.
>     >   
>     >   This directive blocks the calling task for the specified ``ticks`` of clock
>     >   ticks if the value is not equal to :c:macro:`RTEMS_YIELD_PROCESSOR`. 
>     When the
>     > -requested interval has elapsed, the task is made ready.  The clock tick
>     > +requested number of ticks has elapsed, the task is made ready.  The clock
>     tick
>     >   directives automatically updates the delay period.  The calling task may
>     give
>     >   up the processor and remain in the ready state by specifying a value of
>     > -:c:macro:`RTEMS_YIELD_PROCESSOR` in ``ticks``.
>     > +:c:macro:`RTEMS_YIELD_PROCESSOR` in ``ticks``.  Applications requiring
>     use of a
>     > +time base instead of system ticks should make use of ``nanosleep()`` or
>     > +``clock_nanosleep()``.
> 
>     What is a time base?
> 
> 
> A delay specified in some subunit of seconds instead of clock ticks.
> 
> 
>     nanosleep() has the same issues as rtems_task_wake_after(). If you want
>     to wait for fixed intervals, then you have to use clock_nanosleep() with
>     TIMER_ABSTIME and CLOCK_MONOTONIC.
> 
>     The wording with the interval is not really wrong. Only the clock
>     resolution is a bit coarse (clock ticks). I guess the real problem is
>     that if you want to implement a periodic task with
> 
>     while (1) {
>             f();
>             rtems_task_wake_after(period);
>     }
> 
>     then this doesn't work if the time between calls to
>     rtems_task_wake_after() varies within the range of clock ticks. This can
>     be fixed by using clock_nanosleep() with TIMER_ABSTIME and CLOCK_MONOTONIC.
> 
> 
> The issue with specifying "interval" is that "time interval" is a common phrase
> in general and a clock tick can vary depending on application configuration.
> While the use of "interval" isn't necessarily wrong, "time interval" is very
> misleading in this context and could easily be assumed. Would "clock tick
> interval" be reasonable for clarity as a way to distance the verbiage from "time
> interval"?

The key issue is the use of language such as:

  ticks

    This parameter is the interval in clock ticks to delay the
    task or RTEMS_YIELD_PROCESSOR to yield the processor.

The task may not be delayed by the interval in clock ticks. The interference of
this language is the task is delayed by the period of a clock tick multiplied by
the interval. The task is delayed an indeterminate period of time because the
period of time from the call to the next tick is considered a "tick interval"
when it is only part of a tick interval. Better wording maybe:

 ticks

    This parameter is a count of clock ticks to delay the
    task or RTEMS_YIELD_PROCESSOR to yield the processor.

This may seem apparent to some but it seems not to others and what we have
documented is taken at face value.

This came to light when testing RTEMS 5 and EPICS 7 when the EPICS
systemTickTest test was run. The issue tracking this is:

https://gitlab.com/nsf-noirlab/gemini/rtsw/epics-base/epics-base/-/issues/30

A contributing factor is the improved timestamps introduced in RTEMS 5.

We need to document the fact users need to +1 to the interval if their usage is
the task needs to sleep for a period no shorter then the internal, ie internal x
clock_tick_period.

The test code shows clock_nanosleep() does the right thing and determines if the
remaining period until then next tick is shorter than the requested period and
if not the sleep is extended to the next tick.

To observe how this gets confusing, RTEMS 4.x + EPICS 7 is using the classic API
for epicsThreadSleep:

https://github.com/epics-base/epics-base/blob/7.0/modules/libcom/src/osi/os/RTEMS-score/osdThread.c#L494

and RTEMS 5,6 + EPICS 7 is using POSIX which is:

https://github.com/epics-base/epics-base/blob/7.0/modules/libcom/src/osi/os/posix/osdThread.c#L841

The timing around this boundary condition has changed.

To make it a little more complicated EPICS 7 RTEMSposix uses the classic API for
the call epicsEventWaitWithTimeout and that is used in task loops such as [1]:

    for (epicsEventWaitWithTimeout(ClockTimePvt.loopEvent,
             ClockTimePvt.ClockTimeSyncInterval);
         ClockTimePvt.synchronize == CLOCKTIME_SYNC;
         epicsEventWaitWithTimeout(ClockTimePvt.loopEvent,
             ClockTimePvt.ClockTimeSyncInterval)) {

That call is the issue Andrew Johnson raised in the Gemini Issue #30 I linked above.

Chris

[1]
https://github.com/epics-base/epics-base/blob/7.0/modules/libcom/src/osi/osiClockTime.c