From 51127f674a3f047dad2218efdbd04c49688b69f7 Mon Sep 17 00:00:00 2001
From: Marian Buschsieweke <marian.buschsieweke@ovgu.de>
Date: Thu, 18 May 2023 00:04:41 +0200
Subject: [PATCH] drivers/periph/rtc: improve doc on rtc_set_alarm

- point out behavior on denormalized time stamps
- use errno codes to indicate errors (and adapt the few instances of
  actual error handling to use them)
---
 cpu/native/periph/rtc.c          | 11 ++++++-----
 cpu/qn908x/periph/rtc.c          |  3 ++-
 cpu/sam0_common/periph/rtc_rtt.c |  4 +++-
 drivers/include/periph/rtc.h     | 11 ++++++++---
 drivers/rtt_rtc/rtt_rtc.c        |  1 +
 5 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/cpu/native/periph/rtc.c b/cpu/native/periph/rtc.c
index f544c9261d..088e465332 100644
--- a/cpu/native/periph/rtc.c
+++ b/cpu/native/periph/rtc.c
@@ -22,13 +22,14 @@
  * @}
  */
 
-#include <time.h>
+#include <err.h>
+#include <errno.h>
 #include <stdlib.h>
 #include <string.h>
-#include <err.h>
+#include <time.h>
 
-#include "periph/rtc.h"
 #include "cpu.h"
+#include "periph/rtc.h"
 #include "timex.h"
 #include "ztimer.h"
 
@@ -206,11 +207,11 @@ int rtc_set_alarm(struct tm *time, rtc_alarm_cb_t cb, void *arg)
 {
     if (!_native_rtc_initialized) {
         warnx("rtc_set_alarm: not initialized");
-        return -1;
+        return -EIO;
     }
     if (!_native_rtc_powered) {
         warnx("rtc_set_alarm: not powered on");
-        return -1;
+        return -EIO;
     }
 
     struct tm now;
diff --git a/cpu/qn908x/periph/rtc.c b/cpu/qn908x/periph/rtc.c
index a939fe3a57..968e881e0e 100644
--- a/cpu/qn908x/periph/rtc.c
+++ b/cpu/qn908x/periph/rtc.c
@@ -20,6 +20,7 @@
  * @}
  */
 
+#include <errno.h>
 #include <stdlib.h>
 
 #include "cpu.h"
@@ -104,7 +105,7 @@ int rtc_set_alarm(struct tm *time, rtc_alarm_cb_t cb, void *arg)
     if (ts <= RTC->SEC) {
         /* The requested time is in the past at the time of executing this
          * instruction, so we return invalid time. */
-        return -2;
+        return -EINVAL;
     }
 
     /* If the requested time arrives (SEC_INT should have fired) before we get
diff --git a/cpu/sam0_common/periph/rtc_rtt.c b/cpu/sam0_common/periph/rtc_rtt.c
index cf46172608..adc7a952dc 100644
--- a/cpu/sam0_common/periph/rtc_rtt.c
+++ b/cpu/sam0_common/periph/rtc_rtt.c
@@ -26,8 +26,10 @@
  * @}
  */
 
+#include <errno.h>
 #include <stdint.h>
 #include <string.h>
+
 #include "pm_layered.h"
 #include "periph/rtc.h"
 #include "periph/rtt.h"
@@ -611,7 +613,7 @@ int rtc_set_alarm(struct tm *time, rtc_alarm_cb_t cb, void *arg)
 
     if ((time->tm_year < reference_year) ||
         (time->tm_year > (reference_year + 63))) {
-        return -2;
+        return -EINVAL;
     }
 
     /* make sure that preceding changes have been applied */
diff --git a/drivers/include/periph/rtc.h b/drivers/include/periph/rtc.h
index aae0b47856..1744cf73da 100644
--- a/drivers/include/periph/rtc.h
+++ b/drivers/include/periph/rtc.h
@@ -113,9 +113,14 @@ int rtc_get_time_ms(struct tm *time, uint16_t *ms);
  * @param[in] cb            Callback executed when alarm is hit.
  * @param[in] arg           Argument passed to callback when alarm is hit.
  *
- * @return  0 for success
- * @return -2 invalid `time` parameter
- * @return -1 other errors
+ * @note    The driver must be prepared to work with denormalized time values
+ *          (e.g. seconds > 60). The driver may normalize the value, or just
+ *          keep it denormalized. In either case, the timeout should occur at
+ *          the equivalent normalized time.
+ *
+ * @retval  0           success
+ * @return  -EINVAL     @p time was invalid (e.g. in the past, out of range)
+ * @return  <0          other error (negative errno code to indicate cause)
  */
 int rtc_set_alarm(struct tm *time, rtc_alarm_cb_t cb, void *arg);
 
diff --git a/drivers/rtt_rtc/rtt_rtc.c b/drivers/rtt_rtc/rtt_rtc.c
index 2e3bed2dc3..139523d3cf 100644
--- a/drivers/rtt_rtc/rtt_rtc.c
+++ b/drivers/rtt_rtc/rtt_rtc.c
@@ -23,6 +23,7 @@
  * @}
  */
 
+#include <errno.h>
 #include <stdlib.h>
 #include <string.h>