Mistake on this page?
Report an issue in GitHub or email us
mbed_mktime.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2017-2019 ARM Limited
3  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
18 #ifndef MBED_MKTIME_H
19 #define MBED_MKTIME_H
20 
21 #include <time.h>
22 #include <stdbool.h>
23 #include <stdint.h>
24 
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28 
29 /** \addtogroup platform-public-api */
30 /** @{*/
31 
32 /**
33  * \defgroup platform_mktime mktime functions
34  * @{
35  */
36 
37 /* Time range across the whole 32-bit range should be supported which means that years in range 1970 - 2106 can be
38  * encoded. We have two types of RTC devices:
39  * a) RTCs which handles all leap years in the mentioned year range correctly. Leap year is determined by checking if
40  * the year counter value is divisible by 400, 100, and 4. No problem here.
41  * b) RTCs which handles leap years correctly up to 2100. The RTC does a simple bit comparison to see if the two
42  * lowest order bits of the year counter are zero. In this case 2100 year will be considered
43  * 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
44  * 29.02.2100 (invalid). So after 28.02.2100 the day counter will be off by a day.
45  */
46 typedef enum {
47  RTC_FULL_LEAP_YEAR_SUPPORT,
48  RTC_4_YEAR_LEAP_YEAR_SUPPORT
49 } rtc_leap_year_support_t;
50 
51 /** Compute if a year is a leap year or not.
52  *
53  * @param year The year to test it shall be in the range [70:206]. Year 0 is
54  * translated into year 1900 CE.
55  * @param leap_year_support use RTC_FULL_LEAP_YEAR_SUPPORT if RTC device is able
56  * to correctly detect all leap years in range [70:206] otherwise use RTC_4_YEAR_LEAP_YEAR_SUPPORT.
57  *
58  * @return true if the year in input is a leap year and false otherwise.
59  *
60  * @note For use by the HAL only
61  * @note Year 2100 is treated differently for devices with full leap year support and devices with
62  * partial leap year support. Devices with partial leap year support treats 2100 as a leap year.
63  */
64 bool _rtc_is_leap_year(int year, rtc_leap_year_support_t leap_year_support);
65 
66 /* Convert a calendar time into time since UNIX epoch as a time_t.
67  *
68  * This function is a thread safe (partial) replacement for mktime. It is
69  * tailored around RTC peripherals needs and is not by any mean a complete
70  * replacement of mktime.
71  *
72  * @param time The calendar time to convert into a time_t since epoch.
73  * The fields from tm used for the computation are:
74  * - tm_sec
75  * - tm_min
76  * - tm_hour
77  * - tm_mday
78  * - tm_mon
79  * - tm_year
80  * Other fields are ignored and won't be renormalized by a call to this function.
81  * A valid calendar time is comprised between:
82  * the 1st of January 1970 at 00:00:00 to the 7th of February 2106 at 06:28:15.
83  * @param leap_year_support use RTC_FULL_LEAP_YEAR_SUPPORT if RTC device is able
84  * to correctly detect all leap years in range [70:206] otherwise use RTC_4_YEAR_LEAP_YEAR_SUPPORT.
85  * @param seconds holder for the result - calendar time as seconds since UNIX epoch.
86  *
87  * @return true on success, false if conversion error occurred.
88  *
89  * @note Leap seconds are not supported.
90  * @note Values in output range from 0 to UINT_MAX.
91  * @note Full and partial leap years support.
92  * @note For use by the HAL only
93  */
94 bool _rtc_maketime(const struct tm *time, time_t *seconds, rtc_leap_year_support_t leap_year_support);
95 
96 /* Convert a given time in seconds since epoch into calendar time.
97  *
98  * This function is a thread safe (partial) replacement for localtime. It is
99  * tailored around RTC peripherals specification and is not by any means a
100  * complete of localtime.
101  *
102  * @param timestamp The time (in seconds) to convert into calendar time. Valid
103  * input are in the range [0 : UINT32_MAX].
104  * @param calendar_time Pointer to the object which will contain the result of
105  * the conversion. The tm fields filled by this function are:
106  * - tm_sec
107  * - tm_min
108  * - tm_hour
109  * - tm_mday
110  * - tm_mon
111  * - tm_year
112  * - tm_wday
113  * - tm_yday
114  * The object remains untouched if the time in input is invalid.
115  * @param leap_year_support use RTC_FULL_LEAP_YEAR_SUPPORT if RTC device is able
116  * to correctly detect all leap years in range [70:206] otherwise use RTC_4_YEAR_LEAP_YEAR_SUPPORT.
117  * @return true if the conversion was successful, false otherwise.
118  *
119  * @note For use by the HAL only.
120  * @note Full and partial leap years support.
121  */
122 bool _rtc_localtime(time_t timestamp, struct tm *time_info, rtc_leap_year_support_t leap_year_support);
123 
124 /** @}*/
125 
126 #ifdef __cplusplus
127 }
128 #endif
129 
130 #endif /* MBED_MKTIME_H */
131 
132 /** @}*/
bool _rtc_is_leap_year(int year, rtc_leap_year_support_t leap_year_support)
Compute if a year is a leap year or not.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.