From a21512c1698d8106bcece0d24ff590dc92682678 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 18 May 2017 22:25:56 -0300 Subject: rtc.txt: standardize document format Each text file under Documentation follows a different format. Some doesn't even have titles! Change its representation to follow the adopted standard, using ReST markups for it to be parseable by Sphinx: - adjust identation of the titles; - mark a table as such; - don't capitalize chapter names. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Alexandre Belloni --- Documentation/rtc.txt | 44 +++++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 21 deletions(-) (limited to 'Documentation') diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt index ddc366026e00..47feb4414b7e 100644 --- a/Documentation/rtc.txt +++ b/Documentation/rtc.txt @@ -1,6 +1,6 @@ - - Real Time Clock (RTC) Drivers for Linux - ======================================= +======================================= +Real Time Clock (RTC) Drivers for Linux +======================================= When Linux developers talk about a "Real Time Clock", they usually mean something that tracks wall clock time and is battery backed so that it @@ -32,8 +32,8 @@ only issue an alarm up to 24 hours in the future, other hardware may be able to schedule one any time in the upcoming century. - Old PC/AT-Compatible driver: /dev/rtc - -------------------------------------- +Old PC/AT-Compatible driver: /dev/rtc +-------------------------------------- All PCs (even Alpha machines) have a Real Time Clock built into them. Usually they are built into the chipset of the computer, but some may @@ -105,8 +105,8 @@ that will be using this driver. See the code at the end of this document. (The original /dev/rtc driver was written by Paul Gortmaker.) - New portable "RTC Class" drivers: /dev/rtcN - -------------------------------------------- +New portable "RTC Class" drivers: /dev/rtcN +-------------------------------------------- Because Linux supports many non-ACPI and non-PC platforms, some of which have more than one RTC style clock, it needed a more portable solution @@ -136,35 +136,37 @@ 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 +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 -hctosys: 1 if the RTC provided the system time at boot via the +================ ============================================================== +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 +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 +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 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. -offset: The amount which the rtc clock has been adjusted in firmware. + 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. +offset 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. +================ ============================================================== -IOCTL INTERFACE +IOCTL interface --------------- The ioctl() calls supported by /dev/rtc are also supported by the RTC class -- cgit v1.2.3 From 3fde00a014ed1b0716a1d73fdebd96188e2ff6fe Mon Sep 17 00:00:00 2001 From: Florian Fainelli Date: Mon, 26 Jun 2017 14:15:02 -0700 Subject: dt-bindings: Document the Broadcom STB wake-up timer node Document the binding for the Broadcom STB SoCs wake-up timer node allowing the system to generate alarms and exit low power states. Acked-by: Rob Herring Signed-off-by: Florian Fainelli Signed-off-by: Alexandre Belloni --- .../bindings/rtc/brcm,brcmstb-waketimer.txt | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 Documentation/devicetree/bindings/rtc/brcm,brcmstb-waketimer.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/rtc/brcm,brcmstb-waketimer.txt b/Documentation/devicetree/bindings/rtc/brcm,brcmstb-waketimer.txt new file mode 100644 index 000000000000..1d990bcc0baf --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/brcm,brcmstb-waketimer.txt @@ -0,0 +1,22 @@ +Broadcom STB wake-up Timer + +The Broadcom STB wake-up timer provides a 27Mhz resolution timer, with the +ability to wake up the system from low-power suspend/standby modes. + +Required properties: +- compatible : should contain "brcm,brcmstb-waketimer" +- reg : the register start and length for the WKTMR block +- interrupts : The TIMER interrupt +- interrupt-parent: The phandle to the Always-On (AON) Power Management (PM) L2 + interrupt controller node +- clocks : The phandle to the UPG fixed clock (27Mhz domain) + +Example: + +waketimer@f0411580 { + compatible = "brcm,brcmstb-waketimer"; + reg = <0xf0411580 0x14>; + interrupts = <0x3>; + interrupt-parent = <&aon_pm_l2_intc>; + clocks = <&upg_fixed>; +}; -- cgit v1.2.3 From 7f1e988dffbd808ad17f22b6b88a9aa42ebe739a Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Tue, 30 May 2017 09:53:31 +0200 Subject: rtc: gemini: Augment DT bindings for Faraday The Gemini RTC is actually a standard IP block from Faraday Technology called FTRTC010. Rename the bindings, add the generic compatible string and add definitions for the two available clocks. Cc: devicetree@vger.kernel.org Cc: Po-Yu Chuang Acked-by: Rob Herring Signed-off-by: Linus Walleij Signed-off-by: Alexandre Belloni --- .../devicetree/bindings/rtc/cortina,gemini.txt | 14 ----------- .../devicetree/bindings/rtc/faraday,ftrtc010.txt | 28 ++++++++++++++++++++++ 2 files changed, 28 insertions(+), 14 deletions(-) delete mode 100644 Documentation/devicetree/bindings/rtc/cortina,gemini.txt create mode 100644 Documentation/devicetree/bindings/rtc/faraday,ftrtc010.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/rtc/cortina,gemini.txt b/Documentation/devicetree/bindings/rtc/cortina,gemini.txt deleted file mode 100644 index 4ce4e794ddbb..000000000000 --- a/Documentation/devicetree/bindings/rtc/cortina,gemini.txt +++ /dev/null @@ -1,14 +0,0 @@ -* Cortina Systems Gemini RTC - -Gemini SoC real-time clock. - -Required properties: -- compatible : Should be "cortina,gemini-rtc" - -Examples: - -rtc@45000000 { - compatible = "cortina,gemini-rtc"; - reg = <0x45000000 0x100>; - interrupts = <17 IRQ_TYPE_LEVEL_HIGH>; -}; diff --git a/Documentation/devicetree/bindings/rtc/faraday,ftrtc010.txt b/Documentation/devicetree/bindings/rtc/faraday,ftrtc010.txt new file mode 100644 index 000000000000..e3938f5e0b6c --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/faraday,ftrtc010.txt @@ -0,0 +1,28 @@ +* Faraday Technology FTRTC010 Real Time Clock + +This RTC appears in for example the Storlink Gemini family of +SoCs. + +Required properties: +- compatible : Should be one of: + "faraday,ftrtc010" + "cortina,gemini-rtc", "faraday,ftrtc010" + +Optional properties: +- clocks: when present should contain clock references to the + PCLK and EXTCLK clocks. Faraday calls the later CLK1HZ and + says the clock should be 1 Hz, but implementers actually seem + to choose different clocks here, like Cortina who chose + 32768 Hz (a typical low-power clock). +- clock-names: should name the clocks "PCLK" and "EXTCLK" + respectively. + +Examples: + +rtc@45000000 { + compatible = "cortina,gemini-rtc"; + reg = <0x45000000 0x100>; + interrupts = <17 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&foo 0>, <&foo 1>; + clock-names = "PCLK", "EXTCLK"; +}; -- cgit v1.2.3 From d2be279bcd8055ddfd92cc5f5d305eb3651e059b Mon Sep 17 00:00:00 2001 From: Amelie Delaunay Date: Thu, 6 Jul 2017 10:47:44 +0200 Subject: dt-bindings: rtc: stm32: add support for STM32H7 This patch documents support for STM32H7 Real Time Clock. It introduces a new compatible and rework clock definitions. On STM32H7 we have a 'pclk' clock for register access, in addition to the 'rtc_ck' clock. Acked-by: Rob Herring Signed-off-by: Amelie Delaunay Signed-off-by: Alexandre Belloni --- .../devicetree/bindings/rtc/st,stm32-rtc.txt | 32 ++++++++++++++++++---- 1 file changed, 27 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/rtc/st,stm32-rtc.txt b/Documentation/devicetree/bindings/rtc/st,stm32-rtc.txt index e2837b951237..0a4c371a9b7a 100644 --- a/Documentation/devicetree/bindings/rtc/st,stm32-rtc.txt +++ b/Documentation/devicetree/bindings/rtc/st,stm32-rtc.txt @@ -1,17 +1,25 @@ STM32 Real Time Clock Required properties: -- compatible: "st,stm32-rtc". +- compatible: can be either "st,stm32-rtc" or "st,stm32h7-rtc", depending on + the device is compatible with stm32(f4/f7) or stm32h7. - reg: address range of rtc register set. -- clocks: reference to the clock entry ck_rtc. +- clocks: can use up to two clocks, depending on part used: + - "rtc_ck": RTC clock source. + It is required on stm32(f4/f7) and stm32h7. + - "pclk": RTC APB interface clock. + It is not present on stm32(f4/f7). + It is required on stm32h7. +- clock-names: must be "rtc_ck" and "pclk". + It is required only on stm32h7. - interrupt-parent: phandle for the interrupt controller. - interrupts: rtc alarm interrupt. - st,syscfg: phandle for pwrcfg, mandatory to disable/enable backup domain (RTC registers) write protection. -Optional properties (to override default ck_rtc parent clock): -- assigned-clocks: reference to the ck_rtc clock entry. -- assigned-clock-parents: phandle of the new parent clock of ck_rtc. +Optional properties (to override default rtc_ck parent clock): +- assigned-clocks: reference to the rtc_ck clock entry. +- assigned-clock-parents: phandle of the new parent clock of rtc_ck. Example: @@ -25,3 +33,17 @@ Example: interrupts = <17 1>; st,syscfg = <&pwrcfg>; }; + + rtc: rtc@58004000 { + compatible = "st,stm32h7-rtc"; + reg = <0x58004000 0x400>; + clocks = <&rcc RTCAPB_CK>, <&rcc RTC_CK>; + clock-names = "pclk", "rtc_ck"; + assigned-clocks = <&rcc RTC_CK>; + assigned-clock-parents = <&rcc LSE_CK>; + interrupt-parent = <&exti>; + interrupts = <17 1>; + interrupt-names = "alarm"; + st,syscfg = <&pwrcfg>; + status = "disabled"; + }; -- cgit v1.2.3 From 697e5a47aa12cdab6f2a8b284cc923cdf704eafc Mon Sep 17 00:00:00 2001 From: Alexandre Belloni Date: Thu, 6 Jul 2017 11:42:02 +0200 Subject: rtc: add generic nvmem support Many RTCs have an on board non volatile storage. It can be battery backed RAM or an EEPROM. Use the nvmem subsystem to export it to both userspace and in-kernel consumers. This stays compatible with the previous (non documented) ABI that was using /sys/class/rtc/rtcx/device/nvram to export that memory. But will warn about the deprecation. Signed-off-by: Alexandre Belloni --- Documentation/rtc.txt | 2 + drivers/rtc/Kconfig | 8 ++++ drivers/rtc/Makefile | 1 + drivers/rtc/class.c | 4 ++ drivers/rtc/nvmem.c | 113 +++++++++++++++++++++++++++++++++++++++++++++++++ drivers/rtc/rtc-core.h | 8 ++++ include/linux/rtc.h | 7 +++ 7 files changed, 143 insertions(+) create mode 100644 drivers/rtc/nvmem.c (limited to 'Documentation') diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt index 47feb4414b7e..c0c977445fb9 100644 --- a/Documentation/rtc.txt +++ b/Documentation/rtc.txt @@ -164,6 +164,8 @@ offset The amount which the rtc clock has been adjusted in firmware. 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. +*/nvmem The non volatile storage exported as a raw file, as described + in Documentation/nvmem/nvmem.txt ================ ============================================================== IOCTL interface diff --git a/drivers/rtc/Kconfig b/drivers/rtc/Kconfig index d0e4b4a1c2a1..72419ac2c52a 100644 --- a/drivers/rtc/Kconfig +++ b/drivers/rtc/Kconfig @@ -77,6 +77,14 @@ config RTC_DEBUG Say yes here to enable debugging support in the RTC framework and individual RTC drivers. +config RTC_NVMEM + bool "RTC non volatile storage support" + select NVMEM + default RTC_CLASS + help + Say yes here to add support for the non volatile (often battery + backed) storage present on RTCs. + comment "RTC interfaces" config RTC_INTF_SYSFS diff --git a/drivers/rtc/Makefile b/drivers/rtc/Makefile index 4050fc8b9271..acd366b41c85 100644 --- a/drivers/rtc/Makefile +++ b/drivers/rtc/Makefile @@ -15,6 +15,7 @@ ifdef CONFIG_RTC_DRV_EFI rtc-core-y += rtc-efi-platform.o endif +rtc-core-$(CONFIG_RTC_NVMEM) += nvmem.o rtc-core-$(CONFIG_RTC_INTF_DEV) += rtc-dev.o rtc-core-$(CONFIG_RTC_INTF_PROC) += rtc-proc.o rtc-core-$(CONFIG_RTC_INTF_SYSFS) += rtc-sysfs.o diff --git a/drivers/rtc/class.c b/drivers/rtc/class.c index 58e2a05765bb..2ed970d61da1 100644 --- a/drivers/rtc/class.c +++ b/drivers/rtc/class.c @@ -290,6 +290,8 @@ EXPORT_SYMBOL_GPL(rtc_device_register); */ void rtc_device_unregister(struct rtc_device *rtc) { + rtc_nvmem_unregister(rtc); + mutex_lock(&rtc->ops_lock); /* * Remove innards of this RTC, then disable it, before @@ -448,6 +450,8 @@ int __rtc_register_device(struct module *owner, struct rtc_device *rtc) rtc_proc_add_device(rtc); + rtc_nvmem_register(rtc); + rtc->registered = true; dev_info(rtc->dev.parent, "registered as %s\n", dev_name(&rtc->dev)); diff --git a/drivers/rtc/nvmem.c b/drivers/rtc/nvmem.c new file mode 100644 index 000000000000..8567b4ed9ac6 --- /dev/null +++ b/drivers/rtc/nvmem.c @@ -0,0 +1,113 @@ +/* + * RTC subsystem, nvmem interface + * + * Copyright (C) 2017 Alexandre Belloni + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License version 2 as + * published by the Free Software Foundation. + */ + +#include +#include +#include +#include +#include + +#include "rtc-core.h" + +/* + * Deprecated ABI compatibility, this should be removed at some point + */ + +static const char nvram_warning[] = "Deprecated ABI, please use nvmem"; + +static ssize_t +rtc_nvram_read(struct file *filp, struct kobject *kobj, + struct bin_attribute *attr, + char *buf, loff_t off, size_t count) +{ + struct rtc_device *rtc = attr->private; + + dev_warn_once(kobj_to_dev(kobj), nvram_warning); + + return nvmem_device_read(rtc->nvmem, off, count, buf); +} + +static ssize_t +rtc_nvram_write(struct file *filp, struct kobject *kobj, + struct bin_attribute *attr, + char *buf, loff_t off, size_t count) +{ + struct rtc_device *rtc = attr->private; + + dev_warn_once(kobj_to_dev(kobj), nvram_warning); + + return nvmem_device_write(rtc->nvmem, off, count, buf); +} + +static int rtc_nvram_register(struct rtc_device *rtc) +{ + int err; + + rtc->nvram = devm_kzalloc(rtc->dev.parent, + sizeof(struct bin_attribute), + GFP_KERNEL); + if (!rtc->nvram) + return -ENOMEM; + + rtc->nvram->attr.name = "nvram"; + rtc->nvram->attr.mode = 0644; + rtc->nvram->private = rtc; + + sysfs_bin_attr_init(rtc->nvram); + + rtc->nvram->read = rtc_nvram_read; + rtc->nvram->write = rtc_nvram_write; + rtc->nvram->size = rtc->nvmem_config->size; + + err = sysfs_create_bin_file(&rtc->dev.parent->kobj, + rtc->nvram); + if (err) { + devm_kfree(rtc->dev.parent, rtc->nvram); + rtc->nvram = NULL; + } + + return err; +} + +static void rtc_nvram_unregister(struct rtc_device *rtc) +{ + sysfs_remove_bin_file(&rtc->dev.parent->kobj, rtc->nvram); +} + +/* + * New ABI, uses nvmem + */ +void rtc_nvmem_register(struct rtc_device *rtc) +{ + if (!rtc->nvmem_config) + return; + + rtc->nvmem_config->dev = &rtc->dev; + rtc->nvmem_config->owner = rtc->owner; + rtc->nvmem = nvmem_register(rtc->nvmem_config); + if (IS_ERR_OR_NULL(rtc->nvmem)) + return; + + /* Register the old ABI */ + if (rtc->nvram_old_abi) + rtc_nvram_register(rtc); +} + +void rtc_nvmem_unregister(struct rtc_device *rtc) +{ + if (IS_ERR_OR_NULL(rtc->nvmem)) + return; + + /* unregister the old ABI */ + if (rtc->nvram) + rtc_nvram_unregister(rtc); + + nvmem_unregister(rtc->nvmem); +} diff --git a/drivers/rtc/rtc-core.h b/drivers/rtc/rtc-core.h index 7a4ed2f7c7d7..ecab76a3207c 100644 --- a/drivers/rtc/rtc-core.h +++ b/drivers/rtc/rtc-core.h @@ -45,3 +45,11 @@ static inline const struct attribute_group **rtc_get_dev_attribute_groups(void) return NULL; } #endif + +#ifdef CONFIG_RTC_NVMEM +void rtc_nvmem_register(struct rtc_device *rtc); +void rtc_nvmem_unregister(struct rtc_device *rtc); +#else +static inline void rtc_nvmem_register(struct rtc_device *rtc) {} +static inline void rtc_nvmem_unregister(struct rtc_device *rtc) {} +#endif diff --git a/include/linux/rtc.h b/include/linux/rtc.h index 8e4a5f44f59e..d53ecdc060cf 100644 --- a/include/linux/rtc.h +++ b/include/linux/rtc.h @@ -14,6 +14,7 @@ #include #include +#include #include extern int rtc_month_days(unsigned int month, unsigned int year); @@ -144,6 +145,12 @@ struct rtc_device { bool registered; + struct nvmem_config *nvmem_config; + struct nvmem_device *nvmem; + /* Old ABI support */ + bool nvram_old_abi; + struct bin_attribute *nvram; + #ifdef CONFIG_RTC_INTF_DEV_UIE_EMUL struct work_struct uie_task; struct timer_list uie_timer; -- cgit v1.2.3