Time: support nanosecond/native unit

Signed-off-by: Peter M <petermm@gmail.com>

Author: petermm

CHANGELOG.md

@@ -78,6 +78,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `network:sta_status/0` to get the current connection state of the sta interface.
 - Added ESP32 `-DATOMVM_ELIXIR_SUPPORT=on` configuration option
 - Added support for ESP32 development builds to include NVS partition data at build time
+- Added `nanosecond` and `native` time unit support to `erlang:system_time/1`, `erlang:monotonic_time/1`, and `calendar:system_time_to_universal_time/2`
 
 ### Changed
 

doc/src/programmers-guide.md

@@ -679,20 +679,22 @@ Use [`erlang:timestamp/0`](./apidocs/erlang/estdlib/erlang.md#timestamp0) to get
 {MegaSecs, Secs, MicroSecs} = erlang:timestamp().
 ```
 
-Use [`erlang:system_time/1`](./apidocs/erlang/estdlib/erlang.md#system_time1) to obtain the seconds, milliseconds or microseconds since the UNIX epoch (Midnight, Jan 1, 1970, UTC):
+Use [`erlang:system_time/1`](./apidocs/erlang/estdlib/erlang.md#system_time1) to obtain the seconds, milliseconds, microseconds or nanoseconds since the UNIX epoch (Midnight, Jan 1, 1970, UTC):
 
 ```erlang
 Seconds = erlang:system_time(second).
 MilliSeconds = erlang:system_time(millisecond).
 MicroSeconds = erlang:system_time(microsecond).
+NanoSeconds = erlang:system_time(nanosecond).
 ```
 
-Use [`erlang:monotonic_time/1`](./apidocs/erlang/estdlib/erlang.md#monotonic_time1) to obtain a (possibly not strictly) monotonically increasing time measurement.  Use the same time units to convert to seconds, milliseconds, or microseconds:
+Use [`erlang:monotonic_time/1`](./apidocs/erlang/estdlib/erlang.md#monotonic_time1) to obtain a (possibly not strictly) monotonically increasing time measurement.  Use the same time units to convert to seconds, milliseconds, microseconds or nanoseconds:
 
 ```erlang
 Seconds = erlang:monotonic_time(second).
 MilliSeconds = erlang:monotonic_time(millisecond).
 MicroSeconds = erlang:monotonic_time(microsecond).
+NanoSeconds = erlang:monotonic_time(nanosecond).
 ```
 
 ```{caution}
@@ -722,7 +724,7 @@ permission to set the system time.
 
 On the ESP32 platform, you can use the Wifi network to set the system time automatically.  For information about how to set system time on the ESP32 using SNTP, see the [Network Programming Guide](./network-programming-guide.md).
 
-To convert a time (in seconds, milliseconds, or microseconds from the UNIX epoch) to a date-time, use the [`calendar:system_time_to_universal_time/2`](./apidocs/erlang/estdlib/calendar.md#system_time_to_universal_time2) function.  For example,
+To convert a time (in seconds, milliseconds, microseconds, or nanoseconds from the UNIX epoch) to a date-time, use the [`calendar:system_time_to_universal_time/2`](./apidocs/erlang/estdlib/calendar.md#system_time_to_universal_time2) function.  For example,
 
 ```erlang
 Milliseconds = ... %% get milliseconds from the UNIX epoch
@@ -731,7 +733,7 @@ Milliseconds = ... %% get milliseconds from the UNIX epoch
 } = calendar:system_time_to_universal_time(Milliseconds, millisecond).
 ```
 
-Valid time units are `second`, `millisecond`, and `microsecond`.
+Valid time units are `second`, `millisecond`, `microsecond`, and `nanosecond`.
 
 ### Date and Time
 

libs/estdlib/src/erlang.erl

@@ -155,7 +155,7 @@
 -type atom_encoding() :: latin1 | utf8 | unicode.
 
 -type mem_type() :: binary.
--type time_unit() :: second | millisecond | microsecond.
+-type time_unit() :: second | millisecond | microsecond | nanosecond | native.
 -type timestamp() :: {
     MegaSecs :: non_neg_integer(), Secs :: non_neg_integer(), MicroSecs :: non_neg_integer
 }.

src/libAtomVM/defaultatoms.def

@@ -97,6 +97,7 @@ X(ATOMVM_VERSION_ATOM, "\xE", "atomvm_version")
 X(SECOND_ATOM, "\x6", "second")
 X(MILLISECOND_ATOM, "\xB", "millisecond")
 X(MICROSECOND_ATOM, "\xB", "microsecond")
+X(NANOSECOND_ATOM, "\xA", "nanosecond")
 
 X(INFINITY_ATOM, "\x8", "infinity")
 X(TIMEOUT_VALUE_ATOM, "\xD", "timeout_value")

src/libAtomVM/nifs.c

@@ -1726,6 +1726,9 @@ term nif_erlang_monotonic_time_1(Context *ctx, int argc, term argv[])
     } else if (argv[0] == MICROSECOND_ATOM) {
         return make_maybe_boxed_int64(ctx, ((int64_t) ts.tv_sec) * 1000000UL + ts.tv_nsec / 1000UL);
 
+    } else if (argv[0] == NANOSECOND_ATOM || argv[0] == NATIVE_ATOM) {
+        return make_maybe_boxed_int64(ctx, ((int64_t) ts.tv_sec) * 1000000000ULL + ts.tv_nsec);
+
     } else {
         RAISE_ERROR(BADARG_ATOM);
     }
@@ -1748,6 +1751,9 @@ term nif_erlang_system_time_1(Context *ctx, int argc, term argv[])
     } else if (argv[0] == MICROSECOND_ATOM) {
         return make_maybe_boxed_int64(ctx, ((int64_t) ts.tv_sec) * 1000000UL + ts.tv_nsec / 1000UL);
 
+    } else if (argv[0] == NANOSECOND_ATOM || argv[0] == NATIVE_ATOM) {
+        return make_maybe_boxed_int64(ctx, ((int64_t) ts.tv_sec) * 1000000000ULL + ts.tv_nsec);
+
     } else {
         RAISE_ERROR(BADARG_ATOM);
     }
@@ -1876,6 +1882,10 @@ term nif_calendar_system_time_to_universal_time_2(Context *ctx, int argc, term a
         ts.tv_sec = (time_t) (value / 1000000);
         ts.tv_nsec = (value % 1000000) * 1000;
 
+    } else if (argv[1] == NANOSECOND_ATOM || argv[1] == NATIVE_ATOM) {
+        ts.tv_sec = (time_t) (value / 1000000000);
+        ts.tv_nsec = (value % 1000000000) * 1;
+
     } else {
         RAISE_ERROR(BADARG_ATOM);
     }

src/platforms/esp32/test/main/test_erl_sources/test_monotonic_time.erl

@@ -23,11 +23,51 @@
 
 start() ->
     ok = test_monotonic_time(),
+    ok = test_monotonic_time_nanosecond(),
+    ok = test_monotonic_time_native(),
+    ok = test_time_unit_ratios(),
     ok.
 
 test_monotonic_time() ->
     test_monotonic_time([500, 1000, 1500, 2500, 5000]).
 
+test_monotonic_time_nanosecond() ->
+    DelayMs = 200,
+    T1 = erlang:monotonic_time(nanosecond),
+    timer:sleep(DelayMs),
+    T2 = erlang:monotonic_time(nanosecond),
+    Diff = T2 - T1,
+    true = Diff >= DelayMs * 1000000,
+    ok.
+
+test_monotonic_time_native() ->
+    DelayMs = 200,
+    T1 = erlang:monotonic_time(native),
+    timer:sleep(DelayMs),
+    T2 = erlang:monotonic_time(native),
+    Diff = T2 - T1,
+    true = Diff >= DelayMs * 1000000,
+    ok.
+
+% Readings coarsest-to-finest: finer value is always taken later so
+% finer >= coarser * scale.  Upper bound allows 1 ms between calls.
+test_time_unit_ratios() ->
+    S = erlang:monotonic_time(second),
+    Ms = erlang:monotonic_time(millisecond),
+    Us = erlang:monotonic_time(microsecond),
+    Ns = erlang:monotonic_time(nanosecond),
+
+    true = Ms >= S * 1000,
+    true = Ms < S * 1000 + 1000,
+
+    true = Us >= Ms * 1000,
+    true = Us < Ms * 1000 + 1000000,
+
+    true = Ns >= Us * 1000,
+    true = Ns < Us * 1000 + 1000000,
+
+    ok.
+
 test_monotonic_time([]) ->
     ok;
 test_monotonic_time([Delay | Tail]) ->

src/platforms/rp2/tests/test_erl_sources/test_clocks.erl

@@ -25,16 +25,31 @@
 -define(BEFORE_START_DATE, 1693769340).
 
 start() ->
-    test_clock(system_time, fun() -> erlang:system_time(millisecond) end),
-    test_clock(monotonic_time, fun() -> erlang:monotonic_time(millisecond) end),
+    test_clock(system_time, fun() -> erlang:system_time(millisecond) end, 100, 500),
+    test_clock(monotonic_time, fun() -> erlang:monotonic_time(millisecond) end, 100, 500),
+    test_clock(
+        system_time_nanosecond, fun() -> erlang:system_time(nanosecond) end, 100000000, 500000000
+    ),
+    test_clock(
+        monotonic_time_nanosecond,
+        fun() -> erlang:monotonic_time(nanosecond) end,
+        100000000,
+        500000000
+    ),
+    test_clock(system_time_native, fun() -> erlang:system_time(native) end, 100000000, 500000000),
+    test_clock(
+        monotonic_time_native, fun() -> erlang:monotonic_time(native) end, 100000000, 500000000
+    ),
     Date = erlang:universaltime(),
     if
         Date < ?START_DATE ->
             pico:rtc_set_datetime(?START_DATE);
         true ->
             ok
     end,
-    test_clock(system_time_after_set_rtc, fun() -> erlang:system_time(millisecond) end),
+    ok = test_time_unit_ratios(system_time, fun(Unit) -> erlang:system_time(Unit) end),
+    ok = test_time_unit_ratios(monotonic_time, fun(Unit) -> erlang:monotonic_time(Unit) end),
+    test_clock(system_time_after_set_rtc, fun() -> erlang:system_time(millisecond) end, 100, 500),
     NewDate = erlang:universaltime(),
     if
         NewDate >= ?START_DATE -> ok;
@@ -50,14 +65,33 @@ start() ->
     end,
     ok.
 
-test_clock(Case, Fun) ->
+% Readings coarsest-to-finest: finer value is always taken later so
+% finer >= coarser * scale.  Upper bound allows 1 ms between calls.
+test_time_unit_ratios(Case, Fun) ->
+    S = Fun(second),
+    Ms = Fun(millisecond),
+    Us = Fun(microsecond),
+    Ns = Fun(nanosecond),
+
+    Ms >= S * 1000 orelse throw({ratio_fail, Case, second_to_ms, S, Ms}),
+    Ms < S * 1000 + 1000 orelse throw({ratio_upper, Case, second_to_ms, S, Ms}),
+
+    Us >= Ms * 1000 orelse throw({ratio_fail, Case, ms_to_us, Ms, Us}),
+    Us < Ms * 1000 + 1000000 orelse throw({ratio_upper, Case, ms_to_us, Ms, Us}),
+
+    Ns >= Us * 1000 orelse throw({ratio_fail, Case, us_to_ns, Us, Ns}),
+    Ns < Us * 1000 + 1000000 orelse throw({ratio_upper, Case, us_to_ns, Us, Ns}),
+
+    ok.
+
+test_clock(Case, Fun, MinDelta, MaxDelta) ->
     StartTime = Fun(),
     receive
     after 100 -> ok
     end,
     EndTime = Fun(),
     Delta = EndTime - StartTime,
     if
-        Delta >= 100 andalso Delta < 500 -> ok;
+        Delta >= MinDelta andalso Delta < MaxDelta -> ok;
         true -> throw({unexpected_delta, Delta, Case, StartTime, EndTime})
     end.

tests/erlang_tests/test_monotonic_time.erl

@@ -28,9 +28,33 @@ start() ->
     after 1 -> ok
     end,
     T2 = erlang:monotonic_time(millisecond),
-    test_diff(T2 - T1).
+    1 = test_diff(T2 - T1),
+
+    N1 = erlang:monotonic_time(nanosecond),
+    receive
+    after 1 -> ok
+    end,
+    N2 = erlang:monotonic_time(nanosecond),
+    true = is_integer(N2 - N1) andalso (N2 - N1) >= 0,
+
+    ok = test_native_monotonic_time(),
+
+    1.
 
 test_diff(X) when is_integer(X) andalso X >= 0 ->
     1;
 test_diff(X) when X < 0 ->
     0.
+
+-if(?OTP_RELEASE >= 22).
+test_native_monotonic_time() ->
+    Na1 = erlang:monotonic_time(native),
+    receive
+    after 1 -> ok
+    end,
+    Na2 = erlang:monotonic_time(native),
+    true = is_integer(Na2 - Na1) andalso (Na2 - Na1) >= 0,
+    ok.
+-else.
+test_native_monotonic_time() -> ok.
+-endif.

tests/erlang_tests/test_system_time.erl

@@ -26,6 +26,10 @@ start() ->
     ok = test_system_time(second, 1001),
     ok = test_system_time(millisecond, 10),
     ok = test_system_time(microsecond, 1),
+    ok = test_system_time(nanosecond, 1),
+    ok = test_native_system_time(),
+
+    ok = test_time_unit_ratios(),
 
     ok = expect(fun() -> erlang:system_time(not_a_time_unit) end, badarg),
 
@@ -40,6 +44,34 @@ test_system_time(Unit, SleepMs) ->
     true = (After > Before),
     ok.
 
+test_system_time_unit(_Name, Fun) ->
+    T = Fun(),
+    true = is_integer(T) andalso T > 0,
+    ok.
+
+% Readings are taken coarsest-to-finest so the finer value is always >= the
+% coarser value * its scale factor.  The upper-bound allows for at most 1 ms
+% of wall-clock time between consecutive calls.
+test_time_unit_ratios() ->
+    S = erlang:system_time(second),
+    Ms = erlang:system_time(millisecond),
+    Us = erlang:system_time(microsecond),
+    Ns = erlang:system_time(nanosecond),
+
+    true = Ms >= S * 1000,
+    % within 1 s of each other
+    true = Ms < S * 1000 + 1000,
+
+    true = Us >= Ms * 1000,
+    % within 1 ms
+    true = Us < Ms * 1000 + 1000000,
+
+    true = Ns >= Us * 1000,
+    % within 1 ms
+    true = Ns < Us * 1000 + 1000000,
+
+    ok.
+
 verify_system_time_value(M) when is_integer(M) andalso M > 0 ->
     M.
 
@@ -76,4 +108,27 @@ test_system_time_to_universal_time() ->
 
     {{1969, 12, 31}, {23, 59, 59}} = calendar:system_time_to_universal_time(-1, second),
 
+    {{1970, 1, 1}, {0, 0, 0}} = calendar:system_time_to_universal_time(0, nanosecond),
+    {{1970, 1, 1}, {0, 0, 0}} = calendar:system_time_to_universal_time(1, nanosecond),
+    {{1970, 1, 1}, {0, 0, 1}} = calendar:system_time_to_universal_time(1000000000, nanosecond),
+    {{1970, 1, 1}, {0, 0, 1}} = calendar:system_time_to_universal_time(1001000000, nanosecond),
+    {{2023, 7, 8}, {20, 19, 39}} = calendar:system_time_to_universal_time(
+        1688847579000000000, nanosecond
+    ),
+
+    ok = test_native_universal_time(),
+
+    ok.
+
+-if(?OTP_RELEASE >= 22).
+test_native_system_time() ->
+    ok = test_system_time(native, 1).
+
+test_native_universal_time() ->
+    {{1970, 1, 1}, {0, 0, 0}} = calendar:system_time_to_universal_time(0, native),
+    {{1970, 1, 1}, {0, 0, 1}} = calendar:system_time_to_universal_time(1000000000, native),
     ok.
+-else.
+test_native_system_time() -> ok.
+test_native_universal_time() -> ok.
+-endif.