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