Kev Mann / mbed-dev-OS5_10_4

RTC auf true

hal/rtc_api.h@2:7aab896b1a3b, 2019-03-13 (annotated)

Committer:
kevman
Date:
Wed Mar 13 11:03:24 2019 +0000
Revision:
2:7aab896b1a3b
Parent:
0:38ceb79fef03 
2019-03-13

Who changed what in which revision?

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