/*
** refclock_datum - clock driver for the Datum Programmable Time Server
**
** Important note: This driver assumes that you have termios. If you have
** a system that does not have termios, you will have to modify this driver.
**
** Sorry, I have only tested this driver on SUN and HP platforms.
*/
/*
** This driver supports the Datum Programmable Time System (PTS) clock.
** The clock works in very straight forward manner. When it receives a
** time code request (e.g., the ascii string "//k/mn"), it responds with
** a seven byte BCD time code. This clock only responds with a
** time code after it first receives the "//k/mn" message. It does not
** periodically send time codes back at some rate once it is started.
** the returned time code can be broken down into the following fields.
**
** _______________________________
** Bit Index | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
** ===============================
** byte 0: | - - - - | H D |
** ===============================
** byte 1: | T D | U D |
** ===============================
** byte 2: | - - | T H | U H |
** ===============================
** byte 3: | - | T M | U M |
** ===============================
** byte 4: | - | T S | U S |
** ===============================
** byte 5: | t S | h S |
** ===============================
** byte 6: | m S | - - - - |
** ===============================
**
** In the table above:
**
** "-" means don't care
** "H D", "T D", and "U D" means Hundreds, Tens, and Units of Days
** "T H", and "UH" means Tens and Units of Hours
** "T M", and "U M" means Tens and Units of Minutes
** "T S", and "U S" means Tens and Units of Seconds
** "t S", "h S", and "m S" means tenths, hundredths, and thousandths
** of seconds
**
** The Datum PTS communicates throught the RS232 port on your machine.
** Right now, it assumes that you have termios. This driver has been tested
** on SUN and HP workstations. The Datum PTS supports various IRIG and
** NASA input codes. This driver assumes that the name of the device is
** /dev/datum. You will need to make a soft link to your RS232 device or
** create a new driver to use this refclock.
*/
/*
** Datum PTS defines
*/
/*
** Note that if GMT is defined, then the Datum PTS must use Greenwich
** time. Otherwise, this driver allows the Datum PTS to use the current
** wall clock for its time. It determines the time zone offset by minimizing
** the error after trying several time zone offsets. If the Datum PTS
** time is Greenwich time and GMT is not defined, everything should still
** work since the time zone will be found to be 0. What this really means
** is that your system time (at least to start with) must be within the
** correct time by less than +- 30 minutes. The default is for GMT to not
** defined. If you really want to force GMT without the funny +- 30 minute
** stuff then you must define (uncomment) GMT below.
*/
/*
** I don't use a fixed array of MAXUNITS like everyone else just because
** I don't like to program that way. Sorry if this bothers anyone. I assume
** that you can use any id for your unit and I will search for it in a
** dynamic array of units until I find it. I was worried that users might
** enter a bad id in their configuration file (larger than MAXUNITS) and
** besides, it is just cleaner not to have to assume that you have a fixed
** number of anything in a program.
*/
struct datum_pts_unit {
struct peer *peer; /* peer used by ntp */
int PTS_fd; /* file descriptor for PTS */
u_int unit; /* id for unit */
u_long timestarted; /* time started */
l_fp lastrec; /* time tag for the receive time (system) */
l_fp lastref; /* reference time (Datum time) */
u_long yearstart; /* the year that this clock started */
int coderecv; /* number of time codes received */
int day; /* day */
int hour; /* hour */
int minute; /* minutes */
int second; /* seconds */
int msec; /* miliseconds */
int usec; /* miliseconds */
u_char leap; /* funny leap character code */
char retbuf[8]; /* returned time from the datum pts */
char nbytes; /* number of bytes received from datum pts */
double sigma2; /* average squared error (roughly) */
int tzoff; /* time zone offest from GMT */
};
/*
** PTS static constant variables for internal use
*/
static char TIME_REQUEST[6]; /* request message sent to datum for time */
static int nunits; /* number of active units */
/*
** Callback function prototypes that ntpd needs to know about.
*/
/*
** This is the call back function structure that ntpd actually uses for
** this refclock.
*/
struct refclock refclock_datum = {
datum_pts_start, /* start up a new Datum refclock */
datum_pts_shutdown, /* shutdown a Datum refclock */
datum_pts_poll, /* sends out the time request */
datum_pts_control, /* not used */
datum_pts_init, /* initialization (called first) */
datum_pts_buginfo, /* not used */
NOFLAGS /* we are not setting any special flags */
};
/*
** The datum_pts_receive callback function is handled differently from the
** rest. It is passed to the ntpd io data structure. Basically, every
** 64 seconds, the datum_pts_poll() routine is called. It sends out the time
** request message to the Datum Programmable Time System. Then, ntpd
** waits on a select() call to receive data back. The datum_pts_receive()
** function is called as data comes back. We expect a seven byte time
** code to be returned but the datum_pts_receive() function may only get
** a few bytes passed to it at a time. In other words, this routine may
** get called by the io stuff in ntpd a few times before we get all seven
** bytes. Once the last byte is received, we process it and then pass the
** new time measurement to ntpd for updating the system time. For now,
** there is no 3 state filtering done on the time measurements. The
** jitter may be a little high but at least for its current use, it is not
** a problem. We have tried to keep things as simple as possible. This
** clock should not jitter more than 1 or 2 mseconds at the most once
** things settle down. It is important to get the right drift calibrated
** in the ntpd.drift file as well as getting the right tick set up right
** using tickadj for SUNs. Tickadj is not used for the HP but you need to
** remember to bring up the adjtime daemon because HP does not support
** the adjtime() call.
*/
static void datum_pts_receive (struct recvbuf *);
/*......................................................................*/
/* datum_pts_start - start up the datum PTS. This means open the */
/* RS232 device and set up the data structure for my unit. */
/*......................................................................*/
static int
datum_pts_start(
int unit,
struct peer *peer
)
{
struct refclockproc *pp;
struct datum_pts_unit *datum_pts;
int fd;
#ifdef HAVE_TERMIOS
int rc;
struct termios arg;
#endif
#ifdef DEBUG_DATUM_PTC
if (debug)
printf("Starting Datum PTS unit %d\n", unit);
#endif
/*
** Open the Datum PTS device
*/
fd = open(DATUM_DEV, O_RDWR);
/*
** Create the memory for the new unit
*/
datum_pts = emalloc_zero(sizeof(*datum_pts));
datum_pts->unit = unit; /* set my unit id */
datum_pts->yearstart = 0; /* initialize the yearstart to 0 */
datum_pts->sigma2 = 0.0; /* initialize the sigma2 to 0 */
datum_pts->PTS_fd = fd;
if (-1 == fcntl(datum_pts->PTS_fd, F_SETFL, 0)) /* clear the descriptor flags */
msyslog(LOG_ERR, "MSF_ARCRON(%d): fcntl(F_SETFL, 0): %m.",
unit);
#ifdef DEBUG_DATUM_PTC
if (debug)
printf("Opening RS232 port with file descriptor %d\n",
datum_pts->PTS_fd);
#endif
/*
** Set up the RS232 terminal device information. Note that we assume that
** we have termios. This code has only been tested on SUNs and HPs. If your
** machine does not have termios this driver cannot be initialized. You can change this
** if you want by editing this source. Please give the changes back to the
** ntp folks so that it can become part of their regular distribution.
*/
if (!io_addclock(&pp->io)) {
pp->io.fd = -1;
#ifdef DEBUG_DATUM_PTC
if (debug)
printf("Problem adding clock\n");
#endif
msyslog(LOG_ERR, "Datum_PTS: Problem adding clock");
close(datum_pts->PTS_fd);
free(datum_pts);
return 0;
}
peer->procptr->unitptr = datum_pts;
/*
** Now add one to the number of units and return a successful code
*/
nunits++;
return 1;
}
/*......................................................................*/
/* datum_pts_shutdown - this routine shuts doen the device and */
/* removes the memory for the unit. */
/*......................................................................*/
static void
datum_pts_shutdown(
int unit,
struct peer *peer
)
{
struct refclockproc *pp;
struct datum_pts_unit *datum_pts;
#ifdef DEBUG_DATUM_PTC
if (debug)
printf("Shutdown Datum PTS\n");
#endif
msyslog(LOG_ERR, "Datum_PTS: Shutdown Datum PTS");
/*
** We found the unit so close the file descriptor and free up the memory used
** by the structure.
*/
pp = peer->procptr;
datum_pts = pp->unitptr;
if (NULL != datum_pts) {
io_closeclock(&pp->io);
free(datum_pts);
}
}
/*......................................................................*/
/* datum_pts_poll - this routine sends out the time request to the */
/* Datum PTS device. The time will be passed back in the */
/* datum_pts_receive() routine. */
/*......................................................................*/
static void
datum_pts_poll(
int unit,
struct peer *peer
)
{
int error_code;
struct datum_pts_unit *datum_pts;
datum_pts = peer->procptr->unitptr;
#ifdef DEBUG_DATUM_PTC
if (debug)
printf("Poll Datum PTS\n");
#endif
/*
** Find the right unit and send out a time request once it is found.
*/
error_code = write(datum_pts->PTS_fd, TIME_REQUEST, 6);
if (error_code != 6)
perror("TIME_REQUEST");
datum_pts->nbytes = 0;
}
/*......................................................................*/
/* datum_pts_control - not used */
/*......................................................................*/
static void
datum_pts_control(
int unit,
const struct refclockstat *in,
struct refclockstat *out,
struct peer *peer
)
{
#ifdef DEBUG_DATUM_PTC
if (debug)
printf("Control Datum PTS\n");
#endif
}
/*......................................................................*/
/* datum_pts_init - initializes things for all possible Datum */
/* time code generators that might be used. In practice, this is */
/* only called once at the beginning before anything else is */
/* called. */
/*......................................................................*/
static void
datum_pts_init(void)
{
/* */
/*...... open up the log file if we are debugging ......................*/
/* */
/*
** Open up the log file if we are debugging. For now, send data out to the
** screen (stdout).
*/
#ifdef DEBUG_DATUM_PTC
if (debug)
printf("Init Datum PTS\n");
#endif
/*
** Initialize the time request command string. This is the only message
** that we ever have to send to the Datum PTS (although others are defined).
*/
memcpy(TIME_REQUEST, "//k/mn",6);
/*
** Initialize the number of units to 0 and set the dynamic array of units to
** NULL since there are no units defined yet.
*/
nunits = 0;
}
/*......................................................................*/
/* datum_pts_buginfo - not used */
/*......................................................................*/
static void
datum_pts_buginfo(
int unit,
register struct refclockbug *bug,
register struct peer *peer
)
{
#ifdef DEBUG_DATUM_PTC
if (debug)
printf("Buginfo Datum PTS\n");
#endif
}
/*......................................................................*/
/* datum_pts_receive - receive the time buffer that was read in */
/* by the ntpd io handling routines. When 7 bytes have been */
/* received (it may take several tries before all 7 bytes are */
/* received), then the time code must be unpacked and sent to */
/* the ntpd clock_receive() routine which causes the systems */
/* clock to be updated (several layers down). */
/*......................................................................*/
static void
datum_pts_receive(
struct recvbuf *rbufp
)
{
int i;
size_t nb;
l_fp tstmp;
struct peer *p;
struct datum_pts_unit *datum_pts;
char *dpt;
int dpend;
int tzoff;
int timerr;
double ftimerr, abserr;
#ifdef DEBUG_DATUM_PTC
double dispersion;
#endif
int goodtime;
/*double doffset;*/
/*
** Get the time code (maybe partial) message out of the rbufp buffer.
*/
#ifdef DEBUG_DATUM_PTC
if (debug)
printf("Receive Datum PTS: %d bytes\n", dpend);
#endif
/* */
/*...... save the ntp system time when the first byte is received ......*/
/* */
/*
** Save the ntp system time when the first byte is received. Note that
** because it may take several calls to this routine before all seven
** bytes of our return message are finally received by the io handlers in
** ntpd, we really do want to use the time tag when the first byte is
** received to reduce the jitter.
*/
nb = datum_pts->nbytes;
if (nb == 0) {
datum_pts->lastrec = rbufp->recv_time;
}
/*
** Increment our count to the number of bytes received so far. Return if we
** haven't gotten all seven bytes yet.
** [Sec 3388] make sure we do not overrun the buffer.
** TODO: what to do with excessive bytes, if we ever get them?
*/
for (i=0; (i < dpend) && (nb < sizeof(datum_pts->retbuf)); i++, nb++) {
datum_pts->retbuf[nb] = dpt[i];
}
datum_pts->nbytes = nb;
if (nb < 7) {
return;
}
/*
** Convert the seven bytes received in our time buffer to day, hour, minute,
** second, and msecond values. The usec value is not used for anything
** currently. It is just the fractional part of the time stored in units
** of microseconds.
*/
#ifdef DEBUG_DATUM_PTC
if (debug)
printf("day %d, hour %d, minute %d, second %d, msec %d\n",
datum_pts->day,
datum_pts->hour,
datum_pts->minute,
datum_pts->second,
datum_pts->msec);
#endif
/*
** Get the GMT time zone offset. Note that GMT should be zero if the Datum
** reference time is using GMT as its time base. Otherwise we have to
** determine the offset if the Datum PTS is using time of day as its time
** base.
*/
goodtime = 0; /* We are not sure about the time and offset yet */
#ifdef GMT
/*
** This is the case where the Datum PTS is using GMT so there is no time
** zone offset.
*/
tzoff = 0; /* set time zone offset to 0 */
#else
/*
** This is the case where the Datum PTS is using regular time of day for its
** time so we must compute the time zone offset. The way we do it is kind of
** funny but it works. We loop through different time zones (0 to 24) and
** pick the one that gives the smallest error (+- one half hour). The time
** zone offset is stored in the datum_pts structure for future use. Normally,
** the clocktime() routine is only called once (unless the time zone offset
** changes due to daylight savings) since the goodtime flag is set when a
** good time is found (with a good offset). Note that even if the Datum
** PTS is using GMT, this mechanism will still work since it should come up
** with a value for tzoff = 0 (assuming that your system clock is within
** a half hour of the Datum time (even with time zone differences).
*/
#ifdef DEBUG_DATUM_PTC
printf("Time Zone found (clocktime method) = %d\n",tzoff);
#endif
break;
}
}
}
#endif
/*
** Make sure that we have a good time from the Datum PTS. Clocktime() also
** sets yearstart and lastref.l_ui. We will have to set astref.l_uf (i.e.,
** the fraction of a second) stuff later.
*/
/*
** Compute the time correction as the difference between the reference
** time (i.e., the Datum time) minus the receive time (system time).
*/
tstmp = datum_pts->lastref; /* tstmp is the datum ntp time */
L_SUB(&tstmp, &datum_pts->lastrec); /* tstmp is now the correction */
datum_pts->coderecv++; /* increment a counter */
#ifdef DEBUG_DATUM_PTC
dispersion = DATUM_DISPERSION; /* set the dispersion to 0 */
ftimerr = dispersion;
ftimerr /= (1024.0 * 64.0);
if (debug)
printf("dispersion = %d, %f\n", dispersion, ftimerr);
#endif
/*
** Pass the new time to ntpd through the refclock_receive function. Note
** that we are not trying to make any corrections due to the time it takes
** for the Datum PTS to send the message back. I am (erroneously) assuming
** that the time for the Datum PTS to send the time back to us is negligable.
** I suspect that this time delay may be as much as 15 ms or so (but probably
** less). For our needs at JPL, this kind of error is ok so it is not
** necessary to use fudge factors in the ntp.conf file. Maybe later we will.
*/
/*LFPTOD(&tstmp, doffset);*/
datum_pts->lastref = datum_pts->lastrec;
refclock_receive(datum_pts->peer);
/*
** Compute sigma squared (not used currently). Maybe later, this could be
** used for the dispersion estimate. The problem is that ntpd does not link
** in the math library so sqrt() is not available. Anyway, this is useful
** for debugging. Maybe later I will just use absolute values for the time
** error to come up with my dispersion estimate. Anyway, for now my dispersion
** is set to 0.
*/
