rtc: Document the sysfs interface
Subsystems (2)
PATCH 1/2 rtc: Document the sysfs interface
The sysfs interface to the RTC class drivers is currently undocumented. Add some basic documentation defining the semantics of the fields.
--- Documentation/rtc.txt | 22 ++++++++++++++++++++++ 1 files changed, 22 insertions(+), 0 deletions(-)
Documentation/rtc.txt +22 -0
@@ -135,6 +135,28 @@ a high functionality RTC is integrated into the SOC. That system might read the system clock from the discrete RTC, but use the integrated one for all other tasks, because of its greater functionality. +SYSFS INTERFACE +--------------- + +The sysfs interface under /sys/class/rtc/rtcN provides access to various +rtc attributes without requiring the use of ioctls. All dates and times +are in the RTC's timezone, rather than in system time. + +date: RTC-provided date +max_user_freq: The maximum interrupt rate an unprivileged user may request + from this RTC. +name: The name of the RTC corresponding to this sysfs directory +since_epoch: The number of seconds since the epoch according to the RTC +time: RTC-provided time +wakealarm: The time at which the clock will generate a system wakeup + event. This is a one shot wakeup event, so must be reset + after wake if a daily wakeup is required. Format is either + seconds since the epoch or, if there's a leading +, seconds + in the future. + +IOCTL INTERFACE +--------------- + The ioctl() calls supported by /dev/rtc are also supported by the RTC class framework. However, because the chips and systems are not standardized, some PC/AT functionality might not be provided. And in the same way, some
Signature · 1 line
1.6.4.1
PATCH 2/2 rtc: Add boot_timesource sysfs attribute
CONFIG_RTC_HCTOSYS allows the kernel to read the system time from the RTC at boot and resume, avoiding the need for userspace to do so. Unfortunately userspace currently has no way to know whether this configuration option is enabled and thus cannot sensibly choose whether to run hwclock itself or not. Add a boot_timesource sysfs attribute which indicates whether a given RTC set the system clock.
--- Documentation/rtc.txt | 2 ++ drivers/rtc/rtc-sysfs.c | 14 ++++++++++++++ 2 files changed, 16 insertions(+), 0 deletions(-)
Documentation/rtc.txt +2 -0
@@ -142,6 +142,8 @@ The sysfs interface under /sys/class/rtc/rtcN provides access to various rtc attributes without requiring the use of ioctls. All dates and times are in the RTC's timezone, rather than in system time. +boot_timesource: 1 if the RTC provided the system time at boot via the + CONFIG_RTC_HCTOSYS kernel option, 0 otherwise date: RTC-provided date max_user_freq: The maximum interrupt rate an unprivileged user may request from this RTC.
drivers/rtc/rtc-sysfs.c +14 -0
@@ -102,6 +102,19 @@ rtc_sysfs_set_max_user_freq(struct device *dev, struct device_attribute *attr,return n; } +static ssize_t +rtc_sysfs_show_hctosys (struct device *dev,struct device_attribute *attr, +char *buf) +{ +#ifdef CONFIG_RTC_HCTOSYS_DEVICE +if (strcmp (dev_name (&to_rtc_device (dev)->dev), +CONFIG_RTC_HCTOSYS_DEVICE ) ==0 ) +return sprintf (buf,"1\n" ); + else +#endif +return sprintf (buf,"0\n" ); +} +static struct device_attribute rtc_attrs[] = {__ATTR (name,S_IRUGO , rtc_sysfs_show_name,NULL ),__ATTR (date,S_IRUGO , rtc_sysfs_show_date,NULL ),
@@ -109,6 +122,7 @@ static struct device_attribute rtc_attrs[] = {__ATTR (since_epoch,S_IRUGO , rtc_sysfs_show_since_epoch,NULL ),__ATTR (max_user_freq,S_IRUGO |S_IWUSR , rtc_sysfs_show_max_user_freq, rtc_sysfs_set_max_user_freq), + __ATTR(boot_timesource, S_IRUGO, rtc_sysfs_show_hctosys, NULL), { }, };
Signature · 1 line
1.6.4.1
Re: [rtc-linux] [PATCH 2/2] rtc: Add boot_timesource sysfs attribute
Quoted 6 lines · On Fri, 4 Sep 2009 12:26:08 -0400 Matthew Garrett <[email protected]> wrote:
CONFIG_RTC_HCTOSYSallows the kernel to read the system time from the RTC at boot and resume, avoiding the need for userspace to do so. Unfortunately userspace currently has no way to know whether this configuration option is enabled and thus cannot sensibly choose whether to run hwclock itself or not. Add aboot_timesourcesysfs attribute which indicates whether a given RTC set the system clock.
This feature is meant to be in addition of the regular hwclock call to read the system time.
Have you tested if there are drawbacks by not reading it? Like TZ, DST and similar?
Signature · 6 lines
Best regards, Alessandro Zummo, Tower Technologies - Torino, Italy http://www.towertech.it
Re: [rtc-linux] [PATCH 2/2] rtc: Add boot_timesource sysfs attribute
Quoted 5 lines · Alessandro Zummo
This feature is meant to be in addition of the regular hwclock call to read the system time.
Have you tested if there are drawbacks by not reading it? Like TZ, DST and similar?
Current util-linux has a hwclock that can just set the timezone without performing a full read. However, there's no way of knowing whether it's safe to do this without knowing that the kernel config option was set and used. We'd prefer to avoid always doing --hctosys because it's a noticable performance hit on boot if the work's already been done by the kernel.
Signature · 1 line
Matthew Garrett | [email protected]
Re: [rtc-linux] Re: [PATCH 2/2] rtc: Add boot_timesource sysfs attribute
Quoted 3 lines · On Fri, 4 Sep 2009 17:30:29 +0100 Matthew Garrett <[email protected]> wrote:
We'd prefer to avoid always doing --hctosys because it's a noticable performance hit on boot if the work's already been done by the kernel.
it shouldn't. maybe your hwclock is waiting for the tick or something similar. I'd check it.
Signature · 6 lines
Best regards, Alessandro Zummo, Tower Technologies - Torino, Italy http://www.towertech.it
Re: [rtc-linux] Re: [PATCH 2/2] rtc: Add boot_timesource sysfs attribute
Quoted 9 lines · Alessandro Zummo
Quoted 3 lines · On Fri, 4 Sep 2009 17:30:29 +0100 Matthew Garrett <[email protected]> wrote:
We'd prefer to avoid always doing --hctosys because it's a noticable performance hit on boot if the work's already been done by the kernel.
it shouldn't. maybe your hwclock is waiting for the tick or something similar. I'd check it.
I'm just going by what our userspace people are saying. They'd prefer not to have to run --hctosys if the time's already been set -
https://bugzilla.redhat.com/show_bug.cgi?id=489494 has the discussion.
Signature · 1 line
Matthew Garrett | [email protected]
Re: [rtc-linux] Re: [PATCH 2/2] rtc: Add boot_timesource sysfs attribute
Quoted 7 lines · On Fri, 4 Sep 2009 17:41:27 +0100 Matthew Garrett <[email protected]> wrote:
Quoted 2 lines
it shouldn't. maybe your hwclock is waiting for the tick or something similar. I'd check it.
I'm just going by what our userspace people are saying. They'd prefer not to have to run --hctosys if the time's already been set -
https://bugzilla.redhat.com/show_bug.cgi?id=489494 has the discussion.
that's ok, but nonetheless there's a problem in hwclock if it takes 3 secs to read the time.
Signature · 6 lines
Best regards, Alessandro Zummo, Tower Technologies - Torino, Italy http://www.towertech.it
Re: [rtc-linux] Re: [PATCH 2/2] rtc: Add boot_timesource sysfs attribute
Quoted 2 lines · Alessandro Zummo
that's ok, but nonetheless there's a problem in hwclock if it takes 3 secs to read the time.
The 3-second case is with virtualised access to the cmos, but you're right that it does sound excessive. Even so, it seems like a win to be able to avoid running code that the kernel's already run
Signature · 1 line
Matthew Garrett | [email protected]
Re: [rtc-linux] Re: [PATCH 2/2] rtc: Add boot_timesource sysfs attribute
Quoted 8 lines · On Fri, 4 Sep 2009 17:55:49 +0100 Matthew Garrett <[email protected]> wrote:
Quoted 2 lines · Alessandro Zummo
that's ok, but nonetheless there's a problem in hwclock if it takes 3 secs to read the time.
The 3-second case is with virtualised access to the cmos, but you're right that it does sound excessive. Even so, it seems like a win to be able to avoid running code that the kernel's already run
ok. I find boot_timesource to be not intuitive. I'd vote for hctosys or something like that.
Signature · 6 lines
Best regards, Alessandro Zummo, Tower Technologies - Torino, Italy http://www.towertech.it
Re: [rtc-linux] Re: [PATCH 2/2] rtc: Add boot_timesource sysfs attribute
Ok. How's this?
commit 09895be2ef8528dc33ca8516ca4f5ccbec2ffb05
Author: Matthew Garrett <[email protected]> Date: Fri Sep 4 12:23:02 2009 -0400
rtc: Add hctosys sysfs attribute
CONFIG_RTC_HCTOSYS allows the kernel to read the system time from the RTC at boot and resume, avoiding the need for userspace to do so. Unfortunately userspace currently has no way to know whether this configuration option is enabled and thus cannot sensibly choose whether to run hwclock itself or not. Add a hctosys sysfs attribute which indicates whether a given RTC set the system clock.
Documentation/rtc.txt +2 -0
@@ -143,6 +143,8 @@ rtc attributes without requiring the use of ioctls. All dates and times are in the RTC's timezone, rather than in system time. date: RTC-provided date +hctosys: 1 if the RTC provided the system time at boot via the + CONFIG_RTC_HCTOSYS kernel option, 0 otherwise max_user_freq: The maximum interrupt rate an unprivileged user may request from this RTC. name: The name of the RTC corresponding to this sysfs directory
drivers/rtc/rtc-sysfs.c +14 -0
@@ -102,6 +102,19 @@ rtc_sysfs_set_max_user_freq(struct device *dev, struct device_attribute *attr,return n; } +static ssize_t +rtc_sysfs_show_hctosys (struct device *dev,struct device_attribute *attr, +char *buf) +{ +#ifdef CONFIG_RTC_HCTOSYS_DEVICE +if (strcmp (dev_name (&to_rtc_device (dev)->dev), +CONFIG_RTC_HCTOSYS_DEVICE ) ==0 ) +return sprintf (buf,"1\n" ); + else +#endif +return sprintf (buf,"0\n" ); +} +static struct device_attribute rtc_attrs[] = {__ATTR (name,S_IRUGO , rtc_sysfs_show_name,NULL ),__ATTR (date,S_IRUGO , rtc_sysfs_show_date,NULL ),
@@ -109,6 +122,7 @@ static struct device_attribute rtc_attrs[] = {__ATTR (since_epoch,S_IRUGO , rtc_sysfs_show_since_epoch,NULL ),__ATTR (max_user_freq,S_IRUGO |S_IWUSR , rtc_sysfs_show_max_user_freq, rtc_sysfs_set_max_user_freq), + __ATTR(hctosys, S_IRUGO, rtc_sysfs_show_hctosys, NULL), { }, };
Signature · 1 line
Matthew Garrett | [email protected]
Alessandro Zummo
Acked-byRe: [rtc-linux] Re: [PATCH 2/2] rtc: Add boot_timesource sysfs attribute
Quoted 5 lines · On Fri, 4 Sep 2009 18:09:28 +0100 Matthew Garrett <[email protected]> wrote:
Ok. How's this?
commit
09895be2ef8528dc33ca8516ca4f5ccbec2ffb05Author: Matthew Garrett <[email protected]> Date: Fri Sep 4 12:23:02 2009 -0400
perfect, ty.
Signature · 6 lines
Best regards, Alessandro Zummo, Tower Technologies - Torino, Italy http://www.towertech.it
Re: [rtc-linux] Re: [PATCH 2/2] rtc: Add boot_timesource sysfs attribute
In reply to Matthew GarrettQuoted 2 lines · Matthew Garrett
Documentation/rtc.txt +2
-0+hctosys: 1 if the RTC provided the system time at boot via the + CONFIG_RTC_HCTOSYS kernel option, 0 otherwise
...
drivers/rtc/rtc-sysfs.c rtc_sysfs_set_max_user_freq(struct device *dev, struct device_attribute *attr, · line 114
Quoted 10 lines
drivers/rtc/rtc-sysfs.c +10
-0+static ssize_t +rtc_sysfs_show_hctosys (struct device *dev,struct device_attribute *attr, +char *buf) +{ +#ifdef CONFIG_RTC_HCTOSYS_DEVICE +if (strcmp (dev_name (&to_rtc_device (dev)->dev), +CONFIG_RTC_HCTOSYS_DEVICE ) ==0 ) +return sprintf (buf,"1\n" ); + else +#endif
Strictly speaking this only reports if the RTC was configured to provide the system time at boot, it does not check to see if it actually succeeded in doing so. Obviously failures here are a relatively rare occurrance but they can happen. I don't think it's worth changing the code since it's unlikely userspace will be able to do any better than the kernel did but it might be worth updating the documentation just in case.
Re: [rtc-linux] Re: [PATCH 2/2] rtc: Add boot_timesource sysfs attribute
In reply to Alessandro ZummoQuoted 7 lines · Alessandro Zummo
Quoted 3 lines · On Fri, 4 Sep 2009 17:41:27 +0100 Matthew Garrett <[email protected]> wrote:
Quoted 2 lines
it shouldn't. maybe your hwclock is waiting for the tick or something similar. I'd check it.
Quoted 7 lines
Quoted 4 lines
I'm just going by what our userspace people are saying. They'd prefer not to have to run --hctosys if the time's already been set -
https://bugzilla.redhat.com/show_bug.cgi?id=489494 has the discussion.that's ok, but nonetheless there's a problem in hwclock if it takes 3 secs to read the time.
IMHO 3 seconds is nonsense. It's usually 0.5 - 1 second.
Anyway, the "hwclock --hctosys" in userspace is a mystical voodoo and it's definitely better to move this thing to kernel.
Karel
Signature · 1 line
Karel Zak <[email protected]>
Quoted 4 lines · On Fri, 4 Sep 2009 12:26:07 -0400 Matthew Garrett <[email protected]> wrote:
The sysfs interface to the RTC class drivers is currently undocumented. Add some basic documentation defining the semantics of the fields.
Signed-off-by Matthew Garrett <[email protected]>
thanks!
Signature · 6 lines
Best regards, Alessandro Zummo, Tower Technologies - Torino, Italy http://www.towertech.it
Quoted 7 lines · Matthew Garrett
The sysfs interface to the RTC class drivers is currently undocumented. Add some basic documentation defining the semantics of the fields.
Signed-off-by Matthew Garrett <[email protected]>+SYSFS INTERFACE
+---------------
Wouldn't this be better placed under Documentation/ABI?
Quoted 11 lines · Mark Brown
Quoted 7 lines · Matthew Garrett
The sysfs interface to the RTC class drivers is currently undocumented. Add some basic documentation defining the semantics of the fields.
Signed-off-by Matthew Garrett <[email protected]>+SYSFS INTERFACE
+---------------Wouldn't this be better placed under
Documentation/ABI?
Unsure. I'd assumed it made more sense in the existing docs.
Signature · 1 line
Matthew Garrett | [email protected]
Quoted 5 lines · Matthew Garrett
Quoted 1 line · Mark Brown
Wouldn't this be better placed under
Documentation/ABI?Unsure. I'd assumed it made more sense in the existing docs.
My understanding is that the sysfs ABI (and ABIs in general, I guess) should be moving towards the more formal style of Documentation/ABI to help manage userspace expectations - the separation of the documentation applies to most other things in there as well.
Quoted 11 lines · On Fri, 4 Sep 2009 17:52:06 +0100 Mark Brown…
Quoted 5 lines · Matthew Garrett
Quoted 1 line · Mark Brown
Wouldn't this be better placed under
Documentation/ABI?Unsure. I'd assumed it made more sense in the existing docs.
My understanding is that the sysfs ABI (and ABIs in general, I guess) should be moving towards the more formal style of
Documentation/ABIto help manage userspace expectations - the separation of the documentation applies to most other things in there as well.
Yes, I think you're right.
But I'm not going to pass on a documentation patch just because it's in the wrong place ;)