Harden nRF52 filesystem recovery and flash writes

This commit is contained in:
mikecarper committed 2026-09-22 15:17:39 -07:00
1 parent 6a75e2a861
commit 47af95b4b2
24 files changed
+1220 -218

No files matched your search

+28 -20
View File
@@ -18,6 +18,7 @@ namespace mesh {
*/
class AtomicFileWriter {
static const size_t TEMP_PATH_CAPACITY = 96;
static const uint8_t VALIDATION_ATTEMPTS = 3;
FILESYSTEM* _fs;
const char* _target_path;
@@ -31,7 +32,7 @@ class AtomicFileWriter {
static uint32_t updateCRC32(uint32_t crc, const uint8_t* data, size_t len);
void removeTempFile();
bool validateTempFile();
bool validateFile(const char* path);
public:
AtomicFileWriter(FILESYSTEM* fs, const char* target_path);
@@ -76,28 +77,31 @@ void AtomicFileWriter::removeTempFile() {
}
}
bool AtomicFileWriter::validateTempFile() {
File verify(*_fs);
if (!verify.open(_temp_path, FILE_O_READ)) return false;
bool AtomicFileWriter::validateFile(const char* path) {
for (uint8_t attempt = 0; attempt < VALIDATION_ATTEMPTS; ++attempt) {
File verify(*_fs);
if (!verify.open(path, FILE_O_READ)) continue;
bool valid = verify.size() == _bytes_written;
uint32_t read_crc = 0xFFFFFFFFUL;
size_t remaining = _bytes_written;
uint8_t buf[64];
bool valid = verify.size() == _bytes_written;
uint32_t read_crc = 0xFFFFFFFFUL;
size_t remaining = _bytes_written;
uint8_t buf[64];
while (valid && remaining > 0) {
size_t chunk = remaining < sizeof(buf) ? remaining : sizeof(buf);
int count = verify.read(buf, (uint16_t)chunk);
if (count != (int)chunk) {
valid = false;
break;
while (valid && remaining > 0) {
size_t chunk = remaining < sizeof(buf) ? remaining : sizeof(buf);
int count = verify.read(buf, (uint16_t)chunk);
if (count != (int)chunk) {
valid = false;
break;
}
read_crc = updateCRC32(read_crc, buf, chunk);
remaining -= chunk;
}
read_crc = updateCRC32(read_crc, buf, chunk);
remaining -= chunk;
}
verify.close();
return valid && remaining == 0 && read_crc == _crc;
verify.close();
if (valid && remaining == 0 && read_crc == _crc) return true;
}
return false;
}
AtomicFileWriter::AtomicFileWriter(FILESYSTEM* fs, const char* target_path)
@@ -166,8 +170,12 @@ bool AtomicFileWriter::commit(bool content_valid) {
_opened = false;
}
if (success) success = validateTempFile();
if (success) success = validateFile(_temp_path);
if (success) success = _fs->rename(_temp_path, _target_path);
// A lower layer can acknowledge a metadata update before the physical page
// is durable. Validate the public filename too; callers must never clear a
// dirty flag or announce success while the old/corrupt file is still live.
if (success) success = validateFile(_target_path);
if (!success) removeTempFile();
_finished = true;
+20 -6
View File
@@ -24,18 +24,30 @@ bool IdentityStore::recover(const char* name) {
}
bool IdentityStore::load(const char *name, mesh::LocalIdentity& id) {
return load(name, id, nullptr, 0);
return loadResult(name, id) == IdentityLoadResult::Loaded;
}
bool IdentityStore::load(const char *name, mesh::LocalIdentity& id, char display_name[], int max_name_sz) {
return loadResult(name, id, display_name, max_name_sz)
== IdentityLoadResult::Loaded;
}
IdentityLoadResult IdentityStore::loadResult(
const char *name, mesh::LocalIdentity& id) {
return loadResult(name, id, nullptr, 0);
}
IdentityLoadResult IdentityStore::loadResult(
const char *name, mesh::LocalIdentity& id, char display_name[],
int max_name_sz) {
char filename[40];
if (snprintf(filename, sizeof(filename), "%s/%s.id", _dir, name)
>= (int)sizeof(filename)) return false;
>= (int)sizeof(filename)) return IdentityLoadResult::Unreadable;
for (unsigned attempt = 0; attempt < IO_ATTEMPTS; ++attempt) {
if (!recover(name)) continue;
bool present = false;
if (!mesh::filePresence(_fs, filename, present)) continue;
if (!present) return false;
if (!present) return IdentityLoadResult::Missing;
#if defined(RP2040_PLATFORM)
File file = _fs->open(filename, "r");
#else
@@ -62,10 +74,12 @@ bool IdentityStore::load(const char *name, mesh::LocalIdentity& id, char display
}
file.close();
id = loaded;
return true;
return IdentityLoadResult::Loaded;
}
// Callers may provision a replacement after bounded recovery is exhausted.
return false;
// An existing file which cannot be read is materially different from a
// fresh device. Startup callers must preserve it instead of replacing the
// radio's private key after a transient or localized flash failure.
return IdentityLoadResult::Unreadable;
}
bool IdentityStore::saveWithRetry(const char* name, const mesh::LocalIdentity& id) {
+12
View File
@@ -1,5 +1,7 @@
#pragma once
#include <stdint.h>
#if defined(ESP32) || defined(RP2040_PLATFORM)
#include <FS.h>
#define FILESYSTEM fs::FS
@@ -11,18 +13,28 @@
#endif
#include <Identity.h>
enum class IdentityLoadResult : uint8_t {
Loaded,
Missing,
Unreadable,
};
class IdentityStore {
FILESYSTEM* _fs;
const char* _dir;
public:
static constexpr unsigned IO_ATTEMPTS = 3;
IdentityStore(FILESYSTEM& fs, const char* dir): _fs(&fs), _dir(dir) { }
void useFileSystem(FILESYSTEM& fs) { _fs = &fs; }
void begin() {
if (_dir && _dir[0] == '/') { _fs->mkdir(_dir); } }
// Recover an interrupted non-replacing rename before deciding this is a
// fresh identity. False means the previous image must remain protected.
bool recover(const char* name);
IdentityLoadResult loadResult(const char *name, mesh::LocalIdentity& id);
IdentityLoadResult loadResult(const char *name, mesh::LocalIdentity& id,
char display_name[], int max_name_sz);
bool load(const char *name, mesh::LocalIdentity& id);
bool load(const char *name, mesh::LocalIdentity& id, char display_name[], int max_name_sz);
bool save(const char *name, const mesh::LocalIdentity& id);
+7
View File
@@ -0,0 +1,7 @@
#pragma once
#if defined(NRF52_PLATFORM)
extern "C" bool mesh_flash_nrf5x_flush_checked(void);
#endif
+112
View File
@@ -0,0 +1,112 @@
#pragma once
#if defined(NRF52_PLATFORM)
#include <InternalFileSystem.h>
#include <flash/flash_nrf5x.h>
#include <helpers/IdentityStore.h>
#include <helpers/nrf52/InternalSecondaryFsRepair.h>
namespace mesh {
namespace storage {
#if defined(NRF52840_XXAA)
static const uint32_t INTERNAL_PRIMARY_FS_START = 0xED000UL;
#else
static const uint32_t INTERNAL_PRIMARY_FS_START = 0x6D000UL;
#endif
static const uint32_t INTERNAL_PRIMARY_FS_SIZE =
7UL * FLASH_NRF52_PAGE_SIZE;
static const uint8_t INTERNAL_PRIMARY_FS_MOUNT_ATTEMPTS = 3;
// InternalFileSystem::begin() formats after one failed mount. Identity storage
// instead gets several non-destructive mount attempts and is formatted only
// when every word in the complete reserved range is still erased.
inline InternalSecondaryFsBootResult beginInternalPrimaryFilesystemSafely(
InternalFileSystem& fs, struct lfs_config* config = nullptr) {
const auto mount_with_retries = [&fs, config]() -> bool {
for (uint8_t attempt = 0; attempt < INTERNAL_PRIMARY_FS_MOUNT_ATTEMPTS;
++attempt) {
if (attempt != 0) fs.end();
const bool mounted = config == nullptr
? fs.Adafruit_LittleFS::begin()
: fs.Adafruit_LittleFS::begin(config);
if (mounted) return true;
}
return false;
};
InternalSecondaryFsBootResult result = prepareInternalSecondaryFilesystem(
mount_with_retries,
[]() -> bool {
return isErasedFlashRange(
INTERNAL_PRIMARY_FS_START, INTERNAL_PRIMARY_FS_SIZE,
[](uint32_t address) -> uint32_t {
return *reinterpret_cast<const volatile uint32_t*>(address);
});
},
[&fs]() -> bool {
fs.end();
return fs.format();
});
if (result == InternalSecondaryFsBootResult::Mounted
|| result == InternalSecondaryFsBootResult::InitializedBlank) {
return result;
}
// A node which can never leave startup is not useful. Give transient flash
// or SoftDevice contention three widely spaced chances to clear before the
// explicitly authorized last resort: erase the unusable primary store.
for (uint8_t retry = 0; retry < 3; ++retry) {
delay(3000);
fs.end();
const bool mounted = config == nullptr
? fs.Adafruit_LittleFS::begin()
: fs.Adafruit_LittleFS::begin(config);
if (mounted) return InternalSecondaryFsBootResult::Mounted;
}
fs.end();
if (!fs.format() || !mount_with_retries()) {
return InternalSecondaryFsBootResult::InitializationFailed;
}
return InternalSecondaryFsBootResult::ReinitializedUnreadable;
}
inline bool internalPrimaryFilesystemReady(
InternalSecondaryFsBootResult result) {
return result == InternalSecondaryFsBootResult::Mounted
|| result == InternalSecondaryFsBootResult::InitializedBlank
|| result == InternalSecondaryFsBootResult::ReinitializedUnreadable;
}
template <typename LoadIdentity>
IdentityLoadResult loadIdentityWithPrimaryRecovery(
InternalFileSystem& fs, LoadIdentity load_identity,
struct lfs_config* config = nullptr) {
IdentityLoadResult result = load_identity();
if (result != IdentityLoadResult::Unreadable) return result;
for (uint8_t retry = 0; retry < 3; ++retry) {
delay(3000);
result = load_identity();
if (result != IdentityLoadResult::Unreadable) return result;
}
fs.end();
if (!fs.format()) return IdentityLoadResult::Unreadable;
for (uint8_t attempt = 0; attempt < INTERNAL_PRIMARY_FS_MOUNT_ATTEMPTS;
++attempt) {
if (attempt != 0) fs.end();
const bool mounted = config == nullptr
? fs.Adafruit_LittleFS::begin()
: fs.Adafruit_LittleFS::begin(config);
if (mounted) return load_identity();
}
return IdentityLoadResult::Unreadable;
}
} // namespace storage
} // namespace mesh
#endif // NRF52_PLATFORM
@@ -38,6 +38,7 @@ bool isErasedFlashRange(uint32_t start, uint32_t size, ReadWord read_word) {
enum class InternalSecondaryFsBootResult {
Mounted,
InitializedBlank,
ReinitializedUnreadable,
PreservedNonBlank,
InitializationFailed,
};
+92
View File
@@ -0,0 +1,92 @@
#pragma once
#if defined(NRF52_PLATFORM)
#include <Adafruit_LittleFS.h>
#include <new>
#include <stdint.h>
#include <string.h>
namespace mesh {
namespace storage {
static constexpr char BAD_FILESYSTEM_NODE_NAME[] = "bad file system";
// Emergency-only volatile storage. It is allocated only after physical
// primary flash has failed every retry and a destructive reinitialization.
// Eight KiB is enough for identity/preferences and basic node operation while
// keeping the normal boot's RAM footprint unchanged.
class RamFallbackFileSystem {
static constexpr uint32_t BLOCK_SIZE = 128;
static constexpr uint32_t STORAGE_SIZE = 8UL * 1024UL;
alignas(4) uint8_t _storage[STORAGE_SIZE];
struct lfs_config _config;
Adafruit_LittleFS _filesystem;
static RamFallbackFileSystem* owner(const struct lfs_config* config) {
return static_cast<RamFallbackFileSystem*>(config->context);
}
static bool validRange(lfs_block_t block, lfs_off_t off, lfs_size_t size) {
return block < STORAGE_SIZE / BLOCK_SIZE && off <= BLOCK_SIZE
&& size <= BLOCK_SIZE - off;
}
static int read(const struct lfs_config* config, lfs_block_t block,
lfs_off_t off, void* buffer, lfs_size_t size) {
if (!validRange(block, off, size)) return LFS_ERR_IO;
memcpy(buffer, owner(config)->_storage + block * BLOCK_SIZE + off, size);
return 0;
}
static int program(const struct lfs_config* config, lfs_block_t block,
lfs_off_t off, const void* buffer, lfs_size_t size) {
if (!validRange(block, off, size)) return LFS_ERR_IO;
uint8_t* destination = owner(config)->_storage + block * BLOCK_SIZE + off;
const uint8_t* source = static_cast<const uint8_t*>(buffer);
for (lfs_size_t i = 0; i < size; ++i) destination[i] &= source[i];
return 0;
}
static int erase(const struct lfs_config* config, lfs_block_t block) {
if (!validRange(block, 0, BLOCK_SIZE)) return LFS_ERR_IO;
memset(owner(config)->_storage + block * BLOCK_SIZE, 0xFF, BLOCK_SIZE);
return 0;
}
static int sync(const struct lfs_config*) { return 0; }
public:
RamFallbackFileSystem() : _config{}, _filesystem(&_config) {
memset(_storage, 0xFF, sizeof(_storage));
_config.context = this;
_config.read = read;
_config.prog = program;
_config.erase = erase;
_config.sync = sync;
_config.read_size = 16;
_config.prog_size = 16;
_config.block_size = BLOCK_SIZE;
_config.block_count = STORAGE_SIZE / BLOCK_SIZE;
_config.lookahead = 64;
}
bool begin() {
return _filesystem.format() && _filesystem.begin();
}
Adafruit_LittleFS& filesystem() { return _filesystem; }
};
inline RamFallbackFileSystem* createRamFallbackFileSystem() {
RamFallbackFileSystem* fallback = new (std::nothrow) RamFallbackFileSystem();
if (fallback != nullptr && fallback->begin()) return fallback;
delete fallback;
return nullptr;
}
} // namespace storage
} // namespace mesh
#endif // NRF52_PLATFORM