Diff: platform/mbed_mktime.h

Revision:

184:08ed48f1de7f

Parent:

178:79309dc6340a

Child:

187:0387e8f68319

--- a/platform/mbed_mktime.h	Tue Mar 20 17:01:51 2018 +0000
+++ b/platform/mbed_mktime.h	Thu Apr 19 17:12:19 2018 +0100
@@ -33,14 +33,34 @@
  * @{
  */
 
+/* Time range across the whole 32-bit range should be supported which means that years in range 1970 - 2106 can be
+ * encoded. We have two types of RTC devices:
+ * a) RTCs which handles all leap years in the mentioned year range correctly. Leap year is determined by checking if
+ *    the year counter value is divisible by 400, 100, and 4. No problem here.
+ * b) RTCs which handles leap years correctly up to 2100. The RTC does a simple bit comparison to see if the two
+ *    lowest order bits of the year counter are zero. In this case 2100 year will be considered
+ *    incorrectly as a leap year, so the last valid point in time will be 28.02.2100 23:59:59 and next day will be
+ *    29.02.2100 (invalid). So after 28.02.2100 the day counter will be off by a day.
+ */
+typedef enum {
+    RTC_FULL_LEAP_YEAR_SUPPORT,
+    RTC_4_YEAR_LEAP_YEAR_SUPPORT
+} rtc_leap_year_support_t;
+
 /** Compute if a year is a leap year or not.
  *
- * @param year The year to test it shall be in the range [70:138]. Year 0 is
+ * @param year The year to test it shall be in the range [70:206]. Year 0 is
  * translated into year 1900 CE.
+ * @param leap_year_support use RTC_FULL_LEAP_YEAR_SUPPORT if RTC device is able
+ * to correctly detect all leap years in range [70:206] otherwise use RTC_4_YEAR_LEAP_YEAR_SUPPORT.
+ *
  * @return true if the year in input is a leap year and false otherwise.
- * @note - For use by the HAL only
+ *
+ * @note For use by the HAL only
+ * @note Year 2100 is treated differently for devices with full leap year support and devices with
+ * partial leap year support. Devices with partial leap year support treats 2100 as a leap year.
  */
-bool _rtc_is_leap_year(int year);
+bool _rtc_is_leap_year(int year, rtc_leap_year_support_t leap_year_support);
 
 /* Convert a calendar time into time since UNIX epoch as a time_t.
  *
@@ -48,7 +68,7 @@
  * tailored around RTC peripherals needs and is not by any mean a complete
  * replacement of mktime.
  *
- * @param calendar_time The calendar time to convert into a time_t since epoch.
+ * @param time The calendar time to convert into a time_t since epoch.
  * The fields from tm used for the computation are:
  *   - tm_sec
  *   - tm_min
@@ -57,17 +77,20 @@
  *   - tm_mon
  *   - tm_year
  * Other fields are ignored and won't be renormalized by a call to this function.
- * A valid calendar time is comprised between the 1st january of 1970 at
- * 00:00:00 and the 19th of january 2038 at 03:14:07.
+ * A valid calendar time is comprised between:
+ * the 1st of January 1970 at 00:00:00 to the 7th of February 2106 at 06:28:15.
+ * @param leap_year_support use RTC_FULL_LEAP_YEAR_SUPPORT if RTC device is able
+ * to correctly detect all leap years in range [70:206] otherwise use RTC_4_YEAR_LEAP_YEAR_SUPPORT.
+ * @param seconds holder for the result - calendar time as seconds since UNIX epoch.
  *
- * @return The calendar time as seconds since UNIX epoch if the input is in the
- * valid range. Otherwise ((time_t) -1).
+ * @return true on success, false if conversion error occurred.
  *
  * @note Leap seconds are not supported.
- * @note Values in output range from 0 to INT_MAX.
- * @note - For use by the HAL only
+ * @note Values in output range from 0 to UINT_MAX.
+ * @note Full and partial leap years support.
+ * @note For use by the HAL only
  */
-time_t _rtc_mktime(const struct tm* calendar_time);
+bool _rtc_maketime(const struct tm* time, time_t * seconds, rtc_leap_year_support_t leap_year_support);
 
 /* Convert a given time in seconds since epoch into calendar time.
  *
@@ -76,7 +99,7 @@
  * complete of localtime.
  *
  * @param timestamp The time (in seconds) to convert into calendar time. Valid
- * input are in the range [0 : INT32_MAX].
+ * input are in the range [0 : UINT32_MAX].
  * @param calendar_time Pointer to the object which will contain the result of
  * the conversion. The tm fields filled by this function are:
  *   - tm_sec
@@ -88,11 +111,14 @@
  *   - tm_wday
  *   - tm_yday
  * The object remains untouched if the time in input is invalid.
+ * @param leap_year_support use RTC_FULL_LEAP_YEAR_SUPPORT if RTC device is able
+ * to correctly detect all leap years in range [70:206] otherwise use RTC_4_YEAR_LEAP_YEAR_SUPPORT.
  * @return true if the conversion was successful, false otherwise.
  *
- * @note - For use by the HAL only
+ * @note For use by the HAL only.
+ * @note Full and partial leap years support.
  */
-bool _rtc_localtime(time_t timestamp, struct tm* calendar_time);
+bool _rtc_localtime(time_t timestamp, struct tm* time_info, rtc_leap_year_support_t leap_year_support);
 
 /** @}*/