Clk_ExtTS_Set()
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:
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.
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:
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.
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.