/** @file bkp.h
 * Module handling the Backup (BKP) domain functionalities.
 *
 */

#ifndef _BKP_H_
#define _BKP_H_

//--includes--------------------------------------------------------------------

#include "stdint.h"


//--type definitions------------------------------------------------------------

/**
 * Available clock sources for the RTC. See bkp_configure_rtc() for more
 * information
 */
enum BkpRtcClockSrc {
	BKP_RTC_CLOCK_SRC_LSE  = 0x0,
	BKP_RTC_CLOCK_SRC_LSI  = 0x1,
	BKP_RTC_CLOCK_SRC_HSE  = 0x2,
};

/**
 * Available IRQ sources. This enum is passed to the RTC callback to allow
 * differentiating IRQ sources
 */
enum BkpRtcIrq {
	BKP_RTC_IRQ_NONE     = 0,
	BKP_RTC_IRQ_SECOND   = 0x1 << 0,
	BKP_RTC_IRQ_ALARM    = 0x1 << 1,
	BKP_RTC_IRQ_OVERFLOW = 0x1 << 2,
};

/**
 * Prototype of the IRQ callbacks that the applicative code can provide
 */
typedef void (*BkpRtcCallback)(enum BkpRtcIrq src);


//--functions-------------------------------------------------------------------

/**
 * Configures the RTC, starting it immediately. Configuration is saved between
 * boots as long as VBAT is present
 *
 * The RTC can run on a period of up to 1s and using one of 3 clocks. Clock
 * choice is a question of compromise :
 * - LSE consumes the less energy and continues to run in standby mode, but
 * requires an extra oscillator circuit
 * - LSI consumes little but isn't very accurate and requires extra calibration
 * (see bkp_callibrate_lsi)
 * - HSE consumes the most.
 * WARNING : once configured, the clock source can only changed by reseting the
 * whole backup domain via bkp_reset()
 * Clocks must be enabled prior to calling this function
 *
 * Mulitple IRQs can be enabled and redirected to single callback. The alarm
 * IRQ, triggered at the specified tick value can be rerouted to an exti line
 * for wakeup from stanby, in wich case it doesn't need to be enabled here.
 */
void bkp_configure_rtc(uint32_t period_ms, enum BkpRtcClockSrc clock_src,
		enum BkpRtcIrq irq_mask, uint32_t alarm_tick, BkpRtcCallback callback);

/**
 * Returns the current counter value of the RTC
 */
uint32_t bkp_read_rtc(void);

/**
 * Resets the entire backup domain, composed of everything configured through
 * this module
 */
void bkp_reset(void);

//unimplemented functions
void bkp_configure_tamper();
void bkp_calibrate_lsi(void);
void bkp_configure_lse(bool enable);


#endif //_BKP_H_