rfc2783.txt

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

   cause a slight increase in interrupt latency and interrupt-handling
   overhead.

   The second capability might be useful in implementing certain kinds
   of covert communication channels.

   In most cases, neither of these first two issues is a significant
   security threat, because the traditional UNIX file protection
   facility may be used to to limit access to the relevant special
   files.  Provision of the PPS API adds minimal additional risk.

   The final capability is reserved to highly privileged users.  In UNIX
   systems, this means those with superuser privilege.  Such users can
   evade protections based on file permissions; however, such users can
   in general cause unbounded havoc, and can set the internal timebase
   (and its rate of change), so this API creates no new vulnerabilities.

5 Acknowledgements

   The API in this document draws some of its inspiration from the LBL
   "ppsclock" distribution [2], originally implemented in 1993 by Steve
   McCanne, Craig Leres, and Van Jacobson.  We also thank Poul-Henning
   Kamp, Craig Leres, Judah Levine, and Harlan Stenn for helpful
   comments they contributed during the drafting of this document.
















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


6 References

   1.  Bradner, S., "Key words for use in RFCs to Indicate Requirement
       Levels", BCP 14, RFC 2119, March 1997.

   2.  Steve McCanne, Craig Leres, and Van Jacobson.  PPSCLOCK.
       ftp://ftp.ee.lbl.gov/ppsclock.tar.Z.

   3.  Mills, D., "Network Time Protocol (Version 3):  Specification,
       Implementation and Analysis", RFC 1305, March 1992.

   4.  Mills, D., "A Kernel Model for Precision Timekeeping", RFC 1589,
       March, 1994.

   5.  The Open Group.  The Single UNIX Specification, Version 2 - 6 Vol
       Set for UNIX 98.  Document number T912, The Open Group, February,
       1997.


































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


7 Authors' Addresses

   Jeffrey C. Mogul
   Western Research Laboratory
   Compaq Computer Corporation
   250 University Avenue
   Palo Alto, California, 94305, U.S.A.

   Phone: [phone] (email preferred)
   EMail: [e-mail]


   David L. Mills
   Electrical and Computer Engineering Department
   University of Delaware
   Newark, DE 19716

   Phone: [phone]
   EMail: [e-mail]


   Jan Brittenson
   Sun Microsystems, Inc.
   901 San Antonio Rd  M/S MPK17-202
   Palo Alto, CA 94303
   Email: [e-mail]

   Jonathan Stone
   Stanford Distributed Systems Group
   Stanford, CA 94305

   Phone: [phone]
   EMail: [e-mail]


   Ulrich Windl
   Universitaet Regensburg, Klinikum

   EMail: [e-mail]












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


A. Extensions and related APIs

   The API specified in the main body of this document could be more
   useful with the provision of several extensions or companion APIs.

   At present, the interfaces listed in this appendix are not part of
   the formal specification in this document.

A.1 Extension: Parameters for the "echo" mechanism

   The "echo" mechanism described in the body of this specification
   leaves most of the details to the implementor, especially the
   designation of one or more output pins.

   It might be useful to extend this API to provide either or both of
   these features:

      - A means by which the application can discover which output
        pin is echoing the input pin.

      - A means by which the application can select which output
        pin is echoing the input pin.

A.2 Extension: Obtaining information about external clocks

   The PPS API may be useful with a wide variety of reference clocks,
   connected via several different interface technologies (including
   serial lines, parallel interfaces, and bus-level interfaces).  These
   reference clocks can have many features and parameters, some of which
   might not even have been invented yet.

   We believe that it would be useful to have a mechanism by which an
   application can discover arbitrary features and parameters of a
   reference clock.  These might include:

      - Clock manufacturer, model number, and revision level
      - Whether the clock is synchronized to an absolute standard
      - For synchronized clocks,
           * The specific standard
           * The accuracy of the standard
           * The path used (direct connection, shortwave, longwave,
             satellite, etc.)
           * The distance (offset) and variability of this path








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


      - For PPS sources,
           * The pulse rate
           * The pulse shape
           * Which edge of the pulse corresponds to the epoch

      - The time representation format

   This information might best be provided by an API analogous to the
   standard "curses" API, with a database analogous to the standard
   "terminfo" database.  That is, a "clockinfo" database would contain a
   set of (attribute, value) pairs for each type of clock, and the API
   would provide a means to query this database.

   Additional mechanisms would allow an application to discover the
   clock or clocks connected to the local system, and to discover the
   clockinfo type of a specific clock device.

A.3 Extension: Finding a PPS source

   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"



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


   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, &params);
      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



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


       */
      ioctl(fd, PPSGETPARAMS, &params);
      params.mode |= PPS_CAPTUREASSERT;
      ioctl(fd, PPSSETPARAMS, &params);

      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.

































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


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 RFC Editor function is currently provided by the
   Internet Society.



















Mogul, et al.                Informational                     [Page 31]