mbed library sources. Supersedes mbed-src.
Dependents: Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more
rtc_api.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2006-2013 ARM Limited 00003 * SPDX-License-Identifier: Apache-2.0 00004 * 00005 * Licensed under the Apache License, Version 2.0 (the "License"); 00006 * you may not use this file except in compliance with the License. 00007 * You may obtain a copy of the License at 00008 * 00009 * http://www.apache.org/licenses/LICENSE-2.0 00010 * 00011 * Unless required by applicable law or agreed to in writing, software 00012 * distributed under the License is distributed on an "AS IS" BASIS, 00013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00014 * See the License for the specific language governing permissions and 00015 * limitations under the License. 00016 */ 00017 00018 /** \addtogroup hal */ 00019 /** @{*/ 00020 00021 #ifndef MBED_RTC_API_H 00022 #define MBED_RTC_API_H 00023 00024 #include "device.h" 00025 00026 #include <time.h> 00027 00028 #ifdef __cplusplus 00029 extern "C" { 00030 #endif 00031 00032 /** 00033 * \defgroup hal_rtc RTC hal 00034 * 00035 * The RTC hal provides a low level interface to the Real Time Counter (RTC) of a 00036 * target. 00037 * 00038 * # Defined behaviour 00039 * * The function ::rtc_init is safe to call repeatedly - Verified by test ::rtc_init_test. 00040 * * RTC accuracy is at least 10% - Verified by test ::rtc_accuracy_test. 00041 * * Init/free doesn't stop RTC from counting - Verified by test ::rtc_persist_test. 00042 * * Software reset doesn't stop RTC from counting - Verified by test ::rtc_reset_test. 00043 * * Sleep modes don't stop RTC from counting - Verified by test ::rtc_sleep_test. 00044 * * Shutdown mode doesn't stop RTC from counting - Not verified. 00045 * * The functions ::rtc_write/::rtc_read provides availability to set/get RTC time 00046 * - Verified by test ::rtc_write_read_test. 00047 * * The functions ::rtc_isenabled returns 1 if the RTC is counting and the time has been set, 00048 * 0 otherwise - Verified by test ::rtc_enabled_test. 00049 * 00050 * # Undefined behaviour 00051 * * Calling any function other than ::rtc_init before the initialisation of the RTC 00052 * 00053 * # Potential bugs 00054 * * Incorrect overflow handling - Verified by ::rtc_range_test 00055 * * Glitches due to ripple counter - Verified by ::rtc_glitch_test 00056 * 00057 * @see hal_rtc_tests 00058 * 00059 * @{ 00060 */ 00061 00062 /** 00063 * \defgroup hal_rtc_tests RTC hal tests 00064 * The RTC test validate proper implementation of the RTC hal. 00065 * 00066 * To run the RTC hal tests use the command: 00067 * 00068 * mbed test -t <toolchain> -m <target> -n tests-mbed_hal-rtc* 00069 */ 00070 00071 00072 /** Initialize the RTC peripheral 00073 * 00074 * Powerup the RTC in perpetration for access. This function must be called 00075 * before any other RTC functions ares called. This does not change the state 00076 * of the RTC. It just enables access to it. 00077 * 00078 * @note This function is safe to call repeatedly - Tested by ::rtc_init_test 00079 * 00080 * Example Implementation Pseudo Code: 00081 * @code 00082 * void rtc_init() 00083 * { 00084 * // Enable clock gate so processor can read RTC registers 00085 * POWER_CTRL |= POWER_CTRL_RTC_Msk; 00086 * 00087 * // See if the RTC is already setup 00088 * if (!(RTC_STATUS & RTC_STATUS_COUNTING_Msk)) { 00089 * 00090 * // Setup the RTC clock source 00091 * RTC_CTRL |= RTC_CTRL_CLK32_Msk; 00092 * } 00093 * } 00094 * @endcode 00095 */ 00096 void rtc_init(void); 00097 00098 /** Deinitialize RTC 00099 * 00100 * Powerdown the RTC in preparation for sleep, powerdown or reset. That should only 00101 * affect the CPU domain and not the time keeping logic. 00102 * After this function is called no other RTC functions should be called 00103 * except for ::rtc_init. 00104 * 00105 * @note This function does not stop the RTC from counting - Tested by ::rtc_persist_test 00106 * 00107 * Example Implementation Pseudo Code: 00108 * @code 00109 * void rtc_free() 00110 * { 00111 * // Disable clock gate since processor no longer needs to read RTC registers 00112 * POWER_CTRL &= ~POWER_CTRL_RTC_Msk; 00113 * } 00114 * @endcode 00115 */ 00116 void rtc_free(void); 00117 00118 /** Check if the RTC has the time set and is counting 00119 * 00120 * @retval 0 The time reported by the RTC is not valid 00121 * @retval 1 The time has been set the RTC is counting 00122 * 00123 * Example Implementation Pseudo Code: 00124 * @code 00125 * int rtc_isenabled() 00126 * { 00127 * if (RTC_STATUS & RTC_STATUS_COUNTING_Msk) { 00128 * return 1; 00129 * } else { 00130 * return 0; 00131 * } 00132 * } 00133 * @endcode 00134 */ 00135 int rtc_isenabled(void); 00136 00137 /** Get the current time from the RTC peripheral 00138 * 00139 * @return The current time in seconds 00140 * 00141 * @note Some RTCs are not synchronized with the main clock. If 00142 * this is the case with your RTC then you must read the RTC time 00143 * in a loop to prevent reading the wrong time due to a glitch. 00144 * The test ::rtc_glitch_test is intended to catch this bug. 00145 * 00146 * Example implementation for an unsynchronized ripple counter: 00147 * @code 00148 * time_t rtc_read() 00149 * { 00150 * uint32_t val; 00151 * uint32_t last_val; 00152 * 00153 * // Loop until the same value is read twice 00154 * val = RTC_SECONDS; 00155 * do { 00156 * last_val = val; 00157 * val = RTC_SECONDS; 00158 * } while (last_val != val); 00159 * 00160 * return (time_t)val; 00161 * } 00162 * @endcode 00163 */ 00164 time_t rtc_read(void); 00165 00166 /** Write the current time in seconds to the RTC peripheral 00167 * 00168 * @param t The current time to be set in seconds. 00169 * 00170 * Example Implementation Pseudo Code: 00171 * @code 00172 * void rtc_write(time_t t) 00173 * { 00174 * RTC_SECONDS = t; 00175 * } 00176 * @endcode 00177 */ 00178 void rtc_write(time_t t); 00179 00180 /**@}*/ 00181 00182 #ifdef __cplusplus 00183 } 00184 #endif 00185 00186 #endif 00187 00188 /** @}*/
Generated on Tue Jul 12 2022 20:41:15 by 1.7.2