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          * read8() - Read an 8-bit register
  60          *
  61          * @dev:        Device to read from
  62          * @reg:        Register to read
  63          * @return value read, or -ve on error
  64          */
  65         int (*read8)(struct udevice *dev, unsigned int reg);
  66
  67         /**
  68         * write8() - Write an 8-bit register
  69         *
  70         * @dev:         Device to write to
  71         * @reg:         Register to write
  72         * @value:       Value to write
  73         * @return 0 if OK, -ve on error
  74         */
  75         int (*write8)(struct udevice *dev, unsigned int reg, int val);
  76 };
  77
  78 /* Access the operations for an RTC device */
  79 #define rtc_get_ops(dev)        ((struct rtc_ops *)(dev)->driver->ops)
  80
  81 /**
  82  * dm_rtc_get() - Read the time from an RTC
  83  *
  84  * @dev:        Device to read from
  85  * @time:       Place to put the current time
  86  * @return 0 if OK, -ve on error
  87  */
  88 int dm_rtc_get(struct udevice *dev, struct rtc_time *time);
  89
  90 /**
  91  * dm_rtc_set() - Write a time to an RTC
  92  *
  93  * @dev:        Device to read from
  94  * @time:       Time to write into the RTC
  95  * @return 0 if OK, -ve on error
  96  */
  97 int dm_rtc_set(struct udevice *dev, struct rtc_time *time);
  98
  99 /**
 100  * dm_rtc_reset() - reset the RTC to a known-good state
 101  *
 102  * If the RTC appears to be broken (e.g. it is not counting up in seconds)
 103  * it may need to be reset to a known good state. This function achieves this.
 104  * After resetting the RTC the time should then be set to a known value by
 105  * the caller.
 106  *
 107  * @dev:        Device to read from
 108  * @return 0 if OK, -ve on error
 109  */
 110 int dm_rtc_reset(struct udevice *dev);
 111
 112 /**
 113  * rtc_read8() - Read an 8-bit register
 114  *
 115  * @dev:        Device to read from
 116  * @reg:        Register to read
 117  * @return value read, or -ve on error
 118  */
 119 int rtc_read8(struct udevice *dev, unsigned int reg);
 120
 121 /**
 122  * rtc_write8() - Write an 8-bit register
 123  *
 124  * @dev:        Device to write to
 125  * @reg:        Register to write
 126  * @value:      Value to write
 127  * @return 0 if OK, -ve on error
 128  */
 129 int rtc_write8(struct udevice *dev, unsigned int reg, int val);
 130
 131 /**
 132  * rtc_read16() - Read a 16-bit value from the RTC
 133  *
 134  * @dev:        Device to read from
 135  * @reg:        Offset to start reading from
 136  * @valuep:     Place to put the value that is read
 137  * @return 0 if OK, -ve on error
 138  */
 139 int rtc_read16(struct udevice *dev, unsigned int reg, u16 *valuep);
 140
 141 /**
 142  * rtc_write16() - Write a 16-bit value to the RTC
 143  *
 144  * @dev:        Device to write to
 145  * @reg:        Register to start writing to
 146  * @value:      Value to write
 147  * @return 0 if OK, -ve on error
 148  */
 149 int rtc_write16(struct udevice *dev, unsigned int reg, u16 value);
 150
 151 /**
 152  * rtc_read32() - Read a 32-bit value from the RTC
 153  *
 154  * @dev:        Device to read from
 155  * @reg:        Offset to start reading from
 156  * @valuep:     Place to put the value that is read
 157  * @return 0 if OK, -ve on error
 158  */
 159 int rtc_read32(struct udevice *dev, unsigned int reg, u32 *valuep);
 160
 161 /**
 162  * rtc_write32() - Write a 32-bit value to the RTC
 163  *
 164  * @dev:        Device to write to
 165  * @reg:        Register to start writing to
 166  * @value:      Value to write
 167  * @return 0 if OK, -ve on error
 168  */
 169 int rtc_write32(struct udevice *dev, unsigned int reg, u32 value);
 170
 171 #ifdef CONFIG_RTC_ENABLE_32KHZ_OUTPUT
 172 int rtc_enable_32khz_output(int busnum, int chip_addr);
 173 #endif
 174
 175 #else
 176 int rtc_get (struct rtc_time *);
 177 int rtc_set (struct rtc_time *);
 178 void rtc_reset (void);
 179 #ifdef CONFIG_RTC_ENABLE_32KHZ_OUTPUT
 180 void rtc_enable_32khz_output(void);
 181 #endif
 182
 183 /**
 184  * rtc_read8() - Read an 8-bit register
 185  *
 186  * @reg:        Register to read
 187  * @return value read
 188  */
 189 int rtc_read8(int reg);
 190
 191 /**
 192  * rtc_write8() - Write an 8-bit register
 193  *
 194  * @reg:        Register to write
 195  * @value:      Value to write
 196  */
 197 void rtc_write8(int reg, uchar val);
 198
 199 /**
 200  * rtc_read32() - Read a 32-bit value from the RTC
 201  *
 202  * @reg:        Offset to start reading from
 203  * @return value read
 204  */
 205 u32 rtc_read32(int reg);
 206
 207 /**
 208  * rtc_write32() - Write a 32-bit value to the RTC
 209  *
 210  * @reg:        Register to start writing to
 211  * @value:      Value to write
 212  */
 213 void rtc_write32(int reg, u32 value);
 214
 215 /**
 216  * rtc_init() - Set up the real time clock ready for use
 217  */
 218 void rtc_init(void);
 219 #endif /* CONFIG_DM_RTC */
 220
 221 /**
 222  * is_leap_year - Check if year is a leap year
 223  *
 224  * @year        Year
 225  * @return      1 if leap year
 226  */
 227 static inline bool is_leap_year(unsigned int year)
 228 {
 229         return (!(year % 4) && (year % 100)) || !(year % 400);
 230 }
 231
 232 /**
 233  * rtc_calc_weekday() - Work out the weekday from a time
 234  *
 235  * This only works for the Gregorian calendar - i.e. after 1752 (in the UK).
 236  * It sets time->tm_wdaay to the correct day of the week.
 237  *
 238  * @time:       Time to inspect. tm_wday is updated
 239  * @return 0 if OK, -EINVAL if the weekday could not be determined
 240  */
 241 int rtc_calc_weekday(struct rtc_time *time);
 242
 243 /**
 244  * rtc_to_tm() - Convert a time_t value into a broken-out time
 245  *
 246  * The following fields are set up by this function:
 247  *      tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year, tm_wday
 248  *
 249  * Note that tm_yday and tm_isdst are set to 0.
 250  *
 251  * @time_t:     Number of seconds since 1970-01-01 00:00:00
 252  * @time:       Place to put the broken-out time
 253  */
 254 void rtc_to_tm(u64 time_t, struct rtc_time *time);
 255
 256 /**
 257  * rtc_mktime() - Convert a broken-out time into a time_t value
 258  *
 259  * The following fields need to be valid for this function to work:
 260  *      tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year
 261  *
 262  * Note that tm_wday and tm_yday are ignored.
 263  *
 264  * @time:       Broken-out time to convert
 265  * @return corresponding time_t value, seconds since 1970-01-01 00:00:00
 266  */
 267 unsigned long rtc_mktime(const struct rtc_time *time);
 268
 269 /**
 270  * rtc_month_days() - The number of days in the month
 271  *
 272  * @month:      month (January = 0)
 273  * @year:       year (4 digits)
 274  */
 275 int rtc_month_days(unsigned int month, unsigned int year);
 276
 277 #endif  /* _RTC_H_ */