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