aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorRodolfo Giometti <giometti@linux.it>2009-06-17 19:28:37 -0400
committerLinus Torvalds <torvalds@linux-foundation.org>2009-06-18 16:04:04 -0400
commiteae9d2ba0cfc27a2ad9765f23efb98fb80d80234 (patch)
treef4be40ca528b2f23f97fa9cb6ebe91b8d6696d5b /Documentation
parent8820f27ad9a5ad2a62cdcdf425d7921c31831800 (diff)
LinuxPPS: core support
This patch adds the kernel side of the PPS support currently named "LinuxPPS". 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. 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. To obtain this goal the userland programs shoud use the PPS API specification (RFC 2783 - Pulse-Per-Second API for UNIX-like Operating Systems, Version 1.0) which in part is implemented by this patch. It provides a set of chars devices, one per PPS source, which can be used to get the time signal. The RFC's functions can be implemented by accessing to these char devices. Signed-off-by: Rodolfo Giometti <giometti@linux.it> Cc: David Woodhouse <dwmw2@infradead.org> Cc: Greg KH <greg@kroah.com> Cc: Randy Dunlap <randy.dunlap@oracle.com> Cc: Kay Sievers <kay.sievers@vrfy.org> Acked-by: Alan Cox <alan@lxorguk.ukuu.org.uk> Cc: Michael Kerrisk <mtk.manpages@googlemail.com> Cc: Christoph Hellwig <hch@infradead.org> Cc: Roman Zippel <zippel@linux-m68k.org> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/ABI/testing/sysfs-pps73
-rw-r--r--Documentation/ioctl/ioctl-number.txt2
-rw-r--r--Documentation/pps/pps.txt172
3 files changed, 247 insertions, 0 deletions
diff --git a/Documentation/ABI/testing/sysfs-pps b/Documentation/ABI/testing/sysfs-pps
new file mode 100644
index 000000000000..25028c7bc37d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-pps
@@ -0,0 +1,73 @@
1What: /sys/class/pps/
2Date: February 2008
3Contact: Rodolfo Giometti <giometti@linux.it>
4Description:
5 The /sys/class/pps/ directory will contain files and
6 directories that will provide a unified interface to
7 the PPS sources.
8
9What: /sys/class/pps/ppsX/
10Date: February 2008
11Contact: Rodolfo Giometti <giometti@linux.it>
12Description:
13 The /sys/class/pps/ppsX/ directory is related to X-th
14 PPS source into the system. Each directory will
15 contain files to manage and control its PPS source.
16
17What: /sys/class/pps/ppsX/assert
18Date: February 2008
19Contact: Rodolfo Giometti <giometti@linux.it>
20Description:
21 The /sys/class/pps/ppsX/assert file reports the assert events
22 and the assert sequence number of the X-th source in the form:
23
24 <secs>.<nsec>#<sequence>
25
26 If the source has no assert events the content of this file
27 is empty.
28
29What: /sys/class/pps/ppsX/clear
30Date: February 2008
31Contact: Rodolfo Giometti <giometti@linux.it>
32Description:
33 The /sys/class/pps/ppsX/clear file reports the clear events
34 and the clear sequence number of the X-th source in the form:
35
36 <secs>.<nsec>#<sequence>
37
38 If the source has no clear events the content of this file
39 is empty.
40
41What: /sys/class/pps/ppsX/mode
42Date: February 2008
43Contact: Rodolfo Giometti <giometti@linux.it>
44Description:
45 The /sys/class/pps/ppsX/mode file reports the functioning
46 mode of the X-th source in hexadecimal encoding.
47
48 Please, refer to linux/include/linux/pps.h for further
49 info.
50
51What: /sys/class/pps/ppsX/echo
52Date: February 2008
53Contact: Rodolfo Giometti <giometti@linux.it>
54Description:
55 The /sys/class/pps/ppsX/echo file reports if the X-th does
56 or does not support an "echo" function.
57
58What: /sys/class/pps/ppsX/name
59Date: February 2008
60Contact: Rodolfo Giometti <giometti@linux.it>
61Description:
62 The /sys/class/pps/ppsX/name file reports the name of the
63 X-th source.
64
65What: /sys/class/pps/ppsX/path
66Date: February 2008
67Contact: Rodolfo Giometti <giometti@linux.it>
68Description:
69 The /sys/class/pps/ppsX/path file reports the path name of
70 the device connected with the X-th source.
71
72 If the source is not connected with any device the content
73 of this file is empty.
diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt
index 1f779a25c703..7bb0d934b6d8 100644
--- a/Documentation/ioctl/ioctl-number.txt
+++ b/Documentation/ioctl/ioctl-number.txt
@@ -149,6 +149,8 @@ Code Seq# Include File Comments
149'p' 40-7F linux/nvram.h 149'p' 40-7F linux/nvram.h
150'p' 80-9F user-space parport 150'p' 80-9F user-space parport
151 <mailto:tim@cyberelk.net> 151 <mailto:tim@cyberelk.net>
152'p' a1-a4 linux/pps.h LinuxPPS
153 <mailto:giometti@linux.it>
152'q' 00-1F linux/serio.h 154'q' 00-1F linux/serio.h
153'q' 80-FF Internet PhoneJACK, Internet LineJACK 155'q' 80-FF Internet PhoneJACK, Internet LineJACK
154 <http://www.quicknet.net> 156 <http://www.quicknet.net>
diff --git a/Documentation/pps/pps.txt b/Documentation/pps/pps.txt
new file mode 100644
index 000000000000..125f4ab48998
--- /dev/null
+++ b/Documentation/pps/pps.txt
@@ -0,0 +1,172 @@
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/).