rtc_api.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 /** \addtogroup hal */
00018 /** @{*/
00019 
00020 #ifndef MBED_RTC_API_H
00021 #define MBED_RTC_API_H
00022 
00023 #include "device.h"
00024 
00025 #include <time.h>
00026 
00027 #ifdef __cplusplus
00028 extern "C" {
00029 #endif
00030 
00031 /**
00032  * \defgroup hal_rtc RTC hal
00033  *
00034  * The RTC hal provides a low level interface to the Real Time Counter (RTC) of a
00035  * target.
00036  *
00037  * # Defined behaviour
00038  * * The function ::rtc_init is safe to call repeatedly - Verified by test ::rtc_init_test.
00039  * * RTC accuracy is at least 10% - Verified by test ::rtc_accuracy_test.
00040  * * Init/free doesn't stop RTC from counting - Verified by test ::rtc_persist_test.
00041  * * Software reset doesn't stop RTC from counting - Verified by test ::rtc_reset_test.
00042  * * Sleep modes don't stop RTC from counting - Verified by test ::rtc_sleep_test.
00043  * * Shutdown mode doesn't stop RTC from counting - Not verified.
00044  * * The functions ::rtc_write/::rtc_read provides availability to set/get RTC time
00045  * - Verified by test ::rtc_write_read_test.
00046  * * The functions ::rtc_isenabled returns 1 if the RTC is counting and the time has been set,
00047  * 0 otherwise - Verified by test ::rtc_enabled_test.
00048  *
00049  * # Undefined behaviour
00050  * * Calling any function other than ::rtc_init before the initialisation of the RTC
00051  *
00052  * # Potential bugs
00053  * * Incorrect overflow handling - Verified by ::rtc_range_test
00054  * * Glitches due to ripple counter - Verified by ::rtc_glitch_test
00055  *
00056  * @see hal_rtc_tests
00057  *
00058  * @{
00059  */
00060 
00061 /**
00062  * \defgroup hal_rtc_tests RTC hal tests
00063  * The RTC test validate proper implementation of the RTC hal.
00064  *
00065  * To run the RTC hal tests use the command:
00066  *
00067  *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal-rtc*
00068  */
00069 
00070 
00071 /** Initialize the RTC peripheral
00072  *
00073  * Powerup the RTC in perpetration for access. This function must be called
00074  * before any other RTC functions ares called. This does not change the state
00075  * of the RTC. It just enables access to it.
00076  *
00077  * @note This function is safe to call repeatedly - Tested by ::rtc_init_test
00078  *
00079  * Example Implementation Pseudo Code:
00080  * @code
00081  * void rtc_init()
00082  * {
00083  *     // Enable clock gate so processor can read RTC registers
00084  *     POWER_CTRL |= POWER_CTRL_RTC_Msk;
00085  *
00086  *     // See if the RTC is already setup
00087  *     if (!(RTC_STATUS & RTC_STATUS_COUNTING_Msk)) {
00088  *
00089  *         // Setup the RTC clock source
00090  *         RTC_CTRL |= RTC_CTRL_CLK32_Msk;
00091  *     }
00092  * }
00093  * @endcode
00094  */
00095 void rtc_init(void);
00096 
00097 /** Deinitialize RTC
00098  *
00099  * Powerdown the RTC in preparation for sleep, powerdown or reset. That should only
00100  * affect the CPU domain and not the time keeping logic.
00101  * After this function is called no other RTC functions should be called
00102  * except for ::rtc_init.
00103  *
00104  * @note This function does not stop the RTC from counting - Tested by ::rtc_persist_test
00105  *
00106  * Example Implementation Pseudo Code:
00107  * @code
00108  * void rtc_free()
00109  * {
00110  *     // Disable clock gate since processor no longer needs to read RTC registers
00111  *     POWER_CTRL &= ~POWER_CTRL_RTC_Msk;
00112  * }
00113  * @endcode
00114  */
00115 void rtc_free(void);
00116 
00117 /** Check if the RTC has the time set and is counting
00118  *
00119  * @retval 0 The time reported by the RTC is not valid
00120  * @retval 1 The time has been set the RTC is counting
00121  *
00122  * Example Implementation Pseudo Code:
00123  * @code
00124  * int rtc_isenabled()
00125  * {
00126  *     if (RTC_STATUS & RTC_STATUS_COUNTING_Msk) {
00127  *         return 1;
00128  *     } else {
00129  *         return 0;
00130  *     }
00131  * }
00132  * @endcode
00133  */
00134 int rtc_isenabled(void);
00135 
00136 /** Get the current time from the RTC peripheral
00137  *
00138  * @return The current time in seconds
00139  *
00140  * @note Some RTCs are not synchronized with the main clock. If
00141  * this is the case with your RTC then you must read the RTC time
00142  * in a loop to prevent reading the wrong time due to a glitch.
00143  * The test ::rtc_glitch_test is intended to catch this bug.
00144  *
00145  * Example implementation for an unsynchronized ripple counter:
00146  * @code
00147  * time_t rtc_read()
00148  * {
00149  *     uint32_t val;
00150  *     uint32_t last_val;
00151  *
00152  *     // Loop until the same value is read twice
00153  *     val = RTC_SECONDS;
00154  *     do {
00155  *         last_val = val;
00156  *         val = RTC_SECONDS;
00157  *     } while (last_val != val);
00158  *
00159  *     return (time_t)val;
00160  * }
00161  * @endcode
00162  */
00163 time_t rtc_read(void);
00164 
00165 /** Write the current time in seconds to the RTC peripheral
00166  *
00167  * @param t The current time to be set in seconds.
00168  *
00169  * Example Implementation Pseudo Code:
00170  * @code
00171  * void rtc_write(time_t t)
00172  * {
00173  *     RTC_SECONDS = t;
00174  * }
00175  * @endcode
00176  */
00177 void rtc_write(time_t t);
00178 
00179 /**@}*/
00180 
00181 #ifdef __cplusplus
00182 }
00183 #endif
00184 
00185 #endif
00186 
00187 /** @}*/