Knight KE / Mbed OS Game_Master

游戏王对战板，目前code还是空的

mbed-os/hal/rtc_api.h@0:9b3d4731edbb, 2018-06-21 (annotated)

Committer:
WFKnight
Date:
Thu Jun 21 13:51:43 2018 +0000
Revision:
0:9b3d4731edbb
UART, RTOS, LED

Who changed what in which revision?

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