clock(HW)

clock -- High-precision system clock

Description

The high-precision system clock provides microsecond-precision timekeeping and alarm subsystems. This is a new feature in SCO OpenServer Release 5.0.6, replacing the 10-millisecond-precision clock provided for earlier SCO OpenServer releases. Applications and drivers do not need to be modified or recompiled to take advantage of this feature, but will generally benefit from better performance and general improvements in the timekeeping functionality. Drivers that are used for heavily clock-dependent applications (such as animation, audio/video recording and playback, and motor controls) may want to use new kernel facilities that are provided such as the nano_timeout( ) function.

On Pentium-class machines, the high-precision system clock uses the Pentium TSC cycle counter instead of the 8254 PIT for timekeeping. The TSC is a higher resolution clock than the PIT, enabling nanosecond-precision timekeeping within the kernel. On 386/486 machines, the high-precision system clock uses an enhanced 8254 PIT-based scheme for timekeeping, enabling microsecond precision timekeeping within the kernel.

The high-precision system clock has the largest impact on applications such as animation, audio/video recording and playback, and motor controls that are heavily clock dependent. Most application programs and drivers do not need to be modified or recompiled to take advantage of the new functionality but will perform better when run on a system that uses the high-precision system clock. Programs such as ping that measure short intervals can now measure intervals as short as one microsecond.

The following features are provided.

Microsecond-precision timekeeping (rather than 10ms-precision timekeeping) is made available to application programs through the usual system calls such as gettimeofday(S) and ftime(S)
The full resolution of adjtime(S) is supported, so time adjustments as small as one microsecond are performed accurately. Relatively small time adjustments, such as those made by NTP, are performed smoothly over the course of one second.
The suspend(D3oddi) kernel function as well as the select(S) and nap(S) system calls provide alarm timers with full microsecond-precision.
ODDI Verstion 6 and later drivers can call the nano_timeout( ) function to access a nanosecond-precision alarm timer within the kernel. This function is documented in the Consolidated Hardware Development Kit.
New clock debugging facilities are available. See the <sys/clock.h> header file for information about the clock_debug tunable parameter that implements clock debugging facilities.
An enhanced RTC (real-time clock) driver is included that produces warnings and disables the tracking of the system clock to the realtime clock if the clock hardware fails. This feature can be disabled with the disable_rtc_check tunable parameter discussed in ``Tunable parameters'' below.
Detects and compensates for delayed tick interrupts and some (but not all) missed clock tick interrupts on systems that use the PIT-based clock. Delayed ticks are a normal event related to system load, but can result in clock instability. Missed ticks, caused by ``greedy'' drivers or heavy serial port traffic, can cause the system clock to run slow. New clock/space.c variables enable reporting of missed tick events.

Note that the Pentium TSC-based clock is not dependent on ticks of any sort and so cannot be disrupted by missed or delayed clock ticks.

A number of general enhancements to the system clock have been implemented in conjunction with the high-precision system clock. In particular, time will never move backwards as sometimes occurred with earlier system clock facilities.

Tunable parameters

The behavior of the high-precision system clock is controlled by a set of tunable parameters located in the /etc/conf/pack.d/clock/space.c file.

update_rtc

If set to 1 (default), the realtime clock (RTC) is set to the new system time after an adjtime(S) adjustment. If set to 0, adjtime( ) does not affect the RTC; We do not recommend disabling update_rtc except in certain specific testing situations.

update_rtc_interval

Maximum interval (in seconds) at which the RTC is set to the new system time if update_rtc is not disabled; default is 20.

track_rtc

If set to 1 (default), the system clock tracks the realtime clock to maintain accuracy. If set to 0, the system clock does not track the realtime clock. This variable is automatically set to 0 by the RTC driver if the RTC's VRT bit indicates that RTC/CMOS might be invalid. This can happen, for example, if the CMOS battery fails.

The kernel ignores the track_rtc variable when ntpd(ADMN) (or any process that calls adjtime(S) every second or so) is running, as if track_rtc were set to 0.

For SCO OpenServer Release 5.0.5 and earlier releases, you must manually set track_rtc to 0 when running NTP. For SCO OpenServer Release 5.0.6 and later, do not adjust the value of track_rtc for NTP. The only reason to set track_rtc to 0 is if the RTC is known to be disfunctional.

track_rtc_interval

Interval (in seconds) at which to update the RTC; default is 20.

clock_drift

The maximum rate (expressed as nanoseconds per second) at which adjtime(S) adjustments are made to the system clock. The default value is 250,000,000 (one quarter-second per second).

tsc_clock_hz

Set to 0 (default) to automatically calculate the HZ rate of the Pentium CPU's TSC register. We do not recommend modifying this parameter.

The following tunable parameters can be used to disable certain features of the high-precision system clock on SCO OpenServer Release 5.0.6 and later releases:

disable_tsc_clock: Set to 1 to use the PIT-based system clock rather than the TSC. If this parameter is set to 1, disable_hires_clock and disable_short_timers are ignored; their functionality is disabled automatically.
disable_rtc_check: Set to 1 to check the RTC's ``battery failed'' indicator bit. In SCO OpenServer Release 5.0.6 and later releases, the kernel checks that bit each time it tries to track the RTC. If the ``battery failed'' bit is set, it means that the RTC has determined that the CMOS backup battery is failing. When the kernel sees that, it logs the condition in the /usr/adm/messages file prints a warning to the console, and sets track_rtc to 0 to prevent the system software clock from trying to track a bogus RTC clock. We do not recommend modifying this parameter.
disable_hires_clock: Set to 1 to simulate the old 10ms resolution. This affects the time values returned by gettimeofday( ) and similar functions.
disable_pit_read: Set to 1 to handle some PITs that are known to be defective.
disable_short_timers: Set to 1 to disable the short timers. Short timers offer less latency, but cause more hardware interrupts. This parameter affects delays for calls such as select( ) and nap( ).

APIs and the high-precision clock

As of Release Supplement 506A for SCO OpenServer Release 5.0.6, a subset of APIs that use the kernel clock have been modified to utilize the high-precision clock. These are:

select(S): has microsecond precision, adjusted for kernel entry and exit times, time-sharing delays, and so forth.
usleep(S): has microsecond precision (uses select(S)).
nap(S): has microsecond precision, with one-millisecond granularity.
sleep(S): has microsecond precision, with one second granularity.
gettimeofday(S): returns microsecond precision.
settimeofday(S): accepts and implements microsecond precision.
adjtime(S): accepts and implements microsecond precision
ftime(S): returns millisecond precision.

The following functions do not fully take advantage of the high-precision system clock as of Release Supplement 506A for SCO OpenServer Release 5.0.6:

poll(S): has 10-20 millisecond precision.
alarm(S): has 10-20 millisecond precision.
setitimer(S): has 10-20 millisecond precision.
ualarm(S): has 10-20 millisecond precision (uses setitimer(S)).
timer_settime(S): has 10-20 miillisecond precision.

Differences between versions

Releases prior to SCO OpenServer Release 5.0.6 use the 8254 PIT for timekeeping rather than the Pentium TSC cycle counter, even when running on Pentium class machines.

Tunable parameters for earlier releases are defined in the /etc/conf/pack.d/kernel/space.c file. Only the update_rtc, track_rtc, and clock_drift parameters are defined for earlier releases.

Files