Source   Edit  

Persistent Storage Module for libDaisy

This module wraps libDaisy's PersistentStorage<T> template class to provide type-safe, non-volatile storage of settings in QSPI flash memory.

Features:

• Automatic dirty detection (only saves if settings changed)
• Factory defaults restoration
• State tracking (UNKNOWN, FACTORY, USER)
• Memory-mapped QSPI access (no explicit erase needed)
• Cache invalidation for DMA safety

Requirements:

• Settings struct MUST use POD (Plain Old Data) types only
• No pointers, Nim strings, seqs, or ref types
• Use C-compatible types: cfloat, cint, uint8, uint16, etc.
• Settings struct MUST implement C++ operator== for dirty detection
• Settings struct MUST implement C++ operator!=

About the C++ Operator Requirement:

PersistentStorage uses C++ operator== internally to detect if settings have changed. This is called "dirty detection" - the save() method only writes to flash if the settings are different from what's already stored.

Why you need a {.emit.} block:

Nim cannot export C++ operators using {.exportcpp.} or {.exportc.} because Nim's FFI doesn't support the exact C++ operator syntax required. The generated code would have Nim calling conventions and wrong parameter types.

Therefore, you MUST define the operators in a small {.emit.} block:

type
  MySettings {.bycopy, exportc: "MySettings".} = object
    param1 {.exportc.}: cfloat
    param2 {.exportc.}: uint8

# This emit block is REQUIRED - no pure-Nim alternative exists
{.emit: """
inline bool operator==(const MySettings& a, const MySettings& b) {
  return a.param1 == b.param1 && a.param2 == b.param2;
}
inline bool operator!=(const MySettings& a, const MySettings& b) {
  return !(a == b);
}
""".}

This is NOT boilerplate - it's a necessary FFI boundary for C++ interop. See examples/settings_manager.nim for a complete working example.

QSPI Flash Layout:

• Each PersistentStorage instance uses sizeof(SettingsStruct) + 4 bytes
• Extra 4 bytes store the state (UNKNOWN/FACTORY/USER)
• Address offset must be page-aligned (256 bytes)
• Seed 1.0: 1MB flash (IS25LP080D)
• Seed 1.1+: 8MB flash (IS25LP064A)

Usage Example:

import nimphea
import nimphea/per/qspi
import nimphea_persistent_storage

# Define settings struct (POD types only!)
type
  SynthSettings {.bycopy, exportc: "SynthSettings".} = object
    gain {.exportc.}: cfloat
    frequency {.exportc.}: cfloat
    waveform {.exportc.}: uint8

# Implement C++ comparison operators (REQUIRED for dirty detection)
# This cannot be done in pure Nim - emit block is necessary
{.emit: """
inline bool operator==(const SynthSettings& a, const SynthSettings& b) {
  return a.gain == b.gain &&
         a.frequency == b.frequency &&
         a.waveform == b.waveform;
}
inline bool operator!=(const SynthSettings& a, const SynthSettings& b) {
  return !(a == b);
}
""".}

# Initialize QSPI in memory-mapped mode
var qspi: QSPIHandle
var qspiConfig = QSPIConfig(
  device: QSPIDevice.IS25LP064A,
  mode: QSPIMode.MEMORY_MAPPED
)
discard qspi.init(qspiConfig)

# Create persistent storage
var storage = newPersistentStorage[SynthSettings](qspi)

# Initialize with factory defaults
let defaults = SynthSettings(
  gain: 0.5,
  frequency: 440.0,
  waveform: 0
)
storage.init(defaults, address_offset = 0)

# Check state
if storage.getState() == FACTORY:
  echo "First boot - using factory settings"
else:
  echo "User settings loaded"

# Modify settings
storage.getSettings().gain = 0.8
storage.getSettings().frequency = 880.0

# Save to flash (only writes if changed)
storage.save()

# Restore factory defaults
storage.restoreDefaults()

Important Notes:

• QSPI MUST be initialized in MEMORY_MAPPED mode for PersistentStorage
• Save operations can take ~100ms due to erase/write operations
• Do NOT call save() from audio callback (causes audio glitches)
• Each save performs sector erase (~50ms) + write (~50ms)
• Settings struct size is limited by available flash space

Memory Layout Example:

Flash Address 0x00000000: [State: 4 bytes][SettingsStruct: N bytes]
Flash Address 0x00000100: [State: 4 bytes][NextSettings: N bytes]
...