[PATCH 03/10] PPS: documentation programs and examples.

Previous thread: none

Next thread: none
From: Rodolfo Giometti
Date: Wednesday, August 20, 2008 - 6:16 am

This patch set adds the PPS support into Linux.

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

RESUBMIT 6 -> 7:

* A new line discipline has been added in order to leave untouched
  the serial ports code (as suggested by Alan).

* n_tty.c exports only GPL symbols.

* ioctl numbers fixed in order to avoid any conflicts.

* Last patch (0010-PPS-low-level-IRQ-timestamps-recording.patch) implements
  low level IRQs timestamps recording which mproves PPS precision but can
  be dropped for kernel inclusion! As suggested by Alan: "After that is
  sorted/merged we can come back to working out the best way to improve
  the IRQ and HARDPPS hacks."

Rodolfo

--

 b/Documentation/ABI/testing/sysfs-pps |   73 +++++++
 b/Documentation/ioctl-number.txt      |    2 
 b/Documentation/pps/Makefile          |   28 ++
 b/Documentation/pps/pps.txt           |  172 +++++++++++++++++
 b/Documentation/pps/ppsfind           |   17 +
 b/Documentation/pps/ppsldisc.c        |   46 ++++
 b/Documentation/pps/ppstest.c         |  151 +++++++++++++++
 b/Documentation/pps/timepps.h         |  195 +++++++++++++++++++
 b/Documentation/tty.txt               |    4 
 b/MAINTAINERS                         |    7 
 b/arch/x86/kernel/irq_32.c            |   17 +
 b/arch/x86/kernel/irq_64.c            |   21 +-
 b/drivers/Kconfig                     |    2 
 b/drivers/Makefile                    |    1 
 b/drivers/char/lp.c                   |   61 ++++++
 b/drivers/char/n_tty.c                |   54 +++--
 b/drivers/pps/Kconfig                 |   33 +++
 b/drivers/pps/Makefile                |    8 
 b/drivers/pps/clients/Kconfig         |   18 +
 b/drivers/pps/clients/Makefile        |    9 
 b/drivers/pps/clients/ktimer.c        |  124 ++++++++++++
 ...
From: Rodolfo Giometti
Date: Wednesday, August 20, 2008 - 6:16 am

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>
---
 Documentation/ABI/testing/sysfs-pps |   73 ++++++++
 Documentation/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                  |  322 +++++++++++++++++++++++++++++++++
 drivers/pps/pps.c                   |  335 +++++++++++++++++++++++++++++++++++
 drivers/pps/sysfs.c                 |  104 +++++++++++
 include/linux/Kbuild                |    1 +
 include/linux/pps.h                 |  202 +++++++++++++++++++++
 13 files changed, 1262 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

diff --git ...
From: Rodolfo Giometti
Date: Wednesday, August 20, 2008 - 6:16 am

This patch adds into the PPS's documentation directory a possible
implementation of the PPS API (RFC 2783) by using the LinuxPPS's char
devices.

This file is not just an example but it can be used into real
systems. :)

Signed-off-by: Rodolfo Giometti <giometti@linux.it>
---
 Documentation/pps/timepps.h |  195 +++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 195 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/pps/timepps.h

diff --git a/Documentation/pps/timepps.h b/Documentation/pps/timepps.h
new file mode 100644
index 0000000..2372949
--- /dev/null
+++ b/Documentation/pps/timepps.h
@@ -0,0 +1,195 @@
+/*
+ * timepps.h -- PPS API main header
+ *
+ * Copyright (C) 2005-2007   Rodolfo Giometti <giometti@linux.it>
+ *
+ *   This program is free software; you can redistribute it and/or modify
+ *   it under the terms of the GNU General Public License as published by
+ *   the Free Software Foundation; either version 2 of the License, or
+ *   (at your option) any later version.
+ *
+ *   This program is distributed in the hope that it will be useful,
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *   GNU General Public License for more details.
+ *
+ *   You should have received a copy of the GNU General Public License
+ *   along with this program; if not, write to the Free Software
+ *   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ */
+
+#ifndef _SYS_TIMEPPS_H_
+#define _SYS_TIMEPPS_H_
+
+#include <sys/syscall.h>
+#include <unistd.h>
+#include <errno.h>
+#include <linux/pps.h>
+
+#define LINUXPPS	1		/* signal we are using LinuxPPS */
+
+/*
+ * New data structures
+ */
+
+struct ntp_fp {
+	unsigned int integral;
+	unsigned int fractional;
+};
+
+union pps_timeu {
+	struct timespec tspec;
+	struct ntp_fp ntpfp;
+	unsigned long longpad[3];
+};
+
+struct pps_info {
+	unsigned long assert_sequence;	/* seq. num. of ...
From: Rodolfo Giometti
Date: Wednesday, August 20, 2008 - 6:16 am

Here some utilities and examples about the PPS API and the LinuxPPS
support.

* ppsldisc.c shows how to manage PPS line discipline;

* ppstest.c implements an useful testing program, while

* ppsfind tries to help the user into finding a specific PPS source by
  using its name or path.

Signed-off-by: Rodolfo Giometti <giometti@linux.it>
---
 Documentation/pps/Makefile   |   28 ++++++++
 Documentation/pps/ppsfind    |   17 +++++
 Documentation/pps/ppsldisc.c |   46 +++++++++++++
 Documentation/pps/ppstest.c  |  151 ++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 242 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/pps/Makefile
 create mode 100644 Documentation/pps/ppsfind
 create mode 100644 Documentation/pps/ppsldisc.c
 create mode 100644 Documentation/pps/ppstest.c

diff --git a/Documentation/pps/Makefile b/Documentation/pps/Makefile
new file mode 100644
index 0000000..9841e6b
--- /dev/null
+++ b/Documentation/pps/Makefile
@@ -0,0 +1,28 @@
+TARGETS = ppstest ppsldisc
+
+CFLAGS += -Wall -O2 -D_GNU_SOURCE
+CFLAGS += -I .
+CFLAGS += -ggdb
+CFLAGS += -D__N_PPS=$(shell awk '/N_PPS/ {print $$3}' ../../include/linux/tty.h)
+
+# -- Actions section --
+
+.PHONY : all depend dep
+
+all : .depend $(TARGETS)
+
+.depend depend dep :
+	$(CC) $(CFLAGS) -M $(TARGETS:=.c) > .depend
+
+ifeq (.depend,$(wildcard .depend))
+include .depend
+endif
+
+
+# -- Clean section --
+
+.PHONY : clean
+
+clean :
+	rm -f *.o *~ core .depend
+	rm -f ${TARGETS}
diff --git a/Documentation/pps/ppsfind b/Documentation/pps/ppsfind
new file mode 100644
index 0000000..93c0e17
--- /dev/null
+++ b/Documentation/pps/ppsfind
@@ -0,0 +1,17 @@
+#!/bin/sh
+
+SYS="/sys/class/pps/"
+
+if [ $# -lt 1 ] ; then
+	echo "usage: ppsfind <name>" >&2
+	exit 1
+fi
+
+for d in $(ls $SYS) ; do
+	if grep $1 $SYS/$d/name >& /dev/null || \
+	   grep $1 $SYS/$d/path >& /dev/null ; then
+		echo "$d: name=$(cat $SYS/$d/name) path=$(cat $SYS/$d/path)"
+	fi
+done
+
+exit ...
From: Rodolfo Giometti
Date: Wednesday, August 20, 2008 - 6:16 am

Each PPS source can be registered/deregistered into the system by
using special modules called "clients". They simply define the PPS
sources' attributes and implement the time signal registartion
mechanism.

This patch adds a special directory for such clients and adds a dummy
client that can be useful to test system integrity on real systems.

Signed-off-by: Rodolfo Giometti <giometti@linux.it>
---
 drivers/pps/Kconfig          |    2 +
 drivers/pps/Makefile         |    1 +
 drivers/pps/clients/Kconfig  |   18 ++++++
 drivers/pps/clients/Makefile |    9 +++
 drivers/pps/clients/ktimer.c |  124 ++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 154 insertions(+), 0 deletions(-)
 create mode 100644 drivers/pps/clients/Kconfig
 create mode 100644 drivers/pps/clients/Makefile
 create mode 100644 drivers/pps/clients/ktimer.c

diff --git a/drivers/pps/Kconfig b/drivers/pps/Kconfig
index cc2eb8e..1afe4e0 100644
--- a/drivers/pps/Kconfig
+++ b/drivers/pps/Kconfig
@@ -30,4 +30,6 @@ config PPS_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.
 
+source drivers/pps/clients/Kconfig
+
 endmenu
diff --git a/drivers/pps/Makefile b/drivers/pps/Makefile
index 19ea582..98960dd 100644
--- a/drivers/pps/Makefile
+++ b/drivers/pps/Makefile
@@ -4,5 +4,6 @@
 
 pps_core-y			:= pps.o kapi.o sysfs.o
 obj-$(CONFIG_PPS)		:= pps_core.o
+obj-y				+= clients/
 
 ccflags-$(CONFIG_PPS_DEBUG) := -DDEBUG
diff --git a/drivers/pps/clients/Kconfig b/drivers/pps/clients/Kconfig
new file mode 100644
index 0000000..60b83be
--- /dev/null
+++ b/drivers/pps/clients/Kconfig
@@ -0,0 +1,18 @@
+#
+# PPS clients configuration
+#
+
+if PPS
+
+comment "PPS clients support"
+
+config PPS_CLIENT_KTIMER
+	tristate "Kernel timer client (Testing client, use for debug)"
+	help
+	  If you say yes here you get support for a PPS debugging client
+	  which uses a kernel timer to generate the PPS ...
From: H. Peter Anvin
Date: Thursday, August 21, 2008 - 2:50 pm

A couple of general questions about this (I don't know the background 
material in enough detail, so pardon if some of these are "obvious"):

1. Does this support (calibrated) sources with frequency other than
    1 Hz?
2. I assume that with the PPS line discipline loaded you can still read
    the data from the main pins on the serial port (almost always used
    for metadata?)

And a minor note: you use the term CD (Carrier Detect), but in most 
references the pin is labelled DCD (Data Carrier Detect).

	-hpa

--

From: Alan Cox
Date: Thursday, August 21, 2008 - 4:20 pm

Yes - thats why the ldisc was done inheriting from the N_TTY discipline.

Alan
--

From: H. Peter Anvin
Date: Thursday, August 21, 2008 - 4:44 pm

Excellent.  It felt like a stupid question, but I thought I'd ask it anyway.

	-hpa
--

From: Rodolfo Giometti
Date: Friday, August 22, 2008 - 1:53 am

No. PPS means Pulse-Per-Second. However the code can be used with

You are right. :)

Ciao,

Rodolfo

-- 

GNU/Linux Solutions                  e-mail: giometti@enneenne.com
Linux Device Driver                          giometti@linux.it
Embedded Systems                     phone:  +39 349 2432127
UNIX programming                     skype:  rodolfo.giometti
--

Previous thread: none

Next thread: none