Thor Hall / mbed-dev_mbed_lib_v125

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of mbed-dev by mbed official

hal/rtc_api.h@186:707f6e361f3e, 2018-06-22 (annotated)

Committer:
Anna Bridge
Date:
Fri Jun 22 16:45:37 2018 +0100
Revision:
186:707f6e361f3e
Parent:
149:156823d33999
Child:
187:92cbb9eec47b
mbed-dev library. Release version 162

Who changed what in which revision?

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