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

2023-06-27 Thread Sebastian Huber 



On 27.06.23 23:37, Kinsey Moore wrote:

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


What about:

Applications requiring use of a clock (CLOCK_REALTIME or 
CLOCK_MONOTONIC) instead of clock ticks should make use of the ...


--
embedded brains GmbH
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.hu...@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/
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

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

2023-06-27 Thread Sebastian Huber 

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
mailto:sebastian.hu...@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 ` or 
yields the
 > +Wakes up after a number of :term:`clock ticks ` 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:

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

2023-06-27 Thread Chris Johns 
On 28/6/2023 7:37 am, Kinsey Moore wrote:
> 
> On Tue, Jun 27, 2023 at 4:05 PM Sebastian Huber
>  >
> 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 ` or 
> yields the
> > +Wakes up after a number of :term:`clock ticks ` 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:

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

2023-06-27 Thread Kinsey Moore 
On Tue, Jun 27, 2023 at 4:05 PM Sebastian Huber <
sebastian.hu...@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 ` or
> yields the
> > +Wakes up after a number of :term:`clock ticks ` 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"?


> >
> >   .. rubric:: RETURN VALUES:
> >
>
> Could you please update
>
> https://git.rtems.org/rtems-central/tree/spec/rtems/task/if/wake-after.yml
>
> since this will keep also the Doxygen up to date.
>
> For clock_nanosleep() references, use ${/c/if/clock-nanosleep:/name}.
>

Will do.

Kinsey
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

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

2023-06-27 Thread Sebastian Huber 

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 ` or yields the

+Wakes up after a number of :term:`clock ticks ` 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?

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.


  
  .. rubric:: RETURN VALUES:
  


Could you please update

https://git.rtems.org/rtems-central/tree/spec/rtems/task/if/wake-after.yml

since this will keep also the Doxygen up to date.

For clock_nanosleep() references, use ${/c/if/clock-nanosleep:/name}.

--
embedded brains GmbH
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.hu...@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/
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

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

2023-06-27 Thread Kinsey Moore 
rtems_task_wake_after takes a parameter in terms of ticks and not any
time base. This updates documentation to reflect that and refers any
applications needing a time base to nanosleep or clock_nanosleep.

Closes #4772
---
 c-user/scheduling-concepts/background.rst |  6 +++---
 c-user/task/directives.rst| 12 +++-
 c-user/task/operations.rst|  9 ++---
 3 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/c-user/scheduling-concepts/background.rst 
b/c-user/scheduling-concepts/background.rst
index 1fe7089..00eb8f0 100644
--- a/c-user/scheduling-concepts/background.rst
+++ b/c-user/scheduling-concepts/background.rst
@@ -160,7 +160,7 @@ Manual Round-Robin
 
 The final mechanism for altering the RTEMS scheduling algorithm is called
 manual round-robin.  Manual round-robin is invoked by using
-the ``rtems_task_wake_after`` directive with a time interval of
+the ``rtems_task_wake_after`` directive with a ticks parameter of
 ``RTEMS_YIELD_PROCESSOR``.  This allows a task to give up the processor and be
 immediately returned to the ready chain at the end of its priority group.  If
 no other tasks of the same priority are ready to run, then the task does not
@@ -243,7 +243,7 @@ of the following conditions:
   option and the requested semaphore is unavailable.
 
 - The running task issues a ``rtems_task_wake_after`` directive which blocks
-  the task for the given time interval.  If the time interval specified is
+  the task for the given number of ticks.  If the number of ticks specified is
   zero, the task yields the processor and remains in the ready state.
 
 - The running task issues a ``rtems_task_wake_when`` directive which blocks the
@@ -280,7 +280,7 @@ conditions:
 - A running task issues a ``rtems_semaphore_release`` directive which releases
   the semaphore on which the blocked task is waiting.
 
-- A timeout interval expires for a task which was blocked by a call to the
+- A tick interval expires for a task which was blocked by a call to the
   ``rtems_task_wake_after`` directive.
 
 - A timeout period expires for a task which blocked by a call to the
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 ` or yields the
+Wakes up after a number of :term:`clock ticks ` 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()``.
 
 .. rubric:: RETURN VALUES:
 
diff --git a/c-user/task/operations.rst b/c-user/task/operations.rst
index 6308d7b..9a55b6c 100644
--- a/c-user/task/operations.rst
+++ b/c-user/task/operations.rst
@@ -75,9 +75,9 @@ Delaying the Currently Executing Task
 -
 
 The ``rtems_task_wake_after`` directive creates a sleep timer which allows a
-task to go to sleep for a specified interval.  The task is blocked until the
-delay interval has elapsed, at which time the task is unblocked.  A task
-calling the ``rtems_task_wake_after`` directive with a delay interval of
+task to go to sleep for a specified number of ticks.  The task is blocked until
+the number of ticks has elapsed, at which time the task is unblocked.  A task
+calling the ``rtems_task_wake_after`` directive with a delay of
 ``RTEMS_YIELD_PROCESSOR`` ticks will yield the processor to any other ready
 task of equal or greater priority and remain ready to execute.
 
@@ -86,6 +86,9 @@ task to go to sleep until a specified date and time.  The 
calling task is
 blocked until the specified date and time has occurred, at which time the task
 is unblocked.
 
+Applications requiring intervals in a time base should use ``nanosleep()`` or
+``clock_nanosleep()``.
+
 Changing Task Priority
 --
 
-- 
2.30.2

___
devel mailing list