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_put() - 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 #else
 170 int rtc_get (struct rtc_time *);
 171 int rtc_set (struct rtc_time *);
 172 void rtc_reset (void);
 173 void rtc_enable_32khz_output(void);
 174
 175 /**
 176  * rtc_read8() - Read an 8-bit register
 177  *
 178  * @reg:        Register to read
 179  * @return value read
 180  */
 181 int rtc_read8(int reg);
 182
 183 /**
 184  * rtc_write8() - Write an 8-bit register
 185  *
 186  * @reg:        Register to write
 187  * @value:      Value to write
 188  */
 189 void rtc_write8(int reg, uchar val);
 190
 191 /**
 192  * rtc_read32() - Read a 32-bit value from the RTC
 193  *
 194  * @reg:        Offset to start reading from
 195  * @return value read
 196  */
 197 u32 rtc_read32(int reg);
 198
 199 /**
 200  * rtc_write32() - Write a 32-bit value to the RTC
 201  *
 202  * @reg:        Register to start writing to
 203  * @value:      Value to write
 204  */
 205 void rtc_write32(int reg, u32 value);
 206
 207 /**
 208  * rtc_init() - Set up the real time clock ready for use
 209  */
 210 void rtc_init(void);
 211 #endif
 212
 213 /**
 214  * rtc_calc_weekday() - Work out the weekday from a time
 215  *
 216  * This only works for the Gregorian calendar - i.e. after 1752 (in the UK).
 217  * It sets time->tm_wdaay to the correct day of the week.
 218  *
 219  * @time:       Time to inspect. tm_wday is updated
 220  * @return 0 if OK, -EINVAL if the weekday could not be determined
 221  */
 222 int rtc_calc_weekday(struct rtc_time *time);
 223
 224 /**
 225  * rtc_to_tm() - Convert a time_t value into a broken-out time
 226  *
 227  * The following fields are set up by this function:
 228  *      tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year, tm_wday
 229  *
 230  * Note that tm_yday and tm_isdst are set to 0.
 231  *
 232  * @time_t:     Number of seconds since 1970-01-01 00:00:00
 233  * @time:       Place to put the broken-out time
 234  * @return 0 if OK, -EINVAL if the weekday could not be determined
 235  */
 236 int rtc_to_tm(int time_t, struct rtc_time *time);
 237
 238 /**
 239  * rtc_mktime() - Convert a broken-out time into a time_t value
 240  *
 241  * The following fields need to be valid for this function to work:
 242  *      tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year
 243  *
 244  * Note that tm_wday and tm_yday are ignored.
 245  *
 246  * @time:       Broken-out time to convert
 247  * @return corresponding time_t value, seconds since 1970-01-01 00:00:00
 248  */
 249 unsigned long rtc_mktime(const struct rtc_time *time);
 250
 251 #endif  /* _RTC_H_ */