C API — Details


#include <cyg/io/wallclock.h>

cyg_uint32 cyg_wallclock_get_current_time( void );

void cyg_wallclock_set_current_time( cyg_uint32 time_stamp );

Cyg_ErrNo cyg_wallclock_get_time_timespec( struct timespec *tp );

Cyg_ErrNo cyg_wallclock_set_time_timespec( struct timespec *tp );

Cyg_ErrNo cyg_wallclock_get_time_date( cyg_uint16 *year , cyg_uint8 *month , cyg_uint8 *day , cyg_uint8 *hour , cyg_uint8 *min , cyg_uint8 *sec , cyg_uint32 *nsec );

Cyg_ErrNo cyg_wallclock_set_time_date( cyg_uint16 year , cyg_uint8 month , cyg_uint8 day , cyg_uint8 hour , cyg_uint8 min , cyg_uint8 sec , cyg_uint32 nsec );

Cyg_ErrNo cyg_wallclock_get_info( wallclock_info_key key , wallclock_info *info );

Cyg_ErrNo cyg_wallclock_set_alarm_timespec( cyg_uint8 alarm_index , struct timespec *alarm_tp );

Cyg_ErrNo cyg_wallclock_set_alarm_date( cyg_uint8 alarm_index , cyg_uint16 year , cyg_uint8 month , cyg_uint8 day , cyg_uint8 hour , cyg_uint8 min , cyg_uint8 sec , cyg_uint32 nsec );

Cyg_ErrNo cyg_wallclock_disable_alarm( cyg_uint8 alarm_index );

Cyg_ErrNo cyg_wallclock_read_scratch( cyg_uint32 offset , cyg_uint8 *buf , cyg_uint32 len );

Cyg_ErrNo cyg_wallclock_write_scratch( cyg_uint32 offset , cyg_uint8 *buf , cyg_uint32 len );


The wallclock package exports a C API for interacting directly with the wallclock. This API is a veneer over a C++ API which is used internally within eCos. Applications should generally use the C API. Wallclock support is also integrated into the POSIX and C++ library packages and if these are part of the configuration the APIs provided by these libraries should be used in preference to the API described here. This API will sidestep any mechanisms present in these other packages for maintenance of the current time and may give rise to inconsistencies between the times that different parts of the system percieve.

The main part of the API consists of functions to set and get the current wallclock time. There are three versions of each set and get function which take the time to be set or got in different formats. The functions cyg_wallclock_get_current_time and cyg_wallclock_set_current_time use a timestamp consisting of seconds since the epoch; no fractions of a second are supported. The functions cyg_wallclock_get_time_timespec and cyg_wallclock_set_time_timespec use a struct timespec consisting of seconds and nanoseconds values; the nanoseconds value is only used or returned non-zero if the underlying wallclock device supports sub-second resolution. Finally, the cyg_wallclock_get_time_date and cyg_wallclock_set_time_date use a date and time broken down into its component parts from the year down to nanoseconds; again the nanoseconds argument is only used or returned non-zero if sub-second support is present.

The function cyg_wallclock_get_info returns information about the wallclock device. The key may be one of the following values:

Resolution in microseconds/tick (NB different from kernel). Returns in "resolution" member of wallclock_info.
The maximum year supported. This is a rough hint of the exact date. Returned in uint32val.
Many modern RTCs have a battery backed scratch space accompanying the RTC. If there is one, this returns its size in bytes in the "uint32val" member of the wallclock_info. If unsupported, either ENOSUPP is returned, or size may be set to 0.
Number of alarms available. Number returned in the "uint32val" member of wallclock_info. If unsupported, either ENOSUPP returned, or uint32val set to 0.
Must be called with an alarm index number in the "uint32val" member of supplied wallclock_info argument. Will return the interrupt vector number for that alarm in the same "uint32val" member. If there is no alarm or no interrupt for it, ENOSUPP is returned.
Sub-second fractions supported. If the wallclock driver supports sub-second resolution, this returns in "uint32val" the number of fractions each second is divided into. If the driver does not support sub-seconds, then this will either return ENOSUPP, or "uint32val" will be zero.
Since not all RTCs will have support for second granularity alarms this call is used to ascertain the minimum alarm period. Must be called with an alarm index number in the "uint32val" member of supplied wallclock_info argument. Will return in "uint32val" the smallest alarm delta as a microsecond value. If the driver returns ENOSUPP, or the value 0, then the default of 1-second granularity can be assumed.

If the wallclock device supports alarms then the functions cyg_wallclock_set_alarm_timespec, cyg_wallclock_set_alarm_date and cyg_wallclock_disable_alarm will be defined and provide support for setting and disabling individual alarms. Expiry of an alarm will cause a given interrupt vector to be raised (as defined bt the CYG_WALLCLOCK_INFO_GET_ALARM_INTVEC key). It is the responsibility of the application to attach an ISR and DSR to this vector and handle any subsequent processing. See the alarm test program for an example.

If the wallclock device supports scratch space then the functions cyg_wallclock_read_scratch and cyg_wallclock_write_scratch will be defined to read and write len bytes at the given offset in the scratch space.