Documentation/driver-api/pps.rst

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