include/rtc.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * (C) Copyright 2001
   4  * Wolfgang Denk, DENX Software Engineering, wd@denx.de.
   5  */
   6
   7 /*
   8  * Generic RTC interface.
   9  */
  10 #ifndef _RTC_H_
  11 #define _RTC_H_
  12
  13 /* bcd<->bin functions are needed by almost all the RTC drivers, let's include
  14  * it there instead of in evey single driver */
  15
  16 #include <bcd.h>
  17 #include <rtc_def.h>
  18 #include <linux/errno.h>
  19
  20 typedef int64_t time64_t;
  21 struct udevice;
  22
  23 #if CONFIG_IS_ENABLED(DM_RTC)
  24 struct rtc_ops {
  25         /**
  26          * get() - get the current time
  27          *
  28          * Returns the current time read from the RTC device. The driver
  29          * is responsible for setting up every field in the structure.
  30          *
  31          * @dev:        Device to read from
  32          * @time:       Place to put the time that is read
  33          */
  34         int (*get)(struct udevice *dev, struct rtc_time *time);
  35
  36         /**
  37          * set() - set the current time
  38          *
  39          * Sets the time in the RTC device. The driver can expect every
  40          * field to be set correctly.
  41          *
  42          * @dev:        Device to read from
  43          * @time:       Time to write
  44          */
  45         int (*set)(struct udevice *dev, const struct rtc_time *time);
  46
  47         /**
  48          * reset() - reset the RTC to a known-good state
  49          *
  50          * This function resets the RTC to a known-good state. The time may
  51          * be unset by this method, so should be set after this method is
  52          * called.
  53          *
  54          * @dev:        Device to read from
  55          * @return 0 if OK, -ve on error
  56          */
  57         int (*reset)(struct udevice *dev);
  58
  59         /**
  60          * read() - Read multiple 8-bit registers
  61          *
  62          * @dev:        Device to read from
  63          * @reg:        First register to read
  64          * @buf:        Output buffer
  65          * @len:        Number of registers to read
  66          * @return 0 if OK, -ve on error
  67          */
  68         int (*read)(struct udevice *dev, unsigned int reg,
  69                     u8 *buf, unsigned int len);
  70
  71         /**
  72          * write() - Write multiple 8-bit registers
  73          *
  74          * @dev:        Device to write to
  75          * @reg:        First register to write
  76          * @buf:        Input buffer
  77          * @len:        Number of registers to write
  78          * @return 0 if OK, -ve on error
  79          */
  80         int (*write)(struct udevice *dev, unsigned int reg,
  81                      const u8 *buf, unsigned int len);
  82
  83         /**
  84          * read8() - Read an 8-bit register
  85          *
  86          * @dev:        Device to read from
  87          * @reg:        Register to read
  88          * @return value read, or -ve on error
  89          */
  90         int (*read8)(struct udevice *dev, unsigned int reg);
  91
  92         /**
  93         * write8() - Write an 8-bit register
  94         *
  95         * @dev:         Device to write to
  96         * @reg:         Register to write
  97         * @value:       Value to write
  98         * Return: 0 if OK, -ve on error
  99         */
 100         int (*write8)(struct udevice *dev, unsigned int reg, int val);
 101 };
 102
 103 /* Access the operations for an RTC device */
 104 #define rtc_get_ops(dev)        ((struct rtc_ops *)(dev)->driver->ops)
 105
 106 /**
 107  * dm_rtc_get() - Read the time from an RTC
 108  *
 109  * @dev:        Device to read from
 110  * @time:       Place to put the current time
 111  * Return: 0 if OK, -ve on error
 112  */
 113 int dm_rtc_get(struct udevice *dev, struct rtc_time *time);
 114
 115 /**
 116  * dm_rtc_set() - Write a time to an RTC
 117  *
 118  * @dev:        Device to read from
 119  * @time:       Time to write into the RTC
 120  * Return: 0 if OK, -ve on error
 121  */
 122 int dm_rtc_set(struct udevice *dev, struct rtc_time *time);
 123
 124 /**
 125  * dm_rtc_reset() - reset the RTC to a known-good state
 126  *
 127  * If the RTC appears to be broken (e.g. it is not counting up in seconds)
 128  * it may need to be reset to a known good state. This function achieves this.
 129  * After resetting the RTC the time should then be set to a known value by
 130  * the caller.
 131  *
 132  * @dev:        Device to read from
 133  * Return: 0 if OK, -ve on error
 134  */
 135 int dm_rtc_reset(struct udevice *dev);
 136
 137 /**
 138  * dm_rtc_read() - Read multiple 8-bit registers
 139  *
 140  * @dev:        Device to read from
 141  * @reg:        First register to read
 142  * @buf:        Output buffer
 143  * @len:        Number of registers to read
 144  * Return: 0 if OK, -ve on error
 145  */
 146 int dm_rtc_read(struct udevice *dev, unsigned int reg, u8 *buf, unsigned int len);
 147
 148 /**
 149  * dm_rtc_write() - Write multiple 8-bit registers
 150  *
 151  * @dev:        Device to write to
 152  * @reg:        First register to write
 153  * @buf:        Input buffer
 154  * @len:        Number of registers to write
 155  * Return: 0 if OK, -ve on error
 156  */
 157 int dm_rtc_write(struct udevice *dev, unsigned int reg,
 158                  const u8 *buf, unsigned int len);
 159
 160 /**
 161  * rtc_read8() - Read an 8-bit register
 162  *
 163  * @dev:        Device to read from
 164  * @reg:        Register to read
 165  * Return: value read, or -ve on error
 166  */
 167 int rtc_read8(struct udevice *dev, unsigned int reg);
 168
 169 /**
 170  * rtc_write8() - Write an 8-bit register
 171  *
 172  * @dev:        Device to write to
 173  * @reg:        Register to write
 174  * @value:      Value to write
 175  * Return: 0 if OK, -ve on error
 176  */
 177 int rtc_write8(struct udevice *dev, unsigned int reg, int val);
 178
 179 /**
 180  * rtc_read16() - Read a 16-bit value from the RTC
 181  *
 182  * @dev:        Device to read from
 183  * @reg:        Offset to start reading from
 184  * @valuep:     Place to put the value that is read
 185  * Return: 0 if OK, -ve on error
 186  */
 187 int rtc_read16(struct udevice *dev, unsigned int reg, u16 *valuep);
 188
 189 /**
 190  * rtc_write16() - Write a 16-bit value to the RTC
 191  *
 192  * @dev:        Device to write to
 193  * @reg:        Register to start writing to
 194  * @value:      Value to write
 195  * Return: 0 if OK, -ve on error
 196  */
 197 int rtc_write16(struct udevice *dev, unsigned int reg, u16 value);
 198
 199 /**
 200  * rtc_read32() - Read a 32-bit value from the RTC
 201  *
 202  * @dev:        Device to read from
 203  * @reg:        Offset to start reading from
 204  * @valuep:     Place to put the value that is read
 205  * Return: 0 if OK, -ve on error
 206  */
 207 int rtc_read32(struct udevice *dev, unsigned int reg, u32 *valuep);
 208
 209 /**
 210  * rtc_write32() - Write a 32-bit value to the RTC
 211  *
 212  * @dev:        Device to write to
 213  * @reg:        Register to start writing to
 214  * @value:      Value to write
 215  * Return: 0 if OK, -ve on error
 216  */
 217 int rtc_write32(struct udevice *dev, unsigned int reg, u32 value);
 218
 219 #ifdef CONFIG_RTC_ENABLE_32KHZ_OUTPUT
 220 int rtc_enable_32khz_output(int busnum, int chip_addr);
 221 #endif
 222
 223 #else
 224 static inline int dm_rtc_get(struct udevice *dev, struct rtc_time *time)
 225 {
 226         return -ENOSYS;
 227 }
 228
 229 static inline int dm_rtc_set(struct udevice *dev, struct rtc_time *time)
 230 {
 231         return -ENOSYS;
 232 }
 233
 234 static inline int dm_rtc_reset(struct udevice *dev)
 235 {
 236         return -ENOSYS;
 237 }
 238
 239 static inline int dm_rtc_read(struct udevice *dev, unsigned int reg, u8 *buf,
 240                               unsigned int len)
 241 {
 242         return -ENOSYS;
 243 }
 244
 245 static inline int dm_rtc_write(struct udevice *dev, unsigned int reg,
 246                                const u8 *buf, unsigned int len)
 247 {
 248         return -ENOSYS;
 249 }
 250
 251 int rtc_get (struct rtc_time *);
 252 int rtc_set (struct rtc_time *);
 253 void rtc_reset (void);
 254 #ifdef CONFIG_RTC_ENABLE_32KHZ_OUTPUT
 255 void rtc_enable_32khz_output(void);
 256 #endif
 257
 258 /**
 259  * rtc_read8() - Read an 8-bit register
 260  *
 261  * @reg:        Register to read
 262  * Return: value read
 263  */
 264 int rtc_read8(int reg);
 265
 266 /**
 267  * rtc_write8() - Write an 8-bit register
 268  *
 269  * @reg:        Register to write
 270  * @value:      Value to write
 271  */
 272 void rtc_write8(int reg, uchar val);
 273
 274 /**
 275  * rtc_read32() - Read a 32-bit value from the RTC
 276  *
 277  * @reg:        Offset to start reading from
 278  * Return: value read
 279  */
 280 u32 rtc_read32(int reg);
 281
 282 /**
 283  * rtc_write32() - Write a 32-bit value to the RTC
 284  *
 285  * @reg:        Register to start writing to
 286  * @value:      Value to write
 287  */
 288 void rtc_write32(int reg, u32 value);
 289
 290 /**
 291  * rtc_init() - Set up the real time clock ready for use
 292  */
 293 void rtc_init(void);
 294 #endif /* CONFIG_DM_RTC */
 295
 296 /**
 297  * is_leap_year - Check if year is a leap year
 298  *
 299  * @year        Year
 300  * Return:      1 if leap year
 301  */
 302 static inline bool is_leap_year(unsigned int year)
 303 {
 304         return (!(year % 4) && (year % 100)) || !(year % 400);
 305 }
 306
 307 /**
 308  * rtc_calc_weekday() - Work out the weekday from a time
 309  *
 310  * This only works for the Gregorian calendar - i.e. after 1752 (in the UK).
 311  * It sets time->tm_wdaay to the correct day of the week.
 312  *
 313  * @time:       Time to inspect. tm_wday is updated
 314  * Return: 0 if OK, -EINVAL if the weekday could not be determined
 315  */
 316 int rtc_calc_weekday(struct rtc_time *time);
 317
 318 /**
 319  * rtc_to_tm() - Convert a time_t value into a broken-out time
 320  *
 321  * The following fields are set up by this function:
 322  *      tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year, tm_wday
 323  *
 324  * Note that tm_yday and tm_isdst are set to 0.
 325  *
 326  * @time_t:     Number of seconds since 1970-01-01 00:00:00
 327  * @time:       Place to put the broken-out time
 328  */
 329 void rtc_to_tm(u64 time_t, struct rtc_time *time);
 330
 331 /**
 332  * rtc_mktime() - Convert a broken-out time into a time64_t value
 333  *
 334  * The following fields need to be valid for this function to work:
 335  *      tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year
 336  *
 337  * Note that tm_wday and tm_yday are ignored.
 338  *
 339  * @time:       Broken-out time to convert
 340  * Return: corresponding time64_t value, seconds since 1970-01-01 00:00:00
 341  */
 342 time64_t rtc_mktime(const struct rtc_time *time);
 343
 344 /**
 345  * rtc_month_days() - The number of days in the month
 346  *
 347  * @month:      month (January = 0)
 348  * @year:       year (4 digits)
 349  */
 350 int rtc_month_days(unsigned int month, unsigned int year);
 351
 352 #endif  /* _RTC_H_ */