include/linux/rtc.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 /*
0003  * Generic RTC interface.
0004  * This version contains the part of the user interface to the Real Time Clock
0005  * service. It is used with both the legacy mc146818 and also  EFI
0006  * Struct rtc_time and first 12 ioctl by Paul Gortmaker, 1996 - separated out
0007  * from <linux/mc146818rtc.h> to this file for 2.4 kernels.
0008  *
0009  * Copyright (C) 1999 Hewlett-Packard Co.
0010  * Copyright (C) 1999 Stephane Eranian <eranian@hpl.hp.com>
0011  */
0012 #ifndef _LINUX_RTC_H_
0013 #define _LINUX_RTC_H_
0014
0015
0016 #include <linux/types.h>
0017 #include <linux/interrupt.h>
0018 #include <linux/nvmem-provider.h>
0019 #include <uapi/linux/rtc.h>
0020
0021 extern int rtc_month_days(unsigned int month, unsigned int year);
0022 extern int rtc_year_days(unsigned int day, unsigned int month, unsigned int year);
0023 extern int rtc_valid_tm(struct rtc_time *tm);
0024 extern time64_t rtc_tm_to_time64(struct rtc_time *tm);
0025 extern void rtc_time64_to_tm(time64_t time, struct rtc_time *tm);
0026 ktime_t rtc_tm_to_ktime(struct rtc_time tm);
0027 struct rtc_time rtc_ktime_to_tm(ktime_t kt);
0028
0029 /*
0030  * rtc_tm_sub - Return the difference in seconds.
0031  */
0032 static inline time64_t rtc_tm_sub(struct rtc_time *lhs, struct rtc_time *rhs)
0033 {
0034     return rtc_tm_to_time64(lhs) - rtc_tm_to_time64(rhs);
0035 }
0036
0037 #include <linux/device.h>
0038 #include <linux/seq_file.h>
0039 #include <linux/cdev.h>
0040 #include <linux/poll.h>
0041 #include <linux/mutex.h>
0042 #include <linux/timerqueue.h>
0043 #include <linux/workqueue.h>
0044
0045 extern struct class *rtc_class;
0046
0047 /*
0048  * For these RTC methods the device parameter is the physical device
0049  * on whatever bus holds the hardware (I2C, Platform, SPI, etc), which
0050  * was passed to rtc_device_register().  Its driver_data normally holds
0051  * device state, including the rtc_device pointer for the RTC.
0052  *
0053  * Most of these methods are called with rtc_device.ops_lock held,
0054  * through the rtc_*(struct rtc_device *, ...) calls.
0055  *
0056  * The (current) exceptions are mostly filesystem hooks:
0057  *   - the proc() hook for procfs
0058  */
0059 struct rtc_class_ops {
0060     int (*ioctl)(struct device *, unsigned int, unsigned long);
0061     int (*read_time)(struct device *, struct rtc_time *);
0062     int (*set_time)(struct device *, struct rtc_time *);
0063     int (*read_alarm)(struct device *, struct rtc_wkalrm *);
0064     int (*set_alarm)(struct device *, struct rtc_wkalrm *);
0065     int (*proc)(struct device *, struct seq_file *);
0066     int (*alarm_irq_enable)(struct device *, unsigned int enabled);
0067     int (*read_offset)(struct device *, long *offset);
0068     int (*set_offset)(struct device *, long offset);
0069     int (*param_get)(struct device *, struct rtc_param *param);
0070     int (*param_set)(struct device *, struct rtc_param *param);
0071 };
0072
0073 struct rtc_device;
0074
0075 struct rtc_timer {
0076     struct timerqueue_node node;
0077     ktime_t period;
0078     void (*func)(struct rtc_device *rtc);
0079     struct rtc_device *rtc;
0080     int enabled;
0081 };
0082
0083 /* flags */
0084 #define RTC_DEV_BUSY 0
0085 #define RTC_NO_CDEV  1
0086
0087 struct rtc_device {
0088     struct device dev;
0089     struct module *owner;
0090
0091     int id;
0092
0093     const struct rtc_class_ops *ops;
0094     struct mutex ops_lock;
0095
0096     struct cdev char_dev;
0097     unsigned long flags;
0098
0099     unsigned long irq_data;
0100     spinlock_t irq_lock;
0101     wait_queue_head_t irq_queue;
0102     struct fasync_struct *async_queue;
0103
0104     int irq_freq;
0105     int max_user_freq;
0106
0107     struct timerqueue_head timerqueue;
0108     struct rtc_timer aie_timer;
0109     struct rtc_timer uie_rtctimer;
0110     struct hrtimer pie_timer; /* sub second exp, so needs hrtimer */
0111     int pie_enabled;
0112     struct work_struct irqwork;
0113
0114     /*
0115      * This offset specifies the update timing of the RTC.
0116      *
0117      * tsched     t1 write(t2.tv_sec - 1sec))  t2 RTC increments seconds
0118      *
0119      * The offset defines how tsched is computed so that the write to
0120      * the RTC (t2.tv_sec - 1sec) is correct versus the time required
0121      * for the transport of the write and the time which the RTC needs
0122      * to increment seconds the first time after the write (t2).
0123      *
0124      * For direct accessible RTCs tsched ~= t1 because the write time
0125      * is negligible. For RTCs behind slow busses the transport time is
0126      * significant and has to be taken into account.
0127      *
0128      * The time between the write (t1) and the first increment after
0129      * the write (t2) is RTC specific. For a MC146818 RTC it's 500ms,
0130      * for many others it's exactly 1 second. Consult the datasheet.
0131      *
0132      * The value of this offset is also used to calculate the to be
0133      * written value (t2.tv_sec - 1sec) at tsched.
0134      *
0135      * The default value for this is NSEC_PER_SEC + 10 msec default
0136      * transport time. The offset can be adjusted by drivers so the
0137      * calculation for the to be written value at tsched becomes
0138      * correct:
0139      *
0140      *  newval = tsched + set_offset_nsec - NSEC_PER_SEC
0141      * and  (tsched + set_offset_nsec) % NSEC_PER_SEC == 0
0142      */
0143     unsigned long set_offset_nsec;
0144
0145     unsigned long features[BITS_TO_LONGS(RTC_FEATURE_CNT)];
0146
0147     time64_t range_min;
0148     timeu64_t range_max;
0149     time64_t start_secs;
0150     time64_t offset_secs;
0151     bool set_start_time;
0152
0153 #ifdef CONFIG_RTC_INTF_DEV_UIE_EMUL
0154     struct work_struct uie_task;
0155     struct timer_list uie_timer;
0156     /* Those fields are protected by rtc->irq_lock */
0157     unsigned int oldsecs;
0158     unsigned int uie_irq_active:1;
0159     unsigned int stop_uie_polling:1;
0160     unsigned int uie_task_active:1;
0161     unsigned int uie_timer_active:1;
0162 #endif
0163 };
0164 #define to_rtc_device(d) container_of(d, struct rtc_device, dev)
0165
0166 #define rtc_lock(d) mutex_lock(&d->ops_lock)
0167 #define rtc_unlock(d) mutex_unlock(&d->ops_lock)
0168
0169 /* useful timestamps */
0170 #define RTC_TIMESTAMP_BEGIN_0000    -62167219200ULL /* 0000-01-01 00:00:00 */
0171 #define RTC_TIMESTAMP_BEGIN_1900    -2208988800LL /* 1900-01-01 00:00:00 */
0172 #define RTC_TIMESTAMP_BEGIN_2000    946684800LL /* 2000-01-01 00:00:00 */
0173 #define RTC_TIMESTAMP_END_2063      2966371199LL /* 2063-12-31 23:59:59 */
0174 #define RTC_TIMESTAMP_END_2079      3471292799LL /* 2079-12-31 23:59:59 */
0175 #define RTC_TIMESTAMP_END_2099      4102444799LL /* 2099-12-31 23:59:59 */
0176 #define RTC_TIMESTAMP_END_2199      7258118399LL /* 2199-12-31 23:59:59 */
0177 #define RTC_TIMESTAMP_END_9999      253402300799LL /* 9999-12-31 23:59:59 */
0178
0179 extern struct rtc_device *devm_rtc_device_register(struct device *dev,
0180                     const char *name,
0181                     const struct rtc_class_ops *ops,
0182                     struct module *owner);
0183 struct rtc_device *devm_rtc_allocate_device(struct device *dev);
0184 int __devm_rtc_register_device(struct module *owner, struct rtc_device *rtc);
0185
0186 extern int rtc_read_time(struct rtc_device *rtc, struct rtc_time *tm);
0187 extern int rtc_set_time(struct rtc_device *rtc, struct rtc_time *tm);
0188 int __rtc_read_alarm(struct rtc_device *rtc, struct rtc_wkalrm *alarm);
0189 extern int rtc_read_alarm(struct rtc_device *rtc,
0190             struct rtc_wkalrm *alrm);
0191 extern int rtc_set_alarm(struct rtc_device *rtc,
0192                 struct rtc_wkalrm *alrm);
0193 extern int rtc_initialize_alarm(struct rtc_device *rtc,
0194                 struct rtc_wkalrm *alrm);
0195 extern void rtc_update_irq(struct rtc_device *rtc,
0196             unsigned long num, unsigned long events);
0197
0198 extern struct rtc_device *rtc_class_open(const char *name);
0199 extern void rtc_class_close(struct rtc_device *rtc);
0200
0201 extern int rtc_irq_set_state(struct rtc_device *rtc, int enabled);
0202 extern int rtc_irq_set_freq(struct rtc_device *rtc, int freq);
0203 extern int rtc_update_irq_enable(struct rtc_device *rtc, unsigned int enabled);
0204 extern int rtc_alarm_irq_enable(struct rtc_device *rtc, unsigned int enabled);
0205 extern int rtc_dev_update_irq_enable_emul(struct rtc_device *rtc,
0206                         unsigned int enabled);
0207
0208 void rtc_handle_legacy_irq(struct rtc_device *rtc, int num, int mode);
0209 void rtc_aie_update_irq(struct rtc_device *rtc);
0210 void rtc_uie_update_irq(struct rtc_device *rtc);
0211 enum hrtimer_restart rtc_pie_update_irq(struct hrtimer *timer);
0212
0213 void rtc_timer_init(struct rtc_timer *timer, void (*f)(struct rtc_device *r),
0214             struct rtc_device *rtc);
0215 int rtc_timer_start(struct rtc_device *rtc, struct rtc_timer *timer,
0216             ktime_t expires, ktime_t period);
0217 void rtc_timer_cancel(struct rtc_device *rtc, struct rtc_timer *timer);
0218 int rtc_read_offset(struct rtc_device *rtc, long *offset);
0219 int rtc_set_offset(struct rtc_device *rtc, long offset);
0220 void rtc_timer_do_work(struct work_struct *work);
0221
0222 static inline bool is_leap_year(unsigned int year)
0223 {
0224     return (!(year % 4) && (year % 100)) || !(year % 400);
0225 }
0226
0227 #define devm_rtc_register_device(device) \
0228     __devm_rtc_register_device(THIS_MODULE, device)
0229
0230 #ifdef CONFIG_RTC_HCTOSYS_DEVICE
0231 extern int rtc_hctosys_ret;
0232 #else
0233 #define rtc_hctosys_ret -ENODEV
0234 #endif
0235
0236 #ifdef CONFIG_RTC_NVMEM
0237 int devm_rtc_nvmem_register(struct rtc_device *rtc,
0238                 struct nvmem_config *nvmem_config);
0239 #else
0240 static inline int devm_rtc_nvmem_register(struct rtc_device *rtc,
0241                       struct nvmem_config *nvmem_config)
0242 {
0243     return 0;
0244 }
0245 #endif
0246
0247 #ifdef CONFIG_RTC_INTF_SYSFS
0248 int rtc_add_group(struct rtc_device *rtc, const struct attribute_group *grp);
0249 int rtc_add_groups(struct rtc_device *rtc, const struct attribute_group **grps);
0250 #else
0251 static inline
0252 int rtc_add_group(struct rtc_device *rtc, const struct attribute_group *grp)
0253 {
0254     return 0;
0255 }
0256
0257 static inline
0258 int rtc_add_groups(struct rtc_device *rtc, const struct attribute_group **grps)
0259 {
0260     return 0;
0261 }
0262 #endif
0263 #endif /* _LINUX_RTC_H_ */