Something went wrong. Try again.
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
11 kB · 311 lines
at master
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312.. SPDX-License-Identifier: GPL-2.0
======================PPS - Pulse Per Second======================
Copyright (C) 2007 Rodolfo Giometti <giometti@enneenne.com>
This program is free software; you can redistribute it and/or modifyit under the terms of the GNU General Public License as published bythe 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 ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See theGNU General Public License for more details.
Overview--------
LinuxPPS provides a programming interface (API) to define in thesystem several PPS sources.
PPS means "pulse per second" and a PPS source is just a device whichprovides a high precision signal each second so that an applicationcan use it to adjust system clock time.
A PPS source can be connected to a serial port (usually to the DataCarrier Detect pin) or to a parallel port (ACK-pin) or to a specialCPU's GPIOs (this is the common case in embedded systems) but in eachcase when a new pulse arrives the system must apply to it a timestampand record it for userland.
Common use is the combination of the NTPD as userland program, with aGPS receiver as PPS source, to obtain a wallclock-time withsub-millisecond synchronisation to UTC.
RFC considerations------------------
While implementing a PPS API as RFC 2783 defines and using an embeddedCPU GPIO-Pin as physical link to the signal, I encountered a deeperproblem:
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 isOK for the serial and parallel port, where you can do somethinguseful besides(!) the gathering of timestamps as it is the centraltask for a PPS API. But this assumption does not work for a singlepurpose GPIO line. In this case even basic file-related functionality(like read() and write()) makes no sense at all and should not be aprecondition for the use of a PPS API.
The problem can be simply solved if you consider that a PPS source isnot always connected with a GPS data source.
So your programs should check if the GPS data source (the serial portfor instance) is a PPS source too, and if not they should provide thepossibility to open another device as PPS source.
In LinuxPPS the PPS sources are simply char devices usually mappedinto 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 bythe USB stack. Users have reported clock instability around +-1ms whensynchronized with PPS through USB. With USB 2.0, jitter may decreasedown to the order of 125 microseconds.
This may be suitable for time server synchronization with NTP becauseof its undersampling and algorithms.
If your device doesn't report PPS, you can check that the feature issupported by its driver. Most of the time, you only need to add a callto usb_serial_handle_dcd_change after checking the DCD status (seech341 and pl2303 examples).
Coding example--------------
To register a PPS source into the kernel you should define a structpps_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 yourinitialization 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 particularPPS source, "default_params" tells the system what the initial defaultparameters for the device should be (it is obvious that these parametersmust be a subset of ones defined in the structpps_source_info which describe the capabilities of the driver).
Once you have registered a new PPS source into the system you cansignal 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 userasked 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 andinside 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 asequence number::
$ cat /sys/class/pps/pps0/assert 1170026870.983207967#8
Where before the "#" is the timestamp in seconds; after it is thesequence 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 usethe 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 (ifnot 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 producethem also. For example, running a distributed simulation, which requirescomputers' clock to be synchronized very tightly.
To do so the class pps-gen has been added. PPS generators can beregistered in the kernel by defining a struct pps_gen_source_info asfollows::
static const struct pps_gen_source_info pps_gen_dummy_info = { .use_system_clock = true, .get_time = pps_gen_dummy_get_time, .enable = pps_gen_dummy_enable, };
Where the use_system_clock states if the generator uses the systemclock to generate its pulses, or they are from a peripheral deviceclock. Method get_time() is used to query the time stored into thegenerator clock, while the method enable() is used to enable ordisable the PPS pulse generation.
Then calling the function pps_gen_register_source() in yourinitialization routine as follows creates a new generator in thesystem::
pps_gen = pps_gen_register_source(&pps_gen_dummy_info);
Generators SYSFS support------------------------
If the SYSFS filesystem is enabled in the kernel it provides a new class::
$ ls /sys/class/pps-gen/ pps-gen0/ pps-gen1/ pps-gen2/
Every directory is the ID of a PPS generator defined in the system andinside of it you find several files::
$ ls -F /sys/class/pps-gen/pps-gen0/ dev enable name power/ subsystem@ system time uevent
To enable the PPS signal generation you can use the command below::
$ echo 1 > /sys/class/pps-gen/pps-gen0/enable
Parallel port generator------------------------
One way to do this is to invent some complicated hardware solutions but itmay be neither necessary nor affordable. The cheap way is to load a PPSgenerator on one of the computers (master) and PPS clients on others(slaves), and use very simple cables to deliver signals using parallelports, 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 onlyusing polling in the interrupt handler which actually can be done way moreprecisely because interrupt handling delays can be quite big and random. Socurrent parport PPS generator implementation (pps_gen_parport module) isgeared towards using the clear edge for time synchronization.
Clear edge polling is done with disabled interrupts so it's better to selectdelay between assert and clear edge as small as possible to reduce systemlatencies. But if it is too small slave won't be able to capture clear edgetransition. The default of 30us should be good enough in most situations.The delay can be selected using 'delay' pps_gen_parport module parameter.
Intel Timed I/O PPS signal generator------------------------------------
Intel Timed I/O is a high precision device, present on 2019 and newer IntelCPUs, that can generate PPS signals.
Timed I/O and system time are both driven by same hardware clock. The signalis generated with a precision of ~20 nanoseconds. The generated PPS signalis used to synchronize an external device with system clock. For example,it can be used to share your clock with a device that receives PPS signal,generated by Timed I/O device. There are dedicated Timed I/O pins to deliverthe PPS signal to an external device.
Usage of Intel Timed I/O as PPS generator:
Start generating PPS signal::
$echo 1 > /sys/class/pps-gen/pps-genx/enable
Stop generating PPS signal::
$echo 0 > /sys/class/pps-gen/pps-genx/enable