Set External timestamp.
Files
clk.h / Application’s source file
Called from
Clk_SetTS()
Prototype
Arguments
ts_sec
External timestamp value to set (in seconds, UTC+00).
Returned Values
DEF_OK, if External timestamp succesfully set;
DEF_FAIL, otherwise.
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 section 3-1-1) in order for the clock/calendar to be maintained by an external clock/timestamp mechanism.
Notes / Warnings
External timestamp values are converted from Clock timestamp’s CLK_TS_SEC data type. If the External timestamp has more bits than the CLK_TS_SEC data type, Clk_ExtTS_Set() must pad the External timestamp’s higher order bits with 0 bits. If the External timestamp has less bits than the CLK_TS_SEC data type, Clk_ExtTS_Set() must truncate the Clock timestamp’s higher order bits greater than the External timestamp.
External timestamp values must be converted from the reference of the Clock epoch start date/time. External timestamp should start on midnight of January 1st of its epoch start year. Converted External timestamp must be representable in External epoch. Thus equivalent date of the External timestamp must be greater than or equal to the External epoch start year and less than the External epoch end year.
If the External timestamp includes an (optional) external time zone, Clk_ExtTS_Set() must add the external time zone offset to the converted External timestamp.
The External timestamp is calculated by one of the following equations where:
Clock TS
Clock timestamp (in seconds, from UTC+00)
External TS
Converted External timestamp (in seconds)
Clock start year
Clock epoch start year (CLK_EPOCH_YR_START)
External start year
External timestamp epoch start year
External end year
External timestamp epoch end 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):
External TS = Clock 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 before External epoch end year:
2010 Oct 8, 16:11:11 UTC
Clock TS (in seconds) = 339869471
External start year = 1970
Leap day count = 7
External TZ (in seconds) = -18000
External TS (in seconds) = 1286536271
2010 Oct 8, 11: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 External epoch end year:
2120 Oct 8, 11:11:11 UTC
Clock TS (in seconds) = 3811144271
External start year = 1970
External end year = 2106
Leap day count = 7
External TZ (in seconds) = -18000
External TS (in seconds) = 4757811071
This example overflows the External (32-bit) timestamp with an equivalent date incorrectly greater than or equal to the External epoch end year.
When External epoch start year is greater than Clock epoch start year (CLK_EPOCH_YR_START):
External TS = Clock 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 after External epoch start year:
2010 Oct 8, 16:11:11 UTC
Clock TS (in seconds) = 339869471
External start year = 2010
Leap day count = 3
External TZ (in seconds) = -18000
External TS (in seconds) = 24232271
2010 Oct 8, 11:11:11 UTC-05:00
This example successfully converts an External timestamp into a representable Clock timestamp without underflowing.
- Invalid equivalent date to convert is before External epoch start year:
2005 Oct 8, 11:11:11 UTC
Clock TS (in seconds) = 182085071
External start year = 2010
Leap day count = 3
External TZ (in seconds) = -18000
External TS (in seconds) = -133552129
This example underflows to a negative External timestamp since the equivalent date to convert is incorrectly less than the External epoch start year.