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