Clk_ExtTS_Get

Get Clock module’s timestamp from converted External timestamp.

Files

clk.h / Application’s source file

Called from

Clk_GetTS()

Prototype

CLK_TS_SEC  Clk_ExtTS_Get (void);

Arguments

None.

Returned Values

Current Clock module timestamp (in seconds, UTC+00).

Required Configuration

Required callback function that must be implemented in your application if CLK_CFG_EXT_EN is DEF_ENABLED in clk_cfg.h (see Module Configuration) in order for the clock/calendar to be maintained by an external clock/timestamp mechanism.

Notes / Warnings

Clock timestamp values must be returned via CLK_TS_SEC data type. If the External timestamp has more bits than the CLK_TS_SEC data type, Clk_ExtTS_Get() must truncate the External timestamp's higher order bits greater than the CLK_TS_SEC data type. If the External timestamp has less bits than the CLK_TS_SEC data type, Clk_ExtTS_Get() must pad the Clock timestamp's higher order bits with 0 bits.

External timestamp values must be returned from the reference of the Clock epoch start date/time. External timestamp should start on midnight of January 1st of its epoch start year. Returned Clock timestamp must be representable in Clock epoch. Thus equivalent date of the External timestamp must be greater than or equal to CLK_EPOCH_YR_START and less than CLK_EPOCH_YR_END.

If the External timestamp includes an (optional) external time zone, Clk_ExtTS_Get() must subtract the external time zone offset from the converted External timestamp.

The Clock timestamp is calculated by one of the following equations where:

Clock TS

Timestamp converted for Clock (in seconds, from UTC+00)

External TS

External timestamp to convert (in seconds)

Clock start year

Clock epoch start year (CLK_EPOCH_YR_START)

Clock end year

Clock epoch end year (CLK_EPOCH_YR_END)

External start year

External timestamp epoch start year

Leap day count

Number of leap days between Clock epoch start year and External epoch start year

Seconds per day

Number of seconds per day (86400)

External TZ

Time zone offset applied to External timestamp (in seconds, from UTC+00)

When External epoch start year is less than Clock epoch start year (CLK_EPOCH_YR_START):

Clock TS = External TS
         - [(((Clock start year - External start year) * 365)
         + leap day count) * seconds per day]
         - External TZ

Examples with a 32-bit External timestamp:

• Valid equivalent date to convert is after Clock epoch start year:

2010 Oct 8, 11:11:11 UTC-05:00
External TS (in seconds) = 1286536271
External start year      = 1970
Leap day count           = 7
External TZ (in seconds) = -18000
Clock TS (in seconds)    = 339869471
2010 Oct 8, 16:11:11 UTC

This example successfully converts an External timestamp into a representable Clock timestamp without underflowing.

• Invalid equivalent date to convert is before Clock epoch start year:

1984 Oct 8, 11:11:11 UTC-05:00
External TS (in seconds) = 466081871
External start year      = 1970
Clock start year         = 2000
Leap day count           = 7
External TZ (in seconds) = -18000
Clock TS (in seconds)    = -480584929

This example underflows to a negative Clock timestamp since the equivalent date to convert is incorrectly less than the Clock epoch start year (CLK_EPOCH_YR_START).

When External epoch start year is greater than Clock epoch start year (CLK_EPOCH_YR_START):

Clock TS = External TS
         + [(((External start year - Clock start year) * 365)
         + leap day count) * seconds per day]
         - External TZ

Examples with a 32-bit External timestamp:

• Valid equivalent date to convert is before Clock epoch end year:

2010 Oct 8, 11:11:11 UTC-05:00
External TS (in seconds) = 24232271
External start year      = 2010
Leap day count           = 3
External TZ (in seconds) = -18000
Clock TS (in seconds)    = 339869471
2010 Oct 8, 16:11:11 UTC-05:00

This example successfully converts an External timestamp into a representable Clock timestamp without overflowing.

• Invalid equivalent date to convert is after Clock epoch end year:

2140 Oct 8, 11:11:11 UTC-05:00
External TS (in seconds) = 4126677071
External start year      = 2010
Clock end year           = 2136
Leap day count           = 3
External TZ (in seconds) = -18000
Clock TS (in seconds)    = 4442314271

This example overflows the Clock timestamp (32-bit) CLK_TS_SEC data type with an equivalent date incorrectly greater than or equal to the Clock epoch end year (CLK_EPOCH_YR_END).

Example Template

CLK_TS_SEC  Clk_ExtTS_Get (void)
{
    CLK_TS_SEC  ts_sec;
 
    ts_sec = BSP_ClockGetTS();
    return (ts_sec);
}