1 /* 2 * refclock_atom - clock driver for 1-pps signals 3 */ 4 #ifdef HAVE_CONFIG_H 5 #include <config.h> 6 #endif 7 8 #include <stdio.h> 9 #include <ctype.h> 10 11 #include "ntpd.h" 12 #include "ntp_io.h" 13 #include "ntp_unixtime.h" 14 #include "ntp_refclock.h" 15 #include "ntp_stdlib.h" 16 17 /* 18 * This driver requires the PPSAPI interface (RFC 2783) 19 */ 20 #if defined(REFCLOCK) && defined(CLOCK_ATOM) && defined(HAVE_PPSAPI) 21 #include "ppsapi_timepps.h" 22 #include "refclock_atom.h" 23 24 /* 25 * This driver furnishes an interface for pulse-per-second (PPS) signals 26 * produced by a cesium clock, timing receiver or related equipment. It 27 * can be used to remove accumulated jitter over a congested link and 28 * retime a server before redistributing the time to clients. It can 29 *also be used as a holdover should all other synchronization sources 30 * beconme unreachable. 31 * 32 * Before this driver becomes active, the local clock must be set to 33 * within +-0.4 s by another means, such as a radio clock or NTP 34 * itself. There are two ways to connect the PPS signal, normally at TTL 35 * levels, to the computer. One is to shift to EIA levels and connect to 36 * pin 8 (DCD) of a serial port. This requires a level converter and 37 * may require a one-shot flipflop to lengthen the pulse. The other is 38 * to connect the PPS signal directly to pin 10 (ACK) of a PC paralell 39 * port. These methods are architecture dependent. 40 * 41 * This driver requires the Pulse-per-Second API for Unix-like Operating 42 * Systems, Version 1.0, RFC-2783 (PPSAPI). Implementations are 43 * available for FreeBSD, Linux, SunOS, Solaris and Tru64. However, at 44 * present only the Tru64 implementation provides the full generality of 45 * the API with multiple PPS drivers and multiple handles per driver. If 46 * the PPSAPI is normally implemented in the /usr/include/sys/timepps.h 47 * header file and kernel support specific to each operating system. 48 * 49 * This driver normally uses the PLL/FLL clock discipline implemented in 50 * the ntpd code. Ordinarily, this is the most accurate means, as the 51 * median filter in the driver interface is much larger than in the 52 * kernel. However, if the systemic clock frequency error is large (tens 53 * to hundreds of PPM), it's better to used the kernel support, if 54 * available. 55 * 56 * This deriver is subject to the mitigation rules described in the 57 * "mitigation rulse and the prefer peer" page. However, there is an 58 * important difference. If this driver becomes the PPS driver according 59 * to these rules, it is acrive only if (a) a prefer peer other than 60 * this driver is among the survivors or (b) there are no survivors and 61 * the minsane option of the tos command is zero. This is intended to 62 * support space missions where updates from other spacecraft are 63 * infrequent, but a reliable PPS signal, such as from an Ultra Stable 64 * Oscillator (USO) is available. 65 * 66 * Fudge Factors 67 * 68 * The PPS timestamp is captured on the rising (assert) edge if flag2 is 69 * dim (default) and on the falling (clear) edge if lit. If flag3 is dim 70 * (default), the kernel PPS support is disabled; if lit it is enabled. 71 * If flag4 is lit, each timesampt is copied to the clockstats file for 72 * later analysis. This can be useful when constructing Allan deviation 73 * plots. The time1 parameter can be used to compensate for 74 * miscellaneous device driver and OS delays. 75 */ 76 /* 77 * Interface definitions 78 */ 79 #define DEVICE "/dev/pps%d" /* device name and unit */ 80 #define PRECISION (-20) /* precision assumed (about 1 us) */ 81 #define REFID "PPS\0" /* reference ID */ 82 #define DESCRIPTION "PPS Clock Discipline" /* WRU */ 83 84 /* 85 * PPS unit control structure 86 */ 87 struct ppsunit { 88 struct refclock_atom atom; /* atom structure pointer */ 89 int fddev; /* file descriptor */ 90 }; 91 92 /* 93 * Function prototypes 94 */ 95 static int atom_start (int, struct peer *); 96 static void atom_shutdown (int, struct peer *); 97 static void atom_poll (int, struct peer *); 98 static void atom_timer (int, struct peer *); 99 100 /* 101 * Transfer vector 102 */ 103 struct refclock refclock_atom = { 104 atom_start, /* start up driver */ 105 atom_shutdown, /* shut down driver */ 106 atom_poll, /* transmit poll message */ 107 noentry, /* control (not used) */ 108 noentry, /* initialize driver (not used) */ 109 noentry, /* buginfo (not used) */ 110 atom_timer, /* called once per second */ 111 }; 112 113 114 /* 115 * atom_start - initialize data for processing 116 */ 117 static int 118 atom_start( 119 int unit, /* unit number (not used) */ 120 struct peer *peer /* peer structure pointer */ 121 ) 122 { 123 struct refclockproc *pp; 124 struct ppsunit *up; 125 char device[80]; 126 127 /* 128 * Allocate and initialize unit structure 129 */ 130 pp = peer->procptr; 131 peer->precision = PRECISION; 132 pp->clockdesc = DESCRIPTION; 133 pp->stratum = STRATUM_UNSPEC; 134 memcpy((char *)&pp->refid, REFID, 4); 135 up = emalloc(sizeof(struct ppsunit)); 136 memset(up, 0, sizeof(struct ppsunit)); 137 pp->unitptr = up; 138 139 /* 140 * Open PPS device. This can be any serial or parallel port and 141 * not necessarily the port used for the associated radio. 142 */ 143 snprintf(device, sizeof(device), DEVICE, unit); 144 up->fddev = tty_open(device, O_RDWR, 0777); 145 if (up->fddev <= 0) { 146 msyslog(LOG_ERR, 147 "refclock_atom: %s: %m", device); 148 return (0); 149 } 150 151 /* 152 * Light up the PPSAPI interface. 153 */ 154 return (refclock_ppsapi(up->fddev, &up->atom)); 155 } 156 157 158 /* 159 * atom_shutdown - shut down the clock 160 */ 161 static void 162 atom_shutdown( 163 int unit, /* unit number (not used) */ 164 struct peer *peer /* peer structure pointer */ 165 ) 166 { 167 struct refclockproc *pp; 168 struct ppsunit *up; 169 170 pp = peer->procptr; 171 up = pp->unitptr; 172 if (up->fddev > 0) 173 close(up->fddev); 174 free(up); 175 } 176 177 /* 178 * atom_timer - called once per second 179 */ 180 void 181 atom_timer( 182 int unit, /* unit pointer (not used) */ 183 struct peer *peer /* peer structure pointer */ 184 ) 185 { 186 struct ppsunit *up; 187 struct refclockproc *pp; 188 char tbuf[80]; 189 190 pp = peer->procptr; 191 up = pp->unitptr; 192 if (refclock_pps(peer, &up->atom, pp->sloppyclockflag) <= 0) 193 return; 194 195 peer->flags |= FLAG_PPS; 196 197 /* 198 * If flag4 is lit, record each second offset to clockstats. 199 * That's so we can make awesome Allan deviation plots. 200 */ 201 if (pp->sloppyclockflag & CLK_FLAG4) { 202 snprintf(tbuf, sizeof(tbuf), "%.9f", 203 pp->filter[pp->coderecv]); 204 record_clock_stats(&peer->srcadr, tbuf); 205 } 206 } 207 208 209 /* 210 * atom_poll - called by the transmit procedure 211 */ 212 static void 213 atom_poll( 214 int unit, /* unit number (not used) */ 215 struct peer *peer /* peer structure pointer */ 216 ) 217 { 218 struct refclockproc *pp; 219 220 /* 221 * Don't wiggle the clock until some other driver has numbered 222 * the seconds. 223 */ 224 if (sys_leap == LEAP_NOTINSYNC) 225 return; 226 227 pp = peer->procptr; 228 pp->polls++; 229 if (pp->codeproc == pp->coderecv) { 230 peer->flags &= ~FLAG_PPS; 231 refclock_report(peer, CEVNT_TIMEOUT); 232 return; 233 } 234 pp->lastref = pp->lastrec; 235 refclock_receive(peer); 236 } 237 #else 238 int refclock_atom_bs; 239 #endif /* REFCLOCK */ 240