At the present time, the common clock package relies on kernel facilities. It is hoped in future that this dependency will be removed.
However at the present time, a clock management thread is used to provide an asynchronous route for managing clock operations. This can be important if the package is required to update the wallclock, since with some wallclock drivers, it can take over one second to update the wallclock time in hardware, and it would be inappropriate for applications to stall and wait for such operations to complete.
It also allows modules to be notified that time has changed, either by a step change or by gradual fine adjustment. It can either use a user-supplied callback function, or broadcast a nominated kernel condition variable as the mechanism for notification. When it does so, it passes both the newly set time, and the cumulative time offset since the last received notification.
If a callback function has been provided, it should return as soon as possible, as no further notifications or other processing by the clock management thread can proceed until control is returned to it.
At present, the only underlying HAL clock supported must be the same clock as that used by the kernel, however the API and implementation have been designed to accommodate alternative clocks, and very little is required to complete such an implementation, once an appropriate platform which requires it has been selected, so that it can be verified. Users of this package should certainly not assume that the clock being used to control system time will continue to be the same as the kernel's clock.
The package also makes use of the kernel clock conversion facilities in order to translate clock ticks to or from real time in a scalable way when calling this package's tick conversion functions. The HAL clock API also provides a mechanism to convert ticks to and from real time, but this is not designed to scale beyond nanosecond times, nor tick values greater than 32-bits in width.
It is strongly recommended that users use the time conversion functions provided by this package, not only to avoid duplication, but also because in the case of conversion of absolute time values, the values returned can be affected by any fine adjustment in progress at that time.