rfc2783.txt

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

   The API includes one function that gives applications access to PPS
   timestamps.  As an implementation option, the application may request
   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
   to wait for PPS events.)

   SYNOPSIS

      int time_pps_fetch(pps_handle_t handle,
                              const int tsformat,
                              pps_info_t *ppsinfobuf,
                              const struct timespec *timeout);

   DESCRIPTION

   An application may use time_pps_fetch() to obtain the most recent
   timestamps captured for the PPS source specified by the handle
   parameter.  The tsformat parameter specifies the desired timestamp
   format; if the requested timestamp format is not supported, the call
   fails and returns an error value.  The application MUST specify
   exactly one timestamp format.






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


   This function blocks until either a timestamp is captured from the
   PPS source, or until the specified timeout duration has expired.  If
   the timeout parameter is a NULL pointer, the function simply blocks
   until a timestamp is captured.  If the timeout parameter specifies a
   delay of zero, the function returns immediately.

   Support for blocking behavior is an implementation option.  If the
   PPS_CANWAIT mode bit is clear, and the timeout parameter is either
   NULL or points to a non-zero value, the function returns an
   EOPNOTSUPP error.  An application can discover whether the feature is
   implemented by using time_pps_getcap() to see if the PPS_CANWAIT mode
   bit is set.

   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
   timeout or error, the contents of the ppsinfobuf are undefined.

   If this function is invoked before the system has captured a
   timestamp for the signal source, the ppsinfobuf returned will have
   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).

   RETURN VALUES

   On successful completion, the time_pps_fetch() function returns 0.
   Otherwise, a value of -1 is returned and errno is set to indicate the
   error.

   ERRORS

   If the time_pps_fetch() function fails, errno may be set to one of
   the following values:

   [EBADF]         The handle parameter is not associated with a valid
                   file descriptor.

   [EFAULT]        A parameter points to an invalid address.

   [EINTR]         A signal was delivered before the time limit
                   specified by the timeout parameter expired and before
                   a timestamp has been captured.

   [EINVAL]        The requested timestamp format is not supported.

   [EOPNOTSUPP]    The use of the PPS API is not supported for the
                   associated file descriptor.

   [ETIMEDOUT]     The timeout duration has expired.



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


3.4.4 New functions: disciplining the kernel timebase

   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
   code used to discipline the operating system's internal timebase.

   SYNOPSIS

      int time_pps_kcbind(pps_handle_t handle,
                              const int kernel_consumer,
                              const int edge,
                              const int tsformat);
   DESCRIPTION

   An application with appropriate privileges may use time_pps_kcbind()
   to bind a kernel consumer to the PPS source specified by the handle.

   The kernel consumer is identified by the kernel_consumer parameter.
   In the current version of the API, the possible values for this
   parameter are:

      #define PPS_KC_HARDPPS          0
      #define PPS_KC_HARDPPS_PLL      1
      #define PPS_KC_HARDPPS_FLL      2

   with these meanings:

   PPS_KC_HARDPPS  The kernel's hardpps() function (or equivalent).

   PPS_KC_HARDPPS_PLL
                   A variant of hardpps() constrained to use a
                   phase-locked loop.

   PPS_KC_HARDPPS_FLL
                   A variant of hardpps() constrained to use a
                   frequency-locked loop.

   Implementation of any or all of these values is OPTIONAL.

   The edge parameter indicates which edge of the PPS signal causes a
   timestamp to be delivered to the kernel consumer.  It may have the
   value PPS_CAPTUREASSERT, PPS_CAPTURECLEAR, or PPS_CAPTUREBOTH,
   depending on particular characteristics of the PPS source.  It may
   also be zero, which removes any binding between the PPS source and
   the kernel consumer.






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


   The tsformat parameter specifies the format for the timestamps
   delivered to the kernel consumer.  If this value is zero, the
   implementation MAY choose the appropriate format, or return EINVAL.
   The implementation MAY ignore a non-zero value for this parameter.

   The binding created by this call persists until it is changed by a
   subsequent call specifying the same kernel_consumer.  In particular,
   a subsequent call to time_pps_destroy() for the specified handle does
   not affect the binding.

   The binding is independent of any prior or subsequent changes to the
   PPS_CAPTUREASSERT and PPS_CAPTURECLEAR mode bits for the device.
   However, if either the edge or the tsformat parameter values are
   inconsistent with the capabilities of the PPS source, an error is
   returned.  The implementation MAY also return an error if the
   tsformat value is unsupported for time_pps_kcbind(), even if it is
   supported for other uses of the API.

   The operating system may enforce two restrictions on the bindings
   created by time_pps_kcbind():

      1. the kernel MAY return an error if an attempt is made to bind a
         kernel consumer to more than one PPS source a time.

      2. the kernel MAY restrict the ability to set bindings to
         processes with sufficient privileges to modify the system's
         internal timebase.  (On UNIX systems, such modification is
         normally done using settimeofday() and/or adjtime(), and is
         restricted to users with superuser privilege.)

      Warning: If this feature is configured for a PPS source that does
      not have an accurate 1-pulse-per-second signal, or is otherwise
      inappropriately configured, use of this feature may result in
      seriously incorrect timekeeping for the entire system.  For best
      results, the 1-PPS signal should have much better frequency
      stability than the system's internal clock source (usually a
      crystal-controlled oscillator), and should have jitter (variation
      in interarrival time) much less than the system's clock-tick
      interval.

   See RFC 1589 [4] for more information about how the system's timebase
   may be disciplined using a PPS signal.

   RETURN VALUES

   On successful completion, the time_pps_kcbind() function returns 0.
   Otherwise, a value of -1 is returned and errno is set to indicate the
   error.



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


   ERRORS

   If the time_pps_kcbind() function fails, errno may be set to one of
   the following values:

   [EBADF]         The handle parameter is not associated with a valid
                   file descriptor, or the descriptor is not open for
                   writing.

   [EFAULT]        A parameter points to an invalid address.

   [EINVAL]        The requested timestamp format is not supported.

   [EOPNOTSUPP]    The use of the PPS API is not supported for the
                   associated file descriptor, or this OPTIONAL
                   function is not supported.

   [EPERM]         The process's effective user ID does not have the
                   required privileges to set the binding.

3.5 Compliance rules

   The key words "MUST", "MUST NOT", "REQUIRED","SHOULD", SHOULD NOT",
   "MAY", and "OPTIONAL" in this document are to be interpreted as
   described in RFC 2119 [1].

   Some features of this specification are OPTIONAL, but others are
   REQUIRED.

3.5.1 Functions

   An implementation MUST provide these functions:

      - time_pps_create()
      - time_pps_destroy()
      - time_pps_setparams()
      - time_pps_getparams()
      - time_pps_getcap()
      - time_pps_fetch()

   An implementation MUST provide this function, but it may be
   implemented as a function that always return an EOPNOTSUPP error,
   possibly on a per-source basis:

      - time_pps_kcbind()






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


3.5.2 Mode bits

   An implementation MUST support at least one of these mode bits for
   each PPS source:

      - PPS_CAPTUREASSERT
      - PPS_CAPTURECLEAR

   and MAY support both of them.  If an implementation supports both of
   these bits for a PPS source, it SHOULD allow them to be set
   simultaneously.

   An implementation MUST support this timestamp format:

      - PPS_TSFMT_TSPEC

   An implementation MAY support these mode bits:

      - PPS_ECHOASSERT
      - PPS_ECHOCLEAR
      - PPS_OFFSETASSERT
      - PPS_OFFSETCLEAR

   An implementation MAY support this timestamp format:

      - PPS_TSFMT_NTPFP

3.6 Examples

   A very simple use of this API might be:

      int fd;
      pps_handle_t handle;
      pps_params_t params;
      pps_info_t infobuf;
      struct timespec timeout;

      /* Open a file descriptor and enable PPS on rising edges */
      fd = open(PPSfilename, O_RDWR, 0);
      time_pps_create(fd, &handle);
      time_pps_getparams(handle, &params);
      if ((params.mode & PPS_CAPTUREASSERT) == 0) {
          fprintf(stderr, "%s cannot currently CAPTUREASSERT\n",
                PPSfilename);
          exit(1);
      }

      /* create a zero-valued timeout */



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


      timeout.tv_sec = 0;
      timeout.tv_nsec = 0;

      /* loop, printing the most recent timestamp every second or so */
      while (1) {
          sleep(1);
          time_pps_fetch(handle, PPS_TSFMT_TSPEC, &infobuf, &timeout);
          printf("Assert timestamp: %d.%09d, sequence: %ld\n",
                      infobuf.assert_timestamp.tv_sec,
                      infobuf.assert_timestamp.tv_nsec,
                      infobuf.assert_sequence);
      }

   Note that this example omits most of the error-checking that would be
   expected in a reliable program.

   Also note that, on a system that supports PPS_CANWAIT, the function
   of these lines:

         sleep(1);
         time_pps_fetch(handle, PPS_TSFMT_TSPEC, &infobuf, &timeout);

   might be more reliably accomplished using:

         timeout.tv_sec = 100;
         timeout.tv_nsec = 0;
         time_pps_fetch(handle, PPS_TSFMT_TSPEC, &infobuf, &timeout);

   The (arbitrary) timeout value is used to protect against the
   possibility that another application might disable PPS timestamps, or
   that the hardware generating the timestamps might fail.

   A slightly more elaborate use of this API might be:

      int fd;
      pps_handle_t handle;
      pps_params_t params;
      pps_info_t infobuf;
      int avail_mode;
      struct timespec timeout;

      /* Open a file descriptor */
      fd = open(PPSfilename, O_RDWR, 0);
      time_pps_create(fd, &handle);

      /*
       * Find out what features are supported
       */



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


      time_pps_getcap(handle, &avail_mode);
      if ((avail_mode & PPS_CAPTUREASSERT) == 0) {
          fprintf(stderr, "%s cannot CAPTUREASSERT\n", PPSfilename);
          exit(1);
      }
      if ((avail_mode & PPS_OFFSETASSERT) == 0) {
          fprintf(stderr, "%s cannot OFFSETASSERT\n", PPSfilename);
          exit(1);
      }

      /*
       * Capture assert timestamps, and
       *   compensate for a 675 nsec propagation delay
       */

      time_pps_getparams(handle, &params);
      params.assert_offset.tv_sec = 0;
      params.assert_offset.tv_nsec = 675;
      params.mode |= PPS_CAPTUREASSERT | PPS_OFFSETASSERT;
      time_pps_setparams(handle, &params);

      /* create a zero-valued timeout */
      timeout.tv_sec = 0;
      timeout.tv_nsec = 0;

      /* loop, printing the most recent timestamp every second or so */
      while (1) {
          if (avail_mode & PPS_CANWAIT) {
              time_pps_fetch(handle, PPS_TSFMT_TSPEC, &infobuf, NULL);
                              /* waits for the next event */
          } else {
              sleep(1);
              time_pps_fetch(handle, PPS_TSFMT_TSPEC, &infobuf,
                timeout);

          }
          printf("Assert timestamp: %d.%09d, sequence: %ld\n",
                      infobuf.assert_timestamp.tv_sec,
                      infobuf.assert_timestamp.tv_nsec,
                      infobuf.assert_sequence);
      }

   Again, most of the necessary error-checking has been omitted from
   this example.







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


4 Security Considerations

   This API gives applications three capabilities:

      - Causing the system to capture timestamps on certain events.

      - Obtaining timestamps for certain events.

      - Affecting the system's internal timebase.

   The first capability should not affect security directly, but might