Storage & NVS

AtomVM provides persistent storage capabilities primarily through integration with the Espressif IoT Development Framework (IDF) for ESP32-based devices. This system allows Erlang and Elixir applications to store data across reboots using Non-Volatile Storage (NVS) and partition-based flash access. These integrations are implemented as AtomVM Native Implemented Functions (NIFs), providing a bridge between the high-level BEAM bytecode and low-level hardware storage drivers.

Sources: src/platforms/esp32/README.md, doc/src/atomvm-internals.md:129-130

Storage Architecture on ESP32

The storage system in AtomVM for ESP32 is built upon the physical layout of the flash module, which is organized by a partition map. This map defines how different regions of the flash are utilized, ranging from the bootloader to application data.

Flash Layout and Partitions

The ESP32 flash is divided into several logical segments. While the bootloader and virtual machine reside in early sectors, the application code (BEAM bytecode) and user data are stored in specific partitions.

The virtual machine looks for BEAM modules in the data partition starting at 0x210000 (for thin images) or 0x250000 (for Elixir-enabled images). User-specific data persistence is typically handled by the NVS component.

Sources: doc/src/getting-started-guide.md:73-95

Non-Volatile Storage (NVS)

NVS is a specific integration that allows Erlang/Elixir applications to store key-value pairs in a dedicated flash partition. This is highly useful for storing configuration data, credentials, or state information that must survive power cycles.

NVS Features

NVS in AtomVM supports:

• Persistent storage of simple data types.
• Namespace isolation to prevent key collisions between different modules.
• Integration via the nvs_nif.c component.

Sources: src/platforms/esp32/README.md, src/platforms/esp32/components/avm_builtins/nvs_nif.c

Partition-Based Storage

Beyond key-value storage in NVS, AtomVM provides access to raw or structured partitions via the storage_nif.c component. This allows the VM to interact with defined regions of the flash memory as mapped in the ESP32 partition table.

Data Flow for Storage Operations

When an Erlang process requests a storage operation, it traverses the following path:

Implementation Details

The storage components are part of the "AtomVM Built-In Components". Developers can customize the inclusion of these features to optimize for memory constraints.

Component Management

Because AtomVM is designed for resource-constrained micro-controllers, storage integrations are modular.

• GPIO, UART, I2C, SPI, NVS, and Storage are all optional integrations.
• Excluding unneeded storage NIFs reduces the linked code size, improving flash time and potentially decreasing RAM usage.
• Configuration is performed via the IDF menuconfig tool under the "AtomVM Built-In Components" menu.

Sources: src/platforms/esp32/README.md

Storage in JIT Context

On platforms like the Raspberry Pi Pico (RP2), the storage system is also utilized by the Just-In-Time (JIT) compiler. The JIT compiler can stream generated machine code to the flash memory (embedded JIT), allowing native code to persist across reboots. This uses a jit_stream_flash implementation to manage the writing of executable code into storage areas.

Sources: doc/src/atomvm-internals.md:180-195

Summary

The Storage & NVS system in AtomVM provides a bridge between the functional world of Erlang/Elixir and the hardware-specific persistence mechanisms of micro-controllers. By leveraging ESP-IDF partitions and NVS namespaces through optimized NIFs, AtomVM ensures that applications can maintain state and configuration while allowing developers to minimize the firmware footprint by toggling specific storage features.