| C API | ||
|---|---|---|
 | Chapter 123. Wallclock Support |  |
Name
C API — Details
Synopsis
#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
);
Description
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:
- CYG_WALLCLOCK_INFO_RES
- Resolution in microseconds/tick (NB different from kernel). Returns in "resolution" member of wallclock_info.
- CYG_WALLCLOCK_INFO_MAXYEAR
- The maximum year supported. This is a rough hint of the exact date. Returned in uint32val.
- CYG_WALLCLOCK_INFO_GET_SCRATCH_SIZE
- 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.
- CYG_WALLCLOCK_INFO_GET_NUM_ALARMS
- Number of alarms available. Number returned in the "uint32val" member of wallclock_info. If unsupported, either ENOSUPP returned, or uint32val set to 0.
- CYG_WALLCLOCK_INFO_GET_ALARM_INTVEC
- 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.
- CYG_WALLCLOCK_INFO_GET_SUBSECOND_FRACTION
- 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.
- CYG_WALLCLOCK_INFO_GET_ALARM_PERIOD_MIN
-
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. - CYG_WALLCLOCK_INFO_GET_ALARM_STATUS
-
Since not all hardware platforms will have an interrupt
signal routed from the RTC this call can be used to
synchronously interrogate the current RTC alarm
state. The call must be made with an alarm index number
in the "uint32val" member of the supplied
wallclock_infoargument. It will return in "boolval" a boolean indicating the alarm state (falsefor inactive,truefor an active alarm indication). If the driver returnsENOSUPPthen this feature is not available, indicating that the system expects a validCYG_WALLCLOCK_INFO_GET_ALARM_INTVECresult indicating that the platform interrupt support is used to asynchronously report alarm events.
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 by 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.
| |  | |
| Wallclock support |  | Chapter 124. Dallas DS1302 Wallclock Device Driver |
| 2025-10-02 | eCosPro Non-Commercial Public License |