Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
rtc_api.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2013 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 /** \addtogroup hal */
19 /** @{*/
20 
21 #ifndef MBED_RTC_API_H
22 #define MBED_RTC_API_H
23 
24 #include "device.h"
25 
26 #include <time.h>
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
32 /**
33  * \defgroup hal_rtc RTC hal
34  *
35  * The RTC hal provides a low level interface to the Real Time Counter (RTC) of a
36  * target.
37  *
38  * # Defined behaviour
39  * * The function ::rtc_init is safe to call repeatedly - Verified by test ::rtc_init_test.
40  * * RTC accuracy is at least 10% - Verified by test ::rtc_accuracy_test.
41  * * Init/free doesn't stop RTC from counting - Verified by test ::rtc_persist_test.
42  * * Software reset doesn't stop RTC from counting - Verified by test ::rtc_reset_test.
43  * * Sleep modes don't stop RTC from counting - Verified by test ::rtc_sleep_test.
44  * * Shutdown mode doesn't stop RTC from counting - Not verified.
45  * * The functions ::rtc_write/::rtc_read provides availability to set/get RTC time
46  * - Verified by test ::rtc_write_read_test.
47  * * The functions ::rtc_isenabled returns 1 if the RTC is counting and the time has been set,
48  * 0 otherwise - Verified by test ::rtc_enabled_test.
49  *
50  * # Undefined behaviour
51  * * Calling any function other than ::rtc_init before the initialisation of the RTC
52  *
53  * # Potential bugs
54  * * Incorrect overflow handling - Verified by ::rtc_range_test
55  * * Glitches due to ripple counter - Verified by ::rtc_glitch_test
56  *
57  * @see hal_rtc_tests
58  *
59  * @{
60  */
61 
62 /**
63  * \defgroup hal_rtc_tests RTC hal tests
64  * The RTC test validate proper implementation of the RTC hal.
65  *
66  * To run the RTC hal tests use the command:
67  *
68  * mbed test -t <toolchain> -m <target> -n tests-mbed_hal-rtc*
69  */
70 
71 
72 /** Initialize the RTC peripheral
73  *
74  * Powerup the RTC in perpetration for access. This function must be called
75  * before any other RTC functions ares called. This does not change the state
76  * of the RTC. It just enables access to it.
77  *
78  * @note This function is safe to call repeatedly - Tested by ::rtc_init_test
79  *
80  * Example Implementation Pseudo Code:
81  * @code
82  * void rtc_init()
83  * {
84  * // Enable clock gate so processor can read RTC registers
85  * POWER_CTRL |= POWER_CTRL_RTC_Msk;
86  *
87  * // See if the RTC is already setup
88  * if (!(RTC_STATUS & RTC_STATUS_COUNTING_Msk)) {
89  *
90  * // Setup the RTC clock source
91  * RTC_CTRL |= RTC_CTRL_CLK32_Msk;
92  * }
93  * }
94  * @endcode
95  */
96 void rtc_init(void);
97 
98 /** Deinitialize RTC
99  *
100  * Powerdown the RTC in preparation for sleep, powerdown or reset. That should only
101  * affect the CPU domain and not the time keeping logic.
102  * After this function is called no other RTC functions should be called
103  * except for ::rtc_init.
104  *
105  * @note This function does not stop the RTC from counting - Tested by ::rtc_persist_test
106  *
107  * Example Implementation Pseudo Code:
108  * @code
109  * void rtc_free()
110  * {
111  * // Disable clock gate since processor no longer needs to read RTC registers
112  * POWER_CTRL &= ~POWER_CTRL_RTC_Msk;
113  * }
114  * @endcode
115  */
116 void rtc_free(void);
117 
118 /** Check if the RTC has the time set and is counting
119  *
120  * @retval 0 The time reported by the RTC is not valid
121  * @retval 1 The time has been set the RTC is counting
122  *
123  * Example Implementation Pseudo Code:
124  * @code
125  * int rtc_isenabled()
126  * {
127  * if (RTC_STATUS & RTC_STATUS_COUNTING_Msk) {
128  * return 1;
129  * } else {
130  * return 0;
131  * }
132  * }
133  * @endcode
134  */
135 int rtc_isenabled(void);
136 
137 /** Get the current time from the RTC peripheral
138  *
139  * @return The current time in seconds
140  *
141  * @note Some RTCs are not synchronized with the main clock. If
142  * this is the case with your RTC then you must read the RTC time
143  * in a loop to prevent reading the wrong time due to a glitch.
144  * The test ::rtc_glitch_test is intended to catch this bug.
145  *
146  * Example implementation for an unsynchronized ripple counter:
147  * @code
148  * time_t rtc_read()
149  * {
150  * uint32_t val;
151  * uint32_t last_val;
152  *
153  * // Loop until the same value is read twice
154  * val = RTC_SECONDS;
155  * do {
156  * last_val = val;
157  * val = RTC_SECONDS;
158  * } while (last_val != val);
159  *
160  * return (time_t)val;
161  * }
162  * @endcode
163  */
164 time_t rtc_read(void);
165 
166 /** Write the current time in seconds to the RTC peripheral
167  *
168  * @param t The current time to be set in seconds.
169  *
170  * Example Implementation Pseudo Code:
171  * @code
172  * void rtc_write(time_t t)
173  * {
174  * RTC_SECONDS = t;
175  * }
176  * @endcode
177  */
178 void rtc_write(time_t t);
179 
180 /**@}*/
181 
182 #ifdef __cplusplus
183 }
184 #endif
185 
186 #endif
187 
188 /** @}*/
rtc_isenabled
int rtc_isenabled(void)
Check if the RTC has the time set and is counting.
rtc_init
void rtc_init(void)
Initialize the RTC peripheral.
rtc_write
void rtc_write(time_t t)
Write the current time in seconds to the RTC peripheral.
rtc_read
time_t rtc_read(void)
Get the current time from the RTC peripheral.
rtc_free
void rtc_free(void)
Deinitialize RTC.
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.