pps.rst 8.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242
  1. .. SPDX-License-Identifier: GPL-2.0
  2. ======================
  3. PPS - Pulse Per Second
  4. ======================
  5. Copyright (C) 2007 Rodolfo Giometti <giometti@enneenne.com>
  6. This program is free software; you can redistribute it and/or modify
  7. it under the terms of the GNU General Public License as published by
  8. the Free Software Foundation; either version 2 of the License, or
  9. (at your option) any later version.
  10. This program is distributed in the hope that it will be useful,
  11. but WITHOUT ANY WARRANTY; without even the implied warranty of
  12. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13. GNU General Public License for more details.
  14. Overview
  15. --------
  16. LinuxPPS provides a programming interface (API) to define in the
  17. system several PPS sources.
  18. PPS means "pulse per second" and a PPS source is just a device which
  19. provides a high precision signal each second so that an application
  20. can use it to adjust system clock time.
  21. A PPS source can be connected to a serial port (usually to the Data
  22. Carrier Detect pin) or to a parallel port (ACK-pin) or to a special
  23. CPU's GPIOs (this is the common case in embedded systems) but in each
  24. case when a new pulse arrives the system must apply to it a timestamp
  25. and record it for userland.
  26. Common use is the combination of the NTPD as userland program, with a
  27. GPS receiver as PPS source, to obtain a wallclock-time with
  28. sub-millisecond synchronisation to UTC.
  29. RFC considerations
  30. ------------------
  31. While implementing a PPS API as RFC 2783 defines and using an embedded
  32. CPU GPIO-Pin as physical link to the signal, I encountered a deeper
  33. problem:
  34. At startup it needs a file descriptor as argument for the function
  35. time_pps_create().
  36. This implies that the source has a /dev/... entry. This assumption is
  37. OK for the serial and parallel port, where you can do something
  38. useful besides(!) the gathering of timestamps as it is the central
  39. task for a PPS API. But this assumption does not work for a single
  40. purpose GPIO line. In this case even basic file-related functionality
  41. (like read() and write()) makes no sense at all and should not be a
  42. precondition for the use of a PPS API.
  43. The problem can be simply solved if you consider that a PPS source is
  44. not always connected with a GPS data source.
  45. So your programs should check if the GPS data source (the serial port
  46. for instance) is a PPS source too, and if not they should provide the
  47. possibility to open another device as PPS source.
  48. In LinuxPPS the PPS sources are simply char devices usually mapped
  49. into files /dev/pps0, /dev/pps1, etc.
  50. PPS with USB to serial devices
  51. ------------------------------
  52. It is possible to grab the PPS from an USB to serial device. However,
  53. you should take into account the latencies and jitter introduced by
  54. the USB stack. Users have reported clock instability around +-1ms when
  55. synchronized with PPS through USB. With USB 2.0, jitter may decrease
  56. down to the order of 125 microseconds.
  57. This may be suitable for time server synchronization with NTP because
  58. of its undersampling and algorithms.
  59. If your device doesn't report PPS, you can check that the feature is
  60. supported by its driver. Most of the time, you only need to add a call
  61. to usb_serial_handle_dcd_change after checking the DCD status (see
  62. ch341 and pl2303 examples).
  63. Coding example
  64. --------------
  65. To register a PPS source into the kernel you should define a struct
  66. pps_source_info as follows::
  67. static struct pps_source_info pps_ktimer_info = {
  68. .name = "ktimer",
  69. .path = "",
  70. .mode = PPS_CAPTUREASSERT | PPS_OFFSETASSERT |
  71. PPS_ECHOASSERT |
  72. PPS_CANWAIT | PPS_TSFMT_TSPEC,
  73. .echo = pps_ktimer_echo,
  74. .owner = THIS_MODULE,
  75. };
  76. and then calling the function pps_register_source() in your
  77. initialization routine as follows::
  78. source = pps_register_source(&pps_ktimer_info,
  79. PPS_CAPTUREASSERT | PPS_OFFSETASSERT);
  80. The pps_register_source() prototype is::
  81. int pps_register_source(struct pps_source_info *info, int default_params)
  82. where "info" is a pointer to a structure that describes a particular
  83. PPS source, "default_params" tells the system what the initial default
  84. parameters for the device should be (it is obvious that these parameters
  85. must be a subset of ones defined in the struct
  86. pps_source_info which describe the capabilities of the driver).
  87. Once you have registered a new PPS source into the system you can
  88. signal an assert event (for example in the interrupt handler routine)
  89. just using::
  90. pps_event(source, &ts, PPS_CAPTUREASSERT, ptr)
  91. where "ts" is the event's timestamp.
  92. The same function may also run the defined echo function
  93. (pps_ktimer_echo(), passing to it the "ptr" pointer) if the user
  94. asked for that... etc..
  95. Please see the file drivers/pps/clients/pps-ktimer.c for example code.
  96. SYSFS support
  97. -------------
  98. If the SYSFS filesystem is enabled in the kernel it provides a new class::
  99. $ ls /sys/class/pps/
  100. pps0/ pps1/ pps2/
  101. Every directory is the ID of a PPS sources defined in the system and
  102. inside you find several files::
  103. $ ls -F /sys/class/pps/pps0/
  104. assert dev mode path subsystem@
  105. clear echo name power/ uevent
  106. Inside each "assert" and "clear" file you can find the timestamp and a
  107. sequence number::
  108. $ cat /sys/class/pps/pps0/assert
  109. 1170026870.983207967#8
  110. Where before the "#" is the timestamp in seconds; after it is the
  111. sequence number. Other files are:
  112. * echo: reports if the PPS source has an echo function or not;
  113. * mode: reports available PPS functioning modes;
  114. * name: reports the PPS source's name;
  115. * path: reports the PPS source's device path, that is the device the
  116. PPS source is connected to (if it exists).
  117. Testing the PPS support
  118. -----------------------
  119. In order to test the PPS support even without specific hardware you can use
  120. the pps-ktimer driver (see the client subsection in the PPS configuration menu)
  121. and the userland tools available in your distribution's pps-tools package,
  122. http://linuxpps.org , or https://github.com/redlab-i/pps-tools.
  123. Once you have enabled the compilation of pps-ktimer just modprobe it (if
  124. not statically compiled)::
  125. # modprobe pps-ktimer
  126. and the run ppstest as follow::
  127. $ ./ppstest /dev/pps1
  128. trying PPS source "/dev/pps1"
  129. found PPS source "/dev/pps1"
  130. ok, found 1 source(s), now start fetching data...
  131. source 0 - assert 1186592699.388832443, sequence: 364 - clear 0.000000000, sequence: 0
  132. source 0 - assert 1186592700.388931295, sequence: 365 - clear 0.000000000, sequence: 0
  133. source 0 - assert 1186592701.389032765, sequence: 366 - clear 0.000000000, sequence: 0
  134. Please note that to compile userland programs, you need the file timepps.h.
  135. This is available in the pps-tools repository mentioned above.
  136. Generators
  137. ----------
  138. Sometimes one needs to be able not only to catch PPS signals but to produce
  139. them also. For example, running a distributed simulation, which requires
  140. computers' clock to be synchronized very tightly. One way to do this is to
  141. invent some complicated hardware solutions but it may be neither necessary
  142. nor affordable. The cheap way is to load a PPS generator on one of the
  143. computers (master) and PPS clients on others (slaves), and use very simple
  144. cables to deliver signals using parallel ports, for example.
  145. Parallel port cable pinout::
  146. pin name master slave
  147. 1 STROBE *------ *
  148. 2 D0 * | *
  149. 3 D1 * | *
  150. 4 D2 * | *
  151. 5 D3 * | *
  152. 6 D4 * | *
  153. 7 D5 * | *
  154. 8 D6 * | *
  155. 9 D7 * | *
  156. 10 ACK * ------*
  157. 11 BUSY * *
  158. 12 PE * *
  159. 13 SEL * *
  160. 14 AUTOFD * *
  161. 15 ERROR * *
  162. 16 INIT * *
  163. 17 SELIN * *
  164. 18-25 GND *-----------*
  165. Please note that parallel port interrupt occurs only on high->low transition,
  166. so it is used for PPS assert edge. PPS clear edge can be determined only
  167. using polling in the interrupt handler which actually can be done way more
  168. precisely because interrupt handling delays can be quite big and random. So
  169. current parport PPS generator implementation (pps_gen_parport module) is
  170. geared towards using the clear edge for time synchronization.
  171. Clear edge polling is done with disabled interrupts so it's better to select
  172. delay between assert and clear edge as small as possible to reduce system
  173. latencies. But if it is too small slave won't be able to capture clear edge
  174. transition. The default of 30us should be good enough in most situations.
  175. The delay can be selected using 'delay' pps_gen_parport module parameter.