From nobody Sat Nov 30 07:31:25 2024 Received: from galois.linutronix.de (Galois.linutronix.de [193.142.43.55]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D8F83188924; Wed, 11 Sep 2024 13:17:58 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=193.142.43.55 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1726060680; cv=none; b=pezYMzQosvks/c6B5acKzdkvmpH48CTlgLMRJ0dHpGSGf7RORinwcviN6BKRS1lrNzooV7DPZuwLBM3guY289n0xxsL2pJWZGrMAisGj7Erdw3I4rtUk8/ivp3EB8JN6oZUgFu0vXRjxEUx8fAFIDgl+m2FSyl7P/ZD/8PsXuJY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1726060680; c=relaxed/simple; bh=fgDIxovmR+O6gyO4iQm1kvPpi2Rc+D+6v0cg0aS1+4A=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=Y9ZosJ4PP2B54wWx1MzMdk/Mo0ULQxaaUnAwpZXcTessW1g2agILrNmzG5yWnuBABRAQpU6Bc1h9dupbn+EWtbVcSgNMusa87bTduxwip6nudgTgOZ8cr59e1cdZNXzC3J0ag4CcAUaijxd2Jj/ffZH+6jbZtCVVRPcITxHFZUw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linutronix.de; spf=pass smtp.mailfrom=linutronix.de; dkim=pass (2048-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=jRg0x5V8; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=93zpju5x; arc=none smtp.client-ip=193.142.43.55 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linutronix.de Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=linutronix.de Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="jRg0x5V8"; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="93zpju5x" From: Anna-Maria Behnsen DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1726060674; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=wQ8k8a4/pacG0om765Mucc7+Qw1DbjOAO73zMGi/Ls4=; b=jRg0x5V8K/B8oeoM9S3q34lKD37vW8aoEmV0VOA98wePzQ9Y2Q6Kl6LIm6rF8FtFOiEOyW ZLfhJNWZOsYj4/uqhIY7YRid0cf9TrWXoD6CPu05Ip+QN+d8oLJlN6UP+kIj2XQMsidlki 6HfiWSsmnO+wLOjz2ej3qawFAitw+sgPtZcpBix3i9vktk7UqRXfSx4ID1usMkpMg8AwOt rHWVXt+hsUt4ZrGp4CmolLdwarcdMhnsi6wJUZIXNos4LEw9PEzTemaTL7Cne6HGXY33Wj RceY/yOJmBpsUyY405UqPBET1D8Olt9izH89l+N0Q3QGt7u/vfwwBOyKtyCohw== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1726060674; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=wQ8k8a4/pacG0om765Mucc7+Qw1DbjOAO73zMGi/Ls4=; b=93zpju5xEQSDZvvb9gS9W3dZ5S1hhCy9G/Gh7glqAKTV69s7uLiwP3LRvnJcAX6wOGFw7N 76RceADw73UDuOBA== Date: Wed, 11 Sep 2024 15:17:39 +0200 Subject: [PATCH 03/21] ntp: Clean up comments Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20240911-devel-anna-maria-b4-timers-ptp-ntp-v1-3-2d52f4e13476@linutronix.de> References: <20240911-devel-anna-maria-b4-timers-ptp-ntp-v1-0-2d52f4e13476@linutronix.de> In-Reply-To: <20240911-devel-anna-maria-b4-timers-ptp-ntp-v1-0-2d52f4e13476@linutronix.de> To: John Stultz , Frederic Weisbecker , Thomas Gleixner Cc: linux-kernel@vger.kernel.org, netdev@vger.kernel.org, Miroslav Lichvar , Richard Cochran , Christopher S Hall , Anna-Maria Behnsen From: Thomas Gleixner Usage of different comment formatting makes fast reading and parsing the code harder. There are several multi-line comments which do not follow the coding style by starting with a line only containing '/*'. There are also comments which do not start with capitals. Clean up all those comments to be consistent and remove comments which document the obvious. Signed-off-by: Thomas Gleixner Signed-off-by: Anna-Maria Behnsen Acked-by: John Stultz --- kernel/time/ntp.c | 144 +++++++++++++++++++++++++++++---------------------= ---- 1 file changed, 78 insertions(+), 66 deletions(-) diff --git a/kernel/time/ntp.c b/kernel/time/ntp.c index 8e68a85996f7..99213d931f63 100644 --- a/kernel/time/ntp.c +++ b/kernel/time/ntp.c @@ -119,7 +119,8 @@ static long pps_stbcnt; /* stability limit exceeded */ static long pps_errcnt; /* calibration errors */ =20 =20 -/* PPS kernel consumer compensates the whole phase error immediately. +/* + * PPS kernel consumer compensates the whole phase error immediately. * Otherwise, reduce the offset by a fixed factor times the time constant. */ static inline s64 ntp_offset_chunk(s64 offset) @@ -132,8 +133,7 @@ static inline s64 ntp_offset_chunk(s64 offset) =20 static inline void pps_reset_freq_interval(void) { - /* the PPS calibration interval may end - surprisingly early */ + /* The PPS calibration interval may end surprisingly early */ pps_shift =3D PPS_INTMIN; pps_intcnt =3D 0; } @@ -151,9 +151,9 @@ static inline void pps_clear(void) pps_freq =3D 0; } =20 -/* Decrease pps_valid to indicate that another second has passed since - * the last PPS signal. When it reaches 0, indicate that PPS signal is - * missing. +/* + * Decrease pps_valid to indicate that another second has passed since the + * last PPS signal. When it reaches 0, indicate that PPS signal is missing. */ static inline void pps_dec_valid(void) { @@ -174,17 +174,21 @@ static inline void pps_set_freq(s64 freq) static inline int is_error_status(int status) { return (status & (STA_UNSYNC|STA_CLOCKERR)) - /* PPS signal lost when either PPS time or - * PPS frequency synchronization requested + /* + * PPS signal lost when either PPS time or PPS frequency + * synchronization requested */ || ((status & (STA_PPSFREQ|STA_PPSTIME)) && !(status & STA_PPSSIGNAL)) - /* PPS jitter exceeded when - * PPS time synchronization requested */ + /* + * PPS jitter exceeded when PPS time synchronization + * requested + */ || ((status & (STA_PPSTIME|STA_PPSJITTER)) =3D=3D (STA_PPSTIME|STA_PPSJITTER)) - /* PPS wander exceeded or calibration error when - * PPS frequency synchronization requested + /* + * PPS wander exceeded or calibration error when PPS + * frequency synchronization requested */ || ((status & STA_PPSFREQ) && (status & (STA_PPSWANDER|STA_PPSERROR))); @@ -270,8 +274,8 @@ static void ntp_update_frequency(void) new_base =3D div_u64(second_length, NTP_INTERVAL_FREQ); =20 /* - * Don't wait for the next second_overflow, apply - * the change to the tick length immediately: + * Don't wait for the next second_overflow, apply the change to the + * tick length immediately: */ tick_length +=3D new_base - tick_length_base; tick_length_base =3D new_base; @@ -307,10 +311,7 @@ static void ntp_update_offset(long offset) offset *=3D NSEC_PER_USEC; } =20 - /* - * Scale the phase adjustment and - * clamp to the operating range. - */ + /* Scale the phase adjustment and clamp to the operating range. */ offset =3D clamp(offset, -MAXPHASE, MAXPHASE); =20 /* @@ -349,7 +350,8 @@ static void ntp_update_offset(long offset) */ void ntp_clear(void) { - time_adjust =3D 0; /* stop active adjtime() */ + /* Stop active adjtime() */ + time_adjust =3D 0; time_status |=3D STA_UNSYNC; time_maxerror =3D NTP_PHASE_LIMIT; time_esterror =3D NTP_PHASE_LIMIT; @@ -387,7 +389,7 @@ ktime_t ntp_get_next_leap(void) } =20 /* - * this routine handles the overflow of the microsecond field + * This routine handles the overflow of the microsecond field * * The tricky bits of code to handle the accurate clock support * were provided by Dave Mills (Mills@UDEL.EDU) of NTP fame. @@ -452,7 +454,6 @@ int second_overflow(time64_t secs) break; } =20 - /* Bump the maxerror field */ time_maxerror +=3D MAXFREQ / NSEC_PER_USEC; if (time_maxerror > NTP_PHASE_LIMIT) { @@ -688,7 +689,7 @@ static inline void process_adj_status(const struct __ke= rnel_timex *txc) time_state =3D TIME_OK; time_status =3D STA_UNSYNC; ntp_next_leap_sec =3D TIME64_MAX; - /* restart PPS frequency calibration */ + /* Restart PPS frequency calibration */ pps_reset_freq_interval(); } =20 @@ -699,7 +700,7 @@ static inline void process_adj_status(const struct __ke= rnel_timex *txc) if (!(time_status & STA_PLL) && (txc->status & STA_PLL)) time_reftime =3D __ktime_get_real_seconds(); =20 - /* only set allowed bits */ + /* Only set allowed bits */ time_status &=3D STA_RONLY; time_status |=3D txc->status & ~STA_RONLY; } @@ -721,7 +722,7 @@ static inline void process_adjtimex_modes(const struct = __kernel_timex *txc, time_freq =3D txc->freq * PPM_SCALE; time_freq =3D min(time_freq, MAXFREQ_SCALED); time_freq =3D max(time_freq, -MAXFREQ_SCALED); - /* update pps_freq */ + /* Update pps_freq */ pps_set_freq(time_freq); } =20 @@ -754,7 +755,7 @@ static inline void process_adjtimex_modes(const struct = __kernel_timex *txc, =20 =20 /* - * adjtimex mainly allows reading (and writing, if superuser) of + * adjtimex() mainly allows reading (and writing, if superuser) of * kernel time-keeping variables. used by xntpd. */ int __do_adjtimex(struct __kernel_timex *txc, const struct timespec64 *ts, @@ -798,8 +799,7 @@ int __do_adjtimex(struct __kernel_timex *txc, const str= uct timespec64 *ts, txc->offset =3D (u32)txc->offset / NSEC_PER_USEC; } =20 - result =3D time_state; /* mostly `TIME_OK' */ - /* check for errors */ + result =3D time_state; if (is_error_status(time_status)) result =3D TIME_ERROR; =20 @@ -814,7 +814,7 @@ int __do_adjtimex(struct __kernel_timex *txc, const str= uct timespec64 *ts, txc->tick =3D tick_usec; txc->tai =3D *time_tai; =20 - /* fill PPS status fields */ + /* Fill PPS status fields */ pps_fill_timex(txc); =20 txc->time.tv_sec =3D ts->tv_sec; @@ -845,17 +845,21 @@ int __do_adjtimex(struct __kernel_timex *txc, const s= truct timespec64 *ts, =20 #ifdef CONFIG_NTP_PPS =20 -/* actually struct pps_normtime is good old struct timespec, but it is +/* + * struct pps_normtime is basically a struct timespec, but it is * semantically different (and it is the reason why it was invented): * pps_normtime.nsec has a range of ( -NSEC_PER_SEC / 2, NSEC_PER_SEC / 2 ] - * while timespec.tv_nsec has a range of [0, NSEC_PER_SEC) */ + * while timespec.tv_nsec has a range of [0, NSEC_PER_SEC) + */ struct pps_normtime { s64 sec; /* seconds */ long nsec; /* nanoseconds */ }; =20 -/* normalize the timestamp so that nsec is in the - ( -NSEC_PER_SEC / 2, NSEC_PER_SEC / 2 ] interval */ +/* + * Normalize the timestamp so that nsec is in the + * [ -NSEC_PER_SEC / 2, NSEC_PER_SEC / 2 ] interval + */ static inline struct pps_normtime pps_normalize_ts(struct timespec64 ts) { struct pps_normtime norm =3D { @@ -871,7 +875,7 @@ static inline struct pps_normtime pps_normalize_ts(stru= ct timespec64 ts) return norm; } =20 -/* get current phase correction and jitter */ +/* Get current phase correction and jitter */ static inline long pps_phase_filter_get(long *jitter) { *jitter =3D pps_tf[0] - pps_tf[1]; @@ -882,7 +886,7 @@ static inline long pps_phase_filter_get(long *jitter) return pps_tf[0]; } =20 -/* add the sample to the phase filter */ +/* Add the sample to the phase filter */ static inline void pps_phase_filter_add(long err) { pps_tf[2] =3D pps_tf[1]; @@ -890,8 +894,9 @@ static inline void pps_phase_filter_add(long err) pps_tf[0] =3D err; } =20 -/* decrease frequency calibration interval length. - * It is halved after four consecutive unstable intervals. +/* + * Decrease frequency calibration interval length. It is halved after four + * consecutive unstable intervals. */ static inline void pps_dec_freq_interval(void) { @@ -904,8 +909,9 @@ static inline void pps_dec_freq_interval(void) } } =20 -/* increase frequency calibration interval length. - * It is doubled after four consecutive stable intervals. +/* + * Increase frequency calibration interval length. It is doubled after + * four consecutive stable intervals. */ static inline void pps_inc_freq_interval(void) { @@ -918,7 +924,8 @@ static inline void pps_inc_freq_interval(void) } } =20 -/* update clock frequency based on MONOTONIC_RAW clock PPS signal +/* + * Update clock frequency based on MONOTONIC_RAW clock PPS signal * timestamps * * At the end of the calibration interval the difference between the @@ -932,7 +939,7 @@ static long hardpps_update_freq(struct pps_normtime fre= q_norm) long delta, delta_mod; s64 ftemp; =20 - /* check if the frequency interval was too long */ + /* Check if the frequency interval was too long */ if (freq_norm.sec > (2 << pps_shift)) { time_status |=3D STA_PPSERROR; pps_errcnt++; @@ -943,9 +950,10 @@ static long hardpps_update_freq(struct pps_normtime fr= eq_norm) return 0; } =20 - /* here the raw frequency offset and wander (stability) is - * calculated. If the wander is less than the wander threshold - * the interval is increased; otherwise it is decreased. + /* + * Here the raw frequency offset and wander (stability) is + * calculated. If the wander is less than the wander threshold the + * interval is increased; otherwise it is decreased. */ ftemp =3D div_s64(((s64)(-freq_norm.nsec)) << NTP_SCALE_SHIFT, freq_norm.sec); @@ -957,13 +965,14 @@ static long hardpps_update_freq(struct pps_normtime f= req_norm) time_status |=3D STA_PPSWANDER; pps_stbcnt++; pps_dec_freq_interval(); - } else { /* good sample */ + } else { + /* Good sample */ pps_inc_freq_interval(); } =20 - /* the stability metric is calculated as the average of recent - * frequency changes, but is used only for performance - * monitoring + /* + * The stability metric is calculated as the average of recent + * frequency changes, but is used only for performance monitoring */ delta_mod =3D delta; if (delta_mod < 0) @@ -972,7 +981,7 @@ static long hardpps_update_freq(struct pps_normtime fre= q_norm) (NTP_SCALE_SHIFT - SHIFT_USEC), NSEC_PER_USEC) - pps_stabil) >> PPS_INTMIN; =20 - /* if enabled, the system clock frequency is updated */ + /* If enabled, the system clock frequency is updated */ if ((time_status & STA_PPSFREQ) !=3D 0 && (time_status & STA_FREQHOLD) =3D=3D 0) { time_freq =3D pps_freq; @@ -982,17 +991,18 @@ static long hardpps_update_freq(struct pps_normtime f= req_norm) return delta; } =20 -/* correct REALTIME clock phase error against PPS signal */ +/* Correct REALTIME clock phase error against PPS signal */ static void hardpps_update_phase(long error) { long correction =3D -error; long jitter; =20 - /* add the sample to the median filter */ + /* Add the sample to the median filter */ pps_phase_filter_add(correction); correction =3D pps_phase_filter_get(&jitter); =20 - /* Nominal jitter is due to PPS signal noise. If it exceeds the + /* + * Nominal jitter is due to PPS signal noise. If it exceeds the * threshold, the sample is discarded; otherwise, if so enabled, * the time offset is updated. */ @@ -1003,13 +1013,13 @@ static void hardpps_update_phase(long error) time_status |=3D STA_PPSJITTER; pps_jitcnt++; } else if (time_status & STA_PPSTIME) { - /* correct the time using the phase offset */ + /* Correct the time using the phase offset */ time_offset =3D div_s64(((s64)correction) << NTP_SCALE_SHIFT, NTP_INTERVAL_FREQ); - /* cancel running adjtime() */ + /* Cancel running adjtime() */ time_adjust =3D 0; } - /* update jitter */ + /* Update jitter */ pps_jitter +=3D (jitter - pps_jitter) >> PPS_INTMIN; } =20 @@ -1031,41 +1041,43 @@ void __hardpps(const struct timespec64 *phase_ts, c= onst struct timespec64 *raw_t =20 pts_norm =3D pps_normalize_ts(*phase_ts); =20 - /* clear the error bits, they will be set again if needed */ + /* Clear the error bits, they will be set again if needed */ time_status &=3D ~(STA_PPSJITTER | STA_PPSWANDER | STA_PPSERROR); =20 - /* indicate signal presence */ + /* Indicate signal presence */ time_status |=3D STA_PPSSIGNAL; pps_valid =3D PPS_VALID; =20 - /* when called for the first time, - * just start the frequency interval */ + /* + * When called for the first time, just start the frequency + * interval + */ if (unlikely(pps_fbase.tv_sec =3D=3D 0)) { pps_fbase =3D *raw_ts; return; } =20 - /* ok, now we have a base for frequency calculation */ + /* Ok, now we have a base for frequency calculation */ freq_norm =3D pps_normalize_ts(timespec64_sub(*raw_ts, pps_fbase)); =20 - /* check that the signal is in the range - * [1s - MAXFREQ us, 1s + MAXFREQ us], otherwise reject it */ + /* + * Check that the signal is in the range + * [1s - MAXFREQ us, 1s + MAXFREQ us], otherwise reject it + */ if ((freq_norm.sec =3D=3D 0) || (freq_norm.nsec > MAXFREQ * freq_norm.sec) || (freq_norm.nsec < -MAXFREQ * freq_norm.sec)) { time_status |=3D STA_PPSJITTER; - /* restart the frequency calibration interval */ + /* Restart the frequency calibration interval */ pps_fbase =3D *raw_ts; printk_deferred(KERN_ERR "hardpps: PPSJITTER: bad pulse\n"); return; } =20 - /* signal is ok */ - - /* check if the current frequency interval is finished */ + /* Signal is ok. Check if the current frequency interval is finished */ if (freq_norm.sec >=3D (1 << pps_shift)) { pps_calcnt++; - /* restart the frequency calibration interval */ + /* Restart the frequency calibration interval */ pps_fbase =3D *raw_ts; hardpps_update_freq(freq_norm); } --=20 2.39.2