File: rfc2783.txt

package info (click to toggle)
doc-rfc 20181229-2
  • links: PTS, VCS
  • area: non-free
  • in suites: buster
  • size: 570,944 kB
  • sloc: xml: 285,646; sh: 107; python: 90; perl: 42; makefile: 14
file content (1739 lines) | stat: -rw-r--r-- 61,421 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739






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;

      #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

   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
   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: 1 650 617 3304 (email preferred)
   EMail: mogul@wrl.dec.com


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

   Phone: (302) 831-8247
   EMail: mills@udel.edu


   Jan Brittenson
   Sun Microsystems, Inc.
   901 San Antonio Rd  M/S MPK17-202
   Palo Alto, CA 94303
   Email: Jan.Brittenson@Eng.Sun.COM

   Jonathan Stone
   Stanford Distributed Systems Group
   Stanford, CA 94305

   Phone: (650) 723-2513
   EMail: jonathan@dsg.stanford.edu


   Ulrich Windl
   Universitaet Regensburg, Klinikum

   EMail: ulrich.windl@rz.uni-regensburg.de












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]