xref: /freebsd/contrib/ntp/ntpd/refclock_local.c (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
1 
2 /*
3  * refclock_local - local pseudo-clock driver
4  *
5  * wjm 17-aug-1995: add a hook for special treatment of VMS_LOCALUNIT
6  */
7 #ifdef HAVE_CONFIG_H
8 #include <config.h>
9 #endif
10 
11 #ifdef REFCLOCK
12 
13 #include "ntpd.h"
14 #include "ntp_refclock.h"
15 #include "ntp_stdlib.h"
16 
17 #include <stdio.h>
18 #include <ctype.h>
19 
20 #ifdef KERNEL_PLL
21 #include "ntp_syscall.h"
22 #endif
23 
24 /*
25  * This is a hack to allow a machine to use its own system clock as a
26  * reference clock, i.e., to free-run using no outside clock discipline
27  * source. This is useful if you want to use NTP in an isolated
28  * environment with no radio clock or NIST modem available. Pick a
29  * machine that you figure has a good clock oscillator and configure it
30  * with this driver. Set the clock using the best means available, like
31  * eyeball-and-wristwatch. Then, point all the other machines at this
32  * one or use broadcast (not multicast) mode to distribute time.
33  *
34  * Another application for this driver is if you want to use a
35  * particular server's clock as the clock of last resort when all other
36  * normal synchronization sources have gone away. This is especially
37  * useful if that server has an ovenized oscillator. For this you would
38  * configure this driver at a higher stratum (say 5) to prevent the
39  * server's stratum from falling below that.
40  *
41  * A third application for this driver is when an external discipline
42  * source is available, such as the NIST "lockclock" program, which
43  * synchronizes the local clock via a telephone modem and the NIST
44  * Automated Computer Time Service (ACTS), or the Digital Time
45  * Synchronization Service (DTSS), which runs on DCE machines. In this
46  * case the stratum should be set at zero, indicating a bona fide
47  * stratum-1 source. Exercise some caution with this, since there is no
48  * easy way to telegraph via NTP that something might be wrong in the
49  * discipline source itself. In the case of DTSS, the local clock can
50  * have a rather large jitter, depending on the interval between
51  * corrections and the intrinsic frequency error of the clock
52  * oscillator. In extreme cases, this can cause clients to exceed the
53  * 128-ms slew window and drop off the NTP subnet.
54  *
55  * THis driver includes provisions to telegraph synchronization state
56  * and related variables by means of kernel variables with specially
57  * modified kernels. This is done using the ntp_adjtime() syscall.
58  * In the cases where another protocol or device synchronizes the local
59  * host, the data given to the kernel can be slurped up by this driver
60  * and distributed to clients by ordinary NTP messaging.
61  *
62  * In the default mode the behavior of the clock selection algorithm is
63  * modified when this driver is in use. The algorithm is designed so
64  * that this driver will never be selected unless no other discipline
65  * source is available. This can be overriden with the prefer keyword of
66  * the server configuration command, in which case only this driver will
67  * be selected for synchronization and all other discipline sources will
68  * be ignored. This behavior is intended for use when an external
69  * discipline source controls the system clock.
70  *
71  * Fudge Factors
72  *
73  * The stratum for this driver set at 5 by default, but it can be
74  * changed by the fudge command and/or the ntpdc utility. The reference
75  * ID is "LCL" by default, but can be changed using the same mechanism.
76  * *NEVER* configure this driver to operate at a stratum which might
77  * possibly disrupt a client with access to a bona fide primary server,
78  * unless the local clock oscillator is reliably disciplined by another
79  * source. *NEVER NEVER* configure a server which might devolve to an
80  * undisciplined local clock to use multicast mode. Always remember that
81  * an improperly configured local clock driver let loose in the Internet
82  * can cause very serious disruption. This is why most of us who care
83  * about good time use cryptographic authentication.
84  *
85  * This driver provides a mechanism to trim the local clock in both time
86  * and frequency, as well as a way to manipulate the leap bits. The
87  * fudge time1 parameter adjusts the time, in seconds, and the fudge
88  * time2 parameter adjusts the frequency, in ppm. The fudge time1
89  * parameter is additive; that is, it adds an increment to the current
90  * time. The fudge time2 parameter directly sets the frequency.
91  */
92 /*
93  * Local interface definitions
94  */
95 #define PRECISION	(-7)	/* about 10 ms precision */
96 #if defined(VMS) && defined(VMS_LOCALUNIT)
97 #define REFID		"LCLv"	/* reference ID */
98 #else /* VMS VMS_LOCALUNIT */
99 #define REFID		"LCL\0"	/* reference ID */
100 #endif /* VMS VMS_LOCALUNIT */
101 #define DESCRIPTION "Undisciplined local clock" /* WRU */
102 
103 #define STRATUM 	5	/* default stratum */
104 #define DISPERSION	.01	/* default dispersion (10 ms) */
105 
106 /*
107  * Imported from the timer module
108  */
109 extern u_long current_time;
110 
111 /*
112  * Imported from ntp_proto
113  */
114 extern s_char sys_precision;
115 
116 #ifdef KERNEL_PLL
117 /*
118  * Imported from ntp_loopfilter
119  */
120 extern int pll_control; 	/* kernel pll control */
121 extern int kern_enable;		/* kernel pll enabled */
122 extern int ext_enable;		/* external clock enable */
123 #endif /* KERNEL_PLL */
124 
125 /*
126  * Function prototypes
127  */
128 static	int local_start P((int, struct peer *));
129 static	void	local_poll	P((int, struct peer *));
130 
131 /*
132  * Local variables
133  */
134 static	u_long poll_time;	/* last time polled */
135 
136 /*
137  * Transfer vector
138  */
139 struct	refclock refclock_local = {
140 	local_start,		/* start up driver */
141 	noentry,		/* shut down driver (not used) */
142 	local_poll,	 	/* transmit poll message */
143 	noentry,		/* not used (old lcl_control) */
144 	noentry,		/* initialize driver (not used) */
145 	noentry,		/* not used (old lcl_buginfo) */
146 	NOFLAGS 		/* not used */
147 };
148 
149 
150 /*
151  * local_start - start up the clock
152  */
153 static int
154 local_start(
155 	int unit,
156 	struct peer *peer
157 	)
158 {
159 	struct refclockproc *pp;
160 
161 	pp = peer->procptr;
162 
163 	/*
164 	 * Initialize miscellaneous variables
165 	 */
166 	peer->precision = sys_precision;
167 	pp->leap = LEAP_NOTINSYNC;
168 	peer->stratum = STRATUM;
169 	pp->stratum = STRATUM;
170 	pp->clockdesc = DESCRIPTION;
171 	memcpy(&pp->refid, "INIT", 4);
172 	poll_time = current_time;
173 	return (1);
174 }
175 
176 
177 /*
178  * local_poll - called by the transmit procedure
179  *
180  * LOCKCLOCK: If the kernel supports the nanokernel or microkernel
181  * system calls, the leap bits are extracted from the kernel. If there
182  * is a kernel error or the kernel leap bits are set to 11, the NTP leap
183  * bits are set to 11 and the stratum is set to infinity. Otherwise, the
184  * NTP leap bits are set to the kernel leap bits and the stratum is set
185  * as fudged. This behavior does not faithfully follow the
186  * specification, but is probably more appropriate in a multiple-server
187  * national laboratory network.
188  */
189 static void
190 local_poll(
191 	int unit,
192 	struct peer *peer
193 	)
194 {
195 #if defined(KERNEL_PLL) && defined(LOCKCLOCK)
196 	struct timex ntv;
197 #endif /* KERNEL_PLL LOCKCLOCK */
198 	struct refclockproc *pp;
199 
200 #if defined(VMS) && defined(VMS_LOCALUNIT)
201 	if (unit == VMS_LOCALUNIT) {
202 		extern void vms_local_poll(struct peer *);
203 
204 		vms_local_poll(peer);
205 		return;
206 	}
207 #endif /* VMS && VMS_LOCALUNIT */
208 	pp = peer->procptr;
209 	pp->polls++;
210 
211 	/*
212 	 * Ramble through the usual filtering and grooming code, which
213 	 * is essentially a no-op and included mostly for pretty
214 	 * billboards. We allow a one-time time adjustment using fudge
215 	 * time1 (s) and a continuous frequency adjustment using fudge
216 	 * time 2 (ppm).
217 	 */
218 	get_systime(&pp->lastrec);
219 	pp->fudgetime1 += pp->fudgetime2 * 1e-6 * (current_time -
220 	    poll_time);
221 	poll_time = current_time;
222 	refclock_process_offset(pp, pp->lastrec, pp->lastrec,
223 	    pp->fudgetime1);
224 
225 	/*
226 	 * If another process is disciplining the system clock, we set
227 	 * the leap bits and quality indicators from the kernel.
228 	 */
229 #if defined(KERNEL_PLL) && defined(LOCKCLOCK)
230 	memset(&ntv,  0, sizeof ntv);
231 	switch (ntp_adjtime(&ntv)) {
232 	case TIME_OK:
233 		pp->leap = LEAP_NOWARNING;
234 		peer->stratum = pp->stratum;
235 		break;
236 
237 	case TIME_INS:
238 		pp->leap = LEAP_ADDSECOND;
239 		peer->stratum = pp->stratum;
240 		break;
241 
242 	case TIME_DEL:
243 		pp->leap = LEAP_DELSECOND;
244 		peer->stratum = pp->stratum;
245 		break;
246 
247 	default:
248 		pp->leap = LEAP_NOTINSYNC;
249 		peer->stratum = STRATUM_UNSPEC;
250 	}
251 	pp->disp = 0;
252 	pp->jitter = 0;
253 #else /* KERNEL_PLL LOCKCLOCK */
254 	pp->leap = LEAP_NOWARNING;
255 	pp->disp = DISPERSION;
256 	pp->jitter = 0;
257 #endif /* KERNEL_PLL LOCKCLOCK */
258 	pp->lastref = pp->lastrec;
259 	refclock_receive(peer);
260 	pp->fudgetime1 = 0;
261 }
262 #else
263 int refclock_local_bs;
264 #endif /* REFCLOCK */
265