adjust root folder
This commit is contained in:
Steve Karg
@@ -0,0 +1,324 @@
|
||||
/**
|
||||
* \file
|
||||
*
|
||||
* \brief AVR XMEGA 32-bit Real Time Counter driver definitions
|
||||
*
|
||||
* Copyright (c) 2010-2012 Atmel Corporation. All rights reserved.
|
||||
*
|
||||
* \asf_license_start
|
||||
*
|
||||
* \page License
|
||||
*
|
||||
* Redistribution and use in source and binary forms, with or without
|
||||
* modification, are permitted provided that the following conditions are met:
|
||||
*
|
||||
* 1. Redistributions of source code must retain the above copyright notice,
|
||||
* this list of conditions and the following disclaimer.
|
||||
*
|
||||
* 2. Redistributions in binary form must reproduce the above copyright notice,
|
||||
* this list of conditions and the following disclaimer in the documentation
|
||||
* and/or other materials provided with the distribution.
|
||||
*
|
||||
* 3. The name of Atmel may not be used to endorse or promote products derived
|
||||
* from this software without specific prior written permission.
|
||||
*
|
||||
* 4. This software may only be redistributed and used in connection with an
|
||||
* Atmel microcontroller product.
|
||||
*
|
||||
* THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
|
||||
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
||||
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
|
||||
* EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
|
||||
* ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
||||
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
|
||||
* ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
||||
* POSSIBILITY OF SUCH DAMAGE.
|
||||
*
|
||||
* \asf_license_stop
|
||||
*
|
||||
*/
|
||||
#ifndef DRIVERS_RTC32_RTC32_H
|
||||
#define DRIVERS_RTC32_RTC32_H
|
||||
|
||||
#include <compiler.h>
|
||||
#include <conf_rtc32.h>
|
||||
|
||||
/**
|
||||
* \defgroup rtc32_group 32-bit Real Time Counter (RTC32)
|
||||
*
|
||||
* See \ref xmega_rtc32_quickstart.
|
||||
*
|
||||
* This is a driver implementation for the XMEGA RTC32.
|
||||
*
|
||||
* This driver can be used to keep track of time; setting alarms, with or
|
||||
* without function callbacks; initializing and checking the battery backup
|
||||
* system.
|
||||
*
|
||||
* \section rtc32_min_alarm_time Minimum allowed alarm time
|
||||
*
|
||||
* Due to the RTC32 clock synchronization, there is a minimum alarm time that
|
||||
* will generate a interrupt. This minimum time is 2 RTC32 clock cycles.
|
||||
*
|
||||
* Also, if a new RTC32 clock cycle is imminent at the time of setting the
|
||||
* alarm, there is a risk that it will be missed even with the value 2. If there
|
||||
* is a risk that this may occur, it is recommended to use a minimum alarm time
|
||||
* of 3.
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* \def CONFIG_RTC32_COMPARE_INT_LEVEL
|
||||
* \brief Configuration symbol for interrupt level to use on alarm
|
||||
*
|
||||
* Define this in \ref conf_rtc32.h as the desired interrupt level, or leave it
|
||||
* undefined to use the default.
|
||||
*/
|
||||
#ifdef __DOXYGEN__
|
||||
# define CONFIG_RTC32_COMPARE_INT_LEVEL
|
||||
#endif
|
||||
|
||||
/**
|
||||
* \def CONFIG_RTC32_CLOCK_1024HZ
|
||||
* \brief Configuration symbol for selecting 1024Hz clock instead of 1Hz
|
||||
*
|
||||
* Define this in \ref conf_rtc32.h if 1024Hz clock is desired. Otherwise, leave
|
||||
* it undefined.
|
||||
*/
|
||||
#ifdef __DOXYGEN__
|
||||
# define CONFIG_RTC32_CLOCK_1024HZ
|
||||
#endif
|
||||
|
||||
//! \brief Battery backup system status codes
|
||||
enum vbat_status_code
|
||||
{
|
||||
/**
|
||||
* \brief Backup system is operating and no errors were detected.
|
||||
*
|
||||
* The backup system is configured and had no issues while main power was
|
||||
* lost. Hence, all data stored in the backup domain is valid.
|
||||
*/
|
||||
VBAT_STATUS_OK,
|
||||
|
||||
/**
|
||||
* \brief No power detected on VBAT.
|
||||
*
|
||||
* No power was detected on the VBAT pin and therefore all data within the
|
||||
* backup system is invalid.
|
||||
*
|
||||
* The voltage on the VBAT pin is only sampled after a POR of the device,
|
||||
* therefore it is not possible to detect any voltage loss on the VBAT pin
|
||||
* during normal operation of the device.
|
||||
*/
|
||||
VBAT_STATUS_NO_POWER,
|
||||
|
||||
/**
|
||||
* \brief The backup system must be initialized.
|
||||
*
|
||||
* A POR was detected on VBAT input, indicating that a supply was connected to
|
||||
* the VBAT pin. Since this is also the first start-up of the device, it is
|
||||
* necessary to initialize the RTC32.
|
||||
*/
|
||||
VBAT_STATUS_INIT,
|
||||
|
||||
/**
|
||||
* \brief A POR was detected on the VBAT input.
|
||||
*
|
||||
* POR detection also works while the VBAT system is powered from main power,
|
||||
* but the detection flag is only latched after a POR of the main system.
|
||||
* A POR can happen when the power is lost and restored again on the VBAT pin
|
||||
* while main power was also not present, or even when main power was present,
|
||||
* but in this case the flag will only be latched after the next POR of the main
|
||||
* system.
|
||||
* If a POR is detected on VBAT, it should always be treated as if the backup
|
||||
* system is in an unknown state, i.e., that all data is invalid.
|
||||
*/
|
||||
VBAT_STATUS_BBPOR,
|
||||
|
||||
/**
|
||||
* \brief A brown-out was detected on the VBAT input.
|
||||
*
|
||||
* The backup system is in an unknown state and therefore the time in the RTC32
|
||||
* is invalid. This can happen when the voltage on VBAT drops below the
|
||||
* brown-out detection level while main power is absent.
|
||||
*/
|
||||
VBAT_STATUS_BBBOD,
|
||||
|
||||
/**
|
||||
* \brief A failure was detected on the oscillator.
|
||||
*
|
||||
* The oscillator stopped for at least TBD period of time and because of that
|
||||
* we can not rely on the RTC time any more.
|
||||
*
|
||||
* \todo Determine minimum period for detection of oscillator outage.
|
||||
*/
|
||||
VBAT_STATUS_XOSCFAIL,
|
||||
|
||||
};
|
||||
|
||||
enum vbat_status_code rtc_vbat_system_check (bool first_time_init);
|
||||
|
||||
/**
|
||||
* \brief Callback definition for alarm callback
|
||||
*
|
||||
* \param time The time of the alarm
|
||||
*/
|
||||
typedef void (*rtc_callback_t) (uint32_t time);
|
||||
|
||||
void rtc_set_callback (rtc_callback_t callback);
|
||||
void rtc_set_time (uint32_t time);
|
||||
uint32_t rtc_get_time (void);
|
||||
void rtc_set_alarm (uint32_t time);
|
||||
bool rtc_alarm_has_triggered (void);
|
||||
|
||||
/**
|
||||
* \brief Set alarm relative to current time
|
||||
*
|
||||
* \param offset Offset to current time. This is minimum value, so the alarm
|
||||
* might happen at up to one time unit later. See also \ref
|
||||
* rtc32_min_alarm_time
|
||||
*/
|
||||
static inline void
|
||||
rtc_set_alarm_relative (uint32_t offset)
|
||||
{
|
||||
Assert (offset >= 2);
|
||||
|
||||
rtc_set_alarm (rtc_get_time () + offset);
|
||||
}
|
||||
|
||||
void rtc_init (void);
|
||||
|
||||
//! @}
|
||||
|
||||
/**
|
||||
* \page xmega_rtc32_quickstart Quick start guide for RTC32 driver
|
||||
*
|
||||
* This is the quick start guide for the \ref rtc32_group "RTC32 driver", with
|
||||
* step-by-step instructions on how to configure and use the drivers in a
|
||||
* selection of use cases.
|
||||
*
|
||||
* The use cases contain several code fragments. The code fragments in the
|
||||
* steps for setup can be copied into a custom initialization function, while
|
||||
* the steps for usage can be copied into, e.g., the main application function.
|
||||
*
|
||||
* \section rtc32_basic_use_case Basic use case
|
||||
*
|
||||
* \section rtc32_basic_use_case_setup Setup steps
|
||||
*
|
||||
* \subsection rtc32_basic_use_case_setup_code Example code
|
||||
* Add to the initialization code:
|
||||
* \code
|
||||
* sysclk_init();
|
||||
* rtc_init();
|
||||
* \endcode
|
||||
*
|
||||
* \subsection rtc32_basic_use_case_setup_flow Workflow
|
||||
* -# Ensure that conf_rtc.h is present for the driver.
|
||||
* - \note This configuration file is used by the driver and
|
||||
* should not be included by the user.
|
||||
* -# Initialize system clock:
|
||||
* - \code sysclk_init(); \endcode
|
||||
* -# Call RTC32 driver's own init function to initialize the 32kHz oscillator
|
||||
* and RTC32:
|
||||
* - \code rtc_init(); \endcode
|
||||
*
|
||||
* \section rtc32_basic_use_case_usage Usage steps
|
||||
*
|
||||
* \subsection rtc32_basic_use_case_usage_code Example code
|
||||
* Add to, e.g., main loop in application C-file:
|
||||
* \code
|
||||
* rtc_get_time();
|
||||
* \endcode
|
||||
*
|
||||
* \subsection rtc32_basic_use_case_usage_flow Workflow
|
||||
* -# Get current time of the RTC32:
|
||||
* - \code rtc_get_time(); \endcode
|
||||
*
|
||||
* \section rtc32_use_cases Advanced use cases
|
||||
* For more advanced use of the RTC32 driver, see the following use cases:
|
||||
* - \subpage rtc32_use_case_1 :
|
||||
*/
|
||||
|
||||
/**
|
||||
* \page rtc32_use_case_1 Use case #1
|
||||
*
|
||||
* This use case shows how to set an alarm for the RTC32.
|
||||
*
|
||||
* \section rtc32_use_case_1_setup Setup steps
|
||||
*
|
||||
* \subsection rtc32_basic_use_case_setup_prereq Prerequisites
|
||||
* For the setup code of this use case to work, the following must
|
||||
* be added to the project:
|
||||
* -# PMIC for interrupt handling.
|
||||
* -# Sleep Manager.
|
||||
* -# A \ref rtc_callback_t "callback" function, called alarm, that
|
||||
* reschedules the alarm must be provided
|
||||
* by the user.
|
||||
* \code
|
||||
* static void alarm(uint32_t time)
|
||||
* {
|
||||
* rtc_set_alarm(2);
|
||||
* }
|
||||
* \endcode
|
||||
* \note Since the next alarm will be rounded up to the next second pass, this
|
||||
* will actually happen in 3 seconds.
|
||||
*
|
||||
* \subsection rtc32_use_case_1_setup_code Example code
|
||||
* Add to application initialization:
|
||||
* \code
|
||||
* pmic_init();
|
||||
* sysclk_init();
|
||||
* sleepmgr_init();
|
||||
* rtc_init();
|
||||
* rtc_set_callback(alarm);
|
||||
* cpu_irq_enable();
|
||||
* \endcode
|
||||
*
|
||||
* \subsection rtc32_use_case_1_setup_flow Workflow
|
||||
* -# Ensure that conf_rtc32.h is present for the driver.
|
||||
* - \note This configuration file is used by the driver and
|
||||
* should not be included by the user.
|
||||
* -# Call the init function of the PMIC driver to enable all interrupt levels:
|
||||
* - \code pmic_init(); \endcode
|
||||
* -# Initialize system clock:
|
||||
* - \code sysclk_init(); \endcode
|
||||
* -# Call the init function of the sleep manager driver to be able to sleep
|
||||
* waiting for alarm:
|
||||
* - \code sleepmgr_init(); \endcode
|
||||
* -# Call RTC32 driver's own init function to initialize the 32kHz oscillator
|
||||
* and RTC32:
|
||||
* - \code rtc_init(); \endcode
|
||||
* -# Set callback function to call on alarm:
|
||||
* - \code rtc_set_callback(alarm); \endcode
|
||||
* - \note The callback function alarm must be defined by the user.
|
||||
* -# Enable interrupts globally:
|
||||
* - \code cpu_irq_enable(); \endcode
|
||||
*
|
||||
* \section rtc32_use_case_1_usage Usage steps
|
||||
*
|
||||
* \subsection rtc32_use_case_1_usage_code Example code
|
||||
* \code
|
||||
* rtc_set_alarm_relative(3);
|
||||
* while (true) {
|
||||
* sleepmgr_enter_sleep();
|
||||
* }
|
||||
* \endcode
|
||||
*
|
||||
* \subsection rtc32_use_case_1_usage_flow Workflow
|
||||
* -# Set the alarm to trigger on next time unit roll over:
|
||||
* - \code rtc_set_alarm_relative(3); \endcode
|
||||
* \note The lowest value which is safe to use is 3. The use of 2 could
|
||||
* happen in a second change, and we would not get an interrupt. A
|
||||
* value of 3 causes the alarm to be set of in 3-4 seconds.
|
||||
* -# Sleep between each triggered alarm:
|
||||
* - \code
|
||||
* while (true) {
|
||||
* sleepmgr_enter_sleep();
|
||||
* }
|
||||
* \endcode
|
||||
*/
|
||||
|
||||
#endif /* DRIVERS_RTC32_RTC32_H */
|
||||
Reference in New Issue
Block a user