Document RTC calibration functions

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) {

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