Description

These functions are used to allow users of this package to register and deregister for notifications of changes to system time. This may help allow the user to know when to update any timers or alarms.

Parameters which affect the method of delivering notifications are passed in within the info function argument. Other fields in that same structure are then used to pass information about time updates back to the user when a time change event occurs, which happens as a consequence of calls to either cyg_clock_set_systime() or to cyg_clock_adjust_systime().

There are two primary mechanisms for notification: the user may supply a callback function; or the user can supply a condition variable, which they may then wait on to be signalled.

The cyg_clock_timechange_info structure is defined by including <cyg/clock/api.h> and has the following contents relevant to the user:

/* Forward definition to avoid circular dependency */
struct cyg_clock_timechange_info_s;

typedef struct cyg_clock_timechange_info_s cyg_clock_timechange_info;

typedef void (cyg_clock_timechange_cb_fn_t)( cyg_clock_timechange_info *changeinfo );

struct cyg_clock_timechange_info_s {
    CYG_ADDRWORD                  userdata;
    cyg_drv_mutex_t               *mutex;
    cyg_drv_cond_t                *cv;
    cyg_clock_timechange_cb_fn_t  *cb;

    /* VALUES ABOVE ARE SET BY USER BEFORE REGISTRATION
     * VALUES BELOW ARE SET BY THE CLOCK PACKAGE ON TIME CHANGE EVENTS
     */

    cyg_bool                      adjtime;
    struct timespec               newtime;
    struct timespec               offset;
};

Other members of this structure exist, but are private to the common clock package's implementation and do not form part of the API. They must not be modified by the user.

The cyg_clock_timechange_info structure passed in must be persistent while the registration is in effect, as it will be used by the common clock package to maintain the registration. The address of the same structure object must be passed in on deregistration.

cyg_clock_timechange_info details

Here is a description of the purpose of each of the cyg_clock_timechange_info structure members:

Using a callback function

Some special care is required if using the callback function method for notifications.

If a callback function is used, it must be brief, as further users of this package who have registered a callback will not be notified until the callback returns. For this reason, and to improve determinism, and to avoid delaying clock package operations, the condition variable approach should be preferred.

The callback function method is still available however as it is realized that sometimes there may be no alternative.

Users should not call back into any time-keeping functions (in this package or others) from a callback function, in order to avoid re-entrancy issues. An exception is for the time conversion functions.

Even with a callback function, it is recommended to still use a mutex lock to prevent the timechange info structure being updated while it is in the process of being read; and if such a mutex is provided with the 'mutex' member, it will be locked before the callback is called, and unlocked after.

Return value

These functions return a standard error code, as defined in <errno.h>, or ENOERR on success.