rfc2783.txt

来自「著名的RFC文档,其中有一些文档是已经翻译成中文的的.」· 文本 代码 · 共 1,740 行 · 第 1/4 页

      #define assert_offset   assert_off_tu.tspec
      #define clear_offset    clear_off_tu.tspec

      #define assert_offset_ntpfp     assert_off_tu.ntpfp
      #define clear_offset_ntpfp      clear_off_tu.ntpfp

   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
   most recent clear event.  The order in which these events were
   actually received is defined by the timetamps, not by any other



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


   aspect of the specification.  Each timestamp field represents the
   value of the operating system's internal timebase when the
   timestamped event occurred, or as close as possible to that time
   (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
   time of the most recent transition was captured for this PPS source.
   An application can use current_mode to discover the format of the
   timestamps returned.

   The assert_sequence number increases once per captured assert
   timestamp.  Its initial value is undefined.  If incremented past the
   largest value for the type, the next value is zero.  The
   clear_sequence number increases once per captured clear timestamp.
   Its initial value is undefined, and may be different from the initial
   value of assert_sequence.  If incremented past the largest value for
   the type, the next value is zero.  Due to possible signal loss or
   excessive signal noise, the assert-sequence number and the clear-
   sequence number might not always increase in step with each other.

      Note that these sequence numbers are most useful in applications
      where events other than PPS transitions are to be captured, which
      might be involved in a precision stopwatch application, for
      example. In such cases, the sequence numbers may be used to detect
      overruns, where the application has 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 occur between two calls to the
      time_pps_fetch() function (defined later).

      In order to obtain an uninterrupted series of sequence numbers
      (and hence of event timestamps), it may be necessary to sample the
      pps_info_t values at a rate somewhat faster than the underlying
      event rate.  For example, an application interested in both assert
      and clear timestamps may need to sample at least twice per second.
      Proper use of the sequence numbers allows an application to
      discover if it has missed any event timestamps due to an
      insufficient sampling rate.

   The pps_params_t data type is used to discover and modify parameters
   of a PPS source.  The data type includes a mode field, described in
   section 3.3.  It also includes an api_version field, a read-only
   value giving the version of the API.  Currently, the only defined
   value is:

      #define PPS_API_VERS_1  1

   This field is present to enable binary compatibility with future
   versions of the API.




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


      Note: the term "read-only" in this specification means that an
      application cannot modify the relevant data item; only the
      implementation can modify the value.  The implementation MUST
      ignore attempts by the application to modify a read-only field.

   As an OPTIONAL feature of the API, the implementation MAY support
   adding offsets to the timestamps that are captured.  (Values of type
   "struct timespec" can represent negative offsets.)  The assert_offset
   field of a pps_params_t value specifies a value to be added to
   generate a captured assert_timestamp.  The clear_offset of a
   pps_params_t value field specifies a value to be added to generate a
   captured clear_timestamp.  Since the offsets, if any, apply to all
   users of a given PPS source, the implementation SHOULD impose access
   controls on the use of this feature; for example, allowing only the
   super-user to set the offset values.  The default value for both
   offsets is zero.

3.3 Mode bit definitions

   A set of mode bits is associated with each PPS source.

   The bits in the mode field of the pps_params_t type are:

      /* Device/implementation parameters */
      #define PPS_CAPTUREASSERT       0x01
      #define PPS_CAPTURECLEAR        0x02
      #define PPS_CAPTUREBOTH         0x03

      #define PPS_OFFSETASSERT        0x10
      #define PPS_OFFSETCLEAR         0x20

      #define PPS_CANWAIT             0x100
      #define PPS_CANPOLL             0x200

      /* Kernel actions */
      #define PPS_ECHOASSERT          0x40
      #define PPS_ECHOCLEAR           0x80

      /* Timestamp formats */
      #define PPS_TSFMT_TSPEC         0x1000
      #define PPS_TSFMT_NTPFP         0x2000

   These mode bits are divided into three categories:

      1. Device/implementation parameters:  These are parameters either
         of the device or of the implementation.  If the implementation
         allows these to be changed, then these bits are read/write for
         users with sufficient privilege (such as the super-user), and



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


         read-only for other users.  If the implementation does not
         allow these bits to be changed, they are read-only.

      2. Kernel actions:  These bits specify certain kernel actions to
         be taken on arrival of a signal.  If the implementation
         supports one of these actions, then the corresponding bit is
         read/write for users with sufficient privilege (such as the
         super-user), and read-only for other users.  If the
         implementation does not support the action, the corresponding
         bit is always zero.

      3. Timestamp formats:  These bits indicate the set of timestamp
         formats available for the device.  They are always read-only.

   In more detail, the meanings of the Device/implementation parameter
   mode bits are:

   PPS_CAPTUREASSERT
                   If this bit is set, the assert timestamp for the
                   associated PPS source will be captured.

   PPS_CAPTURECLEAR
                   If this bit is set, the clear timestamp for the
                   associated PPS source will be captured.

   PPS_CAPTUREBOTH Defined as the union of PPS_CAPTUREASSERT and
                   PPS_CAPTURECLEAR, for convenience.

   PPS_OFFSETASSERT
                   If set, the assert_offset value is added to the
                   current value of the operating system's internal
                   timebase in order to generate the captured
                   assert_timestamp.

   PPS_OFFSETCLEAR If set, the clear_offset value is added to the
                   current value of the operating system's internal
                   timebase in order to generate the captured
                   clear_timestamp.

   PPS_CANWAIT     If set, the application may request that the
                   time_pps_fetch() function (see section 3.4.3) should
                   block until the next timestamp arrives.  Note: this
                   mode bit is read-only.

   PPS_CANPOLL     This bit is reserved for future use.  An application
                   SHOULD NOT depend on any functionality implied either
                   by its presence or by its absence.




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


   If neither PPS_CAPTUREASSERT nor PPS_CAPTURECLEAR is set, no valid
   timestamp will be available via the API.

   The meanings of the Kernel action mode bits are:

   PPS_ECHOASSERT   If set, after the capture of an assert timestamp,
                   the implementation generates a signal transition as
                   rapidly as possible on an output signal pin.  This
                   MUST NOT affect the delay between the PPS source's
                   transition to the asserted phase and the capture of
                   the assert timestamp.

   PPS_ECHOCLEAR    If set, after the capture of a clear timestamp, the
                   implementation generates a signal transition as
                   rapidly as possible on an output signal pin.  This
                   MUST NOT affect the delay between the PPS source's
                   transition to the clear phase and the capture of the
                   clear timestamp.

   The timestamp formats are:

   PPS_TSFMT_TSPEC Timestamps and offsets are represented as values of
                   type "struct timespec".  All implementations MUST
                   support this format, and this format is the default
                   unless an application specifies otherwise.

   PPS_TSFMT_NTPFP Timestamps and offsets are represented as values of
                   type "ntp_fp_t", which corresponds to the NTP
                   "64-bit unsigned fixed-point" timestamp format [3].
                   Support for this format is OPTIONAL.

   Other timestamp format bits may be defined as fields are added to the
   "pps_timeu_t" union.

   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
   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.

3.4 New functions

   In the description of functions that follows, we use the following
   function parameters:

   filedes         A file descriptor (type: int), for a serial line or
                   other source of PPS events.





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


   ppshandle       A variable of type "pps_handle_t", as defined in
                   section 3.2.

   ppsinfobuf      A record of type "pps_info_t", as defined in
                   section 3.2.

   ppsparams       A record of type "pps_params_t", as defined in
                   section 3.2.

   tsformat        An integer with exactly one of the timestamp format
                   bits set.

3.4.1 New functions: obtaining PPS sources

   The API includes functions to create and destroy PPS source
   "handles".

   SYNOPSIS

      int time_pps_create(int filedes, pps_handle_t *handle);
      int time_pps_destroy(pps_handle_t handle);

   DESCRIPTION

   All of the other functions in the PPS API operate on PPS handles
   (type: pps_handle_t).  The time_pps_create() is used to convert an
   already-open UNIX file descriptor, for an appropriate special file,
   into a PPS handle.

   The definition of what special files are appropriate for use with the
   PPS API is outside the scope of this specification, and may vary
   based on both operating system implementation, and local system
   configuration.  One typical case is a serial line, whose DCD pin is
   connected to a source of PPS events.

   The mode in which the UNIX file descriptor was originally opened
   affects what operations are allowed on the PPS handle.  The
   time_pps_setparams() and time_pps_kcbind() functions (see sections
   3.4.2 and 3.4.4) SHOULD be prohibited by the implementation if the
   descriptor is open only for reading (O_RDONLY).

      Note: operations on a descriptor opened with an inappropriate mode
      might fail with EBADF.

   The time_pps_destroy() function makes the PPS handle unusable, and
   frees any storage that might have been allocated for it.  It does not
   close the associated file descriptor, nor does it change any of the
   parameter settings for the PPS source.



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


      Note: If this API is adapted to an operating system that does not
      follow UNIX conventions for representing an accessible PPS source
      as an integer file descriptor, the time_pps_create() function may
      take different parameters from those shown here.

   RETURN VALUES

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

   If called with a valid handle parameter, the time_pps_destroy()
   function returns 0.  Otherwise, it returns -1.

   ERRORS

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

   [EBADF]         The filedes parameter is not a valid file descriptor.

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

   [EPERM]         The process's effective user ID does not have the
                   required privileges to use the PPS API.

3.4.2 New functions: setting PPS parameters

   The API includes several functions use to set or obtain the
   parameters of a PPS source.

   SYNOPSIS

      int time_pps_setparams(pps_handle_t handle,
                              const pps_params_t *ppsparams);
      int time_pps_getparams(pps_handle_t handle,
                              pps_params_t *ppsparams);
      int time_pps_getcap(pps_handle_t handle, int *mode);

   DESCRIPTION

   A suitably privileged application may use time_pps_setparams() to set
   the parameters (mode bits and timestamp offsets) for a PPS source.
   The pps_params_t type is defined in section 3.2; mode bits are
   defined in section 3.3.  An application may use time_pps_getparams()
   to discover the current settings of the PPS parameters.  An
   application that needs to change only a subset of the existing



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


   parameters must first call time_pps_getparams() to obtain the current
   parameter values, then set the new values using time_pps_setparams().

      Note: a call to time_pps_setparams() replaces the current values
      of all mode bits with those specified via the ppsparams argument,
      except those bits whose state cannot be changed.  Bits might be
      read-only due to access controls, or because they are fixed by the
      implementation.

   The timestamp format of the assert_offset and clear_offset fields is
   defined by the mode field.  That is, on a call to
   time_pps_setparams(), the kernel interprets the supplied offset
   values using the timestamp format given in the mode field of the
   ppsparams argument.  If the requested timestamp format is not
   supported, the time_pps_setparams() function has no effect and
   returns an error value.  On a call to time_pps_getparams(), the
   kernel provides the timestamp format of the offsets by setting one of
   the timestamp format bits in the mode field.

      Note: an application that uses time_pps_getparams() to read the
      current offset values cannot specify which format is used.  The
      implementation SHOULD return the offsets using the same timestamp
      format as was used when the offsets were set.

   An application wishing to discover which mode bits it may set, with
   its current effective user ID, may call time_pps_getcap().  This
   function returns the set of mode bits that may be set by the
   application, without generating an EINVAL or EPERM error, 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
   corresponding to all supported timestamp formats.

   The time_pps_getcap() function MAY ignore the mode in which the
   associated UNIX file descriptor was opened, so the application might
   still receive an EBADF error on a call to time_pps_setparams(), even
   if time_pps_getcap() says that the chosen mode bits are allowed.

   The mode bits returned by time_pps_getcap() for distinct PPS handles
   may differ, reflecting the specific capabilities of the underlying
   hardware connection to the PPS source, or of the source itself.

   RETURN VALUES

   On successful completion, the time_pps_setparams(),
   time_pps_getparams(), and time_pps_getcap() functions return 0.
   Otherwise, a value of -1 is returned and errno is set to indicate the
   error.




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


   ERRORS

   If the time_pps_setparams(), time_pps_getparams(), or
   time_pps_getcap() 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.

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

   [EINVAL]        The operating system does not support all of the
                   requested mode bits.

   [EPERM]         The process's effective user ID does not have the
                   required privileges to use the PPS API, or to set the
                   given mode bits.

3.4.3 New functions: access to PPS timestamps