rfc2783.txt

来自「中、英文RFC文档大全打包下载完全版 .」· 文本 代码 · 共 1,740 行 · 第 1/4 页

Network Working Group                                          J. Mogul
Request for Comments: 2783                                   Compaq WRL
Category: Informational                                        D. Mills
                                                 University of Delaware
                                                          J. Brittenson
                                                                    Sun
                                                               J. Stone
                                                               Stanford
                                                               U. Windl
                                                Universitaet Regensburg
                                                             March 2000


   Pulse-Per-Second API for UNIX-like Operating Systems, Version 1.0

Status of this Memo

   This memo provides information for the Internet community.  It does
   not specify an Internet standard of any kind.  Distribution of this
   memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2000).  All Rights Reserved.

Abstract

   RFC 1589 describes a UNIX kernel implementation model for high-
   precision time-keeping.  This model is meant for use in conjunction
   with the Network Time Protocol (NTP, RFC 1305), or similar time
   synchronization protocols.  One aspect of this model is an accurate
   interface to the high-accuracy, one pulse-per-second (PPS) output
   typically available from precise time sources (such as a GPS or GOES
   receiver).  RFC 1589 did not define an API for managing the PPS
   facility, leaving implementors without a portable means for using PPS
   sources.  This document specifies such an API.















Mogul, et al.                Informational                      [Page 1]

RFC 2783                  Pulse-Per-Second API                March 2000


Table of Contents

   1 Introduction...................................................  2
   2 Data types for representing timestamps.........................  4
   2.1 Resolution...................................................  4
   2.2 Time scale...................................................  5
   3 API............................................................  5
   3.1 PPS abstraction..............................................  6
   3.2 New data structures..........................................  7
   3.3 Mode bit definitions......................................... 10
   3.4 New functions................................................ 12
   3.4.1 New functions: obtaining PPS sources....................... 13
   3.4.2 New functions: setting PPS parameters...................... 14
   3.4.3 New functions: access to PPS timestamps.................... 16
   3.4.4 New functions: disciplining the kernel timebase............ 18
   3.5 Compliance rules............................................. 20
   3.5.1 Functions.................................................. 20
   3.5.2 Mode bits.................................................. 20
   3.6 Examples..................................................... 21
   4 Security Considerations........................................ 24
   5 Acknowledgements............................................... 24
   6 References..................................................... 25
   7 Authors' Addresses............................................. 26
   A. Extensions and related APIs................................... 27
   A.1 Extension: Parameters for the "echo" mechanism............... 27
   A.2 Extension: Obtaining information about external clocks....... 27
   A.3 Extension: Finding a PPS source.............................. 28
   B. Example implementation: PPSDISC Line discipline............... 29
   B.1 Example...................................................... 29
   C. Available implementations..................................... 30
   Full Copyright Statement......................................... 31

1 Introduction

   RFC 1589 [4] describes a model and programming interface for generic
   operating system software that manages the system clock and timer
   functions. The model provides improved accuracy and stability for
   most workstations and servers using the Network Time Protocol (NTP)
   [3] or similar time synchronization protocol.  The model supports the
   use of external timing sources, such as the precision pulse-per-
   second (PPS) signals typically available from precise time sources
   (such as a GPS or GOES receiver).

   However, RFC 1589 did not define an application programming interface
   (API) for the PPS facility.  This document specifies such an
   interface, for use with UNIX (or UNIX-like) operating systems.  Such
   systems often conform to the "Single UNIX Specification" [5],
   sometimes known as POSIX.



Mogul, et al.                Informational                      [Page 2]

RFC 2783                  Pulse-Per-Second API                March 2000


   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
   interface to the computer.  The Data Carrier Detect (DCD) pin is
   frequently used for this purpose.  Typically, the time-code output of
   the time source is transmitted to the computer over the same serial
   line.  The computer detects a signal transition on the DCD pin,
   usually by receiving an interrupt, and records a timestamp as soon as
   possible.

   Although existing practice has focussed on the use of serial lines
   and DCD transitions, PPS signals might also be delivered by other
   kinds of devices.  The API specified in this document does not
   require the use of a serial line, although it may be somewhat biased
   in that direction.

   The typical use of this facility is for the operating system to
   record ("capture") a high-resolution timestamp as soon as possible
   after it detects a PPS signal transition (usually indicated by an
   interrupt).  This timestamp can then be made available, with less
   stringent delay constraints, to time-related software.  The software
   can compare the captured timestamp to the received time-code to
   accurately discover the offset between the system clock and the
   precise time source.

   The operating system may also deliver the PPS event to a kernel
   procedure, called the "in-kernel PPS consumer."  One example would be
   the "hardpps()" procedure, described in RFC 1589, which is used to
   discipline the kernel's internal timebase.

   The API specified in this document allows for one or more signal
   sources attached to a computer system to provide PPS inputs, at the
   option of user-level software.  User-level software may obtain
   signal-transition timestamps for any of these PPS sources.  User-
   level software may optionally specify at most one of these PPS
   sources to be used to discipline the system's internal timebase.

   Although the primary purpose of this API is for capturing true
   pulse-per-second events, the API may also be used for accurately
   timestamping events of other periods, or even aperiodic events, when
   these can be expressed as signal transitions.

   This document does not define internal details of how the API must be
   implemented, and does not specify constraints on the accuracy,
   resolution, or latency of the PPS feature.  However, the utility of
   this feature is inversely proportional to the delay (and variance of
   delay), and implementors are encouraged to take this seriously.





Mogul, et al.                Informational                      [Page 3]

RFC 2783                  Pulse-Per-Second API                March 2000


   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
   thousand per second.  However, since in most implementations the
   timestamping function will be implemented as a processor interrupt at
   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
   generates the signals, or by the operating system.

2 Data types for representing timestamps

   Computer systems use various representations of time.  Because this
   API is concerned with the provision of high-accuracy, high-resolution
   time information, the choice of representation is significant.  (Here
   we consider only binary representations, not human-format
   representations.)

   The two interesting questions are:

      1. what is the resolution of the representation?

      2. what time scale is represented?

   These questions often lead to contentious arguments.  Since this API
   is intended for use with NTP and POSIX-compliant systems, however, we
   can limit the choices to representations compatible with existing NTP
   and POSIX practice, even if that practice is considered "wrong" in
   some quarters.

2.1 Resolution

   In the NTP protocol, "timestamps are represented as a 64-bit unsigned
   fixed-point number, in seconds relative to 0h on 1 January 1900. The
   integer part is in the first 32 bits and the fraction part in the
   last 32 bits [...] The precision of this representation is about 200
   picoseconds" [3].

   However, most computer systems cannot measure time to this resolution
   (this represents a clock rate of 5 GHz).  The POSIX gettimeofday()
   function returns a "struct timeval" value, with a resolution of 1
   microsecond.  The POSIX clock_gettime() function returns a "struct
   timespec" value, with a resolution of 1 nanosecond.

   This API uses an extensible representation, but defaults to the
   "struct timespec" representation.







Mogul, et al.                Informational                      [Page 4]

RFC 2783                  Pulse-Per-Second API                March 2000


2.2 Time scale

   Several different time scales have been proposed for use in computer
   systems.  UTC and TAI are the two obvious candidates.

   Some people would prefer the use of TAI, which is identical to UTC
   except that it does not correct for leap seconds.  Their preference
   for TAI stems from the difficulty of computing precise time
   differences when leap seconds are involved, especially when using
   times in the future (for which the exact number of leap seconds is,
   in general, unknowable).

   However, POSIX and NTP both use UTC, albeit with different base
   dates.  Given that support for TAI would, in general, require other
   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
   UTC time scale.

3 API

   A PPS facility can be used in two different ways:

      1. An application can obtain a timestamp, using the system's
         internal timebase, for the most recent PPS event.

      2. The kernel may directly utilize PPS events to discipline its
         internal timebase, thereby providing highly accurate time to
         all applications.

   This API supports both uses, individually or in combination.  The
   timestamping feature may be used on any number of PPS sources
   simultaneously; the timebase-disciplining feature may be used with at
   most one PPS source.

   Although the proper implementation of this API requires support from
   the kernel of a UNIX system, this document defines the API in terms
   of a set of library routines.  This gives the implementor some
   freedom to divide the effort between kernel code and library code
   (different divisions might be appropriate on microkernels and
   monolithic kernels, for example).











Mogul, et al.                Informational                      [Page 5]

RFC 2783                  Pulse-Per-Second API                March 2000


3.1 PPS abstraction

   A PPS signal consists of a series of pulses, each with an "asserted"
   (logical true) phase, and a "clear" (logical false) phase.  The two
   phases may be of different lengths.  The API may capture an "assert
   timestamp" at the moment of the transition into the asserted phase,
   and a "clear timestamp" at the moment of the transition into the
   clear phase.

   The specific assignment of the logical values "true" and "false" with
   specific voltages of a PPS signal, if applicable, is outside the
   scope of this specification.  However, these assignments SHOULD be
   consistent with applicable standards.  Implementors of PPS sources
   SHOULD document these assignments.

      Reminder to implementors of DCD-based PPS support:  TTL and RS-
      232C (V.24/V.28) interfaces both define the "true" state as the
      one having the highest positive voltage. TTL defines a nominal
      absence of voltage as the "false" state, but RS-232C (V.24/V.28)
      defines the "false" state by the presence of a negative voltage.

   The API supports the direct provision of PPS events (and timestamps)
   to an in-kernel PPS consumer.  This could be the function called
   "hardpps()", as described in RFC 1589 [4], but the API does not
   require the kernel implementation to use that function name
   internally.  The current version of the API supports at most one in-
   kernel PPS consumer, and does not provide a way to explicitly name
   it.  The implementation SHOULD impose access controls on the use of
   this feature.

   The API optionally supports an "echo" feature, in which events on the
   incoming PPS signal may be reflected through software, after the
   capture of the corresponding timestamp, to an output signal pin.
   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
   timestamps; such information may be useful in precise calibration of
   the system.

   The designation of an output pin for the echo signal, and sense and
   shape of the output transition, is outside the scope of this
   specification, but SHOULD be documented for each implementation.  The
   output pin MAY also undergo transitions at other times besides those
   caused by PPS input events.

      Note: this allows an implementation of the echo feature to
      generate an output pulse per input pulse, or an output edge per
      input pulse, or an output pulse per input edge. It also allows the
      same signal pin to be used for several purposes simultaneously.



Mogul, et al.                Informational                      [Page 6]

RFC 2783                  Pulse-Per-Second API                March 2000


   Also, the API optionally provides an application with the ability to
   specify an offset value to be applied to captured timestamps.  This
   can be used to correct for cable and/or radio-wave propagation
   delays, or to compensate for systematic jitter in the external
   signal.  The implementation SHOULD impose access controls on the use
   of this feature.

3.2 New data structures

   The data structure declarations and symbol definitions for this API
   will appear in the header file <sys/timepps.h>.  The header file MUST
   define all constants described in this specification, even if they
   are not supported by the implementation.

   The API includes several implementation-specific types:

      typedef ... pps_handle_t;       /* represents a PPS source */

      typedef unsigned ... pps_seq_t; /* sequence number */

   The "pps_handle_t" type is an opaque scalar type used to represent a
   PPS source within the API.

   The "pps_seq_t" type is an unsigned integer data type of at least 32
   bits.

   The precise declaration of the pps_handle_t and pps_seq_t types is
   system-dependent.

   The API imports the standard POSIX definition for this data type:

      struct timespec {
              time_t  tv_sec;         /* seconds */
              long    tv_nsec;        /* nanoseconds */
      };

   The API defines this structure as an internal (not "on the wire")
   representation of the NTP "64-bit unsigned fixed-point" timestamp
   format [3]:

      typedef struct ntp_fp {
              unsigned int    integral;
              unsigned int    fractional;
      } ntp_fp_t;

   The two fields in this structure may be declared as any unsigned
   integral type, each of at least 32 bits.




Mogul, et al.                Informational                      [Page 7]

RFC 2783                  Pulse-Per-Second API                March 2000


   The API defines this new union as an extensible type for representing
   times:

      typedef union pps_timeu {
              struct timespec tspec;
              ntp_fp_t        ntpfp;
              unsigned long   longpad[3];
      } pps_timeu_t;

   Future revisions of this specification may add more fields to this
   union.

      Note: adding a field to this union that is larger than
      3*sizeof(long) will break binary compatibility.

   The API defines these new data structures:

      typedef struct {
          pps_seq_t   assert_sequence;        /* assert event seq # */
          pps_seq_t   clear_sequence;         /* clear event seq # */
          pps_timeu_t assert_tu;
          pps_timeu_t clear_tu;
          int         current_mode;           /* current mode bits */
      } pps_info_t;

      #define assert_timestamp        assert_tu.tspec
      #define clear_timestamp         clear_tu.tspec

      #define assert_timestamp_ntpfp  assert_tu.ntpfp
      #define clear_timestamp_ntpfp   clear_tu.ntpfp

      typedef struct {
          int         api_version;            /* API version # */
          int         mode;                   /* mode bits */
          pps_timeu_t assert_off_tu;
          pps_timeu_t clear_off_tu;
      } pps_params_t;