Chapter 206. Configuration
Prev Part LX. Common Clock Services Next

Chapter 206. Configuration

The following properties may be configured in this package using the configuration tool:

Management thread priority (CYGNUM_CLOCK_COMMON_THREAD_PRIO)
This specifies the thread priority of the clock management thread. It is strongly recommended that this be a high priority (smaller number) as this thread is intrinsically sensitive to time delays.
Management thread stack size (CYGNUM_CLOCK_COMMON_THREAD_STACK_SIZE)
This sets the stack size for the clock management thread. It must be large enough to accommodate calls into a wallclock driver (potentially in turn using bus drivers such as I²C), as well as any potential registered user callback functions. Note the value of this option is text, not a number.
Fine clock adjustment (CYGFUN_CLOCK_COMMON_ADJTIME)
This component is used to allow fine adjustment of clock times, using the cyg_clock_adjust_systime() API function. This allows system time to be gradually adjusted to a new time, rather than there being a step change by just setting the time. Some extra overhead is incurred when getting and setting time if this is enabled, so it is disabled by default.
Maximum adjustment range (CYGNUM_CLOCK_COMMON_ADJTIME_MAX_RANGE)
If fine clock adjustment is enabled, this option specifies the limit to how far the clock is allowed to be fine adjusted, measured in milliseconds. Requests to adjust beyond this range are rejected. Setting the range too large results in the clock remaining quite inaccurate over a longer time, and setting the time directly would be more relevant. The default is +/- 128ms which corresponds to the norm for NTPv3 (RFC1305) compliance.
Adjustment period as shift (CYGNUM_CLOCK_COMMON_ADJTIME_PERIOD_SHIFT)
This option is used to set the period of time over which the time should be adjusted. After this time has elapsed, the clock adjustment will be complete. The value of this option is used as a shift value to give a power of two in nanoseconds. A value of 1 corresponds to 2ns, a value of 2 corresponds to 4ns, a value of 3 corresponds to 8ns, and so on. As a convenience, a calculated CDL variable CYGNUM_CLOCK_COMMON_ADJTIME_PERIOD_SECS is provided alongside to see the effect of different settings of this variable. Having to use a power of two may seem restrictive, but it avoids some particularly expensive calculations which would be detrimental to efficiency and accuracy.
Adjustment period as secs (CYGNUM_CLOCK_COMMON_ADJTIME_PERIOD_SECS)
This configuration point is not actually used by the package, and exists purely as a convenience to the user. It uses the setting of CYGNUM_CLOCK_COMMON_ADJTIME_PERIOD_SHIFT to report an approximation of the corresponding period of time in seconds over which the time should be adjusted, to allow inspection of the effects of different shift values. The value displayed here is rounded down to the nearest second, although the actual value would not be.
Use wallclock (CYGPKG_CLOCK_COMMON_USE_WALLCLOCK)
Leave this option enabled if a wallclock (RTC) device driver is to be used to maintain time persistently. Time will be initialized using the wallclock driver. If this option is disabled, then a default date of 2012-01-01 00:00:00 is used when starting up, but the time can be set by the application (for example based on user input, or via an external process such as a network time client), and can then be maintained, even though the time will be lost on power off.
Wallclock updates (CYGPKG_CLOCK_COMMON_WALLCLOCK_UPDATES)
When this component is enabled, the wallclock can be updated by this package based on the system time held in this package. The user can request an update using the cyg_clock_sync_wallclock() API function, along with other automatic methods which can be enabled in the following options.
Always update when set (CYGSEM_CLOCK_COMMON_ALWAYS_UPDATE_WALLCLOCK)
This option defaults to disabled, but if it is enabled, whenever the system time is set it always results in the wallclock also being updated immediately afterwards. This could result in unnecessary load if the time is updated often, or delays if parts of the system need to wait for the update to complete.
Regular update interval (CYGNUM_CLOCK_COMMON_WALLCLOCK_UPDATE_PERIOD)
When this option is enabled, the wallclock will be updated periodically. The value of this option gives the period between updates, measured in kernel ticks. The default value of 720000 would correspond to 2 hours if the kernel is using a 100Hz clock.
Tick conversions (CYGFUN_CLOCK_COMMON_TICK_CONVERTERS)
Various subsystems, and users, may need to convert between system clock ticks and real time. This option enables the provision of functionality to do so. These functions also take account of any fine time adjustments made (if CYGFUN_CLOCK_COMMON_ADJTIME is enabled). However this functionality is not enabled by default as there is overhead in having and initialising the converters even if unused. Note that the system clock driving system time may not be the same clock as the kernel clock.
Prev Up Next
Chapter 205. Dependencies Home Chapter 207. API reference