stm32:f1:RTC: add documentation
This commit is contained in:
Ken Sarkies
Karl Palsson
parent
40cde559a7
commit
957c5233f4
@ -138,12 +138,18 @@
|
||||
|
||||
/* TODO */
|
||||
|
||||
/* --- Function prototypes --------------------------------------------------*/
|
||||
|
||||
/** RTC Interrupt Flags */
|
||||
typedef enum {
|
||||
RTC_SEC, RTC_ALR, RTC_OW,
|
||||
/** Counter Second Flag */
|
||||
RTC_SEC,
|
||||
/** Alarm Event Flag */
|
||||
RTC_ALR,
|
||||
/** Counter Overflow Flag */
|
||||
RTC_OW,
|
||||
} rtcflag_t;
|
||||
|
||||
/* --- Function prototypes --------------------------------------------------*/
|
||||
|
||||
BEGIN_DECLS
|
||||
|
||||
void rtc_awake_from_off(enum rcc_osc clock_source);
|
||||
|
||||
@ -11,6 +11,38 @@
|
||||
*
|
||||
* @date 4 March 2013
|
||||
*
|
||||
* The Real Time Clock peripheral consists of a set of 16 bit control, status,
|
||||
* prescaler, counter and alarm registers. Before the latter three can be
|
||||
* written the RTC must be placed in configuration mode by a call to
|
||||
* @ref rtc_enter_config_mode(). The functions below handle this implictly.
|
||||
*
|
||||
* The RTC is completely reset by performing a Backup Domain reset. Note
|
||||
* that this can affect unrelated user data contained in the Backup Domain
|
||||
* registers. Other forms of reset will not affect the RTC registers as they
|
||||
* are contained within the backup domain.
|
||||
*
|
||||
* The RTC clock source to be used is selected by calling
|
||||
* @ref rcc_set_rtc_clock_source().
|
||||
*
|
||||
* The LSE clock source normally comes from a 32.768kHz external crystal
|
||||
* This clock is in the backup domain and so continues to run when only the
|
||||
* V_BAT supply is present. A prescaler value of 7FFF will give a 1 second
|
||||
* count quantum.
|
||||
*
|
||||
* The LSI clock source is a low accuracy internal clock of about 40kHz
|
||||
* frequency, and the HSE clock source is the external high speed clock
|
||||
* divided by 128.
|
||||
*
|
||||
* Initial configuration of the RTC consists of:
|
||||
*
|
||||
* @li perform a Backup Domain reset if appropriate;
|
||||
* @li select the clock to be used;
|
||||
* @li set the prescaler, counter and configuration values;
|
||||
* @li enable the RTC.
|
||||
*
|
||||
* @note reading the RTC registers may result in a corrupted value being
|
||||
* returned in certain cases. Refer to the STM32F1xx Reference Manual.
|
||||
*
|
||||
* LGPL License Terms @ref lgpl_license
|
||||
*/
|
||||
|
||||
@ -40,6 +72,21 @@
|
||||
#include <libopencm3/stm32/rtc.h>
|
||||
#include <libopencm3/stm32/pwr.h>
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC Set Operational from the Off state.
|
||||
|
||||
Power up the backup domain clocks, enable write access to the backup domain,
|
||||
select the clock source and enable the RTC.
|
||||
|
||||
After calling this function all counter and control settings must be
|
||||
established.
|
||||
|
||||
@note The Backup Domain is reset by this function and will therefore result in
|
||||
the loss of any unrelated user data stored there.
|
||||
|
||||
@param[in] clock_source ::rcc_osc. RTC clock source. Only HSE/128, LSE and LSI.
|
||||
*/
|
||||
|
||||
void rtc_awake_from_off(enum rcc_osc clock_source)
|
||||
{
|
||||
uint32_t reg32;
|
||||
@ -106,6 +153,13 @@ void rtc_awake_from_off(enum rcc_osc clock_source)
|
||||
while ((reg32 = (RTC_CRL & RTC_CRL_RTOFF)) == 0);
|
||||
}
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC Enter Configuration Mode.
|
||||
|
||||
Prime the RTC for configuration changes by giving access to the prescaler,
|
||||
and counter and alarm registers.
|
||||
*/
|
||||
|
||||
void rtc_enter_config_mode(void)
|
||||
{
|
||||
uint32_t reg32;
|
||||
@ -117,6 +171,12 @@ void rtc_enter_config_mode(void)
|
||||
RTC_CRL |= RTC_CRL_CNF;
|
||||
}
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC Leave Configuration Mode.
|
||||
|
||||
Revert the RTC to operational state.
|
||||
*/
|
||||
|
||||
void rtc_exit_config_mode(void)
|
||||
{
|
||||
uint32_t reg32;
|
||||
@ -128,6 +188,12 @@ void rtc_exit_config_mode(void)
|
||||
while ((reg32 = (RTC_CRL & RTC_CRL_RTOFF)) == 0);
|
||||
}
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC Set the Alarm Time.
|
||||
|
||||
@param[in] alarm_time uint32_t. time at which the alarm event is triggered.
|
||||
*/
|
||||
|
||||
void rtc_set_alarm_time(uint32_t alarm_time)
|
||||
{
|
||||
rtc_enter_config_mode();
|
||||
@ -136,6 +202,11 @@ void rtc_set_alarm_time(uint32_t alarm_time)
|
||||
rtc_exit_config_mode();
|
||||
}
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC Enable the Alarm.
|
||||
|
||||
*/
|
||||
|
||||
void rtc_enable_alarm(void)
|
||||
{
|
||||
rtc_enter_config_mode();
|
||||
@ -143,6 +214,11 @@ void rtc_enable_alarm(void)
|
||||
rtc_exit_config_mode();
|
||||
}
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC Disable the Alarm.
|
||||
|
||||
*/
|
||||
|
||||
void rtc_disable_alarm(void)
|
||||
{
|
||||
rtc_enter_config_mode();
|
||||
@ -150,6 +226,12 @@ void rtc_disable_alarm(void)
|
||||
rtc_exit_config_mode();
|
||||
}
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC Set the prescaler Value
|
||||
|
||||
@param[in] prescale_val uint32_t. 20 bit prescale divider.
|
||||
*/
|
||||
|
||||
void rtc_set_prescale_val(uint32_t prescale_val)
|
||||
{
|
||||
rtc_enter_config_mode();
|
||||
@ -158,21 +240,45 @@ void rtc_set_prescale_val(uint32_t prescale_val)
|
||||
rtc_exit_config_mode();
|
||||
}
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC return the Counter Value
|
||||
|
||||
@returns uint32_t: the 32 bit counter value.
|
||||
*/
|
||||
|
||||
uint32_t rtc_get_counter_val(void)
|
||||
{
|
||||
return (RTC_CNTH << 16) | RTC_CNTL;
|
||||
}
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC return the prescaler Value
|
||||
|
||||
@returns uint32_t: the 20 bit prescale divider.
|
||||
*/
|
||||
|
||||
uint32_t rtc_get_prescale_div_val(void)
|
||||
{
|
||||
return (RTC_DIVH << 16) | RTC_DIVL;
|
||||
}
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC return the Alarm Value
|
||||
|
||||
@returns uint32_t: the 32 bit alarm value.
|
||||
*/
|
||||
|
||||
uint32_t rtc_get_alarm_val(void)
|
||||
{
|
||||
return (RTC_ALRH << 16) | RTC_ALRL;
|
||||
}
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC set the Counter
|
||||
|
||||
@param[in] uint32_t counter_val: 32 bit time setting for the counter.
|
||||
*/
|
||||
|
||||
void rtc_set_counter_val(uint32_t counter_val)
|
||||
{
|
||||
rtc_enter_config_mode();
|
||||
@ -181,6 +287,12 @@ void rtc_set_counter_val(uint32_t counter_val)
|
||||
rtc_exit_config_mode();
|
||||
}
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC Enable Interrupt
|
||||
|
||||
@param[in] flag_val ::rtcflag_t: The flag to enable.
|
||||
*/
|
||||
|
||||
void rtc_interrupt_enable(rtcflag_t flag_val)
|
||||
{
|
||||
rtc_enter_config_mode();
|
||||
@ -201,6 +313,12 @@ void rtc_interrupt_enable(rtcflag_t flag_val)
|
||||
rtc_exit_config_mode();
|
||||
}
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC Disable Interrupt
|
||||
|
||||
@param[in] flag_val ::rtcflag_t: The flag to disable.
|
||||
*/
|
||||
|
||||
void rtc_interrupt_disable(rtcflag_t flag_val)
|
||||
{
|
||||
rtc_enter_config_mode();
|
||||
@ -221,6 +339,12 @@ void rtc_interrupt_disable(rtcflag_t flag_val)
|
||||
rtc_exit_config_mode();
|
||||
}
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC Clear an Interrupt Flag
|
||||
|
||||
@param[in] flag_val ::rtcflag_t: The flag to clear.
|
||||
*/
|
||||
|
||||
void rtc_clear_flag(rtcflag_t flag_val)
|
||||
{
|
||||
/* Configuration mode not needed. */
|
||||
@ -239,6 +363,13 @@ void rtc_clear_flag(rtcflag_t flag_val)
|
||||
}
|
||||
}
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC Return a Flag Setting
|
||||
|
||||
@param[in] flag_val ::rtcflag_t: The flag to check.
|
||||
@returns uint32_t: a nonzero value if the flag is set, zero otherwise.
|
||||
*/
|
||||
|
||||
uint32_t rtc_check_flag(rtcflag_t flag_val)
|
||||
{
|
||||
uint32_t reg32;
|
||||
@ -262,6 +393,13 @@ uint32_t rtc_check_flag(rtcflag_t flag_val)
|
||||
return reg32;
|
||||
}
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC Start RTC after Standby Mode.
|
||||
|
||||
Enable the backup domain clocks, enable write access to the backup
|
||||
domain and the RTC, and synchronise the RTC register access.
|
||||
*/
|
||||
|
||||
void rtc_awake_from_standby(void)
|
||||
{
|
||||
uint32_t reg32;
|
||||
@ -281,6 +419,17 @@ void rtc_awake_from_standby(void)
|
||||
while ((reg32 = (RTC_CRL & RTC_CRL_RTOFF)) == 0);
|
||||
}
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/** @brief RTC Configuration on Wakeup
|
||||
|
||||
Enable the backup domain clocks and write access to the backup domain.
|
||||
If the RTC has not been enabled, set the clock source and prescaler value.
|
||||
The parameters are not used if the RTC has already been enabled.
|
||||
|
||||
@param[in] clock_source ::rcc_osc. RTC clock source. Only HSE/128, LSE and LSI.
|
||||
@param[in] prescale_val uint32_t. 20 bit prescale divider.
|
||||
*/
|
||||
|
||||
void rtc_auto_awake(enum rcc_osc clock_source, uint32_t prescale_val)
|
||||
{
|
||||
uint32_t reg32;
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user