From nobody Thu Nov 28 09:47:30 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 9D0D31D1E98; Wed, 2 Oct 2024 15:44: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=1727883901; cv=none; b=Q8hUUrksE7rTBcvcxA5CbnwU9FfTVPGNJfBmG7DbU/SGmgXdwPN4xAWuVOndO1racPhLtgyf2JShW+bFJqNJ2xurmpjn2ch573z6Uzqabpq5nUAJd4IxM07qBYdTcfAe+l56MJZtihl1QG0fWWRO2q4U+GMYzy+0DHRdhwNr5zs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1727883901; c=relaxed/simple; bh=HPUwfzIi81z1o+Mt2KeYXhqZBlbX2OzYfIOaooqZL48=; h=Date:From:To:Subject:Cc:In-Reply-To:References:MIME-Version: Message-ID:Content-Type; b=SvzAq4qylh1A2GYQcIbhyZW2N4UmXENj6vliw2GirKBhtw05Qw4IgIjbsbiDuUUIK0FMkM2p9o7j4NzAME3vSCK8C/kll7BJNDl9AC3UD6AnK4A1hy7M0k3fhf3LkvJP1TcNsBKZmvp+e5wo4/maudHQBpjFjR/BXerzTqKuNgQ= 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=teGxVFtA; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=iLWK9RRE; 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="teGxVFtA"; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="iLWK9RRE" Date: Wed, 02 Oct 2024 15:44:56 -0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1727883896; h=from:from:sender:sender:reply-to: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=mTI4pYA22rYyggsmTud0eC5VT6nQWkq1ZesDDgWsu7I=; b=teGxVFtAbRcgZKaFzXcF2uaH9JosAZUGXX8wRLUGI/GHiRGdW7zlSzU+hY+VVoP2fM7SYy J56hK4DHc6VEduGqiULjMQKanFntSj8LQjEY5UJhWIYm5XUU+dlhzHp9ShHFQFwMy55EhO ZpR0AFbV1f7/oI3VrRGzpI8zJQx0Juc7/LoSvHqWtMWjljILN7USCdqYH9IU2JVezpm1/3 ez3a25bqZLEKw98G1BmDeXnrjo0YnUKYLV0QaqeDEIg6Q62CsTFQbQXBij7Q3KlhCXeLai PKGT5grLAK1SYUvNT19sqnqmYxeuHTCW8z/uUo8e4l8VtipuVNEkM+pGnOUBEg== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1727883896; h=from:from:sender:sender:reply-to: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=mTI4pYA22rYyggsmTud0eC5VT6nQWkq1ZesDDgWsu7I=; b=iLWK9RRE1BCb0Y21JyxuxVu7x00sxmKEL1an56y1d7xZQROqzl7CzIr072knsK3KcMvUqp pJ8YqMQGPTNYKtAA== From: "tip-bot2 for Thomas Gleixner" Sender: tip-bot2@linutronix.de Reply-to: linux-kernel@vger.kernel.org To: linux-tip-commits@vger.kernel.org Subject: [tip: timers/core] ntp: Clean up comments Cc: Thomas Gleixner , "Anna-Maria Behnsen" , John Stultz , x86@kernel.org, linux-kernel@vger.kernel.org In-Reply-To: <20240911-devel-anna-maria-b4-timers-ptp-ntp-v1-3-2d52f4e13476@linutronix.de> References: <20240911-devel-anna-maria-b4-timers-ptp-ntp-v1-3-2d52f4e13476@linutronix.de> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-ID: <172788389616.1442.2949348497247504879.tip-bot2@tip-bot2> Robot-ID: Robot-Unsubscribe: Contact to get blacklisted from these emails Precedence: bulk Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable The following commit has been merged into the timers/core branch of tip: Commit-ID: a0581cdb2e5d3ad633e51a945b6f0527ce70b68a Gitweb: https://git.kernel.org/tip/a0581cdb2e5d3ad633e51a945b6f0527c= e70b68a Author: Thomas Gleixner AuthorDate: Wed, 11 Sep 2024 15:17:39 +02:00 Committer: Thomas Gleixner CommitterDate: Wed, 02 Oct 2024 16:53:38 +02:00 ntp: Clean up comments 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 Signed-off-by: Thomas Gleixner Acked-by: John Stultz Link: https://lore.kernel.org/all/20240911-devel-anna-maria-b4-timers-ptp-n= tp-v1-3-2d52f4e13476@linutronix.de --- 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 ed15ec9..e78d3cd 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) { @@ -696,7 +697,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 @@ -707,7 +708,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; } @@ -729,7 +730,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 @@ -762,7 +763,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, @@ -806,8 +807,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 @@ -822,7 +822,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; @@ -853,17 +853,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 { @@ -879,7 +883,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]; @@ -890,7 +894,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]; @@ -898,8 +902,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) { @@ -912,8 +917,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) { @@ -926,7 +932,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 @@ -940,7 +947,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++; @@ -951,9 +958,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); @@ -965,13 +973,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) @@ -980,7 +989,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; @@ -990,17 +999,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. */ @@ -1011,13 +1021,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 @@ -1039,41 +1049,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); }