From 80c027370b4102f876ae0a07cdcd8d2cb1a0dee4 Mon Sep 17 00:00:00 2001
From: Steins7 <steinsset@gmail.com>
Date: Sat, 27 Jul 2024 22:13:46 +0200
Subject: [PATCH] Document BKP module

---
 drv/bkp.c |  5 ++++-
 drv/bkp.h | 38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/drv/bkp.c b/drv/bkp.c
index f57aab9..457fa74 100644
--- a/drv/bkp.c
+++ b/drv/bkp.c
@@ -36,7 +36,6 @@ void bkp_configure_rtc(uint32_t period_ms, enum BkpRtcClockSrc clock_src,
 	rcc_regs->BDCR.RTCSEL = clock_src + 1;
 	rcc_regs->BDCR.RTCEN = 1;
 
-	//compute prescaler
 	uint32_t prescaler = compute_prescaler(period_ms, clock_src);
 
 	//wait for registers to synchronize
@@ -89,6 +88,10 @@ void bkp_reset(void)
 
 //--local functions-------------------------------------------------------------
 
+/**
+ * Computes the prescaler value based on the clock source and the required
+ * period
+ */
 uint32_t compute_prescaler(uint32_t period_ms, enum BkpRtcClockSrc clock_src)
 {
 	uint32_t prescaler;
diff --git a/drv/bkp.h b/drv/bkp.h
index f7e9c0f..c921897 100644
--- a/drv/bkp.h
+++ b/drv/bkp.h
@@ -13,12 +13,20 @@
 
 //--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,
@@ -26,15 +34,45 @@ enum BkpRtcIrq {
 	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