Commit eae9d2ba authored by Rodolfo Giometti's avatar Rodolfo Giometti Committed by Linus Torvalds

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: default avatarRodolfo 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: default avatarAlan 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: default avatarAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent 8820f27a
What: /sys/class/pps/
Date: February 2008
Contact: Rodolfo Giometti <giometti@linux.it>
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 <giometti@linux.it>
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 <giometti@linux.it>
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 <giometti@linux.it>
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 <giometti@linux.it>
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 <giometti@linux.it>
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 <giometti@linux.it>
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 <giometti@linux.it>
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.
......@@ -149,6 +149,8 @@ Code Seq# Include File Comments
'p' 40-7F linux/nvram.h
'p' 80-9F user-space parport
<mailto:tim@cyberelk.net>
'p' a1-a4 linux/pps.h LinuxPPS
<mailto:giometti@linux.it>
'q' 00-1F linux/serio.h
'q' 80-FF Internet PhoneJACK, Internet LineJACK
<http://www.quicknet.net>
......
PPS - Pulse Per Second
----------------------
(C) Copyright 2007 Rodolfo Giometti <giometti@enneenne.com>
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.
Overview
--------
LinuxPPS provides a programming interface (API) to define in the
system several PPS sources.
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.
A PPS source can be connected to a serial port (usually to the Data
Carrier Detect pin) or to a parallel port (ACK-pin) or to a special
CPU's GPIOs (this is the common case in embedded systems) but in each
case when a new pulse arrives the system must apply to it a timestamp
and record it for userland.
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.
RFC considerations
------------------
While implementing a PPS API as RFC 2783 defines and using an embedded
CPU GPIO-Pin as physical link to the signal, I encountered a deeper
problem:
At startup it needs a file descriptor as argument for the function
time_pps_create().
This implies that the source has a /dev/... entry. This assumption is
ok for the serial and parallel port, where you can do something
useful besides(!) the gathering of timestamps as it is the central
task for a PPS-API. But this assumption does not work for a single
purpose GPIO line. In this case even basic file-related functionality
(like read() and write()) makes no sense at all and should not be a
precondition for the use of a PPS-API.
The problem can be simply solved if you consider that a PPS source is
not always connected with a GPS data source.
So your programs should check if the GPS data source (the serial port
for instance) is a PPS source too, and if not they should provide the
possibility to open another device as PPS source.
In LinuxPPS the PPS sources are simply char devices usually mapped
into files /dev/pps0, /dev/pps1, etc..
Coding example
--------------
To register a PPS source into the kernel you should define a struct
pps_source_info_s as follows:
static struct pps_source_info pps_ktimer_info = {
.name = "ktimer",
.path = "",
.mode = PPS_CAPTUREASSERT | PPS_OFFSETASSERT | \
PPS_ECHOASSERT | \
PPS_CANWAIT | PPS_TSFMT_TSPEC,
.echo = pps_ktimer_echo,
.owner = THIS_MODULE,
};
and then calling the function pps_register_source() in your
intialization routine as follows:
source = pps_register_source(&pps_ktimer_info,
PPS_CAPTUREASSERT | PPS_OFFSETASSERT);
The pps_register_source() prototype is:
int pps_register_source(struct pps_source_info_s *info, int default_params)
where "info" is a pointer to a structure that describes a particular
PPS source, "default_params" tells the system what the initial default
parameters for the device should be (it is obvious that these parameters
must be a subset of ones defined in the struct
pps_source_info_s which describe the capabilities of the driver).
Once you have registered a new PPS source into the system you can
signal an assert event (for example in the interrupt handler routine)
just using:
pps_event(source, &ts, PPS_CAPTUREASSERT, ptr)
where "ts" is the event's timestamp.
The same function may also run the defined echo function
(pps_ktimer_echo(), passing to it the "ptr" pointer) if the user
asked for that... etc..
Please see the file drivers/pps/clients/ktimer.c for example code.
SYSFS support
-------------
If the SYSFS filesystem is enabled in the kernel it provides a new class:
$ ls /sys/class/pps/
pps0/ pps1/ pps2/
Every directory is the ID of a PPS sources defined in the system and
inside you find several files:
$ ls /sys/class/pps/pps0/
assert clear echo mode name path subsystem@ uevent
Inside each "assert" and "clear" file you can find the timestamp and a
sequence number:
$ cat /sys/class/pps/pps0/assert
1170026870.983207967#8
Where before the "#" is the timestamp in seconds; after it is the
sequence number. Other files are:
* echo: reports if the PPS source has an echo function or not;
* mode: reports available PPS functioning modes;
* name: reports the PPS source's name;
* path: reports the PPS source's device path, that is the device the
PPS source is connected to (if it exists).
Testing the PPS support
-----------------------
In order to test the PPS support even without specific hardware you can use
the ktimer driver (see the client subsection in the PPS configuration menu)
and the userland tools provided into Documentaion/pps/ directory.
Once you have enabled the compilation of ktimer just modprobe it (if
not statically compiled):
# modprobe ktimer
and the run ppstest as follow:
$ ./ppstest /dev/pps0
trying PPS source "/dev/pps1"
found PPS source "/dev/pps1"
ok, found 1 source(s), now start fetching data...
source 0 - assert 1186592699.388832443, sequence: 364 - clear 0.000000000, sequence: 0
source 0 - assert 1186592700.388931295, sequence: 365 - clear 0.000000000, sequence: 0
source 0 - assert 1186592701.389032765, sequence: 366 - clear 0.000000000, sequence: 0
Please, note that to compile userland programs you need the file timepps.h
(see Documentation/pps/).
......@@ -4577,6 +4577,13 @@ S: Maintained
F: drivers/net/pppol2tp.c
F: include/linux/if_pppol2tp.h
PPS SUPPORT
P: Rodolfo Giometti
M: giometti@enneenne.com
W: http://wiki.enneenne.com/index.php/LinuxPPS_support
L: linuxpps@ml.enneenne.com (subscribers-only)
S: Maintained
PREEMPTIBLE KERNEL
P: Robert Love
M: rml@tech9.net
......
......@@ -52,6 +52,8 @@ source "drivers/i2c/Kconfig"
source "drivers/spi/Kconfig"
source "drivers/pps/Kconfig"
source "drivers/gpio/Kconfig"
source "drivers/w1/Kconfig"
......
......@@ -72,6 +72,7 @@ obj-$(CONFIG_INPUT) += input/
obj-$(CONFIG_I2O) += message/
obj-$(CONFIG_RTC_LIB) += rtc/
obj-y += i2c/ media/
obj-$(CONFIG_PPS) += pps/
obj-$(CONFIG_W1) += w1/
obj-$(CONFIG_POWER_SUPPLY) += power/
obj-$(CONFIG_HWMON) += hwmon/
......
#
# 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
#
# 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
/*
* kernel API
*
*
* Copyright (C) 2005-2009 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.
*/
#include <linux/kernel.h>
#include <linux/module.h>
#include <linux/init.h>
#include <linux/sched.h>
#include <linux/time.h>
#include <linux/spinlock.h>
#include <linux/idr.h>
#include <linux/fs.h>
#include <linux/pps_kernel.h>
/*
* Global variables
*/
DEFINE_SPINLOCK(pps_idr_lock);
DEFINE_IDR(pps_idr);
/*
* Local functions
*/
static void pps_add_offset(struct pps_ktime *ts, struct pps_ktime *offset)
{
ts->nsec += offset->nsec;
while (ts->nsec >= NSEC_PER_SEC) {
ts->nsec -= NSEC_PER_SEC;
ts->sec++;
}
while (ts->nsec < 0) {
ts->nsec += NSEC_PER_SEC;
ts->sec--;
}
ts->sec += offset->sec;
}
/*
* Exported functions
*/
/* pps_get_source - find a PPS source
* @source: the PPS source ID.
*
* This function is used to find an already registered PPS source into the
* system.
*
* The function returns NULL if found nothing, otherwise it returns a pointer
* to the PPS source data struct (the refcounter is incremented by 1).
*/
struct pps_device *pps_get_source(int source)
{
struct pps_device *pps;
unsigned long flags;
spin_lock_irqsave(&pps_idr_lock, flags);
pps = idr_find(&pps_idr, source);
if (pps != NULL)
atomic_inc(&pps->usage);
spin_unlock_irqrestore(&pps_idr_lock, flags);
return pps;
}
/* pps_put_source - free the PPS source data
* @pps: a pointer to the PPS source.
*
* This function is used to free a PPS data struct if its refcount is 0.
*/
void pps_put_source(struct pps_device *pps)
{
unsigned long flags;
spin_lock_irqsave(&pps_idr_lock, flags);
BUG_ON(atomic_read(&pps->usage) == 0);
if (!atomic_dec_and_test(&pps->usage)) {
pps = NULL;
goto exit;
}
/* No more reference to the PPS source. We can safely remove the
* PPS data struct.
*/
idr_remove(&pps_idr, pps->id);
exit:
spin_unlock_irqrestore(&pps_idr_lock, flags);
kfree(pps);
}
/* pps_register_source - add a PPS source in the system
* @info: the PPS info struct
* @default_params: the default PPS parameters of the new source
*
* This function is used to add a new PPS source in the system. The new
* source is described by info's fields and it will have, as default PPS
* parameters, the ones specified into default_params.
*
* The function returns, in case of success, the PPS source ID.
*/
int pps_register_source(struct pps_source_info *info, int default_params)
{
struct pps_device *pps;
int id;
int err;
/* Sanity checks */
if ((info->mode & default_params) != default_params) {
printk(KERN_ERR "pps: %s: unsupported default parameters\n",
info->name);
err = -EINVAL;
goto pps_register_source_exit;
}
if ((info->mode & (PPS_ECHOASSERT | PPS_ECHOCLEAR)) != 0 &&
info->echo == NULL) {
printk(KERN_ERR "pps: %s: echo function is not defined\n",
info->name);
err = -EINVAL;
goto pps_register_source_exit;
}
if ((info->mode & (PPS_TSFMT_TSPEC | PPS_TSFMT_NTPFP)) == 0) {
printk(KERN_ERR "pps: %s: unspecified time format\n",
info->name);
err = -EINVAL;
goto pps_register_source_exit;
}
/* Allocate memory for the new PPS source struct */
pps = kzalloc(sizeof(struct pps_device), GFP_KERNEL);
if (pps == NULL) {
err = -ENOMEM;
goto pps_register_source_exit;
}
/* These initializations must be done before calling idr_get_new()
* in order to avoid reces into pps_event().
*/
pps->params.api_version = PPS_API_VERS;
pps->params.mode = default_params;
pps->info = *info;
init_waitqueue_head(&pps->queue);
spin_lock_init(&pps->lock);
atomic_set(&pps->usage, 1);
/* Get new ID for the new PPS source */
if (idr_pre_get(&pps_idr, GFP_KERNEL) == 0) {
err = -ENOMEM;
goto kfree_pps;
}
spin_lock_irq(&pps_idr_lock);
/* Now really allocate the PPS source.
* After idr_get_new() calling the new source will be freely available
* into the kernel.
*/
err = idr_get_new(&pps_idr, pps, &id);
if (err < 0) {
spin_unlock_irq(&pps_idr_lock);
goto kfree_pps;
}
id = id & MAX_ID_MASK;
if (id >= PPS_MAX_SOURCES) {
spin_unlock_irq(&pps_idr_lock);
printk(KERN_ERR "pps: %s: too many PPS sources in the system\n",
info->name);
err = -EBUSY;
goto free_idr;
}
pps->id = id;
spin_unlock_irq(&pps_idr_lock);
/* Create the char device */
err = pps_register_cdev(pps);
if (err < 0) {
printk(KERN_ERR "pps: %s: unable to create char device\n",
info->name);
goto free_idr;
}
pr_info("new PPS source %s at ID %d\n", info->name, id);
return id;
free_idr:
spin_lock_irq(&pps_idr_lock);
idr_remove(&pps_idr, id);
spin_unlock_irq(&pps_idr_lock);
kfree_pps:
kfree(pps);
pps_register_source_exit:
printk(KERN_ERR "pps: %s: unable to register source\n", info->name);
return err;
}
EXPORT_SYMBOL(pps_register_source);
/* pps_unregister_source - remove a PPS source from the system
* @source: the PPS source ID
*
* This function is used to remove a previously registered PPS source from
* the system.
*/
void pps_unregister_source(int source)
{
struct pps_device *pps;
spin_lock_irq(&pps_idr_lock);
pps = idr_find(&pps_idr, source);
if (!pps) {
BUG();
spin_unlock_irq(&pps_idr_lock);
return;
}
spin_unlock_irq(&pps_idr_lock);
pps_unregister_cdev(pps);
pps_put_source(pps);
}
EXPORT_SYMBOL(pps_unregister_source);
/* pps_event - register a PPS event into the system
* @source: the PPS source ID
* @ts: the event timestamp
* @event: the event type
* @data: userdef pointer
*
* This function is used by each PPS client in order to register a new
* PPS event into the system (it's usually called inside an IRQ handler).
*
* If an echo function is associated with the PPS source it will be called
* as:
* pps->info.echo(source, event, data);
*/
void pps_event(int source, struct pps_ktime *ts, int event, void *data)
{
struct pps_device *pps;
unsigned long flags;
if ((event & (PPS_CAPTUREASSERT | PPS_CAPTURECLEAR)) == 0) {
printk(KERN_ERR "pps: unknown event (%x) for source %d\n",
event, source);
return;
}
pps = pps_get_source(source);
if (!pps)
return;
pr_debug("PPS event on source %d at %llu.%06u\n",
pps->id, (unsigned long long) ts->sec, ts->nsec);
spin_lock_irqsave(&pps->lock, flags);
/* Must call the echo function? */
if ((pps->params.mode & (PPS_ECHOASSERT | PPS_ECHOCLEAR)))
pps->info.echo(source, event, data);
/* Check the event */
pps->current_mode = pps->params.mode;
if (event & PPS_CAPTUREASSERT) {
/* We have to add an offset? */
if (pps->params.mode & PPS_OFFSETASSERT)
pps_add_offset(ts, &pps->params.assert_off_tu);
/* Save the time stamp */
pps->assert_tu = *ts;
pps->assert_sequence++;
pr_debug("capture assert seq #%u for source %d\n",
pps->assert_sequence, source);
}
if (event & PPS_CAPTURECLEAR) {
/* We have to add an offset? */
if (pps->params.mode & PPS_OFFSETCLEAR)
pps_add_offset(ts, &pps->params.clear_off_tu);
/* Save the time stamp */
pps->clear_tu = *ts;
pps->clear_sequence++;
pr_debug("capture clear seq #%u for source %d\n",
pps->clear_sequence, source);
}
pps->go = ~0;
wake_up_interruptible(&pps->queue);
kill_fasync(&pps->async_queue, SIGIO, POLL_IN);
spin_unlock_irqrestore(&pps->lock, flags);
/* Now we can release the PPS source for (possible) deregistration */
pps_put_source(pps);
}
EXPORT_SYMBOL(pps_event);