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 69PPS with USB to serial devices 70------------------------------ 71 72It is possible to grab the PPS from an USB to serial device. However, 73you should take into account the latencies and jitter introduced by 74the USB stack. Users have reported clock instability around +-1ms when 75synchronized with PPS through USB. With USB 2.0, jitter may decrease 76down to the order of 125 microseconds. 77 78This may be suitable for time server synchronization with NTP because 79of its undersampling and algorithms. 80 81If your device doesn't report PPS, you can check that the feature is 82supported by its driver. Most of the time, you only need to add a call 83to usb_serial_handle_dcd_change after checking the DCD status (see 84ch341 and pl2303 examples). 85 86 87Coding example 88-------------- 89 90To register a PPS source into the kernel you should define a struct 91pps_source_info as follows: 92 93 static struct pps_source_info pps_ktimer_info = { 94 .name = "ktimer", 95 .path = "", 96 .mode = PPS_CAPTUREASSERT | PPS_OFFSETASSERT | 97 PPS_ECHOASSERT | 98 PPS_CANWAIT | PPS_TSFMT_TSPEC, 99 .echo = pps_ktimer_echo, 100 .owner = THIS_MODULE, 101 }; 102 103and then calling the function pps_register_source() in your 104initialization routine as follows: 105 106 source = pps_register_source(&pps_ktimer_info, 107 PPS_CAPTUREASSERT | PPS_OFFSETASSERT); 108 109The pps_register_source() prototype is: 110 111 int pps_register_source(struct pps_source_info *info, int default_params) 112 113where "info" is a pointer to a structure that describes a particular 114PPS source, "default_params" tells the system what the initial default 115parameters for the device should be (it is obvious that these parameters 116must be a subset of ones defined in the struct 117pps_source_info which describe the capabilities of the driver). 118 119Once you have registered a new PPS source into the system you can 120signal an assert event (for example in the interrupt handler routine) 121just using: 122 123 pps_event(source, &ts, PPS_CAPTUREASSERT, ptr) 124 125where "ts" is the event's timestamp. 126 127The same function may also run the defined echo function 128(pps_ktimer_echo(), passing to it the "ptr" pointer) if the user 129asked for that... etc.. 130 131Please see the file drivers/pps/clients/pps-ktimer.c for example code. 132 133 134SYSFS support 135------------- 136 137If the SYSFS filesystem is enabled in the kernel it provides a new class: 138 139 $ ls /sys/class/pps/ 140 pps0/ pps1/ pps2/ 141 142Every directory is the ID of a PPS sources defined in the system and 143inside you find several files: 144 145 $ ls -F /sys/class/pps/pps0/ 146 assert dev mode path subsystem@ 147 clear echo name power/ uevent 148 149 150Inside each "assert" and "clear" file you can find the timestamp and a 151sequence number: 152 153 $ cat /sys/class/pps/pps0/assert 154 1170026870.983207967#8 155 156Where before the "#" is the timestamp in seconds; after it is the 157sequence number. Other files are: 158 159 * echo: reports if the PPS source has an echo function or not; 160 161 * mode: reports available PPS functioning modes; 162 163 * name: reports the PPS source's name; 164 165 * path: reports the PPS source's device path, that is the device the 166 PPS source is connected to (if it exists). 167 168 169Testing the PPS support 170----------------------- 171 172In order to test the PPS support even without specific hardware you can use 173the pps-ktimer driver (see the client subsection in the PPS configuration menu) 174and the userland tools available in your distribution's pps-tools package, 175http://linuxpps.org , or https://github.com/redlab-i/pps-tools. 176 177Once you have enabled the compilation of pps-ktimer just modprobe it (if 178not statically compiled): 179 180 # modprobe pps-ktimer 181 182and the run ppstest as follow: 183 184 $ ./ppstest /dev/pps1 185 trying PPS source "/dev/pps1" 186 found PPS source "/dev/pps1" 187 ok, found 1 source(s), now start fetching data... 188 source 0 - assert 1186592699.388832443, sequence: 364 - clear 0.000000000, sequence: 0 189 source 0 - assert 1186592700.388931295, sequence: 365 - clear 0.000000000, sequence: 0 190 source 0 - assert 1186592701.389032765, sequence: 366 - clear 0.000000000, sequence: 0 191 192Please note that to compile userland programs, you need the file timepps.h. 193This is available in the pps-tools repository mentioned above. 194 195 196Generators 197---------- 198 199Sometimes one needs to be able not only to catch PPS signals but to produce 200them also. For example, running a distributed simulation, which requires 201computers' clock to be synchronized very tightly. One way to do this is to 202invent some complicated hardware solutions but it may be neither necessary 203nor affordable. The cheap way is to load a PPS generator on one of the 204computers (master) and PPS clients on others (slaves), and use very simple 205cables to deliver signals using parallel ports, for example. 206 207Parallel port cable pinout: 208pin name master slave 2091 STROBE *------ * 2102 D0 * | * 2113 D1 * | * 2124 D2 * | * 2135 D3 * | * 2146 D4 * | * 2157 D5 * | * 2168 D6 * | * 2179 D7 * | * 21810 ACK * ------* 21911 BUSY * * 22012 PE * * 22113 SEL * * 22214 AUTOFD * * 22315 ERROR * * 22416 INIT * * 22517 SELIN * * 22618-25 GND *-----------* 227 228Please note that parallel port interrupt occurs only on high->low transition, 229so it is used for PPS assert edge. PPS clear edge can be determined only 230using polling in the interrupt handler which actually can be done way more 231precisely because interrupt handling delays can be quite big and random. So 232current parport PPS generator implementation (pps_gen_parport module) is 233geared towards using the clear edge for time synchronization. 234 235Clear edge polling is done with disabled interrupts so it's better to select 236delay between assert and clear edge as small as possible to reduce system 237latencies. But if it is too small slave won't be able to capture clear edge 238transition. The default of 30us should be good enough in most situations. 239The delay can be selected using 'delay' pps_gen_parport module parameter. 240
