From mboxrd@z Thu Jan 1 00:00:00 1970 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 8E24541DECE; Mon, 6 Jul 2026 15:52:29 +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=1783353154; cv=none; b=mJ0xDdxz5I63mN1rtQyH98JCTQE+bqj2yEWznE6lcEoOW1+mQS184SvnB+ZoC/dRA5n4E/dNJUj79/7g5adshsoWSG4egubKtkefaE++7VWujrG+B/1372MuQsUN5nt2LF07CQy04cFMT17yHMFwcUyQtHYJL0buRLUVHdUXsEQ= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1783353154; c=relaxed/simple; bh=0gsjzrYA3H1GSEVep2O11AzH8pVtMgNEHy8ex9eOxiY=; h=Date:From:To:Subject:Cc:In-Reply-To:References:MIME-Version: Message-ID:Content-Type; b=n5jFnMJ3LWM3jginzkM3CxKBxCGstBfAA1SDKvWR1uzuh2y+V/8mY7RKnckMq39XNk9EnXfNQY4w6pGhbRhdrc8inUbwYI651kuBrleDStcf10HOMJI4cAcf9OkNuHNtq4aGsvH62OfKNgdBun54yNFsEzdLIDe7Czi/WgalPrU= 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=iXtSqmIQ; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=E4Ox1eTw; 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="iXtSqmIQ"; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="E4Ox1eTw" Date: Mon, 06 Jul 2026 15:52:25 -0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1783353147; 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=xMSei193tyNfTNYeBSAD5vA+Km6c3BjdIaPtR+glBGA=; b=iXtSqmIQD5wmlFlN3jyTFJKgQkJEghHvT+WwDujx8Dara70clNmigC4PDjAhA3RadI3Hhh F3CxAR2su8AVTdPCLaMS1pDRMS0t8A6nbp5Em0jWPKDLYAhf2tGJO0aG+CWZQsgGV7UpPA ZS+K8tam8yzC8WGA4mRkKLuWMQytx/0VpClQowSZSgHZL7py1RwLUSCa6C9o8aYPtGAc5C hhrH9332Rz3xpS4LlyIhAlUeDfMuNYPphrWqNbmK+6gAwoG2xxt+nLkuCoVyDkWtNPgAH+ ZUNytJXm4nMOlFfD6CSTblybpSwL0B1W3HpEFlQ1R7CxXO1bHo3ZX73V+b6Y+g== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1783353147; 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=xMSei193tyNfTNYeBSAD5vA+Km6c3BjdIaPtR+glBGA=; b=E4Ox1eTwGj4/RH5twrIl6Ap0aSTXo76CHWEUIBxsAEF4FT2WCtCf/sTqyZ4ltjvUBkar4A cNp/F2cJwl+X42Aw== 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] timekeeping: Document monotonic raw timestamps in snapshots correctly Cc: thomas.weissschuh@linutronix.de, Thomas Gleixner , x86@kernel.org, linux-kernel@vger.kernel.org In-Reply-To: <87wlv9k3wz.ffs@fw13> References: <87wlv9k3wz.ffs@fw13> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-ID: <178335314574.744054.16855639623489076153.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: e2904ddb14a4198ad31eb12a072a6923f0c8ca09 Gitweb: https://git.kernel.org/tip/e2904ddb14a4198ad31eb12a072a6923f0c= 8ca09 Author: Thomas Gleixner AuthorDate: Sun, 05 Jul 2026 14:38:04 +02:00 Committer: Thomas Gleixner CommitterDate: Mon, 06 Jul 2026 17:47:44 +02:00 timekeeping: Document monotonic raw timestamps in snapshots correctly The comments related to raw monotonic timestamps for the various snapshot mechanisms in code and struct documentation are ambiguous. They reference them as CLOCK_MONOTONIC_RAW timestamps, but with the arrival of AUX clocks that's not longer correct. The raw monotonic timestamps only represent CLOCK_MONOTONIC_RAW for the system time clock IDs, i.e. REALTIME, MONOTONIC, BOOTTIME, TAI. For AUX clocks they refer to the monotonic raw clock which is related to the individual AUX clocks. These monotonic raw timestamps have the same conversion factor as CLOCK_MONOTONIC_RAW, but differ from that by an offset: MONORAW(AUX$N) =3D MONORAW(SYSTEM) + OFFSET(AUX$N) The offset is established when a AUX clock is enabled and stays constant for the lifetime of the AUX clock. Update the comments so they reflect reality. Reported-by: Thomas Wei=C3=9Fschuh Signed-off-by: Thomas Gleixner Reviewed-by: Thomas Wei=C3=9Fschuh Link: https://patch.msgid.link/87wlv9k3wz.ffs@fw13 --- include/linux/timekeeping.h | 10 +++++++++- kernel/time/timekeeping.c | 16 +++++++++++++++- 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/include/linux/timekeeping.h b/include/linux/timekeeping.h index 984a866..b4191a8 100644 --- a/include/linux/timekeeping.h +++ b/include/linux/timekeeping.h @@ -276,7 +276,7 @@ static inline bool ktime_get_aux_ts64(clockid_t id, struc= t timespec64 *kt) { ret #endif =20 /** - * struct system_time_snapshot - Simultaneous time capture of CLOCK_MONOTONI= C_RAW, + * struct system_time_snapshot - Simultaneous time capture of monotonic raw = time, * a selected CLOCK_* and the clocksource counter value * @cycles: Clocksource counter value to produce the system times * @hw_cycles: For derived clocksources, the hardware counter value from @@ -289,6 +289,10 @@ static inline bool ktime_get_aux_ts64(clockid_t id, stru= ct timespec64 *kt) { ret * @clock_was_set_seq: The sequence number of clock-was-set events * @cs_was_changed_seq: The sequence number of clocksource change events * @valid: True if the snapshot is valid + * + * @monoraw is CLOCK_MONOTONIC_RAW for system time CLOCK ids. For CLOCK_AUX$N + * clock ids it's the monotonic raw time related to the AUX clock, which is + * CLOCK_MONOTONIC_RAW plus a AUX clock specific offset. */ struct system_time_snapshot { u64 cycles; @@ -326,6 +330,10 @@ struct system_counterval_t { * @sys_counter: Clocksource counter value simultaneous with device time * @sys_systime: System time for @clock_id * @sys_monoraw: Monotonic raw simultaneous with device time + * + * @sys_monoraw is CLOCK_MONOTONIC_RAW for system time CLOCK ids. For + * CLOCK_AUX$N clock ids it's the monotonic raw time related to the AUX cloc= k, + * which is CLOCK_MONOTONIC_RAW plus a AUX clock specific offset. */ struct system_device_crosststamp { clockid_t clock_id; diff --git a/kernel/time/timekeeping.c b/kernel/time/timekeeping.c index b1b5ec4..5985d66 100644 --- a/kernel/time/timekeeping.c +++ b/kernel/time/timekeeping.c @@ -1202,10 +1202,21 @@ static inline u64 tk_clock_read_snapshot(const struct= tk_read_base *tkr, =20 /** * ktime_get_snapshot_id - Simultaneously snapshot a given clock ID with - * CLOCK_MONOTONIC_RAW and the underlying + * the corresponding monotonic raw and the underlying * clocksource counter value. * @clock_id: The clock ID to snapshot * @systime_snapshot: Pointer to struct receiving the system time snapshot + * + * For the system time keeping clocks (REALTIME, MONOTONIC and BOOTTIME) the + * monotonic raw clock is CLOCK_MONOTONIC_RAW. For AUX clocks this is the + * monotonic raw clock related to the AUX clock. These AUX clock related + * monotonic raw clocks have a strict linear offset to the system time + * CLOCK_MONOTONIC_RAW: + * + * MONOTONIC_RAW(AUX$N) =3D CLOCK_MONOTONIC_RAW(system) + offset(AUX$N) + * + * The offset is established when a AUX clock is initialized, but it is + * currently not accessible. */ void ktime_get_snapshot_id(clockid_t clock_id, struct system_time_snapshot *= systime_snapshot) { @@ -1512,6 +1523,9 @@ EXPORT_SYMBOL_GPL(ktime_real_to_base_clock); * @xtstamp: Receives simultaneously captured system and device time * * Reads a timestamp from a device and correlates it to system time + * + * See documentation for ktime_get_snapshot_id() for information about the r= aw + * monotonic time stamp which is used here. */ int get_device_system_crosststamp(int (*get_time_fn) (ktime_t *device_time,