Merge pull request atomvm#579 from pguyot/w19/add-support-for-rtc-slow-memory

Add support for RTC Slow memory

Move rtc_slow_memory feature within AtomVM as it doesn't depend on an additional
esp-idf component.
(see https://github.com/atomvm/atomvm_lib/blob/master/src/atomvm_lib.erl#L38)

This implementation has the following differences with `atomvm_lib:set_rtc_memory/1`:
- it is enabled by default
- the memory is preserved across restarts
- the memory is not initialized (because it is preserved across restarts), so a checksum is used to ensure it is coherent.

These changes are made under both the "Apache 2.0" and the "GNU Lesser General
Public License 2.1 or later" license terms (dual license).

SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later

Author: bettio

.github/workflows/esp32-build.yaml

@@ -46,5 +46,14 @@ jobs:
         . $IDF_PATH/export.sh
         idf.py reconfigure
         idf.py build
-        # Print component size info
+        idf.py size
+    - name: Print component size info with idf.py
+      # size-components doesn't work with a .noinit section on 4.2.x branch.
+      # The bug was fixed on later versions and didn't occur on 4.0.x & 3.x
+      # https://github.com/espressif/esp-idf/issues/8428
+      if: matrix.build-system == 'idf' && matrix.idf-version != '4.2.3'
+      shell: bash
+      working-directory: ./src/platforms/esp32/
+      run: |
+        . $IDF_PATH/export.sh
         idf.py size-components

libs/eavmlib/src/esp.erl

@@ -37,6 +37,8 @@
     nvs_erase_key/1, nvs_erase_key/2,
     nvs_erase_all/0, nvs_erase_all/1,
     nvs_reformat/0,
+    rtc_slow_get_binary/0,
+    rtc_slow_set_binary/1,
     freq_hz/0
 ]).
 
@@ -225,6 +227,28 @@ nvs_erase_all(Namespace) when is_atom(Namespace) ->
 nvs_reformat() ->
     throw(nif_error).
 
+%%-----------------------------------------------------------------------------
+%% @returns the currently stored binary in RTC slow memory.
+%% @doc     Get the binary currently stored in RTC slow memory. Must not be
+%%          called unless the binary was stored with rtc_slow_set_binary/1.
+%%          A limited checksum is ran and this function may throw badarg if
+%%          the checksum is not valid.
+%% @end
+%%-----------------------------------------------------------------------------
+-spec rtc_slow_get_binary() -> binary().
+rtc_slow_get_binary() ->
+    throw(nif_error).
+
+%%-----------------------------------------------------------------------------
+%% @returns ok
+%% @doc     Store a binary to RTC slow memory. This memory is not erased on
+%%          software reset and deep sleeps.
+%% @end
+%%-----------------------------------------------------------------------------
+-spec rtc_slow_set_binary(Bin :: binary()) -> ok.
+rtc_slow_set_binary(Bin) when is_binary(Bin) ->
+    throw(nif_error).
+
 %%-----------------------------------------------------------------------------
 %% @returns Clock frequency (in hz)
 %% @doc     Return the clock frequency on the chip

src/platforms/esp32/components/avm_builtins/CMakeLists.txt

@@ -24,6 +24,7 @@ set(AVM_BUILTIN_COMPONENT_SRCS
     "ledc_nif.c"
     "network_driver.c"
     "nvs_nif.c"
+    "rtc_slow_nif.c"
     "socket_driver.c"
     "spi_driver.c"
     "uart_driver.c"

src/platforms/esp32/components/avm_builtins/Kconfig

@@ -32,6 +32,16 @@ config AVM_ENABLE_NVS_NIFS
     bool "Enable NVS NIFs"
     default y
 
+config AVM_ENABLE_RTC_SLOW_NIFS
+    bool "Enable RTC SLOW NIFs"
+    default y
+
+config AVM_RTC_SLOW_MAX_SIZE
+    int "RTC SLOW maximum binary size"
+    # By default, use the maximum size for esp-idf < 4.4
+    # In newer version, available size is 8170
+    default 4086
+
 config AVM_ENABLE_GPIO_PORT_DRIVER
     bool "Enable GPIO port driver"
     default y

src/platforms/esp32/components/avm_builtins/rtc_slow_nif.c

@@ -0,0 +1,117 @@
+/*
+ * This file is part of AtomVM.
+ *
+ * Copyright 2023 Paul Guyot <[email protected]>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
+ */
+
+#include <sdkconfig.h>
+#ifdef CONFIG_AVM_ENABLE_RTC_SLOW_NIFS
+
+#include <atom.h>
+#include <defaultatoms.h>
+#include <interop.h>
+#include <memory.h>
+#include <nifs.h>
+#include <stdlib.h>
+#include <term.h>
+
+#include <rom/crc.h>
+
+#include "esp32_sys.h"
+
+//#define ENABLE_TRACE
+#include "trace.h"
+
+#ifndef CONFIG_AVM_RTC_SLOW_MAX_SIZE
+#define CONFIG_AVM_RTC_SLOW_MAX_SIZE 4086
+#endif
+
+// Ensure checksum is incorrect when memory is zeroed.
+#define RTC_SLOW_CRC32_MAGIC 0x55555555
+
+RTC_NOINIT_ATTR uint32_t rtc_slow_data_checksum;
+RTC_NOINIT_ATTR uint16_t rtc_slow_data_size;
+RTC_NOINIT_ATTR uint8_t rtc_slow_data[CONFIG_AVM_RTC_SLOW_MAX_SIZE];
+
+static void rtc_slow_nif_init(GlobalContext *global);
+static const struct Nif *rtc_slow_nif_get_nif(const char *nifname);
+
+static term nif_esp_rtc_slow_get_binary(Context *ctx, int argc, term argv[])
+{
+    UNUSED(argc);
+    UNUSED(argv);
+    if (rtc_slow_data_size > sizeof(rtc_slow_data)) {
+        RAISE_ERROR(BADARG_ATOM);
+    }
+    uint32_t checksum = crc32_le(RTC_SLOW_CRC32_MAGIC, rtc_slow_data, rtc_slow_data_size);
+    if (checksum != rtc_slow_data_checksum) {
+        RAISE_ERROR(BADARG_ATOM);
+    }
+    if (UNLIKELY(memory_ensure_free(ctx, term_binary_data_size_in_terms(rtc_slow_data_size) + BINARY_HEADER_SIZE) != MEMORY_GC_OK)) {
+        RAISE_ERROR(OUT_OF_MEMORY_ATOM);
+    }
+
+    return term_from_literal_binary(rtc_slow_data, rtc_slow_data_size, ctx);
+}
+
+static term nif_esp_rtc_slow_set_binary(Context *ctx, int argc, term argv[])
+{
+    UNUSED(argc);
+    VALIDATE_VALUE(argv[0], term_is_binary);
+    term binary = argv[0];
+    size_t size = term_binary_size(binary);
+    if (size > sizeof(rtc_slow_data)) {
+        RAISE_ERROR(BADARG_ATOM);
+    }
+    const uint8_t *data = (const uint8_t *) term_binary_data(binary);
+    rtc_slow_data_checksum = crc32_le(RTC_SLOW_CRC32_MAGIC, data, size);
+    rtc_slow_data_size = size;
+    memcpy(rtc_slow_data, data, size);
+
+    return OK_ATOM;
+}
+
+static const struct Nif esp_rtc_slow_get_binary_nif = {
+    .base.type = NIFFunctionType,
+    .nif_ptr = nif_esp_rtc_slow_get_binary
+};
+static const struct Nif esp_rtc_slow_set_binary_nif = {
+    .base.type = NIFFunctionType,
+    .nif_ptr = nif_esp_rtc_slow_set_binary
+};
+
+void rtc_slow_nif_init(GlobalContext *gloabl)
+{
+    // no-op
+}
+
+const struct Nif *rtc_slow_nif_get_nif(const char *nifname)
+{
+    if (strcmp("esp:rtc_slow_get_binary/0", nifname) == 0) {
+        TRACE("Resolved platform nif %s ...\n", nifname);
+        return &esp_rtc_slow_get_binary_nif;
+    }
+    if (strcmp("esp:rtc_slow_set_binary/1", nifname) == 0) {
+        TRACE("Resolved platform nif %s ...\n", nifname);
+        return &esp_rtc_slow_set_binary_nif;
+    }
+    return NULL;
+}
+
+REGISTER_NIF_COLLECTION(rtc_slow, rtc_slow_nif_init, rtc_slow_nif_get_nif)
+
+#endif

src/platforms/esp32/test/main/test_erl_sources/CMakeLists.txt

@@ -36,17 +36,20 @@ function(compile_erlang module_name)
     set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${CMAKE_CURRENT_BINARY_DIR}/${module_name}.beam")
 endfunction()
 
+compile_erlang(test_rtc_slow)
 compile_erlang(test_socket)
 compile_erlang(test_time_and_processes)
 
 add_custom_command(
     OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/esp32_test_modules.avm"
     COMMAND HostAtomVM-prefix/src/HostAtomVM-build/tools/packbeam/PackBEAM -i esp32_test_modules.avm
         HostAtomVM-prefix/src/HostAtomVM-build/libs/atomvmlib.avm
+        test_rtc_slow.beam
         test_socket.beam
         test_time_and_processes.beam
     DEPENDS
         HostAtomVM
+        "${CMAKE_CURRENT_BINARY_DIR}/test_rtc_slow.beam"
         "${CMAKE_CURRENT_BINARY_DIR}/test_socket.beam"
         "${CMAKE_CURRENT_BINARY_DIR}/test_time_and_processes.beam"
     WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}

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

@@ -0,0 +1,73 @@
+%
+% This file is part of AtomVM.
+%
+% Copyright 2023 Paul Guyot <[email protected]>
+%
+% Licensed under the Apache License, Version 2.0 (the "License");
+% you may not use this file except in compliance with the License.
+% You may obtain a copy of the License at
+%
+%    http://www.apache.org/licenses/LICENSE-2.0
+%
+% Unless required by applicable law or agreed to in writing, software
+% distributed under the License is distributed on an "AS IS" BASIS,
+% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+% See the License for the specific language governing permissions and
+% limitations under the License.
+%
+% SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
+%
+
+-module(test_rtc_slow).
+-export([start/0]).
+
+-define(CONFIG_AVM_RTC_SLOW_MAX_SIZE, 1024).
+
+% Simply ensure rtc_slow nifs can be called
+start() ->
+    % During qemu tests, RTC Slow memory is initialized to 0.
+    % So the checksum is always wrong.
+    ok =
+        try
+            esp:rtc_slow_get_binary()
+        catch
+            error:badarg -> ok
+        end,
+    ok = esp:rtc_slow_set_binary(<<>>),
+    <<>> = esp:rtc_slow_get_binary(),
+    ok = esp:rtc_slow_set_binary(<<42>>),
+    <<42>> = esp:rtc_slow_get_binary(),
+    LargeBin16K = build_bin(16 * 1024),
+    ok =
+        try
+            esp:rtc_slow_set_binary(LargeBin16K),
+            should_fail
+        catch
+            error:badarg -> ok
+        end,
+    <<42>> = esp:rtc_slow_get_binary(),
+    LargeBinMax = build_bin(?CONFIG_AVM_RTC_SLOW_MAX_SIZE),
+    ok = esp:rtc_slow_set_binary(LargeBinMax),
+    LargeBinMaxPlusOne = build_bin(?CONFIG_AVM_RTC_SLOW_MAX_SIZE + 1),
+    ok =
+        try
+            esp:rtc_slow_set_binary(LargeBinMaxPlusOne),
+            should_fail
+        catch
+            error:badarg -> ok
+        end,
+    LargeBinMax = esp:rtc_slow_get_binary(),
+    % Make sure get/set is semantically correct, even with binaries that do not fit the heap
+    esp:rtc_slow_set_binary(<<42:1024>>),
+    X = esp:rtc_slow_get_binary(),
+    true = id(X) =:= <<42:1024>>,
+    esp:rtc_slow_set_binary(<<43:1024>>),
+    Y = esp:rtc_slow_get_binary(),
+    true = id(Y) =:= <<43:1024>>,
+    true = id(X) =:= <<42:1024>>,
+    0.
+
+build_bin(Len) ->
+    <<42:(Len * 8)>>.
+
+id(X) -> X.

src/platforms/esp32/test/main/test_main.c

@@ -212,6 +212,12 @@ TEST_CASE("test_socket", "[test_run]")
     eth_stop(eth_netif);
 }
 
+TEST_CASE("test_rtc_slow", "[test_run]")
+{
+    term ret_value = avm_test_case("test_rtc_slow.beam");
+    TEST_ASSERT(term_to_int(ret_value) == 0);
+}
+
 void app_main(void)
 {
     UNITY_BEGIN();

src/platforms/esp32/test/sdkconfig.defaults

@@ -2,3 +2,4 @@ CONFIG_PARTITION_TABLE_CUSTOM=y
 CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
 CONFIG_ESP_INT_WDT_TIMEOUT_MS=10000
 CONFIG_ETH_USE_OPENETH=y
+CONFIG_AVM_RTC_SLOW_MAX_SIZE=1024