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

Sebastian Huber sebastian.huber at embedded-brains.de
Wed Jun 28 05:50:30 UTC 2023 

On 28.06.23 01:07, Chris Johns wrote:
> 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:

Maybe this issue should be explained in the NOTES section.

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

This version is a bit more clear to me.

> 
> 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.

Yes, this should be documented. Just changing interval to ticks could be 
still confusing.

> 
> 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.

Maybe this could be added also to the NOTES section.

> 
> 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

-- 
embedded brains GmbH
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.huber at embedded-brains.de
phone: +49-89-18 94 741 - 16
fax:   +49-89-18 94 741 - 08

Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/

More information about the devel mailing list