From patchwork Tue Apr 25 18:49:11 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Thomas Gleixner X-Patchwork-Id: 87522 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:b0ea:0:b0:3b6:4342:cba0 with SMTP id b10csp3610319vqo; Tue, 25 Apr 2023 12:01:59 -0700 (PDT) X-Google-Smtp-Source: AKy350YsFZagZ2saZ6otjDUDuKGWbKKF4xO3DT7T0MJs3Zm55+LspuFk6itbsvHZ2E/vpXNc746g X-Received: by 2002:a05:6a20:269f:b0:f0:7b8:c77b with SMTP id h31-20020a056a20269f00b000f007b8c77bmr17547421pze.59.1682449319446; Tue, 25 Apr 2023 12:01:59 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1682449319; cv=none; d=google.com; s=arc-20160816; b=kL7RiJTf8s6g61CnKG+NTCIi0hV5hau/amTsAYKtUQ2guOD6VPkdltncoq6HbA/yfM O80z2/ffIS00dbSnoE/rHweMKX+OE6pKWHBYhXtUXWhuFNcXGc3j8UeqLD/j7VQhxA92 6irFNOJ/kSAAmIh+nveIoflhLGQbfoXW20FuPD2dmzGELQYdJ61CKlCMvvaALXDQj53/ AWK06K7bKaUkIgNvNu6aUwYA0IgnUpr3FXzI8ohGDhqWbg5V896xtVAVYGf8Kp3B0iM3 JUVwW4+QxqP9Fg3VTX9WWPwCScmTwimKHh3YEEREZm4TwLEgFj1eoeRCkORp+iwMwXi9 y5Vg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:date:mime-version:references:subject:cc:to:from :dkim-signature:dkim-signature:message-id; bh=1Xn/v0a0tIvMqOVlnVw+J+mD2M0Fh0VwHZA2QXNtc10=; b=sGScwohrAOpwIatSXhiJeOqRXNWKjwJb/K9R3cUDaqpQuyGYfupNUOFTpEvZXfxYAM wk56XMJlg9f3Wpj27QAM5PMNfU0CtMVr4bUWIHaGR64ssfT2GFYnpNjckZF82NuL/rX1 yKQr50aub+Vn7TDhG1SeLe6OC9b2m3qDW3wnkEI+O6Hi21fhFSfEVPVh4v8a3XRiHdUf fd/sWPPeQQWf7JY8n17UqU1VKSu+SQa2Qf/od7ZBU88BC1AXoWyvotjL7ACNVOTpPCsz DN3GrUVY7qwcUty/dmnWpTJrsZ77MLihEJDKbiCKTmHZyYsSkdYO/HrEyOMJHzaI64dF SpLw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b=Ipw+A1ZP; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e header.b=lCXWxrPG; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id j192-20020a638bc9000000b00513965a1e60si14061337pge.902.2023.04.25.12.01.46; Tue, 25 Apr 2023 12:01:59 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@linutronix.de header.s=2020 header.b=Ipw+A1ZP; dkim=neutral (no key) header.i=@linutronix.de header.s=2020e header.b=lCXWxrPG; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=linutronix.de Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234849AbjDYStj (ORCPT + 99 others); Tue, 25 Apr 2023 14:49:39 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44808 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234743AbjDYStT (ORCPT ); Tue, 25 Apr 2023 14:49:19 -0400 Received: from galois.linutronix.de (Galois.linutronix.de [IPv6:2a0a:51c0:0:12e:550::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 7554617A2D for ; Tue, 25 Apr 2023 11:49:13 -0700 (PDT) Message-ID: <20230425183313.356427330@linutronix.de> DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1682448551; 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: references:references; bh=1Xn/v0a0tIvMqOVlnVw+J+mD2M0Fh0VwHZA2QXNtc10=; b=Ipw+A1ZPKhuzFMXkdR00YXoHKH0mbjlYJHCHO4CumRcL4l6uBeP0jd8QWbXW37AcOt8BXV FuQem7OiaOUrAa+YZzcFqlgnrlbidtj3817/Nzr6sVQBwDcTr7iV6V4ZLj7sz9ISh7zJZi ov+05vndaVUANu3Ob1uhsMcTZcW2akqF8ubyjpSsa4C7BFxJM+nSlSMklwVdp2hPEJ7mc4 WFNlFAUCoQmn3noKfIXfzzLJy9CgnzXn/gkRY/vDfXIknUfsDI57mfDRxwv/FENaEDoaI4 xiZA6gOJuZSSrX+rjr97I0n7hjKwTxo8FNXoD1I6hLXYJDHDRmeDISrgJuTS7A== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1682448551; 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: references:references; bh=1Xn/v0a0tIvMqOVlnVw+J+mD2M0Fh0VwHZA2QXNtc10=; b=lCXWxrPGHJQfT0LfecpBoJZUukXSftDdkkBGJfaEsSwbkrwR2ODRvkXmZZDLVf9o3PPvZY WYUP3+89N9pAo/Dg== From: Thomas Gleixner To: LKML Cc: Frederic Weisbecker , Anna-Maria Behnsen , Peter Zijlstra , Michael Kerrisk , Sebastian Siewior , syzbot+5c54bd3eb218bb595aa9@syzkaller.appspotmail.com, Dmitry Vyukov Subject: [patch 10/20] posix-timers: Document sys_clock_getres() correctly References: <20230425181827.219128101@linutronix.de> MIME-Version: 1.0 Date: Tue, 25 Apr 2023 20:49:11 +0200 (CEST) X-Spam-Status: No, score=-4.4 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_MED,SPF_HELO_NONE, SPF_PASS,T_SCC_BODY_TEXT_LINE,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1764175977528435525?= X-GMAIL-MSGID: =?utf-8?q?1764175977528435525?= The decades old comment about Posix clock resolution is confusing at best. Remove it and add a proper explanation to sys_clock_getres(). Signed-off-by: Thomas Gleixner Cc: Michael Kerrisk Reviewed-by: Frederic Weisbecker --- kernel/time/posix-timers.c | 81 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 73 insertions(+), 8 deletions(-) --- a/kernel/time/posix-timers.c +++ b/kernel/time/posix-timers.c @@ -67,14 +67,6 @@ static const struct k_clock clock_realti * to implement others. This structure defines the various * clocks. * - * RESOLUTION: Clock resolution is used to round up timer and interval - * times, NOT to report clock times, which are reported with as - * much resolution as the system can muster. In some cases this - * resolution may depend on the underlying clock hardware and - * may not be quantifiable until run time, and only then is the - * necessary code is written. The standard says we should say - * something about this issue in the documentation... - * * FUNCTIONS: The CLOCKs structure defines possible functions to * handle various clock functions. * @@ -1204,6 +1196,79 @@ SYSCALL_DEFINE2(clock_adjtime, const clo return err; } +/** + * sys_clock_getres - Get the resolution of a clock + * @which_clock: The clock to get the resolution for + * @tp: Pointer to a a user space timespec64 for storage + * + * POSIX defines: + * + * "The clock_getres() function shall return the resolution of any + * clock. Clock resolutions are implementation-defined and cannot be set by + * a process. If the argument res is not NULL, the resolution of the + * specified clock shall be stored in the location pointed to by res. If + * res is NULL, the clock resolution is not returned. If the time argument + * of clock_settime() is not a multiple of res, then the value is truncated + * to a multiple of res." + * + * Due to the various hardware constraints the real resolution can vary + * wildly and even change during runtime when the underlying devices are + * replaced. The kernel also can use hardware devices with different + * resolutions for reading the time and for arming timers. + * + * The kernel therefore deviates from the POSIX spec in various aspects: + * + * 1) The resolution returned to user space + * + * For CLOCK_REALTIME, CLOCK_MONOTONIC, CLOCK_BOOTTIME, CLOCK_TAI, + * CLOCK_REALTIME_ALARM, CLOCK_BOOTTIME_ALAREM and CLOCK_MONOTONIC_RAW + * the kernel differentiates only two cases: + * + * I) Low resolution mode: + * + * When high resolution timers are disabled at compile or runtime + * the resolution returned is nanoseconds per tick, which represents + * the precision at which timers expire. + * + * II) High resolution mode: + * + * When high resolution timers are enabled the resolution returned + * is always one nanosecond independent of the actual resolution of + * the underlying hardware devices. + * + * For CLOCK_*_ALARM the actual resolution depends on system + * state. When system is running the resolution is the same as the + * resolution of the other clocks. During suspend the actual + * resolution is the resolution of the underlying RTC device which + * might be way less precise than the clockevent device used during + * running state. + * + * For CLOCK_REALTIME_COARSE and CLOCK_MONOTONIC_COARSE the resolution + * returned is always nanoseconds per tick. + * + * For CLOCK_PROCESS_CPUTIME and CLOCK_THREAD_CPUTIME the resolution + * returned is always one nanosecond under the assumption that the + * underlying scheduler clock has a better resolution than nanoseconds + * per tick. + * + * For dynamic POSIX clocks (PTP devices) the resolution returned is + * always one nanosecond. + * + * 2) Affect on sys_clock_settime() + * + * The kernel does not truncate the time which is handed in to + * sys_clock_settime(). The kernel internal timekeeping is always using + * nanoseconds precision independent of the clocksource device which is + * used to read the time from. The resolution of that device only + * affects the presicion of the time returned by sys_clock_gettime(). + * + * Returns: + * 0 Success. @tp contains the resolution + * -EINVAL @which_clock is not a valid clock ID + * -EFAULT Copying the resolution to @tp faulted + * -ENODEV Dynamic POSIX clock is not backed by a device + * -EOPNOTSUPP Dynamic POSIX clock does not support getres() + */ SYSCALL_DEFINE2(clock_getres, const clockid_t, which_clock, struct __kernel_timespec __user *, tp) {