Clk_ExtTS_Set

Set External timestamp.

Files

clk.h / Application’s source file

Called from

Clk_SetTS()

Prototype

CPU_BOOLEAN  Clk_ExtTS_Set (CLK_TS_SEC  ts_sec);

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 Module Configuration) 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.

Example Template

CPU_BOOLEAN  Clk_ExtTS_Set (CLK_TS_SEC  ts_sec)
{
    BSP_ClockSetTS(ts_sec);
    return (DEF_OK);
}