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