* [PATCH 0/2] Documentation: rtc: move ioctl to ABI @ 2018-01-01 17:30 ` Aishwarya Pant 0 siblings, 0 replies; 6+ messages in thread From: Aishwarya Pant @ 2018-01-01 17:30 UTC (permalink / raw) To: Alessandro Zummo, Alexandre Belloni, Jonathan Corbet, linux-rtc-u79uwXL29TY76Z2rM5mHXA, linux-doc-u79uwXL29TY76Z2rM5mHXA, linux-kernel-u79uwXL29TY76Z2rM5mHXA, linux-api-u79uwXL29TY76Z2rM5mHXA Cc: Julia Lawall, gregkh-hQyY1W1yCW8ekmWlsbkhG0B+6BGkLq7r Two documentation changes in rtc: 1) Minor change to add file permissions to sysfs interface 2) Move ioctl interface to Documentation/ABI Aishwarya Pant (2): Documentation: rtc: add sysfs file permissions Documentation: rtc: move iotcl interface documentation to ABI Documentation/ABI/testing/rtc-cdev | 42 ++++++++++++++++++++++++++ Documentation/ABI/testing/sysfs-class-rtc | 44 ++++++++++++++------------- Documentation/rtc.txt | 49 ++----------------------------- 3 files changed, 67 insertions(+), 68 deletions(-) create mode 100644 Documentation/ABI/testing/rtc-cdev -- 2.15.1 ^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH 0/2] Documentation: rtc: move ioctl to ABI @ 2018-01-01 17:30 ` Aishwarya Pant 0 siblings, 0 replies; 6+ messages in thread From: Aishwarya Pant @ 2018-01-01 17:30 UTC (permalink / raw) To: Alessandro Zummo, Alexandre Belloni, Jonathan Corbet, linux-rtc, linux-doc, linux-kernel, linux-api Cc: Julia Lawall, gregkh Two documentation changes in rtc: 1) Minor change to add file permissions to sysfs interface 2) Move ioctl interface to Documentation/ABI Aishwarya Pant (2): Documentation: rtc: add sysfs file permissions Documentation: rtc: move iotcl interface documentation to ABI Documentation/ABI/testing/rtc-cdev | 42 ++++++++++++++++++++++++++ Documentation/ABI/testing/sysfs-class-rtc | 44 ++++++++++++++------------- Documentation/rtc.txt | 49 ++----------------------------- 3 files changed, 67 insertions(+), 68 deletions(-) create mode 100644 Documentation/ABI/testing/rtc-cdev -- 2.15.1 ^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH 1/2] Documentation: rtc: add sysfs file permissions 2018-01-01 17:30 ` Aishwarya Pant (?) @ 2018-01-01 17:30 ` Aishwarya Pant -1 siblings, 0 replies; 6+ messages in thread From: Aishwarya Pant @ 2018-01-01 17:30 UTC (permalink / raw) To: Alessandro Zummo, Alexandre Belloni, Jonathan Corbet, linux-rtc, linux-doc, linux-kernel, linux-api Cc: Julia Lawall, gregkh Annotate the sysfs interface of rtc with file specific permissions (RO/RW). Signed-off-by: Aishwarya Pant <aishpant@gmail.com> --- Documentation/ABI/testing/sysfs-class-rtc | 44 ++++++++++++++++--------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/Documentation/ABI/testing/sysfs-class-rtc b/Documentation/ABI/testing/sysfs-class-rtc index df2eca7e2e77..5083841b03d4 100644 --- a/Documentation/ABI/testing/sysfs-class-rtc +++ b/Documentation/ABI/testing/sysfs-class-rtc @@ -18,14 +18,14 @@ Date: March 2006 KernelVersion: 2.6.17 Contact: linux-rtc@vger.kernel.org Description: - RTC-provided date in YYYY-MM-DD format + (RO) RTC-provided date in YYYY-MM-DD format What: /sys/class/rtc/rtcX/hctosys Date: September 2009 KernelVersion: 2.6.32 Contact: linux-rtc@vger.kernel.org Description: - 1 if the RTC provided the system time at boot via the + (RO) 1 if the RTC provided the system time at boot via the CONFIG_RTC_HCTOSYS kernel option, 0 otherwise What: /sys/class/rtc/rtcX/max_user_freq @@ -33,7 +33,7 @@ Date: October 2007 KernelVersion: 2.6.24 Contact: linux-rtc@vger.kernel.org Description: - The maximum interrupt rate an unprivileged user may request + (RW) The maximum interrupt rate an unprivileged user may request from this RTC. What: /sys/class/rtc/rtcX/name @@ -41,58 +41,60 @@ Date: March 2006 KernelVersion: 2.6.17 Contact: linux-rtc@vger.kernel.org Description: - The name of the RTC corresponding to this sysfs directory + (RO) The name of the RTC corresponding to this sysfs directory What: /sys/class/rtc/rtcX/range Date: January 2018 KernelVersion: 4.16 Contact: linux-rtc@vger.kernel.org Description: - Valid time range for the RTC, as seconds from epoch, formatted - as [min, max] + (RO) Valid time range for the RTC, as seconds from epoch, + formatted as [min, max] What: /sys/class/rtc/rtcX/since_epoch Date: March 2006 KernelVersion: 2.6.17 Contact: linux-rtc@vger.kernel.org Description: - RTC-provided time as the number of seconds since the epoch + (RO) RTC-provided time as the number of seconds since the epoch What: /sys/class/rtc/rtcX/time Date: March 2006 KernelVersion: 2.6.17 Contact: linux-rtc@vger.kernel.org Description: - RTC-provided time in 24-hour notation (hh:mm:ss) + (RO) RTC-provided time in 24-hour notation (hh:mm:ss) What: /sys/class/rtc/rtcX/*/nvmem Date: February 2016 KernelVersion: 4.6 Contact: linux-rtc@vger.kernel.org Description: - The non volatile storage exported as a raw file, as described in - Documentation/nvmem/nvmem.txt + (RW) The non volatile storage exported as a raw file, as + described in Documentation/nvmem/nvmem.txt What: /sys/class/rtc/rtcX/offset Date: February 2016 KernelVersion: 4.6 Contact: linux-rtc@vger.kernel.org Description: - The amount which the rtc clock has been adjusted in firmware. - Visible only if the driver supports clock offset adjustment. - The unit is parts per billion, i.e. The number of clock ticks - which are added to or removed from the rtc's base clock per - billion ticks. A positive value makes a day pass more slowly, - longer, and a negative value makes a day pass more quickly. + (RW) The amount which the rtc clock has been adjusted in + firmware. Visible only if the driver supports clock offset + adjustment. The unit is parts per billion, i.e. The number of + clock ticks which are added to or removed from the rtc's base + clock per billion ticks. A positive value makes a day pass more + slowly, longer, and a negative value makes a day pass more + quickly. What: /sys/class/rtc/rtcX/wakealarm Date: February 2007 KernelVersion: 2.6.20 Contact: linux-rtc@vger.kernel.org Description: - 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 seconds since the epoch by - default, or if there's a leading +, seconds in the future, or if - there is a leading +=, seconds ahead of the current alarm. + (RW) 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 seconds since the + epoch by default, or if there's a leading +, seconds in the + future, or if there is a leading +=, seconds ahead of the + current alarm. -- 2.15.1 ^ permalink raw reply related [flat|nested] 6+ messages in thread
[parent not found: <cover.1514827586.git.aishpant-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]
* [PATCH 2/2] Documentation: rtc: move iotcl interface documentation to ABI 2018-01-01 17:30 ` Aishwarya Pant @ 2018-01-01 17:31 ` Aishwarya Pant -1 siblings, 0 replies; 6+ messages in thread From: Aishwarya Pant @ 2018-01-01 17:31 UTC (permalink / raw) To: Alessandro Zummo, Alexandre Belloni, Jonathan Corbet, linux-rtc-u79uwXL29TY76Z2rM5mHXA, linux-doc-u79uwXL29TY76Z2rM5mHXA, linux-kernel-u79uwXL29TY76Z2rM5mHXA, linux-api-u79uwXL29TY76Z2rM5mHXA Cc: Julia Lawall, gregkh-hQyY1W1yCW8ekmWlsbkhG0B+6BGkLq7r The ioctl interface should be in Documentation/ABI along with the rest of the interfaces. Signed-off-by: Aishwarya Pant <aishpant-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> --- Documentation/ABI/testing/rtc-cdev | 42 ++++++++++++++++++++++++++++++++ Documentation/rtc.txt | 49 ++------------------------------------ 2 files changed, 44 insertions(+), 47 deletions(-) create mode 100644 Documentation/ABI/testing/rtc-cdev diff --git a/Documentation/ABI/testing/rtc-cdev b/Documentation/ABI/testing/rtc-cdev new file mode 100644 index 000000000000..97447283f13b --- /dev/null +++ b/Documentation/ABI/testing/rtc-cdev @@ -0,0 +1,42 @@ +What: /dev/rtcX +Date: April 2005 +KernelVersion: 2.6.12 +Contact: linux-rtc-u79uwXL29TY76Z2rM5mHXA@public.gmane.org +Description: + The ioctl interface to drivers for real-time clocks (RTCs). + Following actions are supported: + + * RTC_RD_TIME, RTC_SET_TIME: Read or set the RTC time. Time + format is a Gregorian calendar date and 24 hour wall clock + time. + + * RTC_AIE_ON, RTC_AIE_OFF: Enable or disable the alarm interrupt + for RTCs that support alarms + + * RTC_ALM_READ, RTC_ALM_SET: Read or set the alarm time for + RTCs that support alarms. Can be set upto 24 hours in the + future. Requires a separate RTC_AIE_ON call to enable the + alarm interrupt. (Prefer to use RTC_WKALM_*) + + * RTC_WKALM_RD, RTC_WKALM_SET: For RTCs that support a more + powerful interface, which can issue alarms beyond 24 hours and + enable IRQs in the same request. + + * RTC_PIE_ON, RTC_PIE_OFF: Enable or disable the periodic + interrupt for RTCs that support periodic interrupts. + + * RTC_UIE_ON, RTC_UIE_OFF: Enable or disable the update + interrupt for RTCs that support it. + + * RTC_IRQP_READ, RTC_IRQP_SET: Read or set the frequency for + periodic interrupts for RTCs that support periodic interrupts. + Requires a separate RTC_PIE_ON call to enable the periodic + interrupts. + + The ioctl() calls supported by the older /dev/rtc interface are + also supported by the newer 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 + newer features -- including those enabled by ACPI -- are exposed + by the RTC class framework, but can't be supported by the older + driver. diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt index f521262cdc85..a129acf38537 100644 --- a/Documentation/rtc.txt +++ b/Documentation/rtc.txt @@ -136,50 +136,5 @@ 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. -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 -newer features -- including those enabled by ACPI -- are exposed by the -RTC class framework, but can't be supported by the older driver. - - * RTC_RD_TIME, RTC_SET_TIME ... every RTC supports at least reading - time, returning the result as a Gregorian calendar date and 24 hour - wall clock time. To be most useful, this time may also be updated. - - * RTC_AIE_ON, RTC_AIE_OFF, RTC_ALM_SET, RTC_ALM_READ ... when the RTC - is connected to an IRQ line, it can often issue an alarm IRQ up to - 24 hours in the future. (Use RTC_WKALM_* by preference.) - - * RTC_WKALM_SET, RTC_WKALM_RD ... RTCs that can issue alarms beyond - the next 24 hours use a slightly more powerful API, which supports - setting the longer alarm time and enabling its IRQ using a single - request (using the same model as EFI firmware). - - * RTC_UIE_ON, RTC_UIE_OFF ... if the RTC offers IRQs, the RTC framework - will emulate this mechanism. - - * RTC_PIE_ON, RTC_PIE_OFF, RTC_IRQP_SET, RTC_IRQP_READ ... these icotls - are emulated via a kernel hrtimer. - -In many cases, the RTC alarm can be a system wake event, used to force -Linux out of a low power sleep state (or hibernation) back to a fully -operational state. For example, a system could enter a deep power saving -state until it's time to execute some scheduled tasks. - -Note that many of these ioctls are handled by the common rtc-dev interface. -Some common examples: - - * RTC_RD_TIME, RTC_SET_TIME: the read_time/set_time functions will be - called with appropriate values. - - * RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: gets or sets - the alarm rtc_timer. May call the set_alarm driver function. - - * RTC_IRQP_SET, RTC_IRQP_READ: These are emulated by the generic code. - - * RTC_PIE_ON, RTC_PIE_OFF: These are also emulated by the generic code. - -If all else fails, check out the tools/testing/selftests/timers/rtctest.c test! +Check out tools/testing/selftests/timers/rtctest.c for an example usage of the +ioctl interface. -- 2.15.1 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH 2/2] Documentation: rtc: move iotcl interface documentation to ABI @ 2018-01-01 17:31 ` Aishwarya Pant 0 siblings, 0 replies; 6+ messages in thread From: Aishwarya Pant @ 2018-01-01 17:31 UTC (permalink / raw) To: Alessandro Zummo, Alexandre Belloni, Jonathan Corbet, linux-rtc, linux-doc, linux-kernel, linux-api Cc: Julia Lawall, gregkh The ioctl interface should be in Documentation/ABI along with the rest of the interfaces. Signed-off-by: Aishwarya Pant <aishpant@gmail.com> --- Documentation/ABI/testing/rtc-cdev | 42 ++++++++++++++++++++++++++++++++ Documentation/rtc.txt | 49 ++------------------------------------ 2 files changed, 44 insertions(+), 47 deletions(-) create mode 100644 Documentation/ABI/testing/rtc-cdev diff --git a/Documentation/ABI/testing/rtc-cdev b/Documentation/ABI/testing/rtc-cdev new file mode 100644 index 000000000000..97447283f13b --- /dev/null +++ b/Documentation/ABI/testing/rtc-cdev @@ -0,0 +1,42 @@ +What: /dev/rtcX +Date: April 2005 +KernelVersion: 2.6.12 +Contact: linux-rtc@vger.kernel.org +Description: + The ioctl interface to drivers for real-time clocks (RTCs). + Following actions are supported: + + * RTC_RD_TIME, RTC_SET_TIME: Read or set the RTC time. Time + format is a Gregorian calendar date and 24 hour wall clock + time. + + * RTC_AIE_ON, RTC_AIE_OFF: Enable or disable the alarm interrupt + for RTCs that support alarms + + * RTC_ALM_READ, RTC_ALM_SET: Read or set the alarm time for + RTCs that support alarms. Can be set upto 24 hours in the + future. Requires a separate RTC_AIE_ON call to enable the + alarm interrupt. (Prefer to use RTC_WKALM_*) + + * RTC_WKALM_RD, RTC_WKALM_SET: For RTCs that support a more + powerful interface, which can issue alarms beyond 24 hours and + enable IRQs in the same request. + + * RTC_PIE_ON, RTC_PIE_OFF: Enable or disable the periodic + interrupt for RTCs that support periodic interrupts. + + * RTC_UIE_ON, RTC_UIE_OFF: Enable or disable the update + interrupt for RTCs that support it. + + * RTC_IRQP_READ, RTC_IRQP_SET: Read or set the frequency for + periodic interrupts for RTCs that support periodic interrupts. + Requires a separate RTC_PIE_ON call to enable the periodic + interrupts. + + The ioctl() calls supported by the older /dev/rtc interface are + also supported by the newer 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 + newer features -- including those enabled by ACPI -- are exposed + by the RTC class framework, but can't be supported by the older + driver. diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt index f521262cdc85..a129acf38537 100644 --- a/Documentation/rtc.txt +++ b/Documentation/rtc.txt @@ -136,50 +136,5 @@ 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. -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 -newer features -- including those enabled by ACPI -- are exposed by the -RTC class framework, but can't be supported by the older driver. - - * RTC_RD_TIME, RTC_SET_TIME ... every RTC supports at least reading - time, returning the result as a Gregorian calendar date and 24 hour - wall clock time. To be most useful, this time may also be updated. - - * RTC_AIE_ON, RTC_AIE_OFF, RTC_ALM_SET, RTC_ALM_READ ... when the RTC - is connected to an IRQ line, it can often issue an alarm IRQ up to - 24 hours in the future. (Use RTC_WKALM_* by preference.) - - * RTC_WKALM_SET, RTC_WKALM_RD ... RTCs that can issue alarms beyond - the next 24 hours use a slightly more powerful API, which supports - setting the longer alarm time and enabling its IRQ using a single - request (using the same model as EFI firmware). - - * RTC_UIE_ON, RTC_UIE_OFF ... if the RTC offers IRQs, the RTC framework - will emulate this mechanism. - - * RTC_PIE_ON, RTC_PIE_OFF, RTC_IRQP_SET, RTC_IRQP_READ ... these icotls - are emulated via a kernel hrtimer. - -In many cases, the RTC alarm can be a system wake event, used to force -Linux out of a low power sleep state (or hibernation) back to a fully -operational state. For example, a system could enter a deep power saving -state until it's time to execute some scheduled tasks. - -Note that many of these ioctls are handled by the common rtc-dev interface. -Some common examples: - - * RTC_RD_TIME, RTC_SET_TIME: the read_time/set_time functions will be - called with appropriate values. - - * RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: gets or sets - the alarm rtc_timer. May call the set_alarm driver function. - - * RTC_IRQP_SET, RTC_IRQP_READ: These are emulated by the generic code. - - * RTC_PIE_ON, RTC_PIE_OFF: These are also emulated by the generic code. - -If all else fails, check out the tools/testing/selftests/timers/rtctest.c test! +Check out tools/testing/selftests/timers/rtctest.c for an example usage of the +ioctl interface. -- 2.15.1 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH 0/2] Documentation: rtc: move ioctl to ABI 2018-01-01 17:30 ` Aishwarya Pant ` (2 preceding siblings ...) (?) @ 2018-01-11 23:11 ` Alexandre Belloni -1 siblings, 0 replies; 6+ messages in thread From: Alexandre Belloni @ 2018-01-11 23:11 UTC (permalink / raw) To: Aishwarya Pant Cc: Alessandro Zummo, Jonathan Corbet, linux-rtc, linux-doc, linux-kernel, linux-api, Julia Lawall, gregkh On 01/01/2018 at 23:00:02 +0530, Aishwarya Pant wrote: > Two documentation changes in rtc: > 1) Minor change to add file permissions to sysfs interface > 2) Move ioctl interface to Documentation/ABI > > Aishwarya Pant (2): > Documentation: rtc: add sysfs file permissions > Documentation: rtc: move iotcl interface documentation to ABI > Applied, thanks. -- Alexandre Belloni, Free Electrons Embedded Linux and Kernel engineering http://free-electrons.com ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2018-01-11 23:11 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2018-01-01 17:30 [PATCH 0/2] Documentation: rtc: move ioctl to ABI Aishwarya Pant
2018-01-01 17:30 ` Aishwarya Pant
2018-01-01 17:30 ` [PATCH 1/2] Documentation: rtc: add sysfs file permissions Aishwarya Pant
[not found] ` <cover.1514827586.git.aishpant-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
2018-01-01 17:31 ` [PATCH 2/2] Documentation: rtc: move iotcl interface documentation to ABI Aishwarya Pant
2018-01-01 17:31 ` Aishwarya Pant
2018-01-11 23:11 ` [PATCH 0/2] Documentation: rtc: move ioctl " Alexandre Belloni
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.