From 3303bf64350d129961a30d20891b318485d6654e Mon Sep 17 00:00:00 2001
From: Steins7 <steinsset@gmail.com>
Date: Sun, 3 Nov 2024 13:00:46 +0100
Subject: [PATCH] Document RTC calibration functions

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

diff --git a/drv/bkp.c b/drv/bkp.c
index 7b9be0f..802af59 100644
--- a/drv/bkp.c
+++ b/drv/bkp.c
@@ -193,6 +193,11 @@ static uint32_t compute_prescaler(uint32_t period_ms,
 	return (period_ms * prescaler) / 1000;
 }
 
+/**
+ * LSI callibration callback. Measures the LSI deviation from its theorical
+ * frequency using the RTC and stores the effective frequency for calibration
+ * purposes
+ */
 static void lsi_calib_callback(enum TimIRQSource src)
 {
 	if (src == TIM_IRQ_SOURCE_UPDATE) {
diff --git a/drv/bkp.h b/drv/bkp.h
index 7be7294..b83541d 100644
--- a/drv/bkp.h
+++ b/drv/bkp.h
@@ -70,7 +70,8 @@ typedef void (*BkpRtcCallback)(enum BkpRtcIrq src);
  * - 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)
+ * (see bkp_callibrate_lsi). The calibration value is automatically used if
+ * present when calling this function.
  * - HSE consumes the most.
  * WARNING : once configured, the clock source can only changed by reseting the
  * whole backup domain via bkp_reset()
@@ -107,9 +108,24 @@ uint32_t bkp_read_rtc_div(void);
  */
 void bkp_reset(void);
 
+/**
+ * Writes data to the specified backup domain index. The data will persist as
+ * long as VBAT is present
+ */
 void bkp_write_data(enum BkpData data_index, uint16_t data);
+
+/**
+ * Writes data from the specified backup domain data index. The data will
+ * persist as long as VBAT is present
+ */
 uint16_t bkp_read_data(enum BkpData data_index);
 
+/**
+ * Calibrate the LSI oscillator using the specified timer for accurate RTC
+ * timings and store the calibration value at backup domain index
+ * BKP_DATA_LSI_CALIB. This function has no effect if a calibration value is
+ * already present
+ */
 void bkp_calibrate_lsi(enum TimPeriph timer);
 
 //unimplemented functions