extmod/modutime: Provide a generic time module.

Based on extmod/utime_mphal.c, with:
- a globals dict added
- time.localtime wrapper added
- time.time wrapper added
- time.time_ns function added

New configuration options are added for this module:
- MICROPY_PY_UTIME (enabled at basic features level)
- MICROPY_PY_UTIME_GMTIME_LOCALTIME_MKTIME
- MICROPY_PY_UTIME_TIME_TIME_NS

Signed-off-by: Damien George <damien@micropython.org>

extmod/extmod.cmake

@@ -33,6 +33,7 @@ set(MICROPY_SOURCE_EXTMOD
     ${MICROPY_EXTMOD_DIR}/modusocket.c
     ${MICROPY_EXTMOD_DIR}/modussl_axtls.c
     ${MICROPY_EXTMOD_DIR}/modussl_mbedtls.c
+    ${MICROPY_EXTMOD_DIR}/modutime.c
     ${MICROPY_EXTMOD_DIR}/modutimeq.c
     ${MICROPY_EXTMOD_DIR}/moduwebsocket.c
     ${MICROPY_EXTMOD_DIR}/moduzlib.c
@@ -42,7 +43,6 @@ set(MICROPY_SOURCE_EXTMOD
     ${MICROPY_EXTMOD_DIR}/network_ninaw10.c
     ${MICROPY_EXTMOD_DIR}/network_wiznet5k.c
     ${MICROPY_EXTMOD_DIR}/uos_dupterm.c
-    ${MICROPY_EXTMOD_DIR}/utime_mphal.c
     ${MICROPY_EXTMOD_DIR}/vfs.c
     ${MICROPY_EXTMOD_DIR}/vfs_blockdev.c
     ${MICROPY_EXTMOD_DIR}/vfs_fat.c

extmod/extmod.mk

@@ -32,6 +32,7 @@ SRC_EXTMOD_C += \
 	extmod/modusocket.c \
 	extmod/modussl_axtls.c \
 	extmod/modussl_mbedtls.c \
+	extmod/modutime.c \
 	extmod/modutimeq.c \
 	extmod/moduwebsocket.c \
 	extmod/moduzlib.c \
@@ -41,7 +42,6 @@ SRC_EXTMOD_C += \
 	extmod/network_ninaw10.c \
 	extmod/network_wiznet5k.c \
 	extmod/uos_dupterm.c \
-	extmod/utime_mphal.c \
 	extmod/vfs.c \
 	extmod/vfs_blockdev.c \
 	extmod/vfs_fat.c \

extmod/modutime.c

@@ -3,7 +3,7 @@
  *
  * The MIT License (MIT)
  *
- * Copyright (c) 2013-2016 Damien P. George
+ * Copyright (c) 2013-2023 Damien P. George
  * Copyright (c) 2016 Paul Sokolovsky
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -25,18 +25,57 @@
  * THE SOFTWARE.
  */
 
-#include "py/mpconfig.h"
-#if MICROPY_PY_UTIME_MP_HAL
-
-#include <string.h>
-
-#include "py/obj.h"
 #include "py/mphal.h"
-#include "py/smallint.h"
 #include "py/runtime.h"
-#include "extmod/utime_mphal.h"
+#include "py/smallint.h"
+#include "extmod/modutime.h"
+
+#if MICROPY_PY_UTIME
+
+#ifdef MICROPY_PY_UTIME_INCLUDEFILE
+#include MICROPY_PY_UTIME_INCLUDEFILE
+#endif
+
+#if MICROPY_PY_UTIME_GMTIME_LOCALTIME_MKTIME
+
 #include "shared/timeutils/timeutils.h"
 
+// localtime([secs])
+// Convert a time expressed in seconds since the Epoch into an 8-tuple which
+// contains: (year, month, mday, hour, minute, second, weekday, yearday)
+// If secs is not provided or None, then the current time is used.
+// - year    is the full year, eg 2000
+// - month   is 1-12
+// - mday    is 1-31
+// - hour    is 0-23
+// - minute  is 0-59
+// - second  is 0-59
+// - weekday is 0-6 for Mon-Sun
+// - yearday is 1-366
+STATIC mp_obj_t time_localtime(size_t n_args, const mp_obj_t *args) {
+    if (n_args == 0 || args[0] == mp_const_none) {
+        // Get current date and time.
+        return mp_utime_localtime_get();
+    } else {
+        // Convert given seconds to tuple.
+        mp_int_t seconds = mp_obj_get_int(args[0]);
+        timeutils_struct_time_t tm;
+        timeutils_seconds_since_epoch_to_struct_time(seconds, &tm);
+        mp_obj_t tuple[8] = {
+            tuple[0] = mp_obj_new_int(tm.tm_year),
+            tuple[1] = mp_obj_new_int(tm.tm_mon),
+            tuple[2] = mp_obj_new_int(tm.tm_mday),
+            tuple[3] = mp_obj_new_int(tm.tm_hour),
+            tuple[4] = mp_obj_new_int(tm.tm_min),
+            tuple[5] = mp_obj_new_int(tm.tm_sec),
+            tuple[6] = mp_obj_new_int(tm.tm_wday),
+            tuple[7] = mp_obj_new_int(tm.tm_yday),
+        };
+        return mp_obj_new_tuple(8, tuple);
+    }
+}
+MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(mp_utime_localtime_obj, 0, 1, time_localtime);
+
 // mktime()
 // This is the inverse function of localtime. Its argument is a full 8-tuple
 // which expresses a time as per localtime. It returns an integer which is
@@ -57,12 +96,36 @@ STATIC mp_obj_t time_mktime(mp_obj_t tuple) {
 }
 MP_DEFINE_CONST_FUN_OBJ_1(mp_utime_mktime_obj, time_mktime);
 
+#endif // MICROPY_PY_UTIME_GMTIME_LOCALTIME_MKTIME
+
+#if MICROPY_PY_UTIME_TIME_TIME_NS
+
+// time()
+// Return the number of seconds since the Epoch.
+STATIC mp_obj_t time_time(void) {
+    return mp_utime_time_get();
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_0(mp_utime_time_obj, time_time);
+
+// time_ns()
+// Returns the number of nanoseconds since the Epoch, as an integer.
+STATIC mp_obj_t time_time_ns(void) {
+    return mp_obj_new_int_from_ull(mp_hal_time_ns());
+}
+MP_DEFINE_CONST_FUN_OBJ_0(mp_utime_time_ns_obj, time_time_ns);
+
+#endif // MICROPY_PY_UTIME_TIME_TIME_NS
+
 STATIC mp_obj_t time_sleep(mp_obj_t seconds_o) {
+    #ifdef MICROPY_PY_UTIME_CUSTOM_SLEEP
+    mp_utime_sleep(seconds_o);
+    #else
     #if MICROPY_PY_BUILTINS_FLOAT
     mp_hal_delay_ms((mp_uint_t)(1000 * mp_obj_get_float(seconds_o)));
     #else
     mp_hal_delay_ms(1000 * mp_obj_get_int(seconds_o));
     #endif
+    #endif
     return mp_const_none;
 }
 MP_DEFINE_CONST_FUN_OBJ_1(mp_utime_sleep_obj, time_sleep);
@@ -133,10 +196,41 @@ STATIC mp_obj_t time_ticks_add(mp_obj_t ticks_in, mp_obj_t delta_in) {
 }
 MP_DEFINE_CONST_FUN_OBJ_2(mp_utime_ticks_add_obj, time_ticks_add);
 
-// Returns the number of nanoseconds since the Epoch, as an integer.
+STATIC const mp_rom_map_elem_t mp_module_time_globals_table[] = {
-STATIC mp_obj_t time_time_ns(void) {
+    { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_utime) },
-    return mp_obj_new_int_from_ull(mp_hal_time_ns());
-}
-MP_DEFINE_CONST_FUN_OBJ_0(mp_utime_time_ns_obj, time_time_ns);
 
-#endif // MICROPY_PY_UTIME_MP_HAL
+    #if MICROPY_PY_UTIME_GMTIME_LOCALTIME_MKTIME
+    { MP_ROM_QSTR(MP_QSTR_gmtime), MP_ROM_PTR(&mp_utime_localtime_obj) },
+    { MP_ROM_QSTR(MP_QSTR_localtime), MP_ROM_PTR(&mp_utime_localtime_obj) },
+    { MP_ROM_QSTR(MP_QSTR_mktime), MP_ROM_PTR(&mp_utime_mktime_obj) },
+    #endif
+
+    #if MICROPY_PY_UTIME_TIME_TIME_NS
+    { MP_ROM_QSTR(MP_QSTR_time), MP_ROM_PTR(&mp_utime_time_obj) },
+    { MP_ROM_QSTR(MP_QSTR_time_ns), MP_ROM_PTR(&mp_utime_time_ns_obj) },
+    #endif
+
+    { MP_ROM_QSTR(MP_QSTR_sleep), MP_ROM_PTR(&mp_utime_sleep_obj) },
+    { MP_ROM_QSTR(MP_QSTR_sleep_ms), MP_ROM_PTR(&mp_utime_sleep_ms_obj) },
+    { MP_ROM_QSTR(MP_QSTR_sleep_us), MP_ROM_PTR(&mp_utime_sleep_us_obj) },
+
+    { MP_ROM_QSTR(MP_QSTR_ticks_ms), MP_ROM_PTR(&mp_utime_ticks_ms_obj) },
+    { MP_ROM_QSTR(MP_QSTR_ticks_us), MP_ROM_PTR(&mp_utime_ticks_us_obj) },
+    { MP_ROM_QSTR(MP_QSTR_ticks_cpu), MP_ROM_PTR(&mp_utime_ticks_cpu_obj) },
+    { MP_ROM_QSTR(MP_QSTR_ticks_add), MP_ROM_PTR(&mp_utime_ticks_add_obj) },
+    { MP_ROM_QSTR(MP_QSTR_ticks_diff), MP_ROM_PTR(&mp_utime_ticks_diff_obj) },
+
+    #ifdef MICROPY_PY_UTIME_EXTRA_GLOBALS
+    MICROPY_PY_UTIME_EXTRA_GLOBALS
+    #endif
+};
+STATIC MP_DEFINE_CONST_DICT(mp_module_time_globals, mp_module_time_globals_table);
+
+const mp_obj_module_t mp_module_utime = {
+    .base = { &mp_type_module },
+    .globals = (mp_obj_dict_t *)&mp_module_time_globals,
+};
+
+MP_REGISTER_MODULE(MP_QSTR_utime, mp_module_utime);
+
+#endif // MICROPY_PY_UTIME

extmod/modutime.h

@@ -24,8 +24,8 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-#ifndef MICROPY_INCLUDED_EXTMOD_UTIME_MPHAL_H
+#ifndef MICROPY_INCLUDED_EXTMOD_MODUTIME_H
-#define MICROPY_INCLUDED_EXTMOD_UTIME_MPHAL_H
+#define MICROPY_INCLUDED_EXTMOD_MODUTIME_H
 
 #include "py/obj.h"
 
@@ -40,4 +40,4 @@ MP_DECLARE_CONST_FUN_OBJ_2(mp_utime_ticks_diff_obj);
 MP_DECLARE_CONST_FUN_OBJ_2(mp_utime_ticks_add_obj);
 MP_DECLARE_CONST_FUN_OBJ_0(mp_utime_time_ns_obj);
 
-#endif // MICROPY_INCLUDED_EXTMOD_UTIME_MPHAL_H
+#endif // MICROPY_INCLUDED_EXTMOD_MODUTIME_H

ports/cc3200/mods/modutime.c

@@ -34,7 +34,7 @@
 #include "py/smallint.h"
 #include "py/mphal.h"
 #include "shared/timeutils/timeutils.h"
-#include "extmod/utime_mphal.h"
+#include "extmod/modutime.h"
 #include "inc/hw_types.h"
 #include "inc/hw_ints.h"
 #include "inc/hw_memmap.h"

ports/esp32/modutime.c

@@ -32,7 +32,7 @@
 
 #include "py/runtime.h"
 #include "shared/timeutils/timeutils.h"
-#include "extmod/utime_mphal.h"
+#include "extmod/modutime.h"
 
 STATIC mp_obj_t time_localtime(size_t n_args, const mp_obj_t *args) {
     timeutils_struct_time_t tm;

ports/esp8266/modutime.c

@@ -35,7 +35,7 @@
 #include "shared/timeutils/timeutils.h"
 #include "modmachine.h"
 #include "user_interface.h"
-#include "extmod/utime_mphal.h"
+#include "extmod/modutime.h"
 
 /// \module time - time related functions
 ///

ports/mimxrt/modutime.c

@@ -27,7 +27,7 @@
 
 #include "py/runtime.h"
 #include "shared/timeutils/timeutils.h"
-#include "extmod/utime_mphal.h"
+#include "extmod/modutime.h"
 #include "fsl_snvs_lp.h"
 
 // localtime([secs])

ports/nrf/modules/utime/modutime.c

@@ -30,7 +30,7 @@
 #include "py/nlr.h"
 #include "py/smallint.h"
 #include "py/obj.h"
-#include "extmod/utime_mphal.h"
+#include "extmod/modutime.h"
 
 /// \module time - time related functions
 ///

ports/renesas-ra/modutime.c

@@ -31,7 +31,7 @@
 #include "py/smallint.h"
 #include "py/obj.h"
 #include "shared/timeutils/timeutils.h"
-#include "extmod/utime_mphal.h"
+#include "extmod/modutime.h"
 #include "systick.h"
 #include "rtc.h"
 

ports/rp2/modutime.c

@@ -26,7 +26,7 @@
 
 #include "py/runtime.h"
 #include "shared/timeutils/timeutils.h"
-#include "extmod/utime_mphal.h"
+#include "extmod/modutime.h"
 #include "hardware/rtc.h"
 
 // localtime([secs])

ports/samd/modutime.c

@@ -25,7 +25,7 @@
  */
 
 #include "py/runtime.h"
-#include "extmod/utime_mphal.h"
+#include "extmod/modutime.h"
 #include "shared/timeutils/timeutils.h"
 #include "modmachine.h"
 

ports/stm32/modpyb.c

@@ -54,7 +54,7 @@
 #include "modmachine.h"
 #include "extmod/modnetwork.h"
 #include "extmod/vfs.h"
-#include "extmod/utime_mphal.h"
+#include "extmod/modutime.h"
 
 #if MICROPY_PY_PYB
 

ports/stm32/modutime.c

@@ -31,7 +31,7 @@
 #include "py/smallint.h"
 #include "py/obj.h"
 #include "shared/timeutils/timeutils.h"
-#include "extmod/utime_mphal.h"
+#include "extmod/modutime.h"
 #include "systick.h"
 #include "portmodules.h"
 #include "rtc.h"

ports/unix/modtime.c

@@ -38,7 +38,7 @@
 #include "py/runtime.h"
 #include "py/smallint.h"
 #include "py/mphal.h"
-#include "extmod/utime_mphal.h"
+#include "extmod/modutime.h"
 
 #ifdef _WIN32
 static inline int msec_sleep_tv(struct timeval *tv) {

ports/webassembly/modutime.c

@@ -33,7 +33,7 @@
 #include "py/obj.h"
 #include "py/runtime.h"
 #include "shared/timeutils/timeutils.h"
-#include "extmod/utime_mphal.h"
+#include "extmod/modutime.h"
 
 STATIC const mp_rom_map_elem_t time_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_utime) },

ports/windows/msvc/sources.props

@@ -17,9 +17,9 @@
     <PyExtModSource Include="$(PyBaseDir)extmod\modurandom.c" />
     <PyExtModSource Include="$(PyBaseDir)extmod\modure.c" />
     <PyExtModSource Include="$(PyBaseDir)extmod\moduselect.c" />
+    <PyExtModSource Include="$(PyBaseDir)extmod\modutime.c" />
     <PyExtModSource Include="$(PyBaseDir)extmod\modutimeq.c" />
     <PyExtModSource Include="$(PyBaseDir)extmod\moduzlib.c" />
-    <PyExtModSource Include="$(PyBaseDir)extmod\utime_mphal.c" />
     <PyExtModSource Include="$(PyBaseDir)extmod\virtpin.c" />
     <PyExtModSource Include="$(PyBaseDir)extmod\vfs.c" />
     <PyExtModSource Include="$(PyBaseDir)extmod\vfs_posix.c" />

ports/zephyr/modutime.c

@@ -33,7 +33,7 @@
 #include "py/runtime.h"
 #include "py/smallint.h"
 #include "py/mphal.h"
-#include "extmod/utime_mphal.h"
+#include "extmod/modutime.h"
 
 STATIC mp_obj_t mod_time_time(void) {
     /* The absence of FP support is deliberate. The Zephyr port uses

py/mpconfig.h

@@ -1468,10 +1468,19 @@ typedef double mp_float_t;
 #define MICROPY_PY_USELECT_SELECT (1)
 #endif
 
-// Whether to provide "utime" module functions implementation
+// Whether to provide the "utime" module
-// in terms of mp_hal_* functions.
+#ifndef MICROPY_PY_UTIME
-#ifndef MICROPY_PY_UTIME_MP_HAL
+#define MICROPY_PY_UTIME (MICROPY_CONFIG_ROM_LEVEL_AT_LEAST_BASIC_FEATURES)
-#define MICROPY_PY_UTIME_MP_HAL (0)
+#endif
+
+// Whether to provide utime.gmtime/localtime/mktime functions
+#ifndef MICROPY_PY_UTIME_GMTIME_LOCALTIME_MKTIME
+#define MICROPY_PY_UTIME_GMTIME_LOCALTIME_MKTIME (0)
+#endif
+
+// Whether to provide utime.time/time_ns functions
+#ifndef MICROPY_PY_UTIME_TIME_TIME_NS
+#define MICROPY_PY_UTIME_TIME_TIME_NS (0)
 #endif
 
 // Period of values returned by utime.ticks_ms(), ticks_us(), ticks_cpu()