mirror of
git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
synced 2025-10-31 16:54:21 +00:00
c92992fc60
There are a number of driver-specific descriptions that contain a mix of userspace and kernelspace documentation. Just like we did with other similar subsystems, add them at the driver-api groupset, but don't move the directories. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
242 lines
8.4 KiB
ReStructuredText
242 lines
8.4 KiB
ReStructuredText
.. 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 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.
|