Although the clockinfo database described in section A.2, together
with the discover mechanisms described there, would allow an
application to discover the PPS source (or sources) connected to a
system, it might be more complex than necessary.
A simpler approach would be to support a single function that
provides the identity of one or more PPS sources.
For example, the function might be declared as
int time_pps_findsource(int index,
char *path, int pathlen,
char *idstring, int idlen);
The index argument implicitly sets up an ordering on the PPS sources
attached to the system. An application would use this function to
inquire about the Nth source. The function would return -1 if no
such source exists; otherwise, it would return 0, and would place the
pathname of the associated special file in the path argument. It
would also place an identification string in the idstring argument.
The identification string could include the clock make, model,
version, etc., which could then be used by the application to control
its behavior.
This function might simply read the Nth line from a simple database,
containing lines such as:
/dev/tty00 "TrueTime 468-DC"
/dev/pps1 "Homebrew rubidium frequency standard"
allowing the system administrator to describe the configuration of
PPS sources.
B. Example implementation: PPSDISC Line discipline
One possible implementation of the PPS API might be to define a new
"line discipline" and then map the API onto a set of ioctl()
commands. Here we sketch such an implementation; note that this is
not part of the specification of the API, and applications should not
expect this low-level interface to be available.
In this approach, the set of line disciplines is augmented with one
new line discipline, PPSDISC. This discipline will act exactly the
same as the TTYDISC discipline, except for its handling of modem DCD
interrupts.
Once the TIOCSETD ioctl() has been used to select this line
discipline, PPS-related operations on the serial line may be invoked
using new ioctl() commands. For example (values used only for
illustration):
#define PPSFETCH _IOR('t', 75, pps_info_t)
#define PPSSETPARAM _IOW('t', 76, pps_params_t)
#define PPSGETPARAM _IOR('t', 77, pps_params_t)
#define PPSGETCAP _IOR('t', 78, int)
B.1 Example
A typical use might be:
int ldisc = PPSDISC;
pps_params_t params;
pps_info_t infobuf;
ioctl(fd, TIOCSETD, &ldisc); /* set discipline */
/*
* Check the capabilities of this PPS source to see
* if it supports what we need.
*/
ioctl(fd, PPSGETCAP, ¶ms);
if ((params.mode & PPS_CAPTUREASSERT) == 0) {
fprintf(stderr, "PPS source is not suitable\n");
exit(1);
}
/*
* Set this line to timestamp on a rising-edge interrupt
*/
ioctl(fd, PPSGETPARAMS, ¶ms);
params.mode |= PPS_CAPTUREASSERT;
ioctl(fd, PPSSETPARAMS, ¶ms);
sleep(2); /* allow time for the PPS pulse to happen */
/* obtain most recent timestamp and sequence # for this line */
ioctl(fd, PPSFETCH, &infobuf);
Again, this example imprudently omits any error-checking.
C. Available implementations
Several available implementations of this API are listed at
<http://www.ntp.org/ppsapi/PPSImpList.html>. Note that not all of
these implementations correspond to the current version of the
specification.
Full Copyright Statement
Copyright (C) The Internet Society (2000). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFCEditor function is currently provided by the
Internet Society.