]>
Commit | Line | Data |
---|---|---|
c92992fc | 1 | .. SPDX-License-Identifier: GPL-2.0 |
eae9d2ba | 2 | |
28aedd7e MCC |
3 | ====================== |
4 | PPS - Pulse Per Second | |
5 | ====================== | |
eae9d2ba | 6 | |
28aedd7e | 7 | Copyright (C) 2007 Rodolfo Giometti <giometti@enneenne.com> |
eae9d2ba RG |
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 | |
a2d81803 | 53 | OK for the serial and parallel port, where you can do something |
eae9d2ba | 54 | useful besides(!) the gathering of timestamps as it is the central |
a2d81803 | 55 | task for a PPS API. But this assumption does not work for a single |
eae9d2ba RG |
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 | |
a2d81803 | 58 | precondition for the use of a PPS API. |
eae9d2ba RG |
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 | |
fe4c56c9 | 68 | into files /dev/pps0, /dev/pps1, etc. |
eae9d2ba RG |
69 | |
70 | ||
833efc0e PC |
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 | |
fe4c56c9 | 76 | the USB stack. Users have reported clock instability around +-1ms when |
f2c1a053 S |
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. | |
833efc0e PC |
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 | ||
eae9d2ba RG |
89 | Coding example |
90 | -------------- | |
91 | ||
92 | To register a PPS source into the kernel you should define a struct | |
28aedd7e | 93 | pps_source_info as follows:: |
eae9d2ba RG |
94 | |
95 | static struct pps_source_info pps_ktimer_info = { | |
96 | .name = "ktimer", | |
97 | .path = "", | |
a2d81803 RD |
98 | .mode = PPS_CAPTUREASSERT | PPS_OFFSETASSERT | |
99 | PPS_ECHOASSERT | | |
eae9d2ba RG |
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 | |
28aedd7e | 106 | initialization routine as follows:: |
eae9d2ba RG |
107 | |
108 | source = pps_register_source(&pps_ktimer_info, | |
109 | PPS_CAPTUREASSERT | PPS_OFFSETASSERT); | |
110 | ||
28aedd7e | 111 | The pps_register_source() prototype is:: |
eae9d2ba | 112 | |
a2d81803 | 113 | int pps_register_source(struct pps_source_info *info, int default_params) |
eae9d2ba RG |
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 | |
a2d81803 | 119 | pps_source_info which describe the capabilities of the driver). |
eae9d2ba RG |
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) | |
28aedd7e | 123 | just using:: |
eae9d2ba RG |
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 | ||
5d250eeb | 133 | Please see the file drivers/pps/clients/pps-ktimer.c for example code. |
eae9d2ba RG |
134 | |
135 | ||
136 | SYSFS support | |
137 | ------------- | |
138 | ||
28aedd7e | 139 | If the SYSFS filesystem is enabled in the kernel it provides a new class:: |
eae9d2ba RG |
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 | |
28aedd7e | 145 | inside you find several files:: |
eae9d2ba | 146 | |
a2d81803 RD |
147 | $ ls -F /sys/class/pps/pps0/ |
148 | assert dev mode path subsystem@ | |
149 | clear echo name power/ uevent | |
150 | ||
eae9d2ba RG |
151 | |
152 | Inside each "assert" and "clear" file you can find the timestamp and a | |
28aedd7e | 153 | sequence number:: |
eae9d2ba RG |
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 | ||
a2d81803 | 161 | * echo: reports if the PPS source has an echo function or not; |
eae9d2ba | 162 | |
a2d81803 | 163 | * mode: reports available PPS functioning modes; |
eae9d2ba | 164 | |
a2d81803 | 165 | * name: reports the PPS source's name; |
eae9d2ba | 166 | |
a2d81803 RD |
167 | * path: reports the PPS source's device path, that is the device the |
168 | PPS source is connected to (if it exists). | |
eae9d2ba RG |
169 | |
170 | ||
171 | Testing the PPS support | |
172 | ----------------------- | |
173 | ||
174 | In order to test the PPS support even without specific hardware you can use | |
a2d81803 | 175 | the pps-ktimer driver (see the client subsection in the PPS configuration menu) |
e1235e18 | 176 | and the userland tools available in your distribution's pps-tools package, |
a2d81803 | 177 | http://linuxpps.org , or https://github.com/redlab-i/pps-tools. |
eae9d2ba | 178 | |
a2d81803 | 179 | Once you have enabled the compilation of pps-ktimer just modprobe it (if |
28aedd7e | 180 | not statically compiled):: |
eae9d2ba | 181 | |
a2d81803 | 182 | # modprobe pps-ktimer |
eae9d2ba | 183 | |
28aedd7e | 184 | and the run ppstest as follow:: |
eae9d2ba | 185 | |
a2d81803 | 186 | $ ./ppstest /dev/pps1 |
eae9d2ba RG |
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 | ||
a2d81803 | 194 | Please note that to compile userland programs, you need the file timepps.h. |
e1235e18 | 195 | This is available in the pps-tools repository mentioned above. |
46b402a0 AG |
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 | ||
28aedd7e MCC |
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 *-----------* | |
46b402a0 AG |
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. |