hwclock: hctosys drift compensation II COMMENTS

Update source comments and --help output for the
hwclock: hctosys drift compensation II patch.

Signed-off-by: J William Piggott <elseifthen@gmx.com>

diff --git a/sys-utils/hwclock.c b/sys-utils/hwclock.c
index 30db8b62829e6961c2a38937c9964ee4a7665370..4befbab32cf51938b79fc49336064899b0e6fbc7 100644 (file)
--- a/sys-utils/hwclock.c
+++ b/sys-utils/hwclock.c
@@ -684,11 +684,9 @@ set_hardware_clock_exact(const time_t sethwtime,
 }
 
 /*
- * Put the time "systime" on standard output in display format. Except if
+ * Put the time "hwctime" on standard output in display format. Except if
  * hclock_valid == false, just tell standard output that we don't know what
  * time it is.
- *
- * Include in the output the adjustment "sync_duration".
  */
 static void
 display_time(const bool hclock_valid, struct timeval hwctime)
@@ -1022,7 +1020,14 @@ adjust_drift_factor(struct adjtime *adjtime_p,
                struct timeval last_calib;
 
                last_calib = t2tv(adjtime_p->last_calib_time);
-
+               /*
+                * Correction to apply to the current drift factor.
+                *
+                * Simplified: uncorrected_drift / days_since_calibration.
+                *
+                * hclocktime is fully corrected with the current drift factor.
+                * Its difference from nowtime is the missed drift correction.
+                */
                factor_adjust = time_diff(nowtime, hclocktime) /
                                (time_diff(nowtime, last_calib) / sec_per_day);
 
@@ -1057,16 +1062,12 @@ adjust_drift_factor(struct adjtime *adjtime_p,
 }
 
 /*
- * Do the drift adjustment calculation.
- *
- * The way we have to set the clock, we need the adjustment in two parts:
+ * Calculate the drift correction currently needed for the
+ * Hardware Clock based on the last time it was adjusted,
+ * and the current drift factor, as stored in the adjtime file.
  *
- *     1) an integer number of seconds (return as *adjustment_p)
- *     2) a positive fraction of a second (less than 1) (return as *retro_p)
+ * The total drift adjustment needed is stored at tdrift_p.
  *
- * The sum of these two values is the adjustment needed. Positive means to
- * advance the clock or insert seconds. Negative means to retard the clock
- * or remove seconds.
  */
 static void
 calculate_adjustment(const double factor,
@@ -1161,24 +1162,21 @@ static void save_adjtime(const struct adjtime adjtime, const bool testing)
  * Do not update anything if the Hardware Clock does not currently present a
  * valid time.
  *
- * Arguments <factor> and <last_time> are current values from the adjtime
- * file.
+ * <hclock_valid> means the Hardware Clock contains a valid time.
  *
- * <hclock_valid> means the Hardware Clock contains a valid time, and that
- * time is <hclocktime>.
+ * <hclocktime> is the drift corrected time read from the Hardware Clock.
  *
- * <read_time> is the current system time (to be precise, it is the system
- * time at the time <hclocktime> was read, which due to computational delay
- * could be a short time ago).
+ * <read_time> was the system time when the <hclocktime> was read, which due
+ * to computational delay could be a short time ago. It is used to define a
+ * trigger point for setting the Hardware Clock. The fractional part of the
+ * Hardware clock set time is subtracted from read_time to 'refer back', or
+ * delay, the trigger point.  Fractional parts must be accounted for in this
+ * way, because the Hardware Clock can only be set to a whole second.
  *
  * <universal>: the Hardware Clock is kept in UTC.
  *
  * <testing>:  We are running in test mode (no updating of clock).
  *
- * We do not bother to update the clock if the adjustment would be less than
- * one second. This is to avoid cumulative error and needless CPU hogging
- * (remember we use an infinite loop for some timing) if the user runs us
- * frequently.
  */
 static void
 do_adjustment(struct adjtime *adjtime_p,
@@ -1263,11 +1261,11 @@ manipulate_clock(const bool show, const bool adjust, const bool noadjfile,
         */
        bool hclock_valid = FALSE;
        /*
-        * The time the hardware clock had just after we
-        * synchronized to its next clock tick when we
-        * started up. Defined only if hclock_valid is true.
+        * Tick synchronized time read from the Hardware Clock and
+        * then drift correct for all operations except --show.
         */
        struct timeval hclocktime = { 0, 0 };
+       /* Total Hardware Clock drift correction needed. */
        struct timeval tdrift;
        /* local return code */
        int rc = 0;
@@ -1323,6 +1321,14 @@ manipulate_clock(const bool show, const bool adjust, const bool noadjfile,
                                return EX_IOERR;
                }
        }
+       /*
+        * Calculate Hardware Clock drift for --predict with the user
+        * supplied --date option time, and with the time read from the
+        * Hardware Clock for all other operations.  Apply drift correction
+        * to the Hardware Clock time for everything except --show and
+        * --predict.  For --predict negate the drift correction, because we
+        * want to 'predict' a future Hardware Clock time that includes drift.
+        */
        hclocktime = predict ? t2tv(set_time) : hclocktime;
        calculate_adjustment(adjtime.drift_factor,
                             adjtime.last_adj_time,
@@ -1542,6 +1548,7 @@ static void usage(const char *fmt, ...)
        fputs(_("\nFunctions:\n"), usageto);
        fputs(_(" -h, --help           show this help text and exit\n"
                " -r, --show           read hardware clock and print result\n"
+               "     --get            read hardware clock and print drift corrected result\n"
                "     --set            set the RTC to the time given with --date\n"), usageto);
        fputs(_(" -s, --hctosys        set the system time from the hardware clock\n"
                " -w, --systohc        set the hardware clock from the current system time\n"