Version:  2.0.40 2.2.26 2.4.37 3.13 3.14 3.15 3.16 3.17 3.18 3.19 4.0 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 4.10

Linux/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 has reported clock instability around +-1ms when
 75 synchronized with PPS through USB. This isn't suited for time server
 76 synchronization.
 77 
 78 If your device doesn't report PPS, you can check that the feature is
 79 supported by its driver. Most of the time, you only need to add a call
 80 to usb_serial_handle_dcd_change after checking the DCD status (see
 81 ch341 and pl2303 examples).
 82 
 83 
 84 Coding example
 85 --------------
 86 
 87 To register a PPS source into the kernel you should define a struct
 88 pps_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 
100 and then calling the function pps_register_source() in your
101 initialization routine as follows:
102 
103     source = pps_register_source(&pps_ktimer_info,
104                         PPS_CAPTUREASSERT | PPS_OFFSETASSERT);
105 
106 The pps_register_source() prototype is:
107 
108   int pps_register_source(struct pps_source_info_s *info, int default_params)
109 
110 where "info" is a pointer to a structure that describes a particular
111 PPS source, "default_params" tells the system what the initial default
112 parameters for the device should be (it is obvious that these parameters
113 must be a subset of ones defined in the struct
114 pps_source_info_s which describe the capabilities of the driver).
115 
116 Once you have registered a new PPS source into the system you can
117 signal an assert event (for example in the interrupt handler routine)
118 just using:
119 
120     pps_event(source, &ts, PPS_CAPTUREASSERT, ptr)
121 
122 where "ts" is the event's timestamp.
123 
124 The same function may also run the defined echo function
125 (pps_ktimer_echo(), passing to it the "ptr" pointer) if the user
126 asked for that... etc..
127 
128 Please see the file drivers/pps/clients/pps-ktimer.c for example code.
129 
130 
131 SYSFS support
132 -------------
133 
134 If the SYSFS filesystem is enabled in the kernel it provides a new class:
135 
136    $ ls /sys/class/pps/
137    pps0/  pps1/  pps2/
138 
139 Every directory is the ID of a PPS sources defined in the system and
140 inside you find several files:
141 
142    $ ls /sys/class/pps/pps0/
143    assert       clear  echo  mode  name  path  subsystem@  uevent
144 
145 Inside each "assert" and "clear" file you can find the timestamp and a
146 sequence number:
147 
148    $ cat /sys/class/pps/pps0/assert
149    1170026870.983207967#8
150 
151 Where before the "#" is the timestamp in seconds; after it is the
152 sequence 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 
164 Testing the PPS support
165 -----------------------
166 
167 In order to test the PPS support even without specific hardware you can use
168 the ktimer driver (see the client subsection in the PPS configuration menu)
169 and the userland tools provided in the Documentation/pps/ directory.
170 
171 Once you have enabled the compilation of ktimer just modprobe it (if
172 not statically compiled):
173 
174    # modprobe ktimer
175 
176 and 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 
186 Please, note that to compile userland programs you need the file timepps.h
187 (see Documentation/pps/).
188 
189 
190 Generators
191 ----------
192 
193 Sometimes one needs to be able not only to catch PPS signals but to produce
194 them also. For example, running a distributed simulation, which requires
195 computers' clock to be synchronized very tightly. One way to do this is to
196 invent some complicated hardware solutions but it may be neither necessary
197 nor affordable. The cheap way is to load a PPS generator on one of the
198 computers (master) and PPS clients on others (slaves), and use very simple
199 cables to deliver signals using parallel ports, for example.
200 
201 Parallel port cable pinout:
202 pin     name    master      slave
203 1       STROBE    *------     *
204 2       D0        *     |     *
205 3       D1        *     |     *
206 4       D2        *     |     *
207 5       D3        *     |     *
208 6       D4        *     |     *
209 7       D5        *     |     *
210 8       D6        *     |     *
211 9       D7        *     |     *
212 10      ACK       *     ------*
213 11      BUSY      *           *
214 12      PE        *           *
215 13      SEL       *           *
216 14      AUTOFD    *           *
217 15      ERROR     *           *
218 16      INIT      *           *
219 17      SELIN     *           *
220 18-25   GND       *-----------*
221 
222 Please note that parallel port interrupt occurs only on high->low transition,
223 so it is used for PPS assert edge. PPS clear edge can be determined only
224 using polling in the interrupt handler which actually can be done way more
225 precisely because interrupt handling delays can be quite big and random. So
226 current parport PPS generator implementation (pps_gen_parport module) is
227 geared towards using the clear edge for time synchronization.
228 
229 Clear edge polling is done with disabled interrupts so it's better to select
230 delay between assert and clear edge as small as possible to reduce system
231 latencies. But if it is too small slave won't be able to capture clear edge
232 transition. The default of 30us should be good enough in most situations.
233 The delay can be selected using 'delay' pps_gen_parport module parameter.

This page was automatically generated by LXR 0.3.1 (source).  •  Linux is a registered trademark of Linus Torvalds  •  Contact us