fw/services/settings: add growable settings files

settings_file_open pre-allocates the PFS file at ~120% of
max_used_space, so a large per-app cap forces every persist file to
claim that much flash up front, even when most apps only use a few
hundred bytes. To make raising the cap cheap, decouple the enforcement
cap from the physical allocation.

Add an alloc_used_space field to SettingsFile that tracks the physical
allocation budget separately from max_used_space. A new
settings_file_open_growable() API sets alloc_used_space to a small
initial value. When a write needs more physical space but fits within
the enforcement cap, the file is automatically grown via rewrite with
doubling allocation (e.g. 4K -> 8K -> 16K -> ... up to max_used_space).

To prevent grown files from holding flash hostage indefinitely after
the data is no longer needed, settings_file_compact picks the smallest
doubling step that leaves ~2x headroom over live data and lowers
alloc_used_space toward the floor before rewriting. The new
min_alloc_used_space field tracks the per-file floor (the
initial_alloc_size requested at open) so files never shrink below the
caller's stated minimum. Existing callers of settings_file_open() are
unchanged: alloc_used_space and min_alloc_used_space both equal
max_used_space, preserving the old pre-allocation behavior with no
shrink.

The persist service now uses settings_file_open_growable() with a
4 KiB initial allocation (~5 KiB physical), close to the existing
6 KiB cap.

Co-Authored-By: Gerard Marull-Paretas <gerard@teslabs.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Gerard Marull-Paretas <gerard@teslabs.com>
Signed-off-by: Joshua Jun <lets@throw.rocks>

Author: 3 people

include/pbl/services/settings/settings_file.h

@@ -41,6 +41,16 @@ typedef struct SettingsFile {
   //! fail.
   int max_used_space;
 
+  //! The current allocation budget for physical file size. For growable files,
+  //! this starts at a small initial value and grows toward max_used_space on
+  //! demand. For non-growable files, this equals max_used_space.
+  int alloc_used_space;
+
+  //! The floor for alloc_used_space. Compact will not shrink below this. For
+  //! growable files this is the initial_alloc_size requested at open time;
+  //! for non-growable files this equals max_used_space (no shrink).
+  int min_alloc_used_space;
+
   //! Amount of space in the settings_file that is currently dead, i.e.
   //! has been written to with some data, but that data is no longer valid.
   //! (overwritten records get added to this)
@@ -69,6 +79,8 @@ typedef struct SettingsFile {
 //! ignored. We could change this if the need arises.
 status_t settings_file_open(SettingsFile *file, const char *name,
                             int max_used_space);
+status_t settings_file_open_growable(SettingsFile *file, const char *name,
+                                     int max_used_space, int initial_alloc_size);
 void settings_file_close(SettingsFile *file);
 
 bool settings_file_exists(SettingsFile *file, const void *key, size_t key_len);

src/fw/services/persist/service.c

@@ -20,6 +20,7 @@
 #include "util/units.h"
 
 #define PERSIST_STORAGE_MAX_SPACE KiBYTES(6)
+#define PERSIST_STORAGE_INITIAL_ALLOC KiBYTES(4)
 
 typedef struct PersistStore {
   ListNode  list_node;
@@ -124,7 +125,9 @@ SettingsFile * persist_service_lock_and_get_store(const Uuid *uuid) {
   if (!store->file_open) {
     char filename[PERSIST_FILE_NAME_MAX_LENGTH];
     PBL_ASSERTN(PASSED(prv_get_file_name(filename, sizeof(filename), uuid)));
-    PBL_ASSERTN(PASSED(settings_file_open(&store->file, filename, PERSIST_STORAGE_MAX_SPACE)));
+    PBL_ASSERTN(PASSED(settings_file_open_growable(&store->file, filename,
+                                                   PERSIST_STORAGE_MAX_SPACE,
+                                                   PERSIST_STORAGE_INITIAL_ALLOC)));
     store->file_open = true;
   }
   return &store->file;

src/fw/services/settings/settings_file.c

@@ -25,16 +25,17 @@ static bool file_hdr_is_uninitialized(SettingsFileHeader *file_hdr) {
       && (file_hdr->flags == 0xffff);
 }
 
-static status_t prv_open(SettingsFile *file, const char *name, uint8_t flags, int max_used_space) {
+static status_t prv_open(SettingsFile *file, const char *name, uint8_t flags,
+                          int max_used_space, int alloc_used_space,
+                          int min_alloc_used_space) {
   // Making the max_space_total at least a little bit larger than the
-  // max_used_space allows us to avoid thrashing. Without it, if
-  // max_space_total == max_used_space, then if the file is full, changing a
+  // alloc_used_space allows us to avoid thrashing. Without it, if
+  // max_space_total == alloc_used_space, then if the file is full, changing a
   // single value would force the whole file to be rewritten- every single
   // time! It's probably worth it to "waste" a bit of flash space to avoid
   // this pathalogical case.
-  int max_space_total = pfs_sector_optimal_size(max_used_space * 12 / 10, strlen(name));
+  int max_space_total = pfs_sector_optimal_size(alloc_used_space * 12 / 10, strlen(name));
 
-  // TODO: Dynamically sized files?
   int fd = pfs_open(name, flags, FILE_TYPE_STATIC, max_space_total);
   if (fd < 0) {
     PBL_LOG_ERR("Could not open settings file '%s', %d", name, fd);
@@ -50,6 +51,8 @@ static status_t prv_open(SettingsFile *file, const char *name, uint8_t flags, in
   *file = (SettingsFile) {
     .name = kernel_strdup_check(name),
     .max_used_space = max_used_space,
+    .alloc_used_space = alloc_used_space,
+    .min_alloc_used_space = min_alloc_used_space,
     .max_space_total = max_space_total,
   };
 
@@ -73,32 +76,37 @@ static status_t prv_open(SettingsFile *file, const char *name, uint8_t flags, in
     PBL_LOG_WRN("Unrecognized version %d for file %s, removing...",
             file_hdr.version, name);
     pfs_close_and_remove(fd);
-    return prv_open(file, name, flags, max_used_space);
+    return prv_open(file, name, flags, max_used_space, alloc_used_space, min_alloc_used_space);
+  }
+
+  // For growable files, adopt the actual file size before bootup_check so that
+  // any compaction during recovery uses the correct (grown) allocation size.
+  int actual_size = pfs_get_file_size(file->iter.fd);
+  if (alloc_used_space < max_used_space && actual_size > max_space_total) {
+    file->alloc_used_space = actual_size * 10 / 12;
+    file->max_space_total = actual_size;
   }
 
   status_t status = bootup_check(file);
   if (status < 0) {
     PBL_LOG_ERR("Bootup check failed (%"PRId32"), not good. "
             "Attempting to recover by deleting %s...", status, name);
     pfs_close_and_remove(fd);
-    return prv_open(file, name, flags, max_used_space);
+    return prv_open(file, name, flags, max_used_space, alloc_used_space, min_alloc_used_space);
   }
 
   // There's a chance that the caller increased the desired size of the settings file since
   // the file was originally created (i.e. the file was created in an earlier version of the
   // firmware). If we detect that situation, let's re-write the file to the new larger requested
   // size.
-  int actual_size = pfs_get_file_size(file->iter.fd);
-  if (actual_size < max_space_total) {
+  if (alloc_used_space >= max_used_space && actual_size < max_space_total) {
     PBL_LOG_INFO("Re-writing settings file %s to increase its size from %d to %d.",
             name, actual_size, max_space_total);
-    // The settings_file_rewrite_filtered call creates a new file based on file->max_used_space
-    // and copies the contents of the existing file into it.
     status = settings_file_rewrite_filtered(file, NULL, NULL);
     if (status < 0) {
       PBL_LOG_ERR("Could not resize file %s (error %"PRId32"). Creating new one",
               name, status);
-      return prv_open(file, name, flags, max_used_space);
+      return prv_open(file, name, flags, max_used_space, alloc_used_space, min_alloc_used_space);
     }
   }
 
@@ -109,7 +117,16 @@ static status_t prv_open(SettingsFile *file, const char *name, uint8_t flags, in
 
 status_t settings_file_open(SettingsFile *file, const char *name,
                             int max_used_space) {
-  return prv_open(file, name, OP_FLAG_READ | OP_FLAG_WRITE, max_used_space);
+  return prv_open(file, name, OP_FLAG_READ | OP_FLAG_WRITE,
+                  max_used_space, max_used_space, max_used_space);
+}
+
+status_t settings_file_open_growable(SettingsFile *file, const char *name,
+                                     int max_used_space, int initial_alloc_size) {
+  // prv_grow doubles alloc_used_space; a zero seed would loop forever.
+  PBL_ASSERTN(initial_alloc_size > 0);
+  return prv_open(file, name, OP_FLAG_READ | OP_FLAG_WRITE,
+                  max_used_space, initial_alloc_size, initial_alloc_size);
 }
 
 void settings_file_close(SettingsFile *file) {
@@ -199,7 +216,8 @@ status_t settings_file_rewrite_filtered(
 
   SettingsFile new_file;
   status_t status = prv_open(&new_file, file->name, OP_FLAG_OVERWRITE | OP_FLAG_READ,
-                             file->max_used_space);
+                             file->max_used_space, file->alloc_used_space,
+                             file->min_alloc_used_space);
   if (status < 0) {
     PBL_LOG_ERR("Could not open temporary file to compact settings file. Error %"PRIi32".",
             status);
@@ -253,8 +271,11 @@ status_t settings_file_rewrite_filtered(
   // old file. After the close suceeds, we will end up reading the new
   // (compacted) file.
   char *name = kernel_strdup(new_file.name);
+  int alloc_used_space = new_file.alloc_used_space;
+  int min_alloc_used_space = new_file.min_alloc_used_space;
   settings_file_close(&new_file);
-  status = prv_open(file, name, OP_FLAG_READ | OP_FLAG_WRITE, file->max_used_space);
+  status = prv_open(file, name, OP_FLAG_READ | OP_FLAG_WRITE,
+                    file->max_used_space, alloc_used_space, min_alloc_used_space);
   kernel_free(name);
 
   // FIRM-1649: instrumentation. See note at the top of this function.
@@ -272,7 +293,29 @@ void settings_file_set_change_callback(SettingsFileChangeCallback callback) {
 }
 
 T_STATIC status_t settings_file_compact(SettingsFile *file) {
-  return settings_file_rewrite_filtered(file, NULL, NULL);
+  // For growable files, drop alloc_used_space toward the floor when live data
+  // is much smaller than the current allocation. Without this, a file that
+  // burst to e.g. 256 KiB and then idled would hold that flash forever even
+  // after the records were deleted, slowly bleeding free PFS space across
+  // device lifetime. Aim for the smallest doubling step that leaves ~2x
+  // headroom over used_space; the next grow cycle will re-expand if needed.
+  const int old_alloc = file->alloc_used_space;
+  if (file->alloc_used_space > file->min_alloc_used_space) {
+    int target = file->min_alloc_used_space;
+    while (target < file->used_space * 2 && target < file->alloc_used_space) {
+      target *= 2;
+    }
+    if (target < file->alloc_used_space) {
+      file->alloc_used_space = target;
+    }
+  }
+  status_t status = settings_file_rewrite_filtered(file, NULL, NULL);
+  if (status < 0) {
+    // rewrite_filtered fails before the swap if it fails at all; the on-disk
+    // file is still at old_alloc, so put the in-memory book-keeping back.
+    file->alloc_used_space = old_alloc;
+  }
+  return status;
 }
 
 static bool key_matches(SettingsRawIter *iter, const uint8_t *key, int key_len) {
@@ -420,6 +463,27 @@ status_t settings_file_set_byte(SettingsFile *file, const void *key,
   return S_SUCCESS;
 }
 
+static status_t prv_grow(SettingsFile *file, int needed_used_space) {
+  int new_alloc = file->alloc_used_space;
+  while (new_alloc < needed_used_space && new_alloc < file->max_used_space) {
+    new_alloc *= 2;
+  }
+  if (new_alloc > file->max_used_space) {
+    new_alloc = file->max_used_space;
+  }
+  if (new_alloc < needed_used_space) {
+    return E_OUT_OF_STORAGE;
+  }
+
+  int old_alloc = file->alloc_used_space;
+  file->alloc_used_space = new_alloc;
+  status_t status = settings_file_rewrite_filtered(file, NULL, NULL);
+  if (status < 0) {
+    file->alloc_used_space = old_alloc;
+  }
+  return status;
+}
+
 // Internal implementation that takes a timestamp parameter
 // Note that this operation is designed to be atomic from the perspective of
 // an outside observer. That is, either the new value will be completely
@@ -443,7 +507,14 @@ static status_t prv_settings_file_set_internal(SettingsFile *file, const void *k
     return E_OUT_OF_STORAGE;
   }
   if (file->used_space + file->dead_space + rec_size > file->max_space_total) {
-    status_t status = settings_file_compact(file);
+    bool needs_growth = (file->used_space + rec_size > file->max_space_total) &&
+                        (file->alloc_used_space < file->max_used_space);
+    status_t status;
+    if (needs_growth) {
+      status = prv_grow(file, file->used_space + rec_size);
+    } else {
+      status = settings_file_compact(file);
+    }
     if (status < 0) {
       return status;
     }
@@ -612,7 +683,8 @@ status_t settings_file_rewrite(SettingsFile *file,
   SettingsFile new_file;
   status_t status = prv_open(&new_file, file->name,
                              OP_FLAG_OVERWRITE | OP_FLAG_READ,
-                             file->max_used_space);
+                             file->max_used_space, file->alloc_used_space,
+                             file->min_alloc_used_space);
   if (status < 0) {
     return status;
   }
@@ -628,8 +700,11 @@ status_t settings_file_rewrite(SettingsFile *file,
   // old file. After the close suceeds, we will end up reading the new
   // (compacted) file.
   char *name = kernel_strdup(new_file.name);
+  int alloc_used_space = new_file.alloc_used_space;
+  int min_alloc_used_space = new_file.min_alloc_used_space;
   settings_file_close(&new_file);
-  status = prv_open(file, name, OP_FLAG_READ | OP_FLAG_WRITE, file->max_used_space);
+  status = prv_open(file, name, OP_FLAG_READ | OP_FLAG_WRITE,
+                    file->max_used_space, alloc_used_space, min_alloc_used_space);
   kernel_free(name);
 
   return status;

tests/fakes/fake_settings_file.c

@@ -103,6 +103,11 @@ status_t settings_file_open(SettingsFile *file, const char *name,
   }
 }
 
+status_t settings_file_open_growable(SettingsFile *file, const char *name,
+                                     int max_used_space, int initial_alloc_size) {
+  return settings_file_open(file, name, max_used_space);
+}
+
 void settings_file_close(SettingsFile *file) {
   cl_assert(s_settings_file.open);
   s_settings_file.open = false;