fs: littlefs: add api call for lfs_fs_gc

Lfs provide lfs_fs_gc function for some time now.
Function allow offloading of expensive block allocation scan.

Introduce lfs_fs_gc via api call fc_gc.

Signed-off-by: Maciej Zagrabski <[email protected]>

Author: Maciej Zagrabski

include/zephyr/fs/fs.h

@@ -690,6 +690,21 @@ int fs_register(int type, const struct fs_file_system_t *fs);
  */
 int fs_unregister(int type, const struct fs_file_system_t *fs);
 
+/**
+ * @brief Attempt to proactively clean file system
+ *
+ * Returns a negative error code on failure.
+ * Ignored cleaning request is not a failure.
+ *
+ * @param mp Pointer to the mounted fs_mount_t structure.
+ *
+ * @retval 0 on success;
+ * @retval -EINVAL when a bad path to a directory, or a file, is given;
+ * @retval -ENOTSUP when not implemented by underlying file system driver;
+ * @retval <0 an other negative errno code on error.
+ */
+int fs_gc(struct fs_mount_t *mp);
+
 /**
  * @}
  */

include/zephyr/fs/fs_sys.h

@@ -186,6 +186,15 @@ struct fs_file_system_t {
 	 */
 	int (*statvfs)(struct fs_mount_t *mountp, const char *path,
 					struct fs_statvfs *stat);
+#if defined(CONFIG_FILE_SYSTEM_GC) || defined(__DOXYGEN__)
+	/**
+	 * Attempt to proactively clean file system
+	 *
+	 * @param mountp Mount point.
+	 * @return 0 on success, negative errno code on fail.
+	 */
+	int (*gc)(struct fs_mount_t *mountp);
+#endif
 #if defined(CONFIG_FILE_SYSTEM_MKFS) || defined(__DOXYGEN__)
 	/**
 	 * Formats a device to specified file system type.

subsys/fs/Kconfig

@@ -99,6 +99,11 @@ config FILE_SYSTEM_MKFS
 	help
 	  Enables function fs_mkfs that can be used to format a storage device.
 
+config FILE_SYSTEM_GC
+	bool "Allow explicit garbage collector call"
+	help
+	  Enables function fs_gc that can be used to proactively run garbage collector.
+
 config FUSE_FS_ACCESS
 	bool "FUSE based access to file system partitions"
 	depends on ARCH_POSIX

subsys/fs/fs.c

@@ -661,6 +661,26 @@ int fs_statvfs(const char *abs_path, struct fs_statvfs *stat)
 	return rc;
 }
 
+#if defined(CONFIG_FILE_SYSTEM_GC)
+
+int fs_gc(struct fs_mount_t *mp)
+{
+	int rc;
+
+	CHECKIF(mp->fs->gc == NULL) {
+		return -ENOTSUP;
+	}
+
+	rc = mp->fs->gc(mp);
+	if (rc < 0) {
+		LOG_ERR("failed to run garbage collection (%d)", rc);
+	}
+
+	return rc;
+}
+
+#endif /* CONFIG_FILE_SYSTEM_GC */
+
 int fs_mount(struct fs_mount_t *mp)
 {
 	struct fs_mount_t *itr;

subsys/fs/littlefs_fs.c

@@ -582,6 +582,25 @@ static int littlefs_statvfs(struct fs_mount_t *mountp,
 	return lfs_to_errno(ret);
 }
 
+#if defined(CONFIG_FILE_SYSTEM_GC)
+
+static int littlefs_gc(struct fs_mount_t *mountp)
+{
+	ssize_t ret;
+	struct fs_littlefs *fs = mountp->fs_data;
+	struct lfs *lfs = &fs->lfs;
+
+	fs_lock(fs);
+
+	ret = lfs_fs_gc(lfs);
+
+	fs_unlock(fs);
+
+	return lfs_to_errno(ret);
+}
+
+#endif /* CONFIG_FILE_SYSTEM_GC */
+
 #ifdef CONFIG_FS_LITTLEFS_FMP_DEV
 
 #if defined(CONFIG_FLASH_HAS_EXPLICIT_ERASE)
@@ -1056,6 +1075,9 @@ static const struct fs_file_system_t littlefs_fs = {
 	.mkdir = littlefs_mkdir,
 	.stat = littlefs_stat,
 	.statvfs = littlefs_statvfs,
+#if defined(CONFIG_FILE_SYSTEM_GC)
+	.gc = littlefs_gc,
+#endif
 #if defined(CONFIG_FILE_SYSTEM_MKFS)
 	.mkfs = littlefs_mkfs,
 #endif

tests/subsys/fs/common/test_fs_gc.c

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2025 Trackunit
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/kernel.h>
+#include <zephyr/ztest.h>
+#include <zephyr/fs/fs.h>
+
+/* Mount point and paths must be provided by test runner. */
+extern struct fs_mount_t *fs_gc_mp;
+
+void test_fs_gc_simple(void)
+{
+	int ret = 0;
+
+	TC_PRINT("Mount\n");
+	ret = fs_mount(fs_gc_mp);
+	zassert_equal(ret, 0, "Expected fs_mount success (%d)", ret);
+
+	TC_PRINT("Try gc\n");
+	ret = fs_gc(fs_gc_mp);
+	zassert_equal(ret, 0, "Expected fs_gc success (%d)", ret);
+
+	TC_PRINT("Remount filesystem\n");
+	ret = fs_unmount(fs_gc_mp);
+	zassert_equal(ret, 0, "Expected fs_unmount success (%d)", ret);
+
+	ret = fs_mount(fs_gc_mp);
+	zassert_equal(ret, 0, "Expected fs_mount success (%d)", ret);
+
+	ret = fs_unmount(fs_gc_mp);
+	zassert_equal(ret, 0, "Expected fs_unmount success (%d)", ret);
+}

tests/subsys/fs/littlefs/CMakeLists.txt

@@ -20,4 +20,5 @@ target_sources(app PRIVATE
   ../common/test_fs_basic.c
   ../common/test_fs_mount_flags.c
   ../common/test_fs_mkfs.c
+  ../common/test_fs_gc.c
 )

tests/subsys/fs/littlefs/prj.conf

@@ -1,5 +1,6 @@
 CONFIG_FILE_SYSTEM=y
 CONFIG_FILE_SYSTEM_MKFS=y
+CONFIG_FILE_SYSTEM_GC=y
 CONFIG_FILE_SYSTEM_LITTLEFS=y
 CONFIG_MAIN_STACK_SIZE=4096
 

tests/subsys/fs/littlefs/src/testfs_gc.c

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2025 Trackunit
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/ztest.h>
+#include <zephyr/fs/littlefs.h>
+#include "testfs_tests.h"
+#include "testfs_lfs.h"
+
+void test_fs_gc_simple(void);
+
+struct fs_mount_t *fs_gc_mp = &testfs_small_mnt;
+
+static void cleanup(struct fs_mount_t *mp)
+{
+	TC_PRINT("Clean %s\n", mp->mnt_point);
+
+	zassert_equal(testfs_lfs_wipe_partition(mp), TC_PASS,
+		      "Failed to clean partition");
+}
+
+ZTEST(littlefs, test_fs_gc_simple_lfs)
+{
+	cleanup(fs_gc_mp);
+
+	test_fs_gc_simple();
+}