Documentation/pps/pps.txt

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