< draft-mogul-pps-api-04.txt   draft-mogul-pps-api-05.txt >
Network Working Group Jeffrey Mogul, Compaq WRL Network Working Group Jeffrey Mogul, Compaq WRL
Internet-Draft David Mills, UDel Internet-Draft David Mills, UDel
Expires: 31 January 2000 Jan Brittenson, Sun Expires: 17 February 2000 Jan Brittenson, Sun
Jonathan Stone, Stanford Jonathan Stone, Stanford
Poul-Henning Kamp, FreeBSD
Ulrich Windl, Universitaet Regensburg Ulrich Windl, Universitaet Regensburg
23 July 1999 17 August 1999
Pulse-Per-Second API for UNIX-like Operating Systems, Version 1.0 Pulse-Per-Second API for UNIX-like Operating Systems, Version 1.0
draft-mogul-pps-api-04.txt draft-mogul-pps-api-05.txt
STATUS OF THIS MEMO STATUS OF THIS MEMO
This document is an Internet-Draft and is in full This document is an Internet-Draft and is in full
conformance with all provisions of Section 10 of RFC2026. conformance with all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Internet-Drafts are working documents of the Internet
Engineering Task Force (IETF), its areas, and its working Engineering Task Force (IETF), its areas, and its working
groups. Note that other groups may also distribute working groups. Note that other groups may also distribute working
documents as Internet-Drafts. documents as Internet-Drafts.
skipping to change at page 2, line 5 skipping to change at page 2, line 5
in conjunction with the Network Time Protocol (NTP, in conjunction with the Network Time Protocol (NTP,
RFC1305), or similar time synchronization protocols. One RFC1305), or similar time synchronization protocols. One
aspect of this model is an accurate interface to the aspect of this model is an accurate interface to the
high-accuracy, one pulse-per-second (PPS) output typically high-accuracy, one pulse-per-second (PPS) output typically
available from precise time sources (such as a GPS or GOES available from precise time sources (such as a GPS or GOES
receiver). RFC1589 did not define an API for managing the receiver). RFC1589 did not define an API for managing the
PPS facility, leaving implementors without a portable means PPS facility, leaving implementors without a portable means
for using PPS sources. This document specifies such an for using PPS sources. This document specifies such an
API. API.
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
TABLE OF CONTENTS TABLE OF CONTENTS
1 Introduction 2 1 Introduction 2
2 Data types for representing timestamps 4 2 Data types for representing timestamps 4
2.1 Resolution 4 2.1 Resolution 4
2.2 Time scale 4 2.2 Time scale 4
3 API 5 3 API 5
3.1 PPS abstraction 5 3.1 PPS abstraction 5
3.2 New data structures 6 3.2 New data structures 6
skipping to change at page 3, line 5 skipping to change at page 3, line 5
supports the use of external timing sources, such as the precision supports the use of external timing sources, such as the precision
pulse-per-second (PPS) signals typically available from precise time pulse-per-second (PPS) signals typically available from precise time
sources (such as a GPS or GOES receiver). sources (such as a GPS or GOES receiver).
However, RFC1589 did not define an application programming interface However, RFC1589 did not define an application programming interface
(API) for the PPS facility. This document specifies such an (API) for the PPS facility. This document specifies such an
interface, for use with UNIX (or UNIX-like) operating systems. Such interface, for use with UNIX (or UNIX-like) operating systems. Such
systems often conform to the ``Single UNIX Specification'' [5], systems often conform to the ``Single UNIX Specification'' [5],
sometimes known as POSIX. sometimes known as POSIX.
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
One convenient means to provide a PPS signal to a computer system is One convenient means to provide a PPS signal to a computer system is
to connect that signal to a modem-control pin on a serial-line to connect that signal to a modem-control pin on a serial-line
interface to the computer. The Data Carrier Detect (DCD) pin is interface to the computer. The Data Carrier Detect (DCD) pin is
frequently used for this purpose. Typically, the time-code output of frequently used for this purpose. Typically, the time-code output of
the time source is transmitted to the computer over the same serial the time source is transmitted to the computer over the same serial
line. The computer detects a signal transition on the DCD pin, line. The computer detects a signal transition on the DCD pin,
usually by receiving an interrupt, and records a timestamp as soon as usually by receiving an interrupt, and records a timestamp as soon as
possible. possible.
skipping to change at page 3, line 27 skipping to change at page 3, line 27
and DCD transitions, PPS signals might also be delivered by other and DCD transitions, PPS signals might also be delivered by other
kinds of devices. The API specified in this document does not kinds of devices. The API specified in this document does not
require the use of a serial line, although it may be somewhat biased require the use of a serial line, although it may be somewhat biased
in that direction. in that direction.
The typical use of this facility is for the operating system to The typical use of this facility is for the operating system to
record a high-resolution timestamp as soon as possible after it record a high-resolution timestamp as soon as possible after it
detects a PPS signal transition (usually indicated by an interrupt). detects a PPS signal transition (usually indicated by an interrupt).
This timestamp can then be made available, with less stringent delay This timestamp can then be made available, with less stringent delay
constraints, to timekeeping software. The software can compare the constraints, to timekeeping software. The software can compare the
captured timestamp to the received time-code to accurately determine captured timestamp to the received time-code to accurately discover
the absolute offset between the system clock and the precise time the absolute offset between the system clock and the precise time
source. source.
The operating system may also deliver the PPS event to a kernel The operating system may also deliver the PPS event to a kernel
procedure, called the ``in-kernel PPS consumer.'' One example would procedure, called the ``in-kernel PPS consumer.'' One example would
be the ``hardpps()'' procedure, described in RFC1589, which is used be the ``hardpps()'' procedure, described in RFC1589, which is used
to discipline the kernel's internal timebase. to discipline the kernel's internal timebase.
The API specified in this document allows for one or more signal The API specified in this document allows for one or more signal
sources attached to a computer system to provide PPS inputs, at the sources attached to a computer system to provide PPS inputs, at the
skipping to change at page 4, line 5 skipping to change at page 4, line 5
implemented, and does not specify constraints on the accuracy, implemented, and does not specify constraints on the accuracy,
resolution, or latency of the PPS feature. However, the utility of resolution, or latency of the PPS feature. However, the utility of
this feature is inversely proportional to the delay (and variance of this feature is inversely proportional to the delay (and variance of
delay), and implementors are encouraged to take this seriously. delay), and implementors are encouraged to take this seriously.
In principle, the rate of events to be captured, or the frequency of In principle, the rate of events to be captured, or the frequency of
the signals, can range from once per day (or less often) to several the signals, can range from once per day (or less often) to several
thousand per second. However, since in most implementations the thousand per second. However, since in most implementations the
timestamping function will be implemented as a processor interrupt at timestamping function will be implemented as a processor interrupt at
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
a relatively high priority, it is prudent to limit the rate of such a relatively high priority, it is prudent to limit the rate of such
events. This may be done either by mechanisms in the hardware that events. This may be done either by mechanisms in the hardware that
generates the signals, or by the operating system. generates the signals, or by the operating system.
2 Data types for representing timestamps 2 Data types for representing timestamps
Computer systems use various representations of time. Because this Computer systems use various representations of time. Because this
API is concerned with the provision of high-accuracy, high-resolution API is concerned with the provision of high-accuracy, high-resolution
time information, the choice of representation is significant. (Here time information, the choice of representation is significant. (Here
skipping to change at page 5, line 5 skipping to change at page 5, line 5
Several different time scales have been proposed for use in computer Several different time scales have been proposed for use in computer
systems. UTC and TAI are the two obvious candidates. systems. UTC and TAI are the two obvious candidates.
Some people would prefer the use of TAI, which is identical to UTC Some people would prefer the use of TAI, which is identical to UTC
except that it does not correct for leap seconds. Their preference except that it does not correct for leap seconds. Their preference
for TAI stems from the difficulty of computing precise time for TAI stems from the difficulty of computing precise time
differences when leap seconds are involved, especially when using differences when leap seconds are involved, especially when using
times in the future (for which the exact number of leap seconds is, times in the future (for which the exact number of leap seconds is,
in general, unknowable). in general, unknowable).
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
However, POSIX and NTP both use UTC, albeit with different base However, POSIX and NTP both use UTC, albeit with different base
dates. Given that support for TAI would, in general, require other dates. Given that support for TAI would, in general, require other
changes to the POSIX specification, this API uses the POSIX base date changes to the POSIX specification, this API uses the POSIX base date
of 00:00 January 1, 1970 UTC, and conforms to the POSIX use of the of 00:00 January 1, 1970 UTC, and conforms to the POSIX use of the
UTC time scale. UTC time scale.
3 API 3 API
A PPS facility can be used in two different ways: A PPS facility can be used in two different ways:
skipping to change at page 6, line 5 skipping to change at page 6, line 5
--------- ---------
Reminder to implementors of DCD-based PPS support: TTL and Reminder to implementors of DCD-based PPS support: TTL and
RS-232C (V.24/V.28) interfaces both define the "true" state as RS-232C (V.24/V.28) interfaces both define the "true" state as
the one having the highest positive voltage. TTL defines a the one having the highest positive voltage. TTL defines a
nominal absence of voltage as the "false" state, but RS-232C nominal absence of voltage as the "false" state, but RS-232C
(V.24/V.28) defines the "false" state by the presence of a (V.24/V.28) defines the "false" state by the presence of a
negative voltage. negative voltage.
--------- ---------
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
The API supports the direct provision of PPS events (and timestamps) The API supports the direct provision of PPS events (and timestamps)
to an in-kernel PPS consumer. This could be the function called to an in-kernel PPS consumer. This could be the function called
``hardpps()'', as described in RFC1589 [4], but the API does not ``hardpps()'', as described in RFC1589 [4], but the API does not
require the kernel implementation to use that function name require the kernel implementation to use that function name
internally. The current version of the API supports at most one internally. The current version of the API supports at most one
in-kernel PPS consumer, and does not provide a way to explicitly name in-kernel PPS consumer, and does not provide a way to explicitly name
it. The implementation SHOULD impose access controls on the use of it. The implementation SHOULD impose access controls on the use of
this feature. this feature.
The API optionally supports an ``echo'' feature, in which events on The API optionally supports an ``echo'' feature, in which events on
the incoming PPS signal may be reflected through software, after the the incoming PPS signal may be reflected through software, after the
capture of the corresponding timestamp, to an output signal pin. capture of the corresponding timestamp, to an output signal pin.
This feature may be used to determine an upper bound on the actual This feature may be used to discover an upper bound on the actual
delay between the edges of the PPS signal and the capture of the delay between the edges of the PPS signal and the capture of the
timestamps; such information may be useful in precise calibration of timestamps; such information may be useful in precise calibration of
the system. the system.
The designation of an output pin for the echo signal, and sense and The designation of an output pin for the echo signal, and sense and
shape of the output transition, is outside the scope of this shape of the output transition, is outside the scope of this
specification, but SHOULD be documented for each implementation. The specification, but SHOULD be documented for each implementation. The
output pin MAY also undergo transitions at other times besides those output pin MAY also undergo transitions at other times besides those
caused by PPS input events. caused by PPS input events.
skipping to change at page 7, line 5 skipping to change at page 7, line 5
The API includes several implementation-specific types: The API includes several implementation-specific types:
typedef ... pps_handle_t; /* represents a PPS source */ typedef ... pps_handle_t; /* represents a PPS source */
typedef unsigned ... pps_seq_t; /* sequence number */ typedef unsigned ... pps_seq_t; /* sequence number */
The ``pps_handle_t'' type is an opaque scalar type used to represent The ``pps_handle_t'' type is an opaque scalar type used to represent
a PPS source within the API. a PPS source within the API.
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
The ``pps_seq_t'' type is an unsigned integer data type of at least The ``pps_seq_t'' type is an unsigned integer data type of at least
32 bits. 32 bits.
The precise declaration of the pps_handle_t and pps_seq_t types is The precise declaration of the pps_handle_t and pps_seq_t types is
system-dependent. system-dependent.
The API imports the standard POSIX definition for this data type: The API imports the standard POSIX definition for this data type:
struct timespec { struct timespec {
skipping to change at page 8, line 5 skipping to change at page 8, line 5
The API defines these new data structures: The API defines these new data structures:
typedef struct { typedef struct {
pps_seq_t assert_sequence; /* assert event seq # */ pps_seq_t assert_sequence; /* assert event seq # */
pps_seq_t clear_sequence; /* clear event seq # */ pps_seq_t clear_sequence; /* clear event seq # */
pps_timeu_t assert_tu; pps_timeu_t assert_tu;
pps_timeu_t clear_tu; pps_timeu_t clear_tu;
int current_mode; /* current mode bits */ int current_mode; /* current mode bits */
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
} pps_info_t; } pps_info_t;
#define assert_timestamp assert_tu.tspec #define assert_timestamp assert_tu.tspec
#define clear_timestamp clear_tu.tspec #define clear_timestamp clear_tu.tspec
#define assert_timestamp_ntpfp assert_tu.ntpfp #define assert_timestamp_ntpfp assert_tu.ntpfp
#define clear_timestamp_ntpfp clear_tu.ntpfp #define clear_timestamp_ntpfp clear_tu.ntpfp
typedef struct { typedef struct {
skipping to change at page 8, line 38 skipping to change at page 8, line 38
The ``pps_info_t'' type is returned on an inquiry to PPS source. It The ``pps_info_t'' type is returned on an inquiry to PPS source. It
contains the timestamps for the most recent assert event, and the contains the timestamps for the most recent assert event, and the
most recent clear event. The order in which these events were most recent clear event. The order in which these events were
actually received is defined by the timetamps, not by any other actually received is defined by the timetamps, not by any other
aspect of the specification. Each timestamp field represents the aspect of the specification. Each timestamp field represents the
value of the operating system's internal timebase when the value of the operating system's internal timebase when the
timestamped event occurred, or as close as possible to that time timestamped event occurred, or as close as possible to that time
(with the optional addition of a specified offset). The current_mode (with the optional addition of a specified offset). The current_mode
field contains the value of the mode bits (see section 3.3) at the field contains the value of the mode bits (see section 3.3) at the
time of the most recent transition was captured for this PPS source. time of the most recent transition was captured for this PPS source.
An application can use current_mode to determine the format of the An application can use current_mode to discover the format of the
timestamps returned. timestamps returned.
The assert_sequence number increases once per captured assert The assert_sequence number increases once per captured assert
timestamp. Its initial value is undefined. If incremented past the timestamp. Its initial value is undefined. If incremented past the
largest value for the type, the next value is zero. The largest value for the type, the next value is zero. The
clear_sequence number increases once per captured clear timestamp. clear_sequence number increases once per captured clear timestamp.
Its initial value is undefined, and may be different from the initial Its initial value is undefined, and may be different from the initial
value of assert_sequence. If incremented past the largest value for value of assert_sequence. If incremented past the largest value for
the type, the next value is zero. Due to possible signal loss or the type, the next value is zero. Due to possible signal loss or
excessive signal noise, the assert-sequence number and the excessive signal noise, the assert-sequence number and the
clear-sequence number might not always increase in step with each clear-sequence number might not always increase in step with each
other. other.
--------- ---------
Note that these sequence numbers are most useful in Note that these sequence numbers are most useful in
applications where events other than PPS transitions are to be applications where events other than PPS transitions are to be
captured, which might be involved in a precision stopwatch captured, which might be involved in a precision stopwatch
application, for example. In such cases, the sequence numbers application, for example. In such cases, the sequence numbers
may be used to detect overruns, where the application has may be used to detect overruns, where the application has
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
missed one or more events. They may also be used to detect an missed one or more events. They may also be used to detect an
excessive event rate, or to detect that an event has failed to excessive event rate, or to detect that an event has failed to
occur between two calls to the time_pps_fetch() function occur between two calls to the time_pps_fetch() function
(defined later). (defined later).
In order to obtain an uninterrupted series of sequence numbers In order to obtain an uninterrupted series of sequence numbers
(and hence of event timestamps), it may be necessary to sample (and hence of event timestamps), it may be necessary to sample
the pps_info_t values at a rate somewhat faster than the the pps_info_t values at a rate somewhat faster than the
underlying event rate. For example, an application interested underlying event rate. For example, an application interested
skipping to change at page 10, line 5 skipping to change at page 10, line 5
The bits in the mode field of the pps_params_t type are: The bits in the mode field of the pps_params_t type are:
/* Device/implementation parameters */ /* Device/implementation parameters */
#define PPS_CAPTUREASSERT 0x01 #define PPS_CAPTUREASSERT 0x01
#define PPS_CAPTURECLEAR 0x02 #define PPS_CAPTURECLEAR 0x02
#define PPS_CAPTUREBOTH 0x03 #define PPS_CAPTUREBOTH 0x03
#define PPS_OFFSETASSERT 0x10 #define PPS_OFFSETASSERT 0x10
#define PPS_OFFSETCLEAR 0x20 #define PPS_OFFSETCLEAR 0x20
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
#define PPS_CANWAIT 0x100 #define PPS_CANWAIT 0x100
#define PPS_CANPOLL 0x200 #define PPS_CANPOLL 0x200
/* Kernel actions */ /* Kernel actions */
#define PPS_ECHOASSERT 0x40 #define PPS_ECHOASSERT 0x40
#define PPS_ECHOCLEAR 0x80 #define PPS_ECHOCLEAR 0x80
/* Timestamp formats */ /* Timestamp formats */
#define PPS_TSFMT_TSPEC 0x1000 #define PPS_TSFMT_TSPEC 0x1000
skipping to change at page 11, line 5 skipping to change at page 11, line 5
PPS_CAPTUREBOTH Defined as the union of PPS_CAPTUREASSERT and PPS_CAPTUREBOTH Defined as the union of PPS_CAPTUREASSERT and
PPS_CAPTURECLEAR, for convenience. PPS_CAPTURECLEAR, for convenience.
PPS_OFFSETASSERT PPS_OFFSETASSERT
If set, the assert_offset value is added to the If set, the assert_offset value is added to the
current value of the operating system's internal current value of the operating system's internal
timebase in order to generate the captured timebase in order to generate the captured
assert_timestamp. assert_timestamp.
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
PPS_OFFSETCLEAR If set, the clear_offset value is added to the PPS_OFFSETCLEAR If set, the clear_offset value is added to the
current value of the operating system's internal current value of the operating system's internal
timebase in order to generate the captured timebase in order to generate the captured
clear_timestamp. clear_timestamp.
PPS_CANWAIT If set, the application may request that the PPS_CANWAIT If set, the application may request that the
time_pps_fetch() function (see section 3.4.3) should time_pps_fetch() function (see section 3.4.3) should
block until the next timestamp arrives. Note: this block until the next timestamp arrives. Note: this
mode bit is read-only. mode bit is read-only.
skipping to change at page 12, line 5 skipping to change at page 12, line 5
Support for this format is OPTIONAL. Support for this format is OPTIONAL.
Other timestamp format bits may be defined as fields are added to the Other timestamp format bits may be defined as fields are added to the
``pps_timeu_t'' union. ``pps_timeu_t'' union.
The operating system may implement all of these mode bits, or just a The operating system may implement all of these mode bits, or just a
subset of them. If an attempt is made to set an unsupported mode subset of them. If an attempt is made to set an unsupported mode
bit, the API will return an error. If an attempt is made to modify a bit, the API will return an error. If an attempt is made to modify a
read-only mode bit, the API will return an error. read-only mode bit, the API will return an error.
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
3.4 New functions 3.4 New functions
In the description of functions that follows, we use the following In the description of functions that follows, we use the following
function parameters: function parameters:
filedes A file descriptor (type: int), for a serial line or filedes A file descriptor (type: int), for a serial line or
other source of PPS events. other source of PPS events.
ppshandle A variable of type ``pps_handle_t'', as defined in ppshandle A variable of type ``pps_handle_t'', as defined in
section 3.2. section 3.2.
ppsinfobuf A record of type ``pps_info_t'', as defined in ppsinfobuf A record of type ``pps_info_t'', as defined in
section 3.2. section 3.2.
ppsparams A record of type ``pps_params_t'', as defined in ppsparams A record of type ``pps_params_t'', as defined in
section 3.2. section 3.2.
tsformat An integer with exactly one of the timestamp format tsformat An integer with exactly one of the timestamp format
bits set. bits set.
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
3.4.1 New functions: obtaining PPS sources 3.4.1 New functions: obtaining PPS sources
The API includes a function to create and destroy PPS source The API includes a function to create and destroy PPS source
``handles''. ``handles''.
SYNOPSIS SYNOPSIS
int time_pps_create(int filedes, pps_handle_t *handle); int time_pps_create(int filedes, pps_handle_t *handle);
int time_pps_destroy(pps_handle_t handle); int time_pps_destroy(pps_handle_t handle);
skipping to change at page 14, line 5 skipping to change at page 14, line 5
close the associated file descriptor, nor does it change any of the close the associated file descriptor, nor does it change any of the
parameter settings for the PPS source. parameter settings for the PPS source.
--------- ---------
Note: If this API is adapted to an operating system that does Note: If this API is adapted to an operating system that does
not follow UNIX conventions for representing an accessible PPS not follow UNIX conventions for representing an accessible PPS
source as an integer file descriptor, the time_pps_create() source as an integer file descriptor, the time_pps_create()
function may take different parameters from those shown here. function may take different parameters from those shown here.
--------- ---------
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
RETURN VALUES RETURN VALUES
On successful completion, the time_pps_create() function returns 0. On successful completion, the time_pps_create() function returns 0.
Otherwise, a value of -1 is returned and errno is set to indicate the Otherwise, a value of -1 is returned and errno is set to indicate the
error. error.
If called with a valid handle parameter, the time_pps_destroy() If called with a valid handle parameter, the time_pps_destroy()
function returns 0. Otherwise, it returns -1. function returns 0. Otherwise, it returns -1.
skipping to change at page 15, line 5 skipping to change at page 15, line 5
the following values: the following values:
[EBADF] The filedes parameter is not a valid file descriptor. [EBADF] The filedes parameter is not a valid file descriptor.
[EOPNOTSUPP] The use of the PPS API is not supported for the file [EOPNOTSUPP] The use of the PPS API is not supported for the file
descriptor. descriptor.
[EPERM] The process's effective user ID does not have the [EPERM] The process's effective user ID does not have the
required privileges to use the PPS API. required privileges to use the PPS API.
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
3.4.2 New functions: setting PPS parameters 3.4.2 New functions: setting PPS parameters
The API includes several functions use to set or obtain the The API includes several functions use to set or obtain the
parameters of a PPS source. parameters of a PPS source.
SYNOPSIS SYNOPSIS
int time_pps_setparams(pps_handle_t handle, int time_pps_setparams(pps_handle_t handle,
const pps_params_t *ppsparams); const pps_params_t *ppsparams);
int time_pps_getparams(pps_handle_t handle, int time_pps_getparams(pps_handle_t handle,
skipping to change at page 16, line 5 skipping to change at page 16, line 5
kernel provides the timestamp format of the offsets by setting one of kernel provides the timestamp format of the offsets by setting one of
the timestamp format bits in the mode field. the timestamp format bits in the mode field.
--------- ---------
Note: an application that uses time_pps_getparams() to read the Note: an application that uses time_pps_getparams() to read the
current offset values cannot specify which format is used. The current offset values cannot specify which format is used. The
implementation SHOULD return the offsets using the same implementation SHOULD return the offsets using the same
timestamp format as was used when the offsets were set. timestamp format as was used when the offsets were set.
--------- ---------
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
An application wishing to discover which mode bits it may set, with An application wishing to discover which mode bits it may set, with
its current effective user ID, may call time_pps_getcap(). This its current effective user ID, may call time_pps_getcap(). This
function returns the set of mode bits that may be set by the function returns the set of mode bits that may be set by the
application, without generating an EINVAL or EPERM error, for the application, without generating an EINVAL or EPERM error, for the
specified PPS source. It does not return the current values for the specified PPS source. It does not return the current values for the
mode bits. A call to time_pps_getcap() returns the mode bits mode bits. A call to time_pps_getcap() returns the mode bits
corresponding to all supported timestamp formats. corresponding to all supported timestamp formats.
The time_pps_getcap() function MAY ignore the mode in which the The time_pps_getcap() function MAY ignore the mode in which the
skipping to change at page 17, line 5 skipping to change at page 17, line 5
[EOPNOTSUPP] The use of the PPS API is not supported for the [EOPNOTSUPP] The use of the PPS API is not supported for the
associated file descriptor. associated file descriptor.
[EINVAL] The operating system does not support all of the [EINVAL] The operating system does not support all of the
requested mode bits. requested mode bits.
[EPERM] The process's effective user ID does not have the [EPERM] The process's effective user ID does not have the
required privileges to use the PPS API, or to set the required privileges to use the PPS API, or to set the
given mode bits. given mode bits.
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
3.4.3 New functions: access to PPS timestamps 3.4.3 New functions: access to PPS timestamps
The API includes one function that gives applications access to PPS The API includes one function that gives applications access to PPS
timestamps. As an implementation option, the application may request timestamps. As an implementation option, the application may request
the API to block until the next timestamp is captured. (The API does the API to block until the next timestamp is captured. (The API does
not directly support the use of the select() or poll() system calls not directly support the use of the select() or poll() system calls
to wait for PPS events.) to wait for PPS events.)
SYNOPSIS SYNOPSIS
skipping to change at page 17, line 38 skipping to change at page 17, line 38
This function blocks until either a timestamp is captured from the This function blocks until either a timestamp is captured from the
PPS source, or until the specified timeout duration has expired. If PPS source, or until the specified timeout duration has expired. If
the timeout parameter is a NULL pointer, the function simply blocks the timeout parameter is a NULL pointer, the function simply blocks
until a timestamp is captured. If the timeout parameter specifies a until a timestamp is captured. If the timeout parameter specifies a
delay of zero, the function returns immediately. delay of zero, the function returns immediately.
Support for blocking behavior is an implementation option. If the Support for blocking behavior is an implementation option. If the
PPS_CANWAIT mode bit is clear, and the timeout parameter is either PPS_CANWAIT mode bit is clear, and the timeout parameter is either
NULL or points to a non-zero value, the function returns an NULL or points to a non-zero value, the function returns an
EOPNOTSUPP error. An application can determine whether the feature EOPNOTSUPP error. An application can discover whether the feature is
is implemented by using time_pps_getcap() to see if the PPS_CANWAIT implemented by using time_pps_getcap() to see if the PPS_CANWAIT mode
mode bit is set. bit is set.
The result is stored in the ppsinfobuf parameter, whose fields are The result is stored in the ppsinfobuf parameter, whose fields are
defined in section 3.2. If the function returns as the result of a defined in section 3.2. If the function returns as the result of a
timeout or error, the contents of the ppsinfobuf are undefined. timeout or error, the contents of the ppsinfobuf are undefined.
If this function is invoked before the system has captured a If this function is invoked before the system has captured a
timestamp for the signal source, the ppsinfobuf returned will have timestamp for the signal source, the ppsinfobuf returned will have
its timestamp fields set to the time format's base date (e.g., for its timestamp fields set to the time format's base date (e.g., for
PPS_TSFMT_TSPEC, both the tv_sec and tv_nsec fields will be zero). PPS_TSFMT_TSPEC, both the tv_sec and tv_nsec fields will be zero).
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
RETURN VALUES RETURN VALUES
On successful completion, the time_pps_fetch() function returns 0. On successful completion, the time_pps_fetch() function returns 0.
Otherwise, a value of -1 is returned and errno is set to indicate the Otherwise, a value of -1 is returned and errno is set to indicate the
error. error.
ERRORS ERRORS
If the time_pps_fetch() function fails, errno may be set to one of If the time_pps_fetch() function fails, errno may be set to one of
skipping to change at page 19, line 5 skipping to change at page 19, line 5
specified by the timeout parameter expired and before specified by the timeout parameter expired and before
a timestamp has been captured. a timestamp has been captured.
[EINVAL] The requested timestamp format is not supported. [EINVAL] The requested timestamp format is not supported.
[EOPNOTSUPP] The use of the PPS API is not supported for the [EOPNOTSUPP] The use of the PPS API is not supported for the
associated file descriptor. associated file descriptor.
[ETIMEDOUT] The timeout duration has expired. [ETIMEDOUT] The timeout duration has expired.
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
3.4.4 New functions: disciplining the kernel timebase 3.4.4 New functions: disciplining the kernel timebase
The API includes one OPTIONAL function to specify if and how a PPS The API includes one OPTIONAL function to specify if and how a PPS
source is provided to a kernel consumer of PPS events, such as the source is provided to a kernel consumer of PPS events, such as the
code used to discipline the operating system's internal timebase. code used to discipline the operating system's internal timebase.
SYNOPSIS SYNOPSIS
int time_pps_kcbind(pps_handle_t handle, int time_pps_kcbind(pps_handle_t handle,
const int kernel_consumer, const int kernel_consumer,
skipping to change at page 20, line 5 skipping to change at page 20, line 5
value PPS_CAPTUREASSERT, PPS_CAPTURECLEAR, or PPS_CAPTUREBOTH, value PPS_CAPTUREASSERT, PPS_CAPTURECLEAR, or PPS_CAPTUREBOTH,
depending on particular characteristics of the PPS source. It may depending on particular characteristics of the PPS source. It may
also be zero, which removes any binding between the PPS source and also be zero, which removes any binding between the PPS source and
the kernel consumer. the kernel consumer.
The tsformat parameter specifies the format for the timestamps The tsformat parameter specifies the format for the timestamps
delivered to the kernel consumer. If this value is zero, the delivered to the kernel consumer. If this value is zero, the
implementation MAY choose the appropriate format, or return EINVAL. implementation MAY choose the appropriate format, or return EINVAL.
The implementation MAY ignore a non-zero value for this parameter. The implementation MAY ignore a non-zero value for this parameter.
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
The binding created by this call persists until it is changed by a The binding created by this call persists until it is changed by a
subsequent call specifying the same kernel_consumer. In particular, subsequent call specifying the same kernel_consumer. In particular,
a subsequent call to time_pps_destroy() for the specified handle does a subsequent call to time_pps_destroy() for the specified handle does
not affect the binding. not affect the binding.
The binding is independent of any prior or subsequent changes to the The binding is independent of any prior or subsequent changes to the
PPS_CAPTUREASSERT and PPS_CAPTURECLEAR mode bits for the device. PPS_CAPTUREASSERT and PPS_CAPTURECLEAR mode bits for the device.
However, if either the edge or the tsformat parameter values are However, if either the edge or the tsformat parameter values are
inconsistent with the capabilities of the PPS source, an error is inconsistent with the capabilities of the PPS source, an error is
skipping to change at page 21, line 5 skipping to change at page 21, line 5
See RFC1589 [4] for more information about how the system's timebase See RFC1589 [4] for more information about how the system's timebase
may be disciplined using a PPS signal. may be disciplined using a PPS signal.
RETURN VALUES RETURN VALUES
On successful completion, the time_pps_kcbind() function returns 0. On successful completion, the time_pps_kcbind() function returns 0.
Otherwise, a value of -1 is returned and errno is set to indicate the Otherwise, a value of -1 is returned and errno is set to indicate the
error. error.
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
ERRORS ERRORS
If the time_pps_kcbind() function fails, errno may be set to one of If the time_pps_kcbind() function fails, errno may be set to one of
the following values: the following values:
[EBADF] The handle parameter is not associated with a valid [EBADF] The handle parameter is not associated with a valid
file descriptor, or the descriptor is not open for file descriptor, or the descriptor is not open for
writing. writing.
skipping to change at page 22, line 5 skipping to change at page 22, line 5
[EINVAL] The requested timestamp format is not supported. [EINVAL] The requested timestamp format is not supported.
[EOPNOTSUPP] The use of the PPS API is not supported for the [EOPNOTSUPP] The use of the PPS API is not supported for the
associated file descriptor, or this OPTIONAL function associated file descriptor, or this OPTIONAL function
is not supported. is not supported.
[EPERM] The process's effective user ID does not have the [EPERM] The process's effective user ID does not have the
required privileges to set the binding. required privileges to set the binding.
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
3.5 Compliance rules 3.5 Compliance rules
The key words "MUST", "MUST NOT", "REQUIRED","SHOULD", SHOULD NOT", The key words "MUST", "MUST NOT", "REQUIRED","SHOULD", SHOULD NOT",
"MAY", and "OPTIONAL" in this document are to be interpreted as "MAY", and "OPTIONAL" in this document are to be interpreted as
described in RFC2119 [1]. described in RFC2119 [1].
Some features of this specification are OPTIONAL, but others are Some features of this specification are OPTIONAL, but others are
REQUIRED. REQUIRED.
3.5.1 Functions 3.5.1 Functions
skipping to change at page 23, line 5 skipping to change at page 23, line 5
An implementation MAY support these mode bits: An implementation MAY support these mode bits:
- PPS_ECHOASSERT - PPS_ECHOASSERT
- PPS_ECHOCLEAR - PPS_ECHOCLEAR
- PPS_OFFSETASSERT - PPS_OFFSETASSERT
- PPS_OFFSETCLEAR - PPS_OFFSETCLEAR
An implementation MAY support this timestamp format: An implementation MAY support this timestamp format:
- PPS_TSFMT_NTPFP - PPS_TSFMT_NTPFP
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
3.6 Examples 3.6 Examples
A very simple use of this API might be: A very simple use of this API might be:
int fd; int fd;
pps_handle_t handle; pps_handle_t handle;
pps_params_t params; pps_params_t params;
pps_info_t infobuf; pps_info_t infobuf;
struct timespec timeout; struct timespec timeout;
skipping to change at page 24, line 5 skipping to change at page 24, line 5
might be more reliably accomplished using: might be more reliably accomplished using:
timeout.tv_sec = 100; timeout.tv_sec = 100;
timeout.tv_nsec = 0; timeout.tv_nsec = 0;
time_pps_fetch(handle, PPS_TSFMT_TSPEC, &infobuf, &timeout); time_pps_fetch(handle, PPS_TSFMT_TSPEC, &infobuf, &timeout);
The (arbitrary) timeout value is used to protect against the The (arbitrary) timeout value is used to protect against the
possibility that another application might disable PPS timestamps, or possibility that another application might disable PPS timestamps, or
that the hardware generating the timestamps might fail. that the hardware generating the timestamps might fail.
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
A slightly more elaborate use of this API might be: A slightly more elaborate use of this API might be:
int fd; int fd;
pps_handle_t handle; pps_handle_t handle;
pps_params_t params; pps_params_t params;
pps_info_t infobuf; pps_info_t infobuf;
int avail_mode; int avail_mode;
struct timespec timeout; struct timespec timeout;
skipping to change at page 25, line 5 skipping to change at page 25, line 5
/* loop, printing the most recent timestamp every second or so */ /* loop, printing the most recent timestamp every second or so */
while (1) { while (1) {
if (avail_mode & PPS_CANWAIT) { if (avail_mode & PPS_CANWAIT) {
time_pps_fetch(handle, PPS_TSFMT_TSPEC, &infobuf, NULL); time_pps_fetch(handle, PPS_TSFMT_TSPEC, &infobuf, NULL);
/* waits for the next event */ /* waits for the next event */
} else { } else {
sleep(1); sleep(1);
time_pps_fetch(handle, PPS_TSFMT_TSPEC, &infobuf, time_pps_fetch(handle, PPS_TSFMT_TSPEC, &infobuf,
timeout); timeout);
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
} }
printf("Assert timestamp: %d.%09d, sequence: %ld\n", printf("Assert timestamp: %d.%09d, sequence: %ld\n",
infobuf.assert_timestamp.tv_sec, infobuf.assert_timestamp.tv_sec,
infobuf.assert_timestamp.tv_nsec, infobuf.assert_timestamp.tv_nsec,
infobuf.assert_sequence); infobuf.assert_sequence);
} }
Again, most of the necessary error-checking has been omitted from Again, most of the necessary error-checking has been omitted from
this example. this example.
skipping to change at page 25, line 49 skipping to change at page 25, line 49
The final capability is reserved to highly privileged users. In UNIX The final capability is reserved to highly privileged users. In UNIX
systems, this means those with superuser privilege. Such users can systems, this means those with superuser privilege. Such users can
evade protections based on file permissions; however, such users can evade protections based on file permissions; however, such users can
in general cause unbounded havoc, and can set the internal timebase in general cause unbounded havoc, and can set the internal timebase
(and its rate of change), so this API creates no new vulnerabilities. (and its rate of change), so this API creates no new vulnerabilities.
5 Acknowledgements 5 Acknowledgements
The API in this document draws some of its inspiration from the LBL The API in this document draws some of its inspiration from the LBL
``ppsclock'' distribution [2], originally implemented in 1993 by ``ppsclock'' distribution [2], originally implemented in 1993 by
Steve McCanne, Craig Leres, and Van Jacobson. We also thank Craig Steve McCanne, Craig Leres, and Van Jacobson. We also thank
Leres, Judah Levine, and Harlan Stenn for helpful comments they Poul-Henning Kamp, Craig Leres, Judah Levine, and Harlan Stenn for
contributed during the drafting of this document. helpful comments they contributed during the drafting of this
document.
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36 Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
6 References 6 References
1. Scott Bradner. Key words for use in RFCs to Indicate Requirement 1. Scott Bradner. Key words for use in RFCs to Indicate Requirement
Levels. RFC 2119, Harvard University, March, 1997. Levels. RFC 2119, Harvard University, March, 1997.
2. Steve McCanne, Craig Leres, and Van Jacobson. PPSCLOCK. 2. Steve McCanne, Craig Leres, and Van Jacobson. PPSCLOCK.
ftp://ftp.ee.lbl.gov/ppsclock.tar.Z. ftp://ftp.ee.lbl.gov/ppsclock.tar.Z.
3. David L. Mills. Network Time Protocol (Version 3): 3. David L. Mills. Network Time Protocol (Version 3):
skipping to change at page 26, line 55 skipping to change at page 27, line 5
901 San Antonio Rd M/S MPK17-202 901 San Antonio Rd M/S MPK17-202
Palo Alto, CA 94303 Palo Alto, CA 94303
Email: Jan.Brittenson@Eng.Sun.COM Email: Jan.Brittenson@Eng.Sun.COM
Jonathan Stone Jonathan Stone
Stanford Distributed Systems Group Stanford Distributed Systems Group
Stanford, CA 94305 Stanford, CA 94305
Phone: (650) 723-2513 Phone: (650) 723-2513
Email: jonathan@dsg.stanford.edu Email: jonathan@dsg.stanford.edu
Poul-Henning Kamp Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
The FreeBSD Project
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36
Valbygaardsvej 8
DK-4200 Slagelse
Denmark
Phone: +45 58 56 10 59
Email: phk@FreeBSD.org
Ulrich Windl Ulrich Windl
Universitaet Regensburg, Klinikum Universitaet Regensburg, Klinikum
Email: ulrich.windl@rz.uni-regensburg.de Email: ulrich.windl@rz.uni-regensburg.de
A. Extensions and related APIs A. Extensions and related APIs
The API specified in the main body of this document could be more The API specified in the main body of this document could be more
useful with the provision of several extensions or companion APIs. useful with the provision of several extensions or companion APIs.
skipping to change at page 28, line 4 skipping to change at page 27, line 48
serial lines, parallel interfaces, and bus-level interfaces). These serial lines, parallel interfaces, and bus-level interfaces). These
reference clocks can have many features and parameters, some of which reference clocks can have many features and parameters, some of which
might not even have been invented yet. might not even have been invented yet.
We believe that it would be useful to have a mechanism by which an We believe that it would be useful to have a mechanism by which an
application can discover arbitrary features and parameters of a application can discover arbitrary features and parameters of a
reference clock. These might include: reference clock. These might include:
- Clock manufacturer, model number, and revision level - Clock manufacturer, model number, and revision level
- Whether the clock is synchronized to an absolute standard - Whether the clock is synchronized to an absolute standard
- For synchronized clocks, - For synchronized clocks,
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36
* The specific standard * The specific standard
* The accuracy of the standard * The accuracy of the standard
* The path used (direct connection, shortwave, longwave, * The path used (direct connection, shortwave, longwave,
satellite, etc.) satellite, etc.)
* The distance (offset) and variability of this path * The distance (offset) and variability of this path
Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
- For PPS sources, - For PPS sources,
* The pulse rate * The pulse rate
* The pulse shape * The pulse shape
* Which edge of the pulse corresponds to the epoch * Which edge of the pulse corresponds to the epoch
- The time representation format - The time representation format
This information might best be provided by an API analogous to the This information might best be provided by an API analogous to the
standard ``curses'' API, with a database analogous to the standard standard ``curses'' API, with a database analogous to the standard
``terminfo'' database. That is, a ``clockinfo'' database would ``terminfo'' database. That is, a ``clockinfo'' database would
skipping to change at page 29, line 5 skipping to change at page 28, line 50
The index argument implicitly sets up an ordering on the PPS sources The index argument implicitly sets up an ordering on the PPS sources
attached to the system. An application would use this function to attached to the system. An application would use this function to
inquire about the Nth source. The function would return -1 if no inquire about the Nth source. The function would return -1 if no
such source exists; otherwise, it would return 0, and would place the such source exists; otherwise, it would return 0, and would place the
pathname of the associated special file in the path argument. It pathname of the associated special file in the path argument. It
would also place an identification string in the idstring argument. would also place an identification string in the idstring argument.
The identification string could include the clock make, model, The identification string could include the clock make, model,
version, etc., which could then be used by the application to control version, etc., which could then be used by the application to control
its behavior. its behavior.
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36
This function might simply read the Nth line from a simple database, This function might simply read the Nth line from a simple database,
containing lines such as: containing lines such as:
/dev/tty00 "TrueTime 468-DC" /dev/tty00 "TrueTime 468-DC"
/dev/pps1 "Homebrew rubidium frequency standard" /dev/pps1 "Homebrew rubidium frequency standard"
Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
allowing the system administrator to describe the configuration of allowing the system administrator to describe the configuration of
PPS sources. PPS sources.
B. Example implementation: PPSDISC Line discipline B. Example implementation: PPSDISC Line discipline
One possible implementation of the PPS API might be to define a new 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() ``line discipline'' and then map the API onto a set of ioctl()
commands. Here we sketch such an implementation; note that this is commands. Here we sketch such an implementation; note that this is
not part of the specification of the API, and applications should not not part of the specification of the API, and applications should not
expect this low-level interface to be available. expect this low-level interface to be available.
skipping to change at page 30, line 4 skipping to change at page 29, line 49
pps_info_t infobuf; pps_info_t infobuf;
ioctl(fd, TIOCSETD, &ldisc); /* set discipline */ ioctl(fd, TIOCSETD, &ldisc); /* set discipline */
/* /*
* Check the capabilities of this PPS source to see * Check the capabilities of this PPS source to see
* if it supports what we need. * if it supports what we need.
*/ */
ioctl(fd, PPSGETCAP, &params); ioctl(fd, PPSGETCAP, &params);
if ((params.mode & PPS_CAPTUREASSERT) == 0) { if ((params.mode & PPS_CAPTUREASSERT) == 0) {
Internet-Draft Pulse-Per-Second API 23 July 1999 16:36
fprintf(stderr, "PPS source is not suitable\n"); fprintf(stderr, "PPS source is not suitable\n");
exit(1); exit(1);
} }
/* /*
* Set this line to timestamp on a rising-edge interrupt * Set this line to timestamp on a rising-edge interrupt
Internet-Draft Pulse-Per-Second API 17 August 1999 11:18
*/ */
ioctl(fd, PPSGETPARAMS, &params); ioctl(fd, PPSGETPARAMS, &params);
params.mode |= PPS_CAPTUREASSERT; params.mode |= PPS_CAPTUREASSERT;
ioctl(fd, PPSSETPARAMS, &params); ioctl(fd, PPSSETPARAMS, &params);
sleep(2); /* allow time for the PPS pulse to happen */ sleep(2); /* allow time for the PPS pulse to happen */
/* obtain most recent timestamp and sequence # for this line */ /* obtain most recent timestamp and sequence # for this line */
ioctl(fd, PPSFETCH, &infobuf); ioctl(fd, PPSFETCH, &infobuf);
Again, this example imprudently omits any error-checking. Again, this example imprudently omits any error-checking.
C. Available implementations C. Available implementations
Several available implementations of this API are listed at Several available implementations of this API are listed at
<http://www.ntp.org/ppsapi/PPSImpList.html>. <http://www.ntp.org/ppsapi/PPSImpList.html>. Note that not all of
these implementations correspond to the current version of the
specification.
 End of changes. 42 change blocks. 
56 lines changed or deleted 46 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/