Should we document a time zone for the RTEMS epoch?

[Chris Johns]

On 11/2/21 7:25 am, Gedare Bloom wrote:
> On Wed, Feb 10, 2021 at 9:56 AM Joel Sherrill <joel at rtems.org
> <mailto:joel at rtems.org>> wrote:
>     On Wed, Feb 10, 2021, 10:53 AM Sebastian Huber
>     <sebastian.huber at embedded-brains.de
>     <mailto:sebastian.huber at embedded-brains.de>> wrote:
>         On 10/02/2021 17:47, Joel Sherrill wrote:
>         > On Wed, Feb 10, 2021, 10:30 AM Sebastian Huber
>         > <sebastian.huber at embedded-brains.de
>         <mailto:sebastian.huber at embedded-brains.de>
>         > <mailto:sebastian.huber at embedded-brains.de
>         <mailto:sebastian.huber at embedded-brains.de>>> wrote:
>         >
>         >     On 10/02/2021 07:53, Sebastian Huber wrote:
>         >
>         >     > Hello,
>         >     >
>         >     > I try to update the clock manager documentation and noticed that
>         >     there
>         >     > is no time zone specified for the RTEMS epoch. In the timecounter
>         >     > initialization we use:
>         >     >
>         >     > static struct timehands th0 = {
>         >     > [...]
>         >     > #ifdef __rtems__
>         >     >     .th_bintime = { .sec = TOD_SECONDS_1970_THROUGH_1988 },
>         >     >     .th_microtime = { TOD_SECONDS_1970_THROUGH_1988, 0 },
>         >     >     .th_nanotime = { TOD_SECONDS_1970_THROUGH_1988, 0 },
>         >     >     .th_boottime = { .sec = TOD_SECONDS_1970_THROUGH_1988 - 1 },
>         >     > #endif /* __rtems__ */
>         >     >
>         >     > [...]
>         >     >
>         >     > };
>         >     >
>         >     > Since Unix epoch is 1970-01-01T00:00:00Z, this basically defines
>         >     that
>         >     > the RTEMS epoch is 1988-01-01T00:00:00Z. Should this be documented?
>         >     > The current implementation also implies that the time reported by
>         >     > RTEMS is in UTC (modulo leap seconds).
>         >
>         >     I tried to document the clocks provided by RTEMS, see tail of
>         >     (glossary.rst):
>         >
>         >     https://lists.rtems.org/pipermail/devel/2021-February/064451.html
>         <https://lists.rtems.org/pipermail/devel/2021-February/064451.html>
>         >     <https://lists.rtems.org/pipermail/devel/2021-February/064451.html
>         <https://lists.rtems.org/pipermail/devel/2021-February/064451.html>>
>         >
>         >
>         > Is it sufficient to reference the epoch entry in various clock get
>         > time method pages?
>         The relevant epoch and clock is now referenced in the directives.
>         >
>         > And should there be discussion somewhere about TZ environment variable
>         > and the methods in newlib which account for that.
>         I think a time zone is simply not accounted for in the RTEMS Classic
>         API. With the setting above I guess the time zone is fixed to UTC.
> 
> 
>     By default clock_gettime is also UTC. You have to go through the C Library
>     time methods to get timezones
> 
> This is an interesting topic. I would wager to guess that most users implicitly
> assumed their own timezone/time basis (and likely didn't care, as long it was
> consistent).

In my PTP testing I set the global TZ environment variable to AEST and date etc
all worked nicely.

Chris