| 1 | |
| 2 |
|
| 3 | ======================
|
| 4 | PPS - Pulse Per Second
|
| 5 | ======================
|
| 6 |
|
| 7 | Copyright (C) 2007 Rodolfo Giometti <[email protected]>
|
| 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.
|
| 204 |
|
| 205 | To do so the class pps-gen has been added. PPS generators can be
|
| 206 | registered in the kernel by defining a struct pps_gen_source_info as
|
| 207 | follows::
|
| 208 |
|
| 209 | static const struct pps_gen_source_info pps_gen_dummy_info = {
|
| 210 | .use_system_clock = true,
|
| 211 | .get_time = pps_gen_dummy_get_time,
|
| 212 | .enable = pps_gen_dummy_enable,
|
| 213 | };
|
| 214 |
|
| 215 | Where the use_system_clock states if the generator uses the system
|
| 216 | clock to generate its pulses, or they are from a peripheral device
|
| 217 | clock. Method get_time() is used to query the time stored into the
|
| 218 | generator clock, while the method enable() is used to enable or
|
| 219 | disable the PPS pulse generation.
|
| 220 |
|
| 221 | Then calling the function pps_gen_register_source() in your
|
| 222 | initialization routine as follows creates a new generator in the
|
| 223 | system::
|
| 224 |
|
| 225 | pps_gen = pps_gen_register_source(&pps_gen_dummy_info);
|
| 226 |
|
| 227 | Generators SYSFS support
|
| 228 | ------------------------
|
| 229 |
|
| 230 | If the SYSFS filesystem is enabled in the kernel it provides a new class::
|
| 231 |
|
| 232 | $ ls /sys/class/pps-gen/
|
| 233 | pps-gen0/ pps-gen1/ pps-gen2/
|
| 234 |
|
| 235 | Every directory is the ID of a PPS generator defined in the system and
|
| 236 | inside of it you find several files::
|
| 237 |
|
| 238 | $ ls -F /sys/class/pps-gen/pps-gen0/
|
| 239 | dev enable name power/ subsystem@ system time uevent
|
| 240 |
|
| 241 | To enable the PPS signal generation you can use the command below::
|
| 242 |
|
| 243 | $ echo 1 > /sys/class/pps-gen/pps-gen0/enable
|
| 244 |
|
| 245 | Parallel port generator
|
| 246 | ------------------------
|
| 247 |
|
| 248 | One way to do this is to invent some complicated hardware solutions but it
|
| 249 | may be neither necessary nor affordable. The cheap way is to load a PPS
|
| 250 | generator on one of the computers (master) and PPS clients on others
|
| 251 | (slaves), and use very simple cables to deliver signals using parallel
|
| 252 | ports, for example.
|
| 253 |
|
| 254 | Parallel port cable pinout::
|
| 255 |
|
| 256 | pin name master slave
|
| 257 | 1 STROBE *------ *
|
| 258 | 2 D0 * | *
|
| 259 | 3 D1 * | *
|
| 260 | 4 D2 * | *
|
| 261 | 5 D3 * | *
|
| 262 | 6 D4 * | *
|
| 263 | 7 D5 * | *
|
| 264 | 8 D6 * | *
|
| 265 | 9 D7 * | *
|
| 266 | 10 ACK * ------*
|
| 267 | 11 BUSY * *
|
| 268 | 12 PE * *
|
| 269 | 13 SEL * *
|
| 270 | 14 AUTOFD * *
|
| 271 | 15 ERROR * *
|
| 272 | 16 INIT * *
|
| 273 | 17 SELIN * *
|
| 274 | 18-25 GND *-----------*
|
| 275 |
|
| 276 | Please note that parallel port interrupt occurs only on high->low transition,
|
| 277 | so it is used for PPS assert edge. PPS clear edge can be determined only
|
| 278 | using polling in the interrupt handler which actually can be done way more
|
| 279 | precisely because interrupt handling delays can be quite big and random. So
|
| 280 | current parport PPS generator implementation (pps_gen_parport module) is
|
| 281 | geared towards using the clear edge for time synchronization.
|
| 282 |
|
| 283 | Clear edge polling is done with disabled interrupts so it's better to select
|
| 284 | delay between assert and clear edge as small as possible to reduce system
|
| 285 | latencies. But if it is too small slave won't be able to capture clear edge
|
| 286 | transition. The default of 30us should be good enough in most situations.
|
| 287 | The delay can be selected using 'delay' pps_gen_parport module parameter.
|
| 288 |
|
| 289 |
|
| 290 | Intel Timed I/O PPS signal generator
|
| 291 | ------------------------------------
|
| 292 |
|
| 293 | Intel Timed I/O is a high precision device, present on 2019 and newer Intel
|
| 294 | CPUs, that can generate PPS signals.
|
| 295 |
|
| 296 | Timed I/O and system time are both driven by same hardware clock. The signal
|
| 297 | is generated with a precision of ~20 nanoseconds. The generated PPS signal
|
| 298 | is used to synchronize an external device with system clock. For example,
|
| 299 | it can be used to share your clock with a device that receives PPS signal,
|
| 300 | generated by Timed I/O device. There are dedicated Timed I/O pins to deliver
|
| 301 | the PPS signal to an external device.
|
| 302 |
|
| 303 | Usage of Intel Timed I/O as PPS generator:
|
| 304 |
|
| 305 | Start generating PPS signal::
|
| 306 |
|
| 307 | $echo 1 > /sys/class/pps-gen/pps-genx/enable
|
| 308 |
|
| 309 | Stop generating PPS signal::
|
| 310 |
|
| 311 | $echo 0 > /sys/class/pps-gen/pps-genx/enable
|