Time and clock RTS Functions

The compiler RTS library supports two low-level time-related standard C functions:

• time_t time(time_t *timer);
• clock_t clock(void);

time() gives wall-clock time. clock() returns the number of clock cycles since the program began executing; it has nothing to do with wall-clock time.

The default implementation of these functions require that the program be run under CCS, or a similar tool which supports the CIO System Call Protocol. If CIO is not available, and you need to use one of these functions, you must provide your own definition of the function.

Function time()

The time() function gives real-world time, in terms of seconds since an epoch.

For many embedded systems, there is no internal real-world clock, so a program needs to discover the time from some external source. When running under CCS, the default time function uses the CIO System Call Protocol to communicate with CCS, which provides the real world time.

When not running under CCS, the program needs to find some other source from which it can discover time. In order to do that, a new implementation of time must be provided. If the program is running under an operating system, that operating system should provide an implementation of time(); otherwise, the user must provide one.

Consider an embedded processor as similar to a wristwatch. Perhaps the wristwatch maintains the time internally, but during initial power-on, the time is not reliable, and must be set by some external source.

epoch

The function time() returns the number of seconds since an "epoch." On POSIX systems, the epoch is defined as the number of seconds since midnight UTC January 1, 1970

However, the C standard does not require any particular epoch, and the default TI version of time() uses a different epoch: midnight UTC-6 Jan 1, 1900. This causes problems for people porting code using raw time_t values.

As of approximately 2015Q2, there are two distinct implementations of the time functions in the RTS library, the legacy support with 32-bit time_t and TI epoch, and the new support with 64-bit time_t and POSIX epoch. To use either mode, you must include time.h. By default, time_t is the legacy 32-bit time_t with TI epoch, and an additional type __time64_t is defined. Alternately, the user may define the macro __TI_TIME_USES_64 on the command line for all modules which call any time function, in which case time_t is a typedef for __type64_t.

Notable differences between __time32_t and __time64_t:

• __time32_t epoch is Jan 1, 1900 CST-0600
• __time64_t epoch is Jan 1, 1970 UTC-0000
• __time32_t will only reach to Thu Feb 7 06:28:14 2036
• __time64_t will reach to the year 292277026596
• __time32_t is unsigned, so it cannot represent dates before the epoch
• __time64_t is signed, so it can represent dates before the epoch

Function clock()

clock() returns the number of clock cycles since the program began executing.

This information might be available in a register on the device itself, but this varies from platform to platform, so the compiler doesn't provide a standard function to do it. Instead, the compiler RTS provides an implementation that uses the CIO System Call Protocol to communicate with CCS, which will figure out how to compute the right value.

When CCS is not available, the user must provide an implementation of clock which can discover the information from the appropriate location.