[PATCH] rtc: clarify the RTC offset correction

[PATCH] rtc: clarify the RTC offset correction

[Russell King]

The RTC offset correction documentation is not very clear about the
exact relationship between "offset" and the effect it has on the RTC.
Supplement the documentation with an equation giving the relationship.

Signed-off-by: Russell King <rmk+kernel@armlinux.org.uk>
---
 drivers/rtc/interface.c | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/drivers/rtc/interface.c b/drivers/rtc/interface.c
index 8cec9a02c0b8..045e0a72d14b 100644
--- a/drivers/rtc/interface.c
+++ b/drivers/rtc/interface.c
@@ -1004,6 +1004,10 @@ int rtc_read_offset(struct rtc_device *rtc, long *offset)
  * to compensate for differences in the actual clock rate due to temperature,
  * the crystal, capacitor, etc.
  *
+ * The adjustment applied is as follows:
+ *   t = t0 * (1 + offset * 1e-9)
+ * where t0 is the measured length of 1 RTC second with offset = 0
+ *
  * Kernel interface to adjust an rtc clock offset.
  * Return 0 on success, or a negative number on error.
  * If the rtc offset is not setable (or not implemented), return -EINVAL
-- 
2.7.4

Re: [PATCH] rtc: clarify the RTC offset correction

[Alexandre Belloni]

Hi,

On 29/09/2017 at 11:23:25 +0100, Russell King wrote:
> The RTC offset correction documentation is not very clear about the
> exact relationship between "offset" and the effect it has on the RTC.
> Supplement the documentation with an equation giving the relationship.
> 
> Signed-off-by: Russell King <rmk+kernel@armlinux.org.uk>
> ---
>  drivers/rtc/interface.c | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/drivers/rtc/interface.c b/drivers/rtc/interface.c
> index 8cec9a02c0b8..045e0a72d14b 100644
> --- a/drivers/rtc/interface.c
> +++ b/drivers/rtc/interface.c
> @@ -1004,6 +1004,10 @@ int rtc_read_offset(struct rtc_device *rtc, long *offset)
>   * to compensate for differences in the actual clock rate due to temperature,
>   * the crystal, capacitor, etc.
>   *
> + * The adjustment applied is as follows:
> + *   t = t0 * (1 + offset * 1e-9)
> + * where t0 is the measured length of 1 RTC second with offset = 0
> + *

More documentation is available in Documentation/rtc.txt. Maybe it is
worth having the formula in both.


>   * Kernel interface to adjust an rtc clock offset.
>   * Return 0 on success, or a negative number on error.
>   * If the rtc offset is not setable (or not implemented), return -EINVAL
> -- 
> 2.7.4
> 

-- 
Alexandre Belloni, Free Electrons
Embedded Linux and Kernel engineering
http://free-electrons.com

Re: [PATCH] rtc: clarify the RTC offset correction

[Russell King - ARM Linux]

On Tue, Oct 03, 2017 at 03:31:58PM +0200, Alexandre Belloni wrote:
> Hi,
> 
> On 29/09/2017 at 11:23:25 +0100, Russell King wrote:
> > The RTC offset correction documentation is not very clear about the
> > exact relationship between "offset" and the effect it has on the RTC.
> > Supplement the documentation with an equation giving the relationship.
> > 
> > Signed-off-by: Russell King <rmk+kernel@armlinux.org.uk>
> > ---
> >  drivers/rtc/interface.c | 4 ++++
> >  1 file changed, 4 insertions(+)
> > 
> > diff --git a/drivers/rtc/interface.c b/drivers/rtc/interface.c
> > index 8cec9a02c0b8..045e0a72d14b 100644
> > --- a/drivers/rtc/interface.c
> > +++ b/drivers/rtc/interface.c
> > @@ -1004,6 +1004,10 @@ int rtc_read_offset(struct rtc_device *rtc, long *offset)
> >   * to compensate for differences in the actual clock rate due to temperature,
> >   * the crystal, capacitor, etc.
> >   *
> > + * The adjustment applied is as follows:
> > + *   t = t0 * (1 + offset * 1e-9)
> > + * where t0 is the measured length of 1 RTC second with offset = 0
> > + *
> 
> More documentation is available in Documentation/rtc.txt. Maybe it is
> worth having the formula in both.

That sounds like a nightmare - stuff should be documented in detail in
one place and only one place, otherwise we risk the two sets of identical
documentation going out of sync.  A better idea would be to reference the
detailed documentation - which I guess would be easier if rtc.txt were
converted to a .rst file?

-- 
RMK's Patch system: http://www.armlinux.org.uk/developer/patches/
FTTC broadband for 0.8mile line in suburbia: sync at 8.8Mbps down 630kbps up
According to speedtest.net: 8.21Mbps down 510kbps up

Re: [PATCH] rtc: clarify the RTC offset correction

[Alexandre Belloni]

On 29/09/2017 at 11:23:25 +0100, Russell King wrote:
> The RTC offset correction documentation is not very clear about the
> exact relationship between "offset" and the effect it has on the RTC.
> Supplement the documentation with an equation giving the relationship.
> 
> Signed-off-by: Russell King <rmk+kernel@armlinux.org.uk>
> ---
>  drivers/rtc/interface.c | 4 ++++
>  1 file changed, 4 insertions(+)
> 
Applied, thanks.

-- 
Alexandre Belloni, Free Electrons
Embedded Linux and Kernel engineering
http://free-electrons.com