Clean up PPS monitor interface with renames, and additional documentation.

5 files changed, 35 insertions, 17 deletions

diff --git a/gpsd.c b/gpsd.c
index 6aef65c9..0ffb4ccc 100644
--- a/gpsd.c
+++ b/gpsd.c
@@ -1511,7 +1511,7 @@ static void all_reports(struct gps_device_t *device, gps_mask_t changed)
     } else if (isnan(device->newdata.time)) {
 	//gpsd_log(&context.errout, LOG_PROG, "NTP: bad new time\n");
 #if defined(PPS_ENABLE)
-    } else if (device->newdata.time <= device->pps_thread.fixin.real.tv_sec) {
+    } else if (device->newdata.time <= device->pps_thread.fix_in.real.tv_sec) {
 	//gpsd_log(&context.errout, LOG_PROG, "NTP: Not a new time\n");
 #endif /* PPS_ENABLE */
     } else if (!device->ship_to_ntpd) {
@@ -1528,7 +1528,7 @@ static void all_reports(struct gps_device_t *device, gps_mask_t changed)
 	/* propagate this in-band-time to all PPS-only devices */
 	for (ppsonly = devices; ppsonly < devices + MAX_DEVICES; ppsonly++)
 	    if (ppsonly->sourcetype == source_pps)
-		pps_thread_fixin(&ppsonly->pps_thread, &td);
+		pps_thread_fix_in(&ppsonly->pps_thread, &td);
 #endif /* PPS_ENABLE */
 
 #ifdef NTPSHM_ENABLE
diff --git a/gpsmon.c b/gpsmon.c
index 8a3c8167..81d5c90b 100644
--- a/gpsmon.c
+++ b/gpsmon.c
@@ -777,8 +777,12 @@ static void gpsmon_hook(struct gps_device_t *device, gps_mask_t changed UNUSED)
 	    (void)snprintf(buf, sizeof(buf), 
 			"------------------- PPS offset: %.20s ------\n ",
 			timedelta_str);
+	    /*
+	     * In direct mode this would be a bad idea, but we're not actually
+	     * watching for handshake events on a spawned thread here.
+	     */
 	    /* coverity[missing_lock] */
-	    session.pps_thread.ppsout_last = noclobber.pps;
+	    session.pps_thread.pps_out = noclobber.pps;
 	    /* coverity[missing_lock] */
 	    session.pps_thread.ppsout_count++;
 	}
@@ -834,7 +838,7 @@ static void gpsmon_hook(struct gps_device_t *device, gps_mask_t changed UNUSED)
     if ( 0 != isnan(device->newdata.time)) {
 	// "NTP: bad new time
 #if defined(PPS_ENABLE)
-    } else if (device->newdata.time <= device->pps_thread.fixin.real.tv_sec) {
+    } else if (device->newdata.time <= device->pps_thread.fix_in.real.tv_sec) {
 	// "NTP: Not a new time
 #endif /* PPS_ENABLE */
     } else 
diff --git a/libgpsd_core.c b/libgpsd_core.c
index 306bca13..183f4f1f 100644
--- a/libgpsd_core.c
+++ b/libgpsd_core.c
@@ -1648,7 +1648,7 @@ void ntp_latch(struct gps_device_t *device, struct timedelta_t *td)
 
 #ifdef PPS_ENABLE
     /* thread-safe update */
-    pps_thread_fixin(&device->pps_thread, td);
+    pps_thread_fix_in(&device->pps_thread, td);
 #endif /* PPS_ENABLE */
 }
 #endif /* NTP_ENABLE */
diff --git a/ppsthread.c b/ppsthread.c
index 1b9aba03..d3d9fd64 100644
--- a/ppsthread.c
+++ b/ppsthread.c
@@ -483,7 +483,7 @@ static int get_edge_tiocmiwait( volatile struct pps_thread_t *thread_context,
     /* duplicate copy in get_edge_rfc2783 */
     /* quick, grab a copy of last_fixtime before it changes */
     thread_lock(thread_context);
-    *last_fixtime = thread_context->fixin;
+    *last_fixtime = thread_context->fix_in;
     thread_unlock(thread_context);
     /* end duplicate copy in get_edge_rfc2783 */
 
@@ -590,7 +590,7 @@ static int get_edge_rfc2783(struct inner_context_t *inner_context,
 
 	/* quick, grab a copy of last fixtime before it changes */
 	thread_lock(thread_context);
-	*last_fixtime = thread_context->fixin;
+	*last_fixtime = thread_context->fix_in;
 	thread_unlock(thread_context);
     }
 
@@ -1149,7 +1149,7 @@ static void *gpsd_ppsmonitor(void *arg)
 	    else
 		log1 = "no report hook";
 	    thread_lock(thread_context);
-	    thread_context->ppsout_last = ppstimes;
+	    thread_context->pps_out = ppstimes;
 	    thread_context->ppsout_count++;
 	    thread_unlock(thread_context);
 	    timespec_str( &ppstimes.clock, ts_str1, sizeof(ts_str1) );
@@ -1232,12 +1232,12 @@ void pps_thread_deactivate(volatile struct pps_thread_t *pps_thread)
     pps_thread->report_hook = NULL;
 }
 
-void pps_thread_fixin(volatile struct pps_thread_t *pps_thread,
-			      volatile struct timedelta_t *fixin)
+void pps_thread_fix_in(volatile struct pps_thread_t *pps_thread,
+			      volatile struct timedelta_t *fix_in)
 /* thread-safe update of last fix time - only way we pass data in */
 {
     thread_lock(pps_thread);
-    pps_thread->fixin = *fixin;
+    pps_thread->fix_in = *fix_in;
     thread_unlock(pps_thread);
 }
 
@@ -1248,7 +1248,7 @@ int pps_thread_ppsout(volatile struct pps_thread_t *pps_thread,
     volatile int ret;
 
     thread_lock(pps_thread);
-    *td = pps_thread->ppsout_last;
+    *td = pps_thread->pps_out;
     ret = pps_thread->ppsout_count;
     thread_unlock(pps_thread);
 
diff --git a/ppsthread.h b/ppsthread.h
index e5134e79..5c95e72b 100644
--- a/ppsthread.h
+++ b/ppsthread.h
@@ -21,17 +21,31 @@ struct timedelta_t {
 /* WARNING!  this will overflow if x and y differ by more than a few seconds */
 #define timespec_diff_ns(x, y)	(long)(((x).tv_sec-(y).tv_sec)*1000000000+(x).tv_nsec-(y).tv_nsec)
 
+/*
+ * Set context, devicefd, and devicename at initialization time, before
+ * you call pps_thread_activate().  The context pointer can be used to
+ * pass data to the hook routines.
+ *
+ * Do not set the fix_in member or read the pps_out member directly,
+ * these accesses need to be mutex-locked and that is what the last
+ * two functions are for.
+ *
+ * The report hook is called when each PPS event is recognized.  The log
+ * hook is called to log error and status indications from the thread. The
+ * wrap hook is called when the thread terminates as the result of a
+ * deactivate call.
+ */
 struct pps_thread_t {
-    void *context;
+    void *context;		/* PPS thread code leaves this alone */
     int devicefd;		/* device file descriptor */
-    char *devicename;
+    char *devicename;		/* device path */
     char *(*report_hook)(volatile struct pps_thread_t *,
 			 struct timedelta_t *);
     void (*log_hook)(volatile struct pps_thread_t *,
 		     int errlevel, const char *fmt, ...);
     void (*wrap_hook)(volatile struct pps_thread_t *);
-    struct timedelta_t fixin;	/* real & clock time when in-band fix received */
-    struct timedelta_t ppsout_last;
+    struct timedelta_t fix_in;	/* real & clock time when in-band fix received */
+    struct timedelta_t pps_out;	/* real & clock time of last PPS event */
     int ppsout_count;
 };
 
@@ -43,7 +57,7 @@ struct pps_thread_t {
 
 extern void pps_thread_activate(volatile struct pps_thread_t *);
 extern void pps_thread_deactivate(volatile struct pps_thread_t *);
-extern void pps_thread_fixin(volatile struct pps_thread_t *, 
+extern void pps_thread_fix_in(volatile struct pps_thread_t *,
 				     volatile struct timedelta_t *);
 extern int pps_thread_ppsout(volatile struct pps_thread_t *,
 			      volatile struct timedelta_t *);