forked from Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
242 lines
8.4 KiB
242 lines
8.4 KiB
.. SPDX-License-Identifier: GPL-2.0 |
|
|
|
====================== |
|
PPS - Pulse Per Second |
|
====================== |
|
|
|
Copyright (C) 2007 Rodolfo Giometti <[email protected]> |
|
|
|
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 |
|
OK for the serial and parallel port, where you can do something |
|
useful besides(!) the gathering of timestamps as it is the central |
|
task for a PPS API. But this assumption does not work for a single |
|
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 |
|
precondition for the use of a PPS API. |
|
|
|
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 |
|
into files /dev/pps0, /dev/pps1, etc. |
|
|
|
|
|
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 |
|
the USB stack. Users have reported clock instability around +-1ms when |
|
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. |
|
|
|
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). |
|
|
|
|
|
Coding example |
|
-------------- |
|
|
|
To register a PPS source into the kernel you should define a struct |
|
pps_source_info as follows:: |
|
|
|
static struct pps_source_info pps_ktimer_info = { |
|
.name = "ktimer", |
|
.path = "", |
|
.mode = PPS_CAPTUREASSERT | PPS_OFFSETASSERT | |
|
PPS_ECHOASSERT | |
|
PPS_CANWAIT | PPS_TSFMT_TSPEC, |
|
.echo = pps_ktimer_echo, |
|
.owner = THIS_MODULE, |
|
}; |
|
|
|
and then calling the function pps_register_source() in your |
|
initialization routine as follows:: |
|
|
|
source = pps_register_source(&pps_ktimer_info, |
|
PPS_CAPTUREASSERT | PPS_OFFSETASSERT); |
|
|
|
The pps_register_source() prototype is:: |
|
|
|
int pps_register_source(struct pps_source_info *info, int default_params) |
|
|
|
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 |
|
pps_source_info which describe the capabilities of the driver). |
|
|
|
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.. |
|
|
|
Please see the file drivers/pps/clients/pps-ktimer.c for example code. |
|
|
|
|
|
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:: |
|
|
|
$ ls -F /sys/class/pps/pps0/ |
|
assert dev mode path subsystem@ |
|
clear echo name power/ uevent |
|
|
|
|
|
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: |
|
|
|
* echo: reports if the PPS source has an echo function or not; |
|
|
|
* mode: reports available PPS functioning modes; |
|
|
|
* name: reports the PPS source's name; |
|
|
|
* path: reports the PPS source's device path, that is the device the |
|
PPS source is connected to (if it exists). |
|
|
|
|
|
Testing the PPS support |
|
----------------------- |
|
|
|
In order to test the PPS support even without specific hardware you can use |
|
the pps-ktimer driver (see the client subsection in the PPS configuration menu) |
|
and the userland tools available in your distribution's pps-tools package, |
|
http://linuxpps.org , or https://github.com/redlab-i/pps-tools. |
|
|
|
Once you have enabled the compilation of pps-ktimer just modprobe it (if |
|
not statically compiled):: |
|
|
|
# modprobe pps-ktimer |
|
|
|
and the run ppstest as follow:: |
|
|
|
$ ./ppstest /dev/pps1 |
|
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 |
|
|
|
Please note that to compile userland programs, you need the file timepps.h. |
|
This is available in the pps-tools repository mentioned above. |
|
|
|
|
|
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.
|
|
|