= External Clock Discipline and the Local Clock Driver
include::include-html.ad[]

The NTPv4 implementation includes provisions for an external clock,
where the system clock is implemented by some external hardware device.
One implementation might take the form of a bus peripheral with a high
resolution counter disciplined by a GPS receiver, for example. Another
implementation might involve another synchronization protocol, such as
the Digital Time Synchronization Service (DTSS), where the system time
is disciplined to this protocol and NTP clients of the server obtain
synchronization indirectly via the server. A third implementation might
be a completely separate clock discipline algorithm and synchronization
protocol, such as the +Lockclock+ algorithm used with NIST Automated
Computer Time Service (ACTS) modem synchronized time.

When external clocks are used in conjunction with NTP service, some way
needs to be provided for the external clock driver and NTP daemon +ntpd+
to communicate and determine which discipline is in control; this is
necessary to provide backup, for instance, if the external clock
or protocol were to fail, and synchronization service fall back to other
means, such as a local reference clock or another NTP server. In
addition, when the external clock and driver are in control, some means
needs to be provided for the clock driver to pass on the status information
and error statistics to the NTP daemon.

Control and monitoring functions for the external clock and driver are
implemented using the link:driver_local.html[Local Clockdriver]
and the +ntp_adjtime()+ system call. This system call is
implemented by special kernel provisions included in the kernel of
several operating systems, including Solaris, Tru64, FreeBSD, Linux,
and possibly others. When the external clock is disabled or not
implemented, the system call is used to pass time and frequency
information, as well as error statistics, to the kernel. Besides
disciplining the system time, the same interface can be used by other
applications to determine the operating parameters of the discipline.

When the external clock is enabled, +ntpd+ does not discipline the
system clock, nor does it maintain the error statistics. In this case,
the external clock and driver do that using mechanisms unknown to
+ntpd+; however, in this case the kernel state variables are retrieved
at 64 s intervals by the Local Clock driver and used by the clock
selection and mitigation algorithms to determine the system variables
presented to other NTP clients and peers. In this way, downstream
clients and servers in the NTP subnet can make an intelligent choice
when more than one server is available.

In order to implement a reliable mitigation between ordinary NTP sources
and the external clock source, a protocol is necessary between the local
clock driver and the external clock driver; this is implemented using
Boolean variables and certain bits in the kernel clock status word. The
Boolean variables include the following:

+ntp_enable+::
	Set/reset by the +enable+ command. Enables ntpd clock discipline

+ntp_control+::
	Set during initial configuration if kernel support is available

+kern_enable+::
	Set/reset by the +enable+ command

If the +kern_enable+ switch is set, the daemon computes the offset,
frequency, maximum error, estimated error, time constant and status
bits, then provides them to the kernel via +ntp_adjtime()+. If this
switch is not set, these values are not passed to the kernel; however,
the daemon retrieves their present values and uses them in place of the
values computed by the daemon.

The +pps_update+ bit is set in the protocol routine if the prefer peer has
survived and has an offset of less than 128 ms; otherwise it is set to zero.

The +PPS control+ is updated to the current time by kernel support if the
PPS signal is enabled and working correctly. It is set to zero in the adjust
routine if the interval since the last update exceeds 120 s.

The +ntp_enable+ and +kern_enable+ are set by the configuration module.
Normally, both switches default on, so the daemon can control the time
and the kernel discipline can be used, if available. The +pps_update+
switch is set by the protocol module when it believes the PPS provider
source is legitimate and operating nominally. The +ntp_control+
switch is set during configuration by interrogating the kernel. If both
the +kern_enable+ and +ntp_control+ switches are set, the daemon
disciplines the clock via the kernel and the internal daemon discipline
is disabled.

The external clock driver controls the system time and clock selection
in the following way: Normally, the driver adjusts the kernel time using
the +ntp_adjtime()+ system call in the same way as the daemon. In the
case where the kernel discipline is to be used intact, the clock offset
is provided in this call and the loop operates as specified. In the case
where the driver steers only the frequency, the offset is specified as
zero.

'''''

include::includes/footer.adoc[]
