Skip to contentSkip to conversation

LinuxPPS core (Version 2): the PPS Linux implementation.

PATCH In review Rodolfo Giometti 6 participants 9 messages Feb 10, 2009 – Feb 24, 2009

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

This patch adds the PPS core support into Linux.

Currently I just propose the "core" so after inclusion we can add all other related stuff as suggested by several people in this list. :)

PPS means "pulse per second" and its API is specified by RFC 2783 (Pulse-Per-Second API for UNIX-like Operating Systems, Version 1.0).

The code has been tested with the NTPD program
(http://www.eecis.udel.edu/~mills/ntp/html/index.html) and several GPS antennae.

Changelog
=========

Version 1 -> 2
--------------

* fix race during PPS source registration.

* PPS_CHECK removed.

* not needed check in pps_exit() removed.

* Printing stuff on exit removed.

Version [full patchset] -> 1
----------------------------

* stupid filenames removed.

* kernel-doc documentation of exported symbols.

* old BKL-locked ioctl removed.

* !uarg checks in the ioctls removed.

* pps.h revisited but not splitted, since several stuff are shared between kernel and user land (I hope this will not stop inclusion...)

Rodolfo

#1 lore raw

PATCH 1/1 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.

---
 Documentation/ABI/testing/sysfs-pps  |   73 ++++++++
 Documentation/ioctl/ioctl-number.txt |    2 +
 Documentation/pps/pps.txt            |  172 ++++++++++++++++++
 MAINTAINERS                          |    7 +
 drivers/Kconfig                      |    2 +
 drivers/Makefile                     |    1 +
 drivers/pps/Kconfig                  |   33 ++++
 drivers/pps/Makefile                 |    8 +
 drivers/pps/kapi.c                   |  329 ++++++++++++++++++++++++++++++++++
 drivers/pps/pps.c                    |  312 ++++++++++++++++++++++++++++++++
 drivers/pps/sysfs.c                  |  104 +++++++++++
 include/linux/Kbuild                 |    1 +
 include/linux/pps.h                  |  194 ++++++++++++++++++++
 13 files changed, 1238 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/ABI/testing/sysfs-pps
 create mode 100644 Documentation/pps/pps.txt
 create mode 100644 drivers/pps/Kconfig
 create mode 100644 drivers/pps/Makefile
 create mode 100644 drivers/pps/kapi.c
 create mode 100644 drivers/pps/pps.c
 create mode 100644 drivers/pps/sysfs.c
 create mode 100644 include/linux/pps.h
Documentation/ABI/testing/sysfs-pps new file +73 -0
new file mode 100644
index 0000000..25028c7
@@ -0,0 +1,73 @@
+What:		/sys/class/pps/
+Date:		February 2008
+Contact:	Rodolfo Giometti <[email protected]>
+Description:
+		The /sys/class/pps/ directory will contain files and
+		directories that will provide a unified interface to
+		the PPS sources.
+
+What:		/sys/class/pps/ppsX/
+Date:		February 2008
+Contact:	Rodolfo Giometti <[email protected]>
+Description:
+		The /sys/class/pps/ppsX/ directory is related to X-th
+		PPS source into the system. Each directory will
+		contain files to manage and control its PPS source.
+
+What:		/sys/class/pps/ppsX/assert
+Date:		February 2008
+Contact:	Rodolfo Giometti <[email protected]>
+Description:
+		The /sys/class/pps/ppsX/assert file reports the assert events
+		and the assert sequence number of the X-th source in the form:
+
+			<secs>.<nsec>#<sequence>
+
+		If the source has no assert events the content of this file
+		is empty.
+
+What:		/sys/class/pps/ppsX/clear
+Date:		February 2008
+Contact:	Rodolfo Giometti <[email protected]>
+Description:
+		The /sys/class/pps/ppsX/clear file reports the clear events
+		and the clear sequence number of the X-th source in the form:
+
+			<secs>.<nsec>#<sequence>
+
+		If the source has no clear events the content of this file
+		is empty.
+
+What:		/sys/class/pps/ppsX/mode
+Date:		February 2008
+Contact:	Rodolfo Giometti <[email protected]>
+Description:
+		The /sys/class/pps/ppsX/mode file reports the functioning
+		mode of the X-th source in hexadecimal encoding.
+
+		Please, refer to linux/include/linux/pps.h for further
+		info.
+
+What:		/sys/class/pps/ppsX/echo
+Date:		February 2008
+Contact:	Rodolfo Giometti <[email protected]>
+Description:
+		The /sys/class/pps/ppsX/echo file reports if the X-th does
+		or does not support an "echo" function.
+
+What:		/sys/class/pps/ppsX/name
+Date:		February 2008
+Contact:	Rodolfo Giometti <[email protected]>
+Description:
+		The /sys/class/pps/ppsX/name file reports the name of the
+		X-th source.
+
+What:		/sys/class/pps/ppsX/path
+Date:		February 2008
+Contact:	Rodolfo Giometti <[email protected]>
+Description:
+		The /sys/class/pps/ppsX/path file reports the path name of
+		the device connected with the X-th source.
+
+		If the source is not connected with any device the content
+		of this file is empty.
Documentation/ioctl/ioctl-number.txt +2 -0
index f1d6399..df7aeca 100644
@@ -151,6 +151,8 @@ Code	Seq#	Include File		Comments
 'p'	40-7F	linux/nvram.h
 'p'	80-9F				user-space parport
 					<mailto:[email protected]>
+'p'	a1-a4	linux/pps.h		LinuxPPS
+					<mailto:[email protected]>
 'q'	00-1F	linux/serio.h
 'q'	80-FF				Internet PhoneJACK, Internet LineJACK
 					<http://www.quicknet.net>
Documentation/pps/pps.txt new file +172 -0

172 lines not on this page · raw message

MAINTAINERS +7 -0
index d992d40..d2ab232 100644
@@ -3464,6 +3464,13 @@ P:	James Chapman
 M:	[email protected]
 S:	Maintained
 
+PPS SUPPORT
+P:	Rodolfo Giometti
+M:	[email protected]
+W:	http://wiki.enneenne.com/index.php/LinuxPPS_support
+L:	[email protected] (subscribers-only)
+S:	Maintained
+
 PREEMPTIBLE KERNEL
 P:	Robert Love
 M:	[email protected]
drivers/Kconfig +2 -0
index 00cf955..e328e5b 100644
@@ -52,6 +52,8 @@ source "drivers/i2c/Kconfig"
 
 source "drivers/spi/Kconfig"
 
+source "drivers/pps/Kconfig"
+
 source "drivers/gpio/Kconfig"
 
 source "drivers/w1/Kconfig"
drivers/Makefile +1 -0
index c1bf417..ff07ab9 100644
@@ -71,6 +71,7 @@ obj-$(CONFIG_INPUT)		+= input/
 obj-$(CONFIG_I2O)		+= message/
 obj-$(CONFIG_RTC_LIB)		+= rtc/
 obj-y				+= i2c/
+obj-$(CONFIG_PPS)		+= pps/
 obj-$(CONFIG_W1)		+= w1/
 obj-$(CONFIG_POWER_SUPPLY)	+= power/
 obj-$(CONFIG_HWMON)		+= hwmon/
drivers/pps/Kconfig new file +33 -0
new file mode 100644
index 0000000..cc2eb8e
@@ -0,0 +1,33 @@
+#
+# PPS support configuration
+#
+
+menu "PPS support"
+
+config PPS
+	tristate "PPS support"
+	depends on EXPERIMENTAL
+	---help---
+	  PPS (Pulse Per Second) is a special pulse provided by some GPS
+	  antennae. Userland can use it to get a high-precision time
+	  reference.
+
+	  Some antennae's PPS signals are connected with the CD (Carrier
+	  Detect) pin of the serial line they use to communicate with the
+	  host. In this case use the SERIAL_LINE client support.
+
+	  Some antennae's PPS signals are connected with some special host
+	  inputs so you have to enable the corresponding client support.
+
+	  To compile this driver as a module, choose M here: the module
+	  will be called pps_core.ko.
+
+config PPS_DEBUG
+	bool "PPS debugging messages"
+	depends on PPS
+	help
+	  Say Y here if you want the PPS support to produce a bunch of debug
+	  messages to the system log.  Select this if you are having a
+	  problem with PPS support and want to see more of what is going on.
+
+endmenu
drivers/pps/Makefile new file +8 -0
new file mode 100644
index 0000000..19ea582
@@ -0,0 +1,8 @@
+#
+# Makefile for the PPS core.
+#
+
+pps_core-y			:= pps.o kapi.o sysfs.o
+obj-$(CONFIG_PPS)		:= pps_core.o
+
+ccflags-$(CONFIG_PPS_DEBUG) := -DDEBUG
drivers/pps/kapi.c new file +329 -0

329 lines not on this page · raw message

drivers/pps/pps.c new file +312 -0

312 lines not on this page · raw message

drivers/pps/sysfs.c new file +104 -0

104 lines not on this page · raw message

include/linux/Kbuild +1 -0
index 12e9a29..5df789c 100644
@@ -304,6 +304,7 @@ unifdef-y += pmu.h
 unifdef-y += poll.h
 unifdef-y += ppp_defs.h
 unifdef-y += ppp-comp.h
+unifdef-y += pps.h
 unifdef-y += ptrace.h
 unifdef-y += qnx4_fs.h
 unifdef-y += quota.h
include/linux/pps.h new file +194 -0

194 lines not on this page · raw message

Signature · 1 line
1.5.6.3
#2 lore raw

Re: [PATCH 1/1] LinuxPPS core support.

Quoted 10 lines · Rodolfo Giometti

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.

Hm. I was looking at this stuff with the prospect of adding it to the timer tree, but i'm really struggling with a few fundamental questions.

The most basic one is: why do we need this?

The main purpose of your current patchset seems to be to deliver interrupt timestamps to user-space, where it will in essence be used to feed new adjtimex adjustments via ntpd.

I.e. the whole thing comes around in a circle in the end, but via user-space, where jitter will only increase.

Why not cut out the jittery middle man and add some intelligent API to register PPS interrupt sources straight with the NTP code, and let those IRQ timestamps be fed _directly_ into our time adjustment code?

Ingo

#3 lore raw

Re: [PATCH 1/1] LinuxPPS core support.

Quoted 15 lines · Ingo Molnar
Quoted 4 lines

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.

Hm. I was looking at this stuff with the prospect of adding it to the timer tree, but i'm really struggling with a few fundamental questions.

The most basic one is: why do we need this?

The main purpose of your current patchset seems to be to deliver interrupt timestamps to user-space, where it will in essence be used to feed new adjtimex adjustments via ntpd.

Quoted 8 lines

I.e. the whole thing comes around in a circle in the end, but via user-space, where jitter will only increase.

Why not cut out the jittery middle man and add some intelligent API to register PPS interrupt sources straight with the NTP code, and let those IRQ timestamps be fed _directly_ into our time adjustment code?

Well, let's be fair here... the kernel-user space time model involving ntpd has been very carefully developed over a period of over a decade. It's known to work. The userspace involvement isn't just about feeding the data to the local clock, but also -- or perhaps primarily so -- to keep the timing inside ntpd calibrated, as that is the time that will be provided to the outside world.

There is a real benefit to using the model designed for and expected by ntpd, too.

-hpa

Signature · 2 lines
H. Peter Anvin, Intel Open Source Technology Center
I work for Intel.  I don't speak on their behalf.
#4 lore raw

Re: [PATCH 1/1] LinuxPPS core support.

Quoted 25 lines · H. Peter Anvin
Quoted 15 lines · Ingo Molnar
Quoted 4 lines

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.

Hm. I was looking at this stuff with the prospect of adding it to the timer tree, but i'm really struggling with a few fundamental questions.

The most basic one is: why do we need this?

The main purpose of your current patchset seems to be to deliver interrupt timestamps to user-space, where it will in essence be used to feed new adjtimex adjustments via ntpd.

Quoted 8 lines

I.e. the whole thing comes around in a circle in the end, but via user-space, where jitter will only increase.

Why not cut out the jittery middle man and add some intelligent API to register PPS interrupt sources straight with the NTP code, and let those IRQ timestamps be fed _directly_ into our time adjustment code?

Quoted 7 lines

Well, let's be fair here... the kernel-user space time model involving ntpd has been very carefully developed over a period of over a decade. It's known to work. The userspace involvement isn't just about feeding the data to the local clock, but also -- or perhaps primarily so -- to keep the timing inside ntpd calibrated, as that is the time that will be provided to the outside world.

Sure thing, the policy bits should still be done by user-space - something does have to know that there's a PPS device on the serial, parallel or any other port, and has to configure set up the actual parameters as well, etc.

What i'm pointing out is that there's no technical benefit from passing the _timestamps_ through user-space and from not coupling the NTP code with the PPS edges.

Nor has it really been designed into NTP that way. We already have all the traditional PPS parameters in the NTP syscall interface:

include/linux/timex.h:

struct timex {
[...]

        long ppsfreq;           /* pps frequency (scaled ppm) (ro) */
        long jitter;            /* pps jitter (us) (ro) */
        int shift;              /* interval duration (s) (shift) (ro) */
        long stabil;            /* pps stability (scaled ppm) (ro) */
        long jitcnt;            /* jitter limit exceeded (ro) */
        long calcnt;            /* calibration intervals (ro) */
        long errcnt;            /* calibration errors (ro) */
        long stbcnt;            /* stability limit exceeded (ro) */

(these are the bits to query the state of kernel-side PPS support.)

and we have the bits to enable a PPS line disciple, etc., etc. We might need some extensions, but since the PPS device will be handled by the kernel anyway and the NTP adjustments are done in the kernel too, there's no strong reason to route the actual timestamps via user-space. In fact, doing so obviously increases jitter and slows down NTP convergence.

Ingo

maintainer
#5 lore raw

Re: [PATCH 1/1] LinuxPPS core support.

Quoted 65 lines · Ingo Molnar
Quoted 25 lines · H. Peter Anvin
Quoted 15 lines · Ingo Molnar
Quoted 4 lines

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.

Hm. I was looking at this stuff with the prospect of adding it to the timer tree, but i'm really struggling with a few fundamental questions.

The most basic one is: why do we need this?

The main purpose of your current patchset seems to be to deliver interrupt timestamps to user-space, where it will in essence be used to feed new adjtimex adjustments via ntpd.

Quoted 8 lines

I.e. the whole thing comes around in a circle in the end, but via user-space, where jitter will only increase.

Why not cut out the jittery middle man and add some intelligent API to register PPS interrupt sources straight with the NTP code, and let those IRQ timestamps be fed _directly_ into our time adjustment code?

Quoted 7 lines

Well, let's be fair here... the kernel-user space time model involving ntpd has been very carefully developed over a period of over a decade. It's known to work. The userspace involvement isn't just about feeding the data to the local clock, but also -- or perhaps primarily so -- to keep the timing inside ntpd calibrated, as that is the time that will be provided to the outside world.

Sure thing, the policy bits should still be done by user-space - something does have to know that there's a PPS device on the serial, parallel or any other port, and has to configure set up the actual parameters as well, etc.

What i'm pointing out is that there's no technical benefit from passing the _timestamps_ through user-space and from not coupling the NTP code with the PPS edges.

Nor has it really been designed into NTP that way. We already have all the traditional PPS parameters in the NTP syscall interface:

include/linux/timex.h:

struct timex {
[...]

        long ppsfreq;           /* pps frequency (scaled ppm) (ro) */
        long jitter;            /* pps jitter (us) (ro) */
        int shift;              /* interval duration (s) (shift) (ro) */
        long stabil;            /* pps stability (scaled ppm) (ro) */
        long jitcnt;            /* jitter limit exceeded (ro) */
        long calcnt;            /* calibration intervals (ro) */
        long errcnt;            /* calibration errors (ro) */
        long stbcnt;            /* stability limit exceeded (ro) */

(these are the bits to query the state of kernel-side PPS support.)

Quoted 6 lines

and we have the bits to enable a PPS line disciple, etc., etc. We might need some extensions, but since the PPS device will be handled by the kernel anyway and the NTP adjustments are done in the kernel too, there's no strong reason to route the actual timestamps via user-space. In fact, doing so obviously increases jitter and slows down NTP convergence.

Precise time settings can be done in both kernel and user spaces. RFC2783 specifies an API that can be used to fetch PPS timestamps from a PPS source, then these timestamps can be processed by an userland consumer (NTPD in most cases) to set up system time.

Again the RFC2783 specifies a way to manage some kernel consumers which can do the same jobs in kernel land, but all these stuff are declared as "optional".

I agree with you that passing timestamps to userland may increase jitter and slow down NTP convergence but LinuxPPS is a way to have at least one "precise" time setting tool! :) However, as far as I know, the NTPD algorith should take in account such jitters (I'm sorry but I cannot be more precise since I'm not a NTPD guru), in fact if these timestamps are taken "as soon as" possible inside the IRQ handling chain the NTP convergence speed up several times.

In any case, if we wish adding a more performance tool in kernel space we can just do it as RFC2783 says and (maybe) managing it with the struct above.

Ciao,

Rodolfo

Signature · 4 lines
GNU/Linux Solutions                  e-mail: [email protected]
Linux Device Driver                          [email protected]
Embedded Systems                     phone:  +39 349 2432127
UNIX programming                     skype:  rodolfo.giometti
#6 lore raw
In reply to Rodolfo Giometti
Quoted 32 lines · On Tue, 10 Feb 2009 15:05:51 +0100 Rodolfo Giometti <[email protected]> wrote:

This patch adds the PPS core support into Linux.

Currently I just propose the "core" so after inclusion we can add all other related stuff as suggested by several people in this list. :)

PPS means "pulse per second" and its API is specified by RFC 2783 (Pulse-Per-Second API for UNIX-like Operating Systems, Version 1.0).

The code has been tested with the NTPD program
(http://www.eecis.udel.edu/~mills/ntp/html/index.html) and several GPS antennae.

Changelog
=========

Version 1 -> 2
--------------

* fix race during PPS source registration.

* PPS_CHECK removed.

* not needed check in pps_exit() removed.

* Printing stuff on exit removed.

Version [full patchset] -> 1
----------------------------

* stupid filenames removed.

Quoted 9 lines

* kernel-doc documentation of exported symbols.

* old BKL-locked ioctl removed.

* !uarg checks in the ioctls removed.

* pps.h revisited but not splitted, since several stuff are shared between kernel and user land (I hope this will not stop inclusion...)

Is it hard to do this? Just a matter of putting some things into pps_user.h, others into pps_kernel.h and then including both into pps.h?

#7 lore raw
Quoted 5 lines · Andrew Morton

Is it hard to do this? Just a matter of putting some things into pps_user.h, others into pps_kernel.h and then including both into pps.h?

Or perhaps better...

The user code in <linux/pps.h>, and then #include <linux/pps.h> from <linux/pps_kernel.h> That way we don't need any #ifdefs at all.

-hpa

#8 lore raw
Quoted 11 lines · H. Peter Anvin
Quoted 5 lines · Andrew Morton

Is it hard to do this? Just a matter of putting some things into pps_user.h, others into pps_kernel.h and then including both into pps.h?

Or perhaps better...

The user code in <linux/pps.h>, and then #include <linux/pps.h> from <linux/pps_kernel.h> That way we don't need any #ifdefs at all.

*nod*

that's what I had in mind.