Renamed lfs_fs_findfreeblocks -> lfs_fs_gc, tweaked documentation

The idea is in the future this function may be extended to support other
block janitorial work. In such a case calling this lfs_fs_gc provides a
more general name that can include other operations.

This is currently just wishful thinking, however.

lfs.c

@@ -623,7 +623,7 @@ static void lfs_alloc_drop(lfs_t *lfs) {
 }
 
 #ifndef LFS_READONLY
-static int lfs_fs_rawfindfreeblocks(lfs_t *lfs) {
+static int lfs_fs_rawgc(lfs_t *lfs) {
     // Move free offset at the first unused block (lfs->free.i)
     // lfs->free.i is equal lfs->free.size when all blocks are used
     lfs->free.off = (lfs->free.off + lfs->free.i) % lfs->cfg->block_count;
@@ -674,7 +674,7 @@ static int lfs_alloc(lfs_t *lfs, lfs_block_t *block) {
             return LFS_ERR_NOSPC;
         }
 
-        int err = lfs_fs_rawfindfreeblocks(lfs);
+        int err = lfs_fs_rawgc(lfs);
         if(err) {
             return err;
         }
@@ -6201,16 +6201,16 @@ int lfs_fs_traverse(lfs_t *lfs, int (*cb)(void *, lfs_block_t), void *data) {
 }
 
 #ifndef LFS_READONLY
-int lfs_fs_findfreeblocks(lfs_t *lfs) {
+int lfs_fs_gc(lfs_t *lfs) {
     int err = LFS_LOCK(lfs->cfg);
     if (err) {
         return err;
     }
-    LFS_TRACE("lfs_fs_findfreeblocks(%p)", (void*)lfs);
+    LFS_TRACE("lfs_fs_gc(%p)", (void*)lfs);
 
-    err = lfs_fs_rawfindfreeblocks(lfs);
+    err = lfs_fs_rawgc(lfs);
 
-    LFS_TRACE("lfs_fs_findfreeblocks -> %d", err);
+    LFS_TRACE("lfs_fs_gc -> %d", err);
     LFS_UNLOCK(lfs->cfg);
     return err;
 }

lfs.h

@@ -705,12 +705,17 @@ lfs_ssize_t lfs_fs_size(lfs_t *lfs);
 // Returns a negative error code on failure.
 int lfs_fs_traverse(lfs_t *lfs, int (*cb)(void*, lfs_block_t), void *data);
 
-// Use Traverse function and try to find free blocks. LittleFS free blocks
-// search is unpredictable.
+// Attempt to proactively find free blocks
 //
-// Search is costly operation which may delay write. In realtime write
-// scenarios can be better to find them before a write.
-int lfs_fs_findfreeblocks(lfs_t *lfs);
+// Calling this function is not required, but may allowing the offloading of
+// the expensive block allocation scan to a less time-critical code path.
+//
+// Note: littlefs currently does not persist any found free blocks to disk.
+// This may change in the future.
+//
+// Returns a negative error code on failure. Finding no free blocks is
+// not an error.
+int lfs_fs_gc(lfs_t *lfs);
 
 #ifndef LFS_READONLY
 // Attempt to make the filesystem consistent and ready for writing

tests/test_alloc.toml

@@ -26,7 +26,7 @@ code = '''
     }
     for (int n = 0; n < FILES; n++) {
         if (GC) {
-            lfs_fs_findfreeblocks(&lfs) => 0;
+            lfs_fs_gc(&lfs) => 0;
         }
         size_t size = strlen(names[n]);
         for (lfs_size_t i = 0; i < SIZE; i += size) {
@@ -81,7 +81,7 @@ code = '''
         memcpy(buffer, names[n], size);
         for (int i = 0; i < SIZE; i += size) {
             if (GC) {
-                lfs_fs_findfreeblocks(&lfs) => 0;
+                lfs_fs_gc(&lfs) => 0;
             }
             lfs_file_write(&lfs, &file, buffer, size) => size;
         }
@@ -255,8 +255,8 @@ code = '''
     }
     res => LFS_ERR_NOSPC;
 
-    // note that lfs_fs_findfreeblocks should not error here
-    lfs_fs_findfreeblocks(&lfs) => 0;
+    // note that lfs_fs_gc should not error here
+    lfs_fs_gc(&lfs) => 0;
 
     lfs_file_close(&lfs, &file) => 0;
     lfs_unmount(&lfs) => 0;
@@ -309,8 +309,8 @@ code = '''
     }
     res => LFS_ERR_NOSPC;
 
-    // note that lfs_fs_findfreeblocks should not error here
-    lfs_fs_findfreeblocks(&lfs) => 0;
+    // note that lfs_fs_gc should not error here
+    lfs_fs_gc(&lfs) => 0;
 
     lfs_file_close(&lfs, &file) => 0;
     lfs_unmount(&lfs) => 0;
@@ -351,8 +351,8 @@ code = '''
         count += 1;
     }
     err => LFS_ERR_NOSPC;
-    // note that lfs_fs_findfreeblocks should not error here
-    lfs_fs_findfreeblocks(&lfs) => 0;
+    // note that lfs_fs_gc should not error here
+    lfs_fs_gc(&lfs) => 0;
     lfs_file_close(&lfs, &file) => 0;
 
     lfs_remove(&lfs, "exhaustion") => 0;
@@ -451,8 +451,8 @@ code = '''
             break;
         }
     }
-    // note that lfs_fs_findfreeblocks should not error here
-    lfs_fs_findfreeblocks(&lfs) => 0;
+    // note that lfs_fs_gc should not error here
+    lfs_fs_gc(&lfs) => 0;
     lfs_file_close(&lfs, &file) => 0;
 
     lfs_unmount(&lfs) => 0;