rfc2783.txt

来自「RFC 的详细文档！」· 文本 代码 · 共 1,740 行 · 第 1/5 页

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;

      #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