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