[PATCH v5] [PATCH v5] pps: Add elapsed realtime timestamping

From: Alexander Komrakov
Date: Thu Mar 30 2023 - 03:20:21 EST

Some applications like Android needs elapsed realtime timestamping
to PPS pulse for its clock management. Add sysfs node for this.

Signed-off-by: Alexander Komrakov <alexander.komrakov@xxxxxxxxxxxx>
---
Documentation/ABI/testing/sysfs-pps | 27 +++++++++++++++++++++++
Documentation/driver-api/pps.rst | 19 ++++++++++++++++
drivers/pps/kapi.c | 24 +++++++++++++++++---
drivers/pps/sysfs.c | 34 +++++++++++++++++++++++++++++
include/linux/pps_kernel.h | 2 ++
5 files changed, 103 insertions(+), 3 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-pps b/Documentation/ABI/testing/sysfs-pps
index 25028c7bc37d..031ec89e1ed6 100644
--- a/Documentation/ABI/testing/sysfs-pps
+++ b/Documentation/ABI/testing/sysfs-pps
@@ -1,3 +1,30 @@
+What: /sys/class/pps/pps0/assert_elapsed
+Date: October 2021
+Contact: Alexander Komrakov <alexander.komrakov@xxxxxxxxxxxx>
+Description:
+ The /sys/class/pps/ppsX/assert_elapsed file reports the
+ elapsed real-time assert events and the elapsed
+ real-time assert sequence number of the X-th source
+ in the form:
+
+ <secs>.<nsec>#<sequence>
+
+ If the source has no elapsed real-time assert events
+ the content of this file is empty.
+
+What: /sys/class/pps/ppsX/clear_elapsed
+Date: October 2021
+Contact: Alexander Komrakov <alexander.komrakov@xxxxxxxxxxxx>
+Description:
+ The /sys/class/pps/ppsX/clear_elapsed file reports the elapsed
+ real-time clear events and the elapsed real-time clear
+ sequence number of the X-th source in the form:
+
+ <secs>.<nsec>#<sequence>
+
+ If the source has no elapsed real-time clear events the
+ content of this file is empty.
+
What: /sys/class/pps/
Date: February 2008
Contact: Rodolfo Giometti <giometti@xxxxxxxx>
diff --git a/Documentation/driver-api/pps.rst b/Documentation/driver-api/pps.rst
index 2d6b99766ee8..bd0e63f15f95 100644
--- a/Documentation/driver-api/pps.rst
+++ b/Documentation/driver-api/pps.rst
@@ -167,6 +167,25 @@ sequence number. Other files are:
* path: reports the PPS source's device path, that is the device the
PPS source is connected to (if it exists).

+Real-time assert event::
+
+ Calculate the monotonic clock from the timespec clock to generate PPS elapsed
+ real-time event value and store the result into /sys/class/pps/pps0/assert_elapsed.
+ Because we have requirements to make sure the delta between standard time,
+ say the GPS Time, and elapsedRealtime < 1 millisecond,
+ regular linux clock timestamp is not enough for our use case.
+ The pin PPS will generate elapsedRealtime event at 1 sec boundary
+ which is an exact value of the monotonic clock from the kernel PPS driver
+ /sys/class/pps/pps0/assert_elapsed.
+ Whenever AP receives this pulse, kernel's pps driver timestamp this
+ elapsedRealtime event and let this time available via sysfs node
+ /sys/class/pps/pps0/assert_elapsed or the IOCTL call.
+
+ The device's Unix epoch time system clock is not monotonic; it can jump forwards
+ or backwards unpredictably and may be changed at any time by the user,
+ so this time should not be used to order or compare locations.
+ Prefer for that purpose, as the elapsed realtime clock is guaranteed to be monotonic.
+

Testing the PPS support
-----------------------
diff --git a/drivers/pps/kapi.c b/drivers/pps/kapi.c
index d9d566f70ed1..1f3ddccf9642 100644
--- a/drivers/pps/kapi.c
+++ b/drivers/pps/kapi.c
@@ -162,11 +162,21 @@ void pps_event(struct pps_device *pps, struct pps_event_time *ts, int event,
unsigned long flags;
int captured = 0;
struct pps_ktime ts_real = { .sec = 0, .nsec = 0, .flags = 0 };
+ struct pps_ktime ts_real_elapsed = { .sec = 0, .nsec = 0, .flags = 0 };
+ struct timespec64 ts64 = { .tv_sec = 0, .tv_nsec = 0 };

/* check event type */
BUG_ON((event & (PPS_CAPTUREASSERT | PPS_CAPTURECLEAR)) == 0);

- dev_dbg(pps->dev, "PPS event at %lld.%09ld\n",
+ /* Calculate the monotonic clock from the timespec clock and stores the result in pps_ktime format
+ ktime_get_boottime_ts64() : because elapsed realtime includes time spent in sleep */
+ ktime_get_boottime_ts64(&ts64);
+ timespec_to_pps_ktime(&ts_real_elapsed,ts64);
+
+ dev_dbg(pps->dev, "PPS event (monotonic) at %lld.%09d\n",
+ (s64)ts_real_elapsed.sec, ts_real_elapsed.nsec);
+
+ dev_dbg(pps->dev, "PPS event (timestamp) at %lld.%09ld\n",
(s64)ts->ts_real.tv_sec, ts->ts_real.tv_nsec);

timespec_to_pps_ktime(&ts_real, ts->ts_real);
@@ -181,11 +191,15 @@ void pps_event(struct pps_device *pps, struct pps_event_time *ts, int event,
pps->current_mode = pps->params.mode;
if (event & pps->params.mode & PPS_CAPTUREASSERT) {
/* We have to add an offset? */
- if (pps->params.mode & PPS_OFFSETASSERT)
+ if (pps->params.mode & PPS_OFFSETASSERT) {
+ pps_add_offset(&ts_real_elapsed,
+ &pps->params.assert_off_tu);
pps_add_offset(&ts_real,
&pps->params.assert_off_tu);
+ }

/* Save the time stamp */
+ pps->assert_elapsed_tu = ts_real_elapsed;
pps->assert_tu = ts_real;
pps->assert_sequence++;
dev_dbg(pps->dev, "capture assert seq #%u\n",
@@ -195,11 +209,15 @@ void pps_event(struct pps_device *pps, struct pps_event_time *ts, int event,
}
if (event & pps->params.mode & PPS_CAPTURECLEAR) {
/* We have to add an offset? */
- if (pps->params.mode & PPS_OFFSETCLEAR)
+ if (pps->params.mode & PPS_OFFSETCLEAR) {
+ pps_add_offset(&ts_real_elapsed,
+ &pps->params.clear_off_tu);
pps_add_offset(&ts_real,
&pps->params.clear_off_tu);
+ }

/* Save the time stamp */
+ pps->clear_elapsed_tu = ts_real_elapsed;
pps->clear_tu = ts_real;
pps->clear_sequence++;
dev_dbg(pps->dev, "capture clear seq #%u\n",
diff --git a/drivers/pps/sysfs.c b/drivers/pps/sysfs.c
index 134bc33f6ad0..983f16b86a62 100644
--- a/drivers/pps/sysfs.c
+++ b/drivers/pps/sysfs.c
@@ -10,6 +10,7 @@
#include <linux/module.h>
#include <linux/string.h>
#include <linux/pps_kernel.h>
+#include <linux/sysfs.h>

/*
* Attribute functions
@@ -29,6 +30,21 @@ static ssize_t assert_show(struct device *dev, struct device_attribute *attr,
}
static DEVICE_ATTR_RO(assert);

+static ssize_t assert_elapsed_show(struct device *dev,
+ struct device_attribute *attr, char *buf)
+{
+ struct pps_device *pps = dev_get_drvdata(dev);
+
+ if (!(pps->info.mode & PPS_CAPTUREASSERT))
+ return 0;
+
+ return sysfs_emit(buf, "%lld.%09d#%d\n",
+ (long long) pps->assert_elapsed_tu.sec,
+ pps->assert_elapsed_tu.nsec,
+ pps->assert_sequence);
+}
+static DEVICE_ATTR_RO(assert_elapsed);
+
static ssize_t clear_show(struct device *dev, struct device_attribute *attr,
char *buf)
{
@@ -43,6 +59,22 @@ static ssize_t clear_show(struct device *dev, struct device_attribute *attr,
}
static DEVICE_ATTR_RO(clear);

+static ssize_t clear_elapsed_show(struct device *dev,
+ struct device_attribute *attr,
+ char *buf)
+{
+ struct pps_device *pps = dev_get_drvdata(dev);
+
+ if (!(pps->info.mode & PPS_CAPTURECLEAR))
+ return 0;
+
+ return sysfs_emit(buf, "%lld.%09d#%d\n",
+ (long long) pps->clear_elapsed_tu.sec,
+ pps->clear_elapsed_tu.nsec,
+ pps->clear_sequence);
+}
+static DEVICE_ATTR_RO(clear_elapsed);
+
static ssize_t mode_show(struct device *dev, struct device_attribute *attr,
char *buf)
{
@@ -82,6 +114,8 @@ static DEVICE_ATTR_RO(path);
static struct attribute *pps_attrs[] = {
&dev_attr_assert.attr,
&dev_attr_clear.attr,
+ &dev_attr_assert_elapsed.attr,
+ &dev_attr_clear_elapsed.attr,
&dev_attr_mode.attr,
&dev_attr_echo.attr,
&dev_attr_name.attr,
diff --git a/include/linux/pps_kernel.h b/include/linux/pps_kernel.h
index 78c8ac4951b5..807642da12f7 100644
--- a/include/linux/pps_kernel.h
+++ b/include/linux/pps_kernel.h
@@ -47,6 +47,8 @@ struct pps_device {

__u32 assert_sequence; /* PPS assert event seq # */
__u32 clear_sequence; /* PPS clear event seq # */
+ struct pps_ktime assert_elapsed_tu; /* PPS elapsed rt assert seq # */
+ struct pps_ktime clear_elapsed_tu; /* PPS elapsed rt clear event seq */
struct pps_ktime assert_tu;
struct pps_ktime clear_tu;
int current_mode; /* PPS mode at event time */
--
2.25.1

Attachment: smime.p7s
Description: S/MIME Cryptographic Signature