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#if defined(REFCLOCK) && defined(CLOCK_ATOM) 18 19#ifdef HAVE_PPSAPI 20# include "ppsapi_timepps.h" 21#endif /* HAVE_PPSAPI */ 22 23/* 24 * This driver furnishes an interface for pulse-per-second (PPS) signals 25 * produced by a cesium clock, timing receiver or related equipment. It 26 * can be used to remove accumulated jitter and retime a secondary 27 * server when synchronized to a primary server over a congested, wide- 28 * area network and before redistributing the time to local clients. 29 * 30 * Before this driver becomes active, the local clock must be set to 31 * within +-500 ms by another means, such as a radio clock or NTP 32 * itself. There are two ways to connect the PPS signal, normally at TTL 33 * levels, to the computer. One is to shift to EIA levels and connect to 34 * pin 8 (DCD) of a serial port. This requires a level converter and 35 * may require a one-shot flipflop to lengthen the pulse. The other is 36 * to connect the PPS signal directly to pin 10 (ACK) of a PC paralell 37 * port. These methods are architecture dependent. 38 * 39 * Both methods require a modified device driver and kernel interface 40 * compatible with the Pulse-per-Second API for Unix-like Operating 41 * Systems, Version 1.0, RFC-2783 (PPSAPI). Implementations are 42 * available for FreeBSD, Linux, SunOS, Solaris and Alpha. However, at 43 * present only the Alpha implementation provides the full generality of 44 * the API with multiple PPS drivers and multiple handles per driver. If 45 * the PPSAPI is normally implemented in the /usr/include/sys/timepps.h 46 * header file and kernel support specific to each operating system. 47 * However, this driver can operate without this interface if means are 48 * proviced to call the pps_sample() routine from another driver. Please 49 * note; if the PPSAPI interface is present, it must be used. 50 * 51 * In many configurations a single port is used for the radio timecode 52 * and PPS signal. In order to provide for this configuration and others 53 * involving dedicated multiple serial/parallel ports, the driver first 54 * attempts to open the device /dev/pps%d, where %d is the unit number. 55 * If this fails, the driver attempts to open the device specified by 56 * the pps configuration command. If a port is to be shared, the pps 57 * command must be placed before the radio device(s) and the radio 58 * device(s) must be placed before the PPS driver(s) in the 59 * configuration file. 60 * 61 * This driver normally uses the PLL/FLL clock discipline implemented in 62 * the ntpd code. Ordinarily, this is the most accurate means, as the 63 * median filter in the driver interface is much larger than in the 64 * kernel. However, if the systemic clock frequency error is large (tens 65 * to hundreds of PPM), it's better to used the kernel support, if 66 * available. 67 * 68 * Fudge Factors 69 * 70 * If flag2 is dim (default), the on-time epoch is the assert edge of 71 * the PPS signal; if lit, the on-time epoch is the clear edge. If flag2 72 * is lit, the assert edge is used; if flag3 is dim (default), the 73 * kernel PPS support is disabled; if lit it is enabled. The time1 74 * parameter can be used to compensate for miscellaneous device driver 75 * and OS delays. 76 */ 77/* 78 * Interface definitions 79 */ 80#ifdef HAVE_PPSAPI 81#define DEVICE "/dev/pps%d" /* device name and unit */ 82#endif /* HAVE_PPSAPI */ 83 84#define PRECISION (-20) /* precision assumed (about 1 us) */ 85#define REFID "PPS\0" /* reference ID */ 86#define DESCRIPTION "PPS Clock Discipline" /* WRU */ 87#define NANOSECOND 1000000000 /* one second (ns) */ 88#define RANGEGATE 500000 /* range gate (ns) */ 89 90static struct peer *pps_peer; /* atom driver for PPS sources */ 91 92#ifdef HAVE_PPSAPI 93/* 94 * PPS unit control structure 95 */ 96struct ppsunit { 97 struct timespec ts; /* last timestamp */ 98 int fddev; /* pps device descriptor */ 99 pps_params_t pps_params; /* pps parameters */ 100 pps_info_t pps_info; /* last pps data */ 101 pps_handle_t handle; /* pps handlebars */ 102}; 103#endif /* HAVE_PPSAPI */ 104 105/* 106 * Function prototypes 107 */ 108static int atom_start P((int, struct peer *)); 109static void atom_poll P((int, struct peer *)); 110static void atom_shutdown P((int, struct peer *)); 111#ifdef HAVE_PPSAPI 112static void atom_control P((int, struct refclockstat *, struct 113 refclockstat *, struct peer *)); 114static void atom_timer P((int, struct peer *)); 115static int atom_ppsapi P((struct peer *, int)); 116#endif /* HAVE_PPSAPI */ 117 118/* 119 * Transfer vector 120 */ 121#ifdef HAVE_PPSAPI 122struct refclock refclock_atom = { 123 atom_start, /* start up driver */ 124 atom_shutdown, /* shut down driver */ 125 atom_poll, /* transmit poll message */ 126 atom_control, /* fudge control */ 127 noentry, /* initialize driver (not used) */ 128 noentry, /* buginfo (not used) */ 129 atom_timer, /* called once per second */ 130}; 131#else /* HAVE_PPSAPI */ 132struct refclock refclock_atom = { 133 atom_start, /* start up driver */ 134 atom_shutdown, /* shut down driver */ 135 atom_poll, /* transmit poll message */ 136 noentry, /* fudge control (not used) */ 137 noentry, /* initialize driver (not used) */ 138 noentry, /* buginfo (not used) */ 139 NOFLAGS /* not used */ 140}; 141#endif /* HAVE_PPPSAPI */ 142 143 144/* 145 * atom_start - initialize data for processing 146 */ 147static int 148atom_start( 149 int unit, /* unit number (not used) */ 150 struct peer *peer /* peer structure pointer */ 151 ) 152{ 153 struct refclockproc *pp; 154#ifdef HAVE_PPSAPI 155 register struct ppsunit *up; 156 char device[80]; 157 int mode; 158#endif /* HAVE_PPSAPI */ 159 160 /* 161 * Allocate and initialize unit structure 162 */ 163 pps_peer = peer; 164 pp = peer->procptr; 165 peer->precision = PRECISION; 166 pp->clockdesc = DESCRIPTION; 167 pp->stratum = STRATUM_UNSPEC; 168 memcpy((char *)&pp->refid, REFID, 4); 169#ifdef HAVE_PPSAPI 170 up = emalloc(sizeof(struct ppsunit)); 171 memset(up, 0, sizeof(struct ppsunit)); 172 pp->unitptr = (caddr_t)up; 173 174 /* 175 * Open PPS device. This can be any serial or parallel port and 176 * not necessarily the port used for the associated radio. 177 */ 178 sprintf(device, DEVICE, unit); 179 up->fddev = open(device, O_RDWR, 0777); 180 if (up->fddev <= 0) { 181 msyslog(LOG_ERR, 182 "refclock_atom: %s: %m", device); 183 return (0); 184 } 185 186 /* 187 * Light off the PPSAPI interface. 188 */ 189 if (time_pps_create(up->fddev, &up->handle) < 0) { 190 msyslog(LOG_ERR, 191 "refclock_atom: time_pps_create failed: %m"); 192 return (0); 193 } 194 195 /* 196 * If the mode is nonzero, use that for the time_pps_setparams() 197 * mode; otherwise, PPS_CAPTUREASSERT. Enable kernel PPS if 198 * flag3 is lit. 199 */ 200 mode = peer->ttl; 201 if (mode == 0) 202 mode = PPS_CAPTUREASSERT; 203 return (atom_ppsapi(peer, mode)); 204#else /* HAVE_PPSAPI */ 205 return (1); 206#endif /* HAVE_PPSAPI */ 207} 208 209 210/* 211 * atom_shutdown - shut down the clock 212 */ 213static void 214atom_shutdown( 215 int unit, /* unit number (not used) */ 216 struct peer *peer /* peer structure pointer */ 217 ) 218{ 219 struct refclockproc *pp; 220 register struct ppsunit *up; 221 222 pp = peer->procptr; 223 up = (struct ppsunit *)pp->unitptr; 224#ifdef HAVE_PPSAPI 225 if (up->fddev > 0) 226 close(up->fddev); 227 if (up->handle != 0) 228 time_pps_destroy(up->handle); 229#endif /* HAVE_PPSAPI */ 230 if (pps_peer == peer) 231 pps_peer = NULL; 232 free(up); 233} 234 235 236#ifdef HAVE_PPSAPI 237/* 238 * atom_control - fudge control 239 */ 240static void 241atom_control( 242 int unit, /* unit (not used */ 243 struct refclockstat *in, /* input parameters (not uded) */ 244 struct refclockstat *out, /* output parameters (not used) */ 245 struct peer *peer /* peer structure pointer */ 246 ) 247{ 248 struct refclockproc *pp; 249 int mode; 250 251 pp = peer->procptr; 252 if (peer->ttl != 0) /* all legal modes must be nonzero */ 253 return; 254 255 if (pp->sloppyclockflag & CLK_FLAG2) 256 mode = PPS_CAPTURECLEAR; 257 else 258 mode = PPS_CAPTUREASSERT; 259 atom_ppsapi(peer, mode); 260} 261 262 263/* 264 * Initialize PPSAPI 265 */ 266int 267atom_ppsapi( 268 struct peer *peer, /* peer structure pointer */ 269 int mode /* mode */ 270 ) 271{ 272 struct refclockproc *pp; 273 register struct ppsunit *up; 274 int capability; 275 276 pp = peer->procptr; 277 up = (struct ppsunit *)pp->unitptr; 278 if (up->handle == 0) 279 return (0); 280 281 if (time_pps_getcap(up->handle, &capability) < 0) { 282 msyslog(LOG_ERR, 283 "refclock_atom: time_pps_getcap failed: %m"); 284 return (0); 285 } 286 memset(&up->pps_params, 0, sizeof(pps_params_t)); 287 up->pps_params.api_version = PPS_API_VERS_1; 288 up->pps_params.mode = mode | PPS_TSFMT_TSPEC; 289 if (time_pps_setparams(up->handle, &up->pps_params) < 0) { 290 msyslog(LOG_ERR, 291 "refclock_atom: time_pps_setparams failed: %m"); 292 return (0); 293 } 294 if (pp->sloppyclockflag & CLK_FLAG3) { 295 if (time_pps_kcbind(up->handle, PPS_KC_HARDPPS, 296 up->pps_params.mode & ~PPS_TSFMT_TSPEC, 297 PPS_TSFMT_TSPEC) < 0) { 298 msyslog(LOG_ERR, 299 "refclock_atom: time_pps_kcbind failed: %m"); 300 return (0); 301 } 302 pps_enable = 1; 303 } 304#if DEBUG 305 if (debug) { 306 time_pps_getparams(up->handle, &up->pps_params); 307 printf( 308 "refclock_ppsapi: fd %d capability 0x%x version %d mode 0x%x\n", 309 up->fddev, capability, up->pps_params.api_version, 310 up->pps_params.mode); 311 } 312#endif 313 return (1); 314} 315 316 317/* 318 * atom_timer - called once per second 319 * 320 * This routine is called once per second when the PPSAPI interface is 321 * present. It snatches the PPS timestamp from the kernel and saves the 322 * sign-extended fraction in a circular buffer for processing at the 323 * next poll event. 324 */ 325static void 326atom_timer( 327 int unit, /* unit number (not used) */ 328 struct peer *peer /* peer structure pointer */ 329 ) 330{ 331 register struct ppsunit *up; 332 struct refclockproc *pp; 333 pps_info_t pps_info; 334 struct timespec timeout, ts; 335 long sec, nsec; 336 double dtemp; 337 char tbuf[80]; /* monitor buffer */ 338 339 /* 340 * Convert the timespec nanoseconds field to signed double and 341 * save in the median filter. for billboards. No harm is done if 342 * previous data are overwritten. If the discipline comes bum or 343 * the data grow stale, just forget it. A range gate rejects new 344 * samples if less than a jiggle time from the next second. 345 */ 346 pp = peer->procptr; 347 up = (struct ppsunit *)pp->unitptr; 348 if (up->handle == 0) 349 return; 350 351 timeout.tv_sec = 0; 352 timeout.tv_nsec = 0; 353 memcpy(&pps_info, &up->pps_info, sizeof(pps_info_t)); 354 if (time_pps_fetch(up->handle, PPS_TSFMT_TSPEC, &up->pps_info, 355 &timeout) < 0) { 356 refclock_report(peer, CEVNT_FAULT); 357 return; 358 } 359 if (up->pps_params.mode & PPS_CAPTUREASSERT) { 360 ts = up->pps_info.assert_timestamp; 361 } else if (up->pps_params.mode & PPS_CAPTURECLEAR) { 362 ts = up->pps_info.clear_timestamp; 363 } else { 364 refclock_report(peer, CEVNT_FAULT); 365 return; 366 } 367 368 /* 369 * There can be zero, one or two PPS seconds between polls. If 370 * zero, either the poll clock is slightly faster than the PPS 371 * clock or the PPS clock has died. If the PPS clock advanced 372 * once between polls, we make sure the fraction time difference 373 * since the last sample is within the range gate of 5 ms (500 374 * PPM). If the PPS clock advanced twice since the last poll, 375 * the poll bracketed more than one second and the first second 376 * was lost to a slip. Since the interval since the last sample 377 * found is now two seconds, just widen the range gate. If the 378 * PPS clock advanced three or more times, either the signal has 379 * failed for a number of seconds or we have runts, in which 380 * case just ignore them. 381 * 382 * If flag4 is lit, record each second offset to clockstats. 383 * That's so we can make awesome Allan deviation plots. 384 */ 385 sec = ts.tv_sec - up->ts.tv_sec; 386 nsec = ts.tv_nsec - up->ts.tv_nsec; 387 up->ts = ts; 388 if (nsec < 0) { 389 sec --; 390 nsec += NANOSECOND; 391 } else if (nsec >= NANOSECOND) { 392 sec++; 393 nsec -= NANOSECOND; 394 } 395 if (sec * NANOSECOND + nsec > NANOSECOND + RANGEGATE) 396 return; 397 398 else if (sec * NANOSECOND + nsec < NANOSECOND - RANGEGATE) 399 return; 400 401 pp->lastrec.l_ui = ts.tv_sec + JAN_1970; 402 dtemp = ts.tv_nsec * FRAC / 1e9; 403 if (dtemp >= FRAC) 404 pp->lastrec.l_ui++; 405 pp->lastrec.l_uf = (u_int32)dtemp; 406 if (ts.tv_nsec > NANOSECOND / 2) 407 ts.tv_nsec -= NANOSECOND; 408 dtemp = -(double)ts.tv_nsec / NANOSECOND; 409 SAMPLE(dtemp + pp->fudgetime1); 410 if (pp->sloppyclockflag & CLK_FLAG4){ 411 sprintf(tbuf, "%.9f", dtemp); 412 record_clock_stats(&peer->srcadr, tbuf); 413 } 414#ifdef DEBUG 415 if (debug > 1) 416 printf("atom_timer: %lu %f %f\n", current_time, 417 dtemp, pp->fudgetime1); 418#endif 419 return; 420} 421#endif /* HAVE_PPSAPI */ 422 423 424/* 425 * pps_sample - receive PPS data from some other clock driver 426 * 427 * This routine is called once per second when the external clock driver 428 * processes PPS information. It processes the PPS timestamp and saves 429 * the sign-extended fraction in a circular buffer for processing at the 430 * next poll event. This works only for a single PPS device. 431 * 432 * The routine should be used by another configured driver ONLY when 433 * this driver is configured as well and the PPSAPI is NOT in use. 434 */ 435int 436pps_sample( 437 l_fp *offset /* PPS offset */ 438 ) 439{ 440 register struct peer *peer; 441 struct refclockproc *pp; 442 l_fp lftmp; 443 double doffset; 444 445 peer = pps_peer; 446 if (peer == NULL) 447 return (1); 448 449 pp = peer->procptr; 450 451 /* 452 * Convert the timeval to l_fp and save for billboards. Sign- 453 * extend the fraction and stash in the buffer. No harm is done 454 * if previous data are overwritten. If the discipline comes bum 455 * or the data grow stale, just forget it. 456 */ 457 pp->lastrec = *offset; 458 L_CLR(&lftmp); 459 L_ADDF(&lftmp, pp->lastrec.l_f); 460 LFPTOD(&lftmp, doffset); 461 SAMPLE(-doffset + pp->fudgetime1); 462 return (0); 463} 464 465 466/* 467 * atom_poll - called by the transmit procedure 468 */ 469static void 470atom_poll( 471 int unit, /* unit number (not used) */ 472 struct peer *peer /* peer structure pointer */ 473 ) 474{ 475 struct refclockproc *pp; 476 pp = peer->procptr; 477 pp->polls++; 478 479 /* 480 * Valid time is returned only if the prefer peer has survived 481 * the intersection algorithm and within 0.4 s of local time 482 * and not too long ago. This ensures the PPS time is within 483 * 0.5 s of the local time and the seconds numbering is 484 * unambiguous. Note that the leap bits, stratum and refid are 485 * set from the prefer peer, unless overriden by a fudge 486 * command. 487 */ 488 if (pp->codeproc == pp->coderecv) { 489 refclock_report(peer, CEVNT_TIMEOUT); 490 return; 491 492 } else if (sys_prefer == NULL) { 493 pp->codeproc = pp->coderecv; 494 return; 495 496 } else if (fabs(sys_prefer->offset) >= 0.4) { 497 pp->codeproc = pp->coderecv; 498 return; 499 } 500 pp->leap = sys_prefer->leap; 501 if (pp->stratum >= STRATUM_UNSPEC) 502 peer->stratum = sys_prefer->stratum; 503 else 504 peer->stratum = pp->stratum; 505 pp->lastref = pp->lastrec; 506 refclock_receive(peer); 507} 508#else 509int refclock_atom_bs; 510int 511pps_sample( 512 l_fp *offset /* PPS offset */ 513 ) 514{ 515 return (1); 516} 517#endif /* REFCLOCK */ 518