mbed library sources. Supersedes mbed-src.

Dependents:   Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers rtc_api.h Source File

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 /** @}*/