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