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
  19 typedef int64_t time64_t;
  20
  21 #ifdef CONFIG_DM_RTC
  22
  23 struct udevice;
  24
  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 int rtc_get (struct rtc_time *);
 226 int rtc_set (struct rtc_time *);
 227 void rtc_reset (void);
 228 #ifdef CONFIG_RTC_ENABLE_32KHZ_OUTPUT
 229 void rtc_enable_32khz_output(void);
 230 #endif
 231
 232 /**
 233  * rtc_read8() - Read an 8-bit register
 234  *
 235  * @reg:        Register to read
 236  * Return: value read
 237  */
 238 int rtc_read8(int reg);
 239
 240 /**
 241  * rtc_write8() - Write an 8-bit register
 242  *
 243  * @reg:        Register to write
 244  * @value:      Value to write
 245  */
 246 void rtc_write8(int reg, uchar val);
 247
 248 /**
 249  * rtc_read32() - Read a 32-bit value from the RTC
 250  *
 251  * @reg:        Offset to start reading from
 252  * Return: value read
 253  */
 254 u32 rtc_read32(int reg);
 255
 256 /**
 257  * rtc_write32() - Write a 32-bit value to the RTC
 258  *
 259  * @reg:        Register to start writing to
 260  * @value:      Value to write
 261  */
 262 void rtc_write32(int reg, u32 value);
 263
 264 /**
 265  * rtc_init() - Set up the real time clock ready for use
 266  */
 267 void rtc_init(void);
 268 #endif /* CONFIG_DM_RTC */
 269
 270 /**
 271  * is_leap_year - Check if year is a leap year
 272  *
 273  * @year        Year
 274  * Return:      1 if leap year
 275  */
 276 static inline bool is_leap_year(unsigned int year)
 277 {
 278         return (!(year % 4) && (year % 100)) || !(year % 400);
 279 }
 280
 281 /**
 282  * rtc_calc_weekday() - Work out the weekday from a time
 283  *
 284  * This only works for the Gregorian calendar - i.e. after 1752 (in the UK).
 285  * It sets time->tm_wdaay to the correct day of the week.
 286  *
 287  * @time:       Time to inspect. tm_wday is updated
 288  * Return: 0 if OK, -EINVAL if the weekday could not be determined
 289  */
 290 int rtc_calc_weekday(struct rtc_time *time);
 291
 292 /**
 293  * rtc_to_tm() - Convert a time_t value into a broken-out time
 294  *
 295  * The following fields are set up by this function:
 296  *      tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year, tm_wday
 297  *
 298  * Note that tm_yday and tm_isdst are set to 0.
 299  *
 300  * @time_t:     Number of seconds since 1970-01-01 00:00:00
 301  * @time:       Place to put the broken-out time
 302  */
 303 void rtc_to_tm(u64 time_t, struct rtc_time *time);
 304
 305 /**
 306  * rtc_mktime() - Convert a broken-out time into a time64_t value
 307  *
 308  * The following fields need to be valid for this function to work:
 309  *      tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year
 310  *
 311  * Note that tm_wday and tm_yday are ignored.
 312  *
 313  * @time:       Broken-out time to convert
 314  * Return: corresponding time64_t value, seconds since 1970-01-01 00:00:00
 315  */
 316 time64_t rtc_mktime(const struct rtc_time *time);
 317
 318 /**
 319  * rtc_month_days() - The number of days in the month
 320  *
 321  * @month:      month (January = 0)
 322  * @year:       year (4 digits)
 323  */
 324 int rtc_month_days(unsigned int month, unsigned int year);
 325
 326 #endif  /* _RTC_H_ */