ports: Fix machine.RTC.init() method so argument order matches the docs.

This commit makes the argument ordering of `machine.RTC.init()` the same
for all the ports that implement arguments to this method: cc3200, esp32,
mimxrt and samd.  The cc3200 argument ordering is used, which matches the
documentation.

Also document the availability and the differing semantics for the stm32
and renesas-ra port.

Signed-off-by: robert-hh <robert@hammelrath.com>

4 files changed, 31 insertions, 17 deletions

diff --git a/docs/library/machine.RTC.rst b/docs/library/machine.RTC.rst
index ed93c5fff..e2ddd728b 100644
--- a/docs/library/machine.RTC.rst
+++ b/docs/library/machine.RTC.rst
@@ -42,7 +42,14 @@ Methods
 
    Initialise the RTC. Datetime is a tuple of the form:
 
-      ``(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])``
+      ``(year, month, day, hour, minute, second, microsecond, tzinfo)``
+
+   All eight arguments must be present. The ``microsecond`` and ``tzinfo``
+   values are currently ignored but might be used in the future.
+
+   Availability: CC3200, ESP32, MIMXRT, SAMD. The rtc.init() method on
+   the stm32 and renesas-ra ports just (re-)starts the RTC and does not
+   accept arguments.
 
 .. method:: RTC.now()
 
diff --git a/ports/esp32/machine_rtc.c b/ports/esp32/machine_rtc.c
index 087ba9d69..a2f4bb132 100644
--- a/ports/esp32/machine_rtc.c
+++ b/ports/esp32/machine_rtc.c
@@ -101,7 +101,7 @@ static mp_obj_t machine_rtc_make_new(const mp_obj_type_t *type, size_t n_args, s
     return (mp_obj_t)&machine_rtc_obj;
 }
 
-static mp_obj_t machine_rtc_datetime_helper(mp_uint_t n_args, const mp_obj_t *args) {
+static mp_obj_t machine_rtc_datetime_helper(mp_uint_t n_args, const mp_obj_t *args, int hour_index) {
     if (n_args == 1) {
         // Get time
 
@@ -131,7 +131,14 @@ static mp_obj_t machine_rtc_datetime_helper(mp_uint_t n_args, const mp_obj_t *ar
         mp_obj_get_array_fixed_n(args[1], 8, &items);
 
         struct timeval tv = {0};
-        tv.tv_sec = timeutils_seconds_since_epoch(mp_obj_get_int(items[0]), mp_obj_get_int(items[1]), mp_obj_get_int(items[2]), mp_obj_get_int(items[4]), mp_obj_get_int(items[5]), mp_obj_get_int(items[6]));
+        tv.tv_sec = timeutils_seconds_since_epoch(
+            mp_obj_get_int(items[0]),
+            mp_obj_get_int(items[1]),
+            mp_obj_get_int(items[2]),
+            mp_obj_get_int(items[hour_index]),
+            mp_obj_get_int(items[hour_index + 1]),
+            mp_obj_get_int(items[hour_index + 2])
+            );
         tv.tv_usec = mp_obj_get_int(items[7]);
         settimeofday(&tv, NULL);
 
@@ -139,13 +146,13 @@ static mp_obj_t machine_rtc_datetime_helper(mp_uint_t n_args, const mp_obj_t *ar
     }
 }
 static mp_obj_t machine_rtc_datetime(size_t n_args, const mp_obj_t *args) {
-    return machine_rtc_datetime_helper(n_args, args);
+    return machine_rtc_datetime_helper(n_args, args, 4);
 }
 static MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(machine_rtc_datetime_obj, 1, 2, machine_rtc_datetime);
 
 static mp_obj_t machine_rtc_init(mp_obj_t self_in, mp_obj_t date) {
     mp_obj_t args[2] = {self_in, date};
-    machine_rtc_datetime_helper(2, args);
+    machine_rtc_datetime_helper(2, args, 3);
 
     return mp_const_none;
 }
diff --git a/ports/mimxrt/machine_rtc.c b/ports/mimxrt/machine_rtc.c
index 91769ea33..5feeb0da0 100644
--- a/ports/mimxrt/machine_rtc.c
+++ b/ports/mimxrt/machine_rtc.c
@@ -185,7 +185,7 @@ static mp_obj_t machine_rtc_make_new(const mp_obj_type_t *type, size_t n_args, s
     return (mp_obj_t)&machine_rtc_obj;
 }
 
-static mp_obj_t machine_rtc_datetime_helper(size_t n_args, const mp_obj_t *args) {
+static mp_obj_t machine_rtc_datetime_helper(size_t n_args, const mp_obj_t *args, int hour_index) {
     if (n_args == 1) {
         // Get date and time.
         snvs_lp_srtc_datetime_t srtc_date;
@@ -214,9 +214,9 @@ static mp_obj_t machine_rtc_datetime_helper(size_t n_args, const mp_obj_t *args)
         srtc_date.month = mp_obj_get_int(items[1]);
         srtc_date.day = mp_obj_get_int(items[2]);
         // Ignore weekday at items[3]
-        srtc_date.hour = mp_obj_get_int(items[4]);
-        srtc_date.minute = mp_obj_get_int(items[5]);
-        srtc_date.second = mp_obj_get_int(items[6]);
+        srtc_date.hour = mp_obj_get_int(items[hour_index]);
+        srtc_date.minute = mp_obj_get_int(items[hour_index + 1]);
+        srtc_date.second = mp_obj_get_int(items[hour_index + 2]);
         if (SNVS_LP_SRTC_SetDatetime(SNVS, &srtc_date) != kStatus_Success) {
             mp_raise_ValueError(NULL);
         }
@@ -226,13 +226,13 @@ static mp_obj_t machine_rtc_datetime_helper(size_t n_args, const mp_obj_t *args)
 }
 
 static mp_obj_t machine_rtc_datetime(mp_uint_t n_args, const mp_obj_t *args) {
-    return machine_rtc_datetime_helper(n_args, args);
+    return machine_rtc_datetime_helper(n_args, args, 4);
 }
 static MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(machine_rtc_datetime_obj, 1, 2, machine_rtc_datetime);
 
 static mp_obj_t machine_rtc_init(mp_obj_t self_in, mp_obj_t date) {
     mp_obj_t args[2] = {self_in, date};
-    machine_rtc_datetime_helper(2, args);
+    machine_rtc_datetime_helper(2, args, 3);
     return mp_const_none;
 }
 static MP_DEFINE_CONST_FUN_OBJ_2(machine_rtc_init_obj, machine_rtc_init);
diff --git a/ports/samd/machine_rtc.c b/ports/samd/machine_rtc.c
index a906f9176..74c2266d6 100644
--- a/ports/samd/machine_rtc.c
+++ b/ports/samd/machine_rtc.c
@@ -93,7 +93,7 @@ static mp_obj_t machine_rtc_make_new(const mp_obj_type_t *type, size_t n_args, s
     return (mp_obj_t)&machine_rtc_obj;
 }
 
-static mp_obj_t machine_rtc_datetime_helper(size_t n_args, const mp_obj_t *args) {
+static mp_obj_t machine_rtc_datetime_helper(size_t n_args, const mp_obj_t *args, int hour_index) {
     // Rtc *rtc = RTC;
     if (n_args == 1) {
         // Get date and time.
@@ -120,9 +120,9 @@ static mp_obj_t machine_rtc_datetime_helper(size_t n_args, const mp_obj_t *args)
             RTC_MODE2_CLOCK_YEAR(mp_obj_get_int(items[0]) % 100) |
             RTC_MODE2_CLOCK_MONTH(mp_obj_get_int(items[1])) |
             RTC_MODE2_CLOCK_DAY(mp_obj_get_int(items[2])) |
-            RTC_MODE2_CLOCK_HOUR(mp_obj_get_int(items[4])) |
-            RTC_MODE2_CLOCK_MINUTE(mp_obj_get_int(items[5])) |
-            RTC_MODE2_CLOCK_SECOND(mp_obj_get_int(items[6]));
+            RTC_MODE2_CLOCK_HOUR(mp_obj_get_int(items[hour_index])) |
+            RTC_MODE2_CLOCK_MINUTE(mp_obj_get_int(items[hour_index + 1])) |
+            RTC_MODE2_CLOCK_SECOND(mp_obj_get_int(items[hour_index + 2]));
 
         RTC->MODE2.CLOCK.reg = date;
         #if defined(MCU_SAMD21)
@@ -138,13 +138,13 @@ static mp_obj_t machine_rtc_datetime_helper(size_t n_args, const mp_obj_t *args)
 }
 
 static mp_obj_t machine_rtc_datetime(mp_uint_t n_args, const mp_obj_t *args) {
-    return machine_rtc_datetime_helper(n_args, args);
+    return machine_rtc_datetime_helper(n_args, args, 4);
 }
 static MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(machine_rtc_datetime_obj, 1, 2, machine_rtc_datetime);
 
 static mp_obj_t machine_rtc_init(mp_obj_t self_in, mp_obj_t date) {
     mp_obj_t args[2] = {self_in, date};
-    machine_rtc_datetime_helper(2, args);
+    machine_rtc_datetime_helper(2, args, 3);
     return mp_const_none;
 }
 static MP_DEFINE_CONST_FUN_OBJ_2(machine_rtc_init_obj, machine_rtc_init);