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

@@ -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;

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

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 */

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
+ * @note    The driver must be prepared to work with denormalized time values
- * @return -2 invalid `time` parameter
+ *          (e.g. seconds > 60). The driver may normalize the value, or just
- * @return -1 other errors
+ *          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);
 

drivers/rtt_rtc/rtt_rtc.c

@@ -23,6 +23,7 @@
  * @}
  */
 
+#include <errno.h>
 #include <stdlib.h>
 #include <string.h>