diff options
author | Rodolfo Giometti <giometti@linux.it> | 2009-06-17 19:28:37 -0400 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2009-06-18 16:04:04 -0400 |
commit | eae9d2ba0cfc27a2ad9765f23efb98fb80d80234 (patch) | |
tree | f4be40ca528b2f23f97fa9cb6ebe91b8d6696d5b /Documentation | |
parent | 8820f27ad9a5ad2a62cdcdf425d7921c31831800 (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-pps | 73 | ||||
-rw-r--r-- | Documentation/ioctl/ioctl-number.txt | 2 | ||||
-rw-r--r-- | Documentation/pps/pps.txt | 172 |
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 @@ | |||
1 | What: /sys/class/pps/ | ||
2 | Date: February 2008 | ||
3 | Contact: Rodolfo Giometti <giometti@linux.it> | ||
4 | Description: | ||
5 | The /sys/class/pps/ directory will contain files and | ||
6 | directories that will provide a unified interface to | ||
7 | the PPS sources. | ||
8 | |||
9 | What: /sys/class/pps/ppsX/ | ||
10 | Date: February 2008 | ||
11 | Contact: Rodolfo Giometti <giometti@linux.it> | ||
12 | Description: | ||
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 | |||
17 | What: /sys/class/pps/ppsX/assert | ||
18 | Date: February 2008 | ||
19 | Contact: Rodolfo Giometti <giometti@linux.it> | ||
20 | Description: | ||
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 | |||
29 | What: /sys/class/pps/ppsX/clear | ||
30 | Date: February 2008 | ||
31 | Contact: Rodolfo Giometti <giometti@linux.it> | ||
32 | Description: | ||
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 | |||
41 | What: /sys/class/pps/ppsX/mode | ||
42 | Date: February 2008 | ||
43 | Contact: Rodolfo Giometti <giometti@linux.it> | ||
44 | Description: | ||
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 | |||
51 | What: /sys/class/pps/ppsX/echo | ||
52 | Date: February 2008 | ||
53 | Contact: Rodolfo Giometti <giometti@linux.it> | ||
54 | Description: | ||
55 | The /sys/class/pps/ppsX/echo file reports if the X-th does | ||
56 | or does not support an "echo" function. | ||
57 | |||
58 | What: /sys/class/pps/ppsX/name | ||
59 | Date: February 2008 | ||
60 | Contact: Rodolfo Giometti <giometti@linux.it> | ||
61 | Description: | ||
62 | The /sys/class/pps/ppsX/name file reports the name of the | ||
63 | X-th source. | ||
64 | |||
65 | What: /sys/class/pps/ppsX/path | ||
66 | Date: February 2008 | ||
67 | Contact: Rodolfo Giometti <giometti@linux.it> | ||
68 | Description: | ||
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 | |||
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 | Coding example | ||
70 | -------------- | ||
71 | |||
72 | To register a PPS source into the kernel you should define a struct | ||
73 | pps_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 | |||
85 | and then calling the function pps_register_source() in your | ||
86 | intialization routine as follows: | ||
87 | |||
88 | source = pps_register_source(&pps_ktimer_info, | ||
89 | PPS_CAPTUREASSERT | PPS_OFFSETASSERT); | ||
90 | |||
91 | The pps_register_source() prototype is: | ||
92 | |||
93 | int pps_register_source(struct pps_source_info_s *info, int default_params) | ||
94 | |||
95 | where "info" is a pointer to a structure that describes a particular | ||
96 | PPS source, "default_params" tells the system what the initial default | ||
97 | parameters for the device should be (it is obvious that these parameters | ||
98 | must be a subset of ones defined in the struct | ||
99 | pps_source_info_s which describe the capabilities of the driver). | ||
100 | |||
101 | Once you have registered a new PPS source into the system you can | ||
102 | signal an assert event (for example in the interrupt handler routine) | ||
103 | just using: | ||
104 | |||
105 | pps_event(source, &ts, PPS_CAPTUREASSERT, ptr) | ||
106 | |||
107 | where "ts" is the event's timestamp. | ||
108 | |||
109 | The same function may also run the defined echo function | ||
110 | (pps_ktimer_echo(), passing to it the "ptr" pointer) if the user | ||
111 | asked for that... etc.. | ||
112 | |||
113 | Please see the file drivers/pps/clients/ktimer.c for example code. | ||
114 | |||
115 | |||
116 | SYSFS support | ||
117 | ------------- | ||
118 | |||
119 | If the SYSFS filesystem is enabled in the kernel it provides a new class: | ||
120 | |||
121 | $ ls /sys/class/pps/ | ||
122 | pps0/ pps1/ pps2/ | ||
123 | |||
124 | Every directory is the ID of a PPS sources defined in the system and | ||
125 | inside you find several files: | ||
126 | |||
127 | $ ls /sys/class/pps/pps0/ | ||
128 | assert clear echo mode name path subsystem@ uevent | ||
129 | |||
130 | Inside each "assert" and "clear" file you can find the timestamp and a | ||
131 | sequence number: | ||
132 | |||
133 | $ cat /sys/class/pps/pps0/assert | ||
134 | 1170026870.983207967#8 | ||
135 | |||
136 | Where before the "#" is the timestamp in seconds; after it is the | ||
137 | sequence 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 | |||
149 | Testing the PPS support | ||
150 | ----------------------- | ||
151 | |||
152 | In order to test the PPS support even without specific hardware you can use | ||
153 | the ktimer driver (see the client subsection in the PPS configuration menu) | ||
154 | and the userland tools provided into Documentaion/pps/ directory. | ||
155 | |||
156 | Once you have enabled the compilation of ktimer just modprobe it (if | ||
157 | not statically compiled): | ||
158 | |||
159 | # modprobe ktimer | ||
160 | |||
161 | and 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 | |||
171 | Please, note that to compile userland programs you need the file timepps.h | ||
172 | (see Documentation/pps/). | ||