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.
204
205
206 Parallel port generator
207 ------------------------
208
209 One way to do this is to invent some complicated hardware solutions but it
210 may be neither necessary nor affordable. The cheap way is to load a PPS
211 generator on one of the computers (master) and PPS clients on others
212 (slaves), and use very simple cables to deliver signals using parallel
213 ports, for example.
214
215 Parallel port cable pinout::
216
217 pin name master slave
218 1 STROBE *------ *
219 2 D0 * | *
220 3 D1 * | *
221 4 D2 * | *
222 5 D3 * | *
223 6 D4 * | *
224 7 D5 * | *
225 8 D6 * | *
226 9 D7 * | *
227 10 ACK * ------*
228 11 BUSY * *
229 12 PE * *
230 13 SEL * *
231 14 AUTOFD * *
232 15 ERROR * *
233 16 INIT * *
234 17 SELIN * *
235 18-25 GND *-----------*
236
237 Please note that parallel port interrupt occurs only on high->low transition,
238 so it is used for PPS assert edge. PPS clear edge can be determined only
239 using polling in the interrupt handler which actually can be done way more
240 precisely because interrupt handling delays can be quite big and random. So
241 current parport PPS generator implementation (pps_gen_parport module) is
242 geared towards using the clear edge for time synchronization.
243
244 Clear edge polling is done with disabled interrupts so it's better to select
245 delay between assert and clear edge as small as possible to reduce system
246 latencies. But if it is too small slave won't be able to capture clear edge
247 transition. The default of 30us should be good enough in most situations.
248 The delay can be selected using 'delay' pps_gen_parport module parameter.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.