About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / pps




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:40 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.