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