settings: file: change FS (or file system) wording to File

Currently there is inconsistency in repository file names, APIs, Kconfig
options and documentation around file / file-system backend for settings
storage, as both "file" and "FS (file system)" are used. As an example,
there is `CONFIG_SETTINGS_FS` Kconfig option, but the file that implements
this settings backend is called `settings_file.c`. Another example are
names of static functions that implement settings storage API:
`settings_file_load()`, `settings_file_save()` and
`settings_fs_storage_get()`.

This backend is actually storing all settings in a single file, so it makes
sense to use "File" as the name of backend, instead of a more general
"FS" (which would make sense if several files would be used to store
settings).

Fix inconsistency in used wording in the tree and unify it to "settings
file backend". This naming is more precise to how the implementation looks.
It will also make it easier to grep through the codebase and analyze
existing code.

Deprecate settings_mount_fs_backend() function and all Kconfig options
starting with `CONFIG_SETTINGS_FS`.

Signed-off-by: Marcin Niestroj <m.niestroj@emb.dev>

doc/releases/release-notes-3.3.rst

@@ -104,6 +104,18 @@ Deprecated in this release
   :kconfig:option:`CONFIG_COUNTER_RTC_STM32_CLOCK_LSE` options are now
   deprecated.
 
+* File backend for settings APIs and Kconfig options were deprecated:
+
+  :c:func:`settings_mount_fs_backend` in favor of :c:func:`settings_mount_file_backend`
+
+  :kconfig:option:`CONFIG_SETTINGS_FS` in favor of :kconfig:option:`CONFIG_SETTINGS_FILE`
+
+  :kconfig:option:`CONFIG_SETTINGS_FS_DIR` in favor of :kconfig:option:`CONFIG_SETTINGS_FILE_DIR`
+
+  :kconfig:option:`CONFIG_SETTINGS_FS_FILE` in favor of :kconfig:option:`CONFIG_SETTINGS_FILE_PATH`
+
+  :kconfig:option:`CONFIG_SETTINGS_FS_MAX_LINES` in favor of :kconfig:option:`CONFIG_SETTINGS_FILE_MAX_LINES`
+
 Stable API changes in this release
 ==================================
 

doc/services/settings/index.rst

@@ -84,7 +84,7 @@ Zephyr Storage Backends
 
 Zephyr has three storage backends: a Flash Circular Buffer
 (:kconfig:option:`CONFIG_SETTINGS_FCB`), a file in the filesystem
-(:kconfig:option:`CONFIG_SETTINGS_FS`), or non-volatile storage
+(:kconfig:option:`CONFIG_SETTINGS_FILE`), or non-volatile storage
 (:kconfig:option:`CONFIG_SETTINGS_NVS`).
 
 You can declare multiple sources for settings; settings from
@@ -110,8 +110,8 @@ partition with label "storage" by default. A different partition can be
 selected by setting the ``zephyr,settings-partition`` property of the
 chosen node in the devicetree.
 
-The file path used by the file system backend to store settings
-is selected via the option ``CONFIG_SETTINGS_FS_FILE``.
+The file path used by the file backend to store settings is selected via the
+option ``CONFIG_SETTINGS_FILE_PATH``.
 
 Loading data from persisted storage
 ***********************************
@@ -122,7 +122,7 @@ After all data is loaded, the ``h_commit`` handler is issued,
 signalling the application that the settings were successfully
 retrieved.
 
-Technically FCB and filesystem backends may store some history of the entities.
+Technically FCB and file backends may store some history of the entities.
 This means that the newest data entity is stored after any
 older existing data entities.
 Starting with Zephyr 2.1, the back-end must filter out all old entities and
@@ -138,7 +138,7 @@ settings data to the storage medium. A call to ``settings_save()`` uses an
 A key need to be covered by a ``h_export`` only if it is supposed to be stored
 by ``settings_save()`` call.
 
-For both FCB and filesystem back-end only storage requests with data which
+For both FCB and file back-end only storage requests with data which
 changes most actual key's value are stored, therefore there is no need to check
 whether a value changed by the application. Such a storage mechanism implies
 that storage can contain multiple value assignments for a key , while only the
@@ -146,7 +146,7 @@ last is the current value for the key.
 
 Garbage collection
 ==================
-When storage becomes full (FCB) or consumes too much space (file system),
+When storage becomes full (FCB) or consumes too much space (file),
 the backend removes non-recent key-value pairs records and unnecessary
 key-delete records.
 

samples/subsys/settings/boards/native_posix.conf

@@ -1,6 +1,6 @@
 # Enable the LittleFS file system.
 CONFIG_FILE_SYSTEM=y
 CONFIG_FILE_SYSTEM_LITTLEFS=y
-CONFIG_SETTINGS_FS=y
-CONFIG_SETTINGS_FS_DIR="/ff/settings"
-CONFIG_SETTINGS_FS_FILE="/ff/settings/run"
+CONFIG_SETTINGS_FILE=y
+CONFIG_SETTINGS_FILE_DIR="/ff/settings"
+CONFIG_SETTINGS_FILE_PATH="/ff/settings/run"

samples/subsys/settings/boards/native_posix_64.conf

@@ -1,6 +1,6 @@
 # Enable the LittleFS file system.
 CONFIG_FILE_SYSTEM=y
 CONFIG_FILE_SYSTEM_LITTLEFS=y
-CONFIG_SETTINGS_FS=y
-CONFIG_SETTINGS_FS_DIR="/ff/settings"
-CONFIG_SETTINGS_FS_FILE="/ff/settings/run"
+CONFIG_SETTINGS_FILE=y
+CONFIG_SETTINGS_FILE_DIR="/ff/settings"
+CONFIG_SETTINGS_FILE_PATH="/ff/settings/run"

samples/subsys/settings/src/main.c

@@ -12,7 +12,7 @@
 #include <errno.h>
 #include <zephyr/sys/printk.h>
 
-#if IS_ENABLED(CONFIG_SETTINGS_FS)
+#if IS_ENABLED(CONFIG_SETTINGS_FILE)
 #include <zephyr/fs/fs.h>
 #include <zephyr/fs/littlefs.h>
 #endif
@@ -422,7 +422,7 @@ static void example_initialization(void)
 {
 	int rc;
 
-#if IS_ENABLED(CONFIG_SETTINGS_FS)
+#if IS_ENABLED(CONFIG_SETTINGS_FILE)
 	FS_LITTLEFS_DECLARE_DEFAULT_CONFIG(cstorage);
 
 	/* mounting info */
@@ -438,7 +438,7 @@ static void example_initialization(void)
 		printk("mounting littlefs error: [%d]\n", rc);
 	} else {
 
-		rc = fs_unlink(CONFIG_SETTINGS_FS_FILE);
+		rc = fs_unlink(CONFIG_SETTINGS_FILE_PATH);
 		if ((rc != 0) && (rc != -ENOENT)) {
 			printk("can't delete config file%d\n", rc);
 		} else {

subsys/settings/Kconfig

@@ -37,7 +37,7 @@ choice SETTINGS_BACKEND
 	prompt "Storage back-end"
 	default SETTINGS_NVS if NVS
 	default SETTINGS_FCB if FCB
-	default SETTINGS_FS if FILE_SYSTEM
+	default SETTINGS_FILE if FILE_SYSTEM
 	default SETTINGS_NONE
 	depends on SETTINGS
 	help
@@ -49,12 +49,20 @@ config SETTINGS_FCB
 	help
 	  Use FCB as a settings storage back-end.
 
-config SETTINGS_FS
-	bool "File System"
+config SETTINGS_FILE
+	bool "File"
 	depends on FILE_SYSTEM
 	select SETTINGS_ENCODE_LEN
 	help
-	  Use a file system as a settings storage back-end.
+	  Use a file (on mounted file system) as a settings storage back-end.
+
+config SETTINGS_FS
+	bool "FS (DEPRECATED)"
+	depends on FILE_SYSTEM
+	select SETTINGS_ENCODE_LEN
+	select DEPRECATED
+	help
+	  This is deprecated, please use SETTINGS_FILE instead.
 
 config SETTINGS_NVS
 	bool "NVS non-volatile storage support"
@@ -107,26 +115,47 @@ config SETTINGS_FCB_MAGIC
 	help
 	  Magic 32-bit word for to identify valid settings area
 
-config SETTINGS_FS_DIR
+config SETTINGS_FILE_DIR
 	string "Serialization directory"
 	default "/settings"
-	depends on SETTINGS && SETTINGS_FS
+	depends on SETTINGS && SETTINGS_FILE
 	help
 	  Directory where the settings data is stored
 
-config SETTINGS_FS_FILE
+config SETTINGS_FILE_PATH
 	string "Default settings file"
 	default "/settings/run"
-	depends on SETTINGS && SETTINGS_FS
+	depends on SETTINGS && SETTINGS_FILE
 	help
 	  Full path to the default settings file.
 
-config SETTINGS_FS_MAX_LINES
+config SETTINGS_FILE_MAX_LINES
 	int "Compression threshold"
 	default 32
+	depends on SETTINGS && SETTINGS_FILE
+	help
+	  Limit how many items stored in a file before compressing
+
+config SETTINGS_FS_DIR
+	string "Serialization directory (DEPRECATED)"
+	default "/settings"
+	depends on SETTINGS && SETTINGS_FS
+	help
+	  This is deprecated. Use SETTINGS_FILE_DIR instead.
+
+config SETTINGS_FS_FILE
+	string "Default settings file (DEPRECATED)"
+	default "/settings/run"
+	depends on SETTINGS && SETTINGS_FS
+	help
+	  This is deprecated. Use SETTINGS_FILE_PATH instead.
+
+config SETTINGS_FS_MAX_LINES
+	int "Compression threshold (DEPRECATED)"
+	default 32
 	depends on SETTINGS && SETTINGS_FS
 	help
-	  Limit how many items stored in a file before compressing
+	  This is deprecated. Use SETTINGS_FILE_MAX_LINES instead.
 
 config SETTINGS_NVS_SECTOR_SIZE_MULT
 	int "Sector size of the NVS settings area"

subsys/settings/include/settings/settings_file.h

@@ -8,6 +8,7 @@
 #ifndef __SETTINGS_FILE_H_
 #define __SETTINGS_FILE_H_
 
+#include <zephyr/toolchain.h>
 #include <zephyr/settings/settings.h>
 
 #ifdef __cplusplus
@@ -29,7 +30,12 @@ int settings_file_src(struct settings_file *cf);
 /* settings saves go to a file */
 int settings_file_dst(struct settings_file *cf);
 
-void settings_mount_fs_backend(struct settings_file *cf);
+void settings_mount_file_backend(struct settings_file *cf);
+
+__deprecated static inline void settings_mount_fs_backend(struct settings_file *cf)
+{
+	settings_mount_file_backend(cf);
+}
 
 #ifdef __cplusplus
 }

subsys/settings/src/CMakeLists.txt

@@ -8,6 +8,7 @@ zephyr_sources(
   )
 
 zephyr_sources_ifdef(CONFIG_SETTINGS_RUNTIME settings_runtime.c)
+zephyr_sources_ifdef(CONFIG_SETTINGS_FILE settings_file.c)
 zephyr_sources_ifdef(CONFIG_SETTINGS_FS settings_file.c)
 zephyr_sources_ifdef(CONFIG_SETTINGS_FCB settings_fcb.c)
 zephyr_sources_ifdef(CONFIG_SETTINGS_NVS settings_nvs.c)

subsys/settings/src/settings_file.c

@@ -19,19 +19,29 @@
 
 LOG_MODULE_DECLARE(settings, CONFIG_SETTINGS_LOG_LEVEL);
 
+#ifdef CONFIG_SETTINGS_FS
+#define SETTINGS_FILE_MAX_LINES		CONFIG_SETTINGS_FS_MAX_LINES
+#define SETTINGS_FILE_DIR		CONFIG_SETTINGS_FS_DIR
+#define SETTINGS_FILE_PATH		CONFIG_SETTINGS_FS_FILE
+#else
+#define SETTINGS_FILE_MAX_LINES		CONFIG_SETTINGS_FILE_MAX_LINES
+#define SETTINGS_FILE_DIR		CONFIG_SETTINGS_FILE_DIR
+#define SETTINGS_FILE_PATH		CONFIG_SETTINGS_FILE_PATH
+#endif
+
 int settings_backend_init(void);
-void settings_mount_fs_backend(struct settings_file *cf);
+void settings_mount_file_backend(struct settings_file *cf);
 
 static int settings_file_load(struct settings_store *cs,
 			      const struct settings_load_arg *arg);
 static int settings_file_save(struct settings_store *cs, const char *name,
 			      const char *value, size_t val_len);
-static void *settings_fs_storage_get(struct settings_store *cs);
+static void *settings_file_storage_get(struct settings_store *cs);
 
 static const struct settings_store_itf settings_file_itf = {
 	.csi_load = settings_file_load,
 	.csi_save = settings_file_save,
-	.csi_storage_get = settings_fs_storage_get
+	.csi_storage_get = settings_file_storage_get
 };
 
 /*
@@ -500,7 +510,7 @@ static int write_handler(void *ctx, off_t off, char const *buf, size_t len)
 	return rc;
 }
 
-void settings_mount_fs_backend(struct settings_file *cf)
+void settings_mount_file_backend(struct settings_file *cf)
 {
 	settings_line_io_init(read_handler, write_handler, get_len_cb, 1);
 }
@@ -508,8 +518,8 @@ void settings_mount_fs_backend(struct settings_file *cf)
 int settings_backend_init(void)
 {
 	static struct settings_file config_init_settings_file = {
-		.cf_name = CONFIG_SETTINGS_FS_FILE,
-		.cf_maxlines = CONFIG_SETTINGS_FS_MAX_LINES
+		.cf_name = SETTINGS_FILE_PATH,
+		.cf_maxlines = SETTINGS_FILE_MAX_LINES
 	};
 	struct fs_dirent entry;
 	int rc;
@@ -525,20 +535,20 @@ int settings_backend_init(void)
 		k_panic();
 	}
 
-	settings_mount_fs_backend(&config_init_settings_file);
+	settings_mount_file_backend(&config_init_settings_file);
 
 	/*
 	 * Must be called after root FS has been initialized.
 	 */
-	rc = fs_stat(CONFIG_SETTINGS_FS_DIR, &entry);
+	rc = fs_stat(SETTINGS_FILE_DIR, &entry);
 	/* If directory doesn't exist, create it */
 	if (rc == -ENOENT) {
-		rc = fs_mkdir(CONFIG_SETTINGS_FS_DIR);
+		rc = fs_mkdir(SETTINGS_FILE_DIR);
 	}
 	return rc;
 }
 
-static void *settings_fs_storage_get(struct settings_store *cs)
+static void *settings_file_storage_get(struct settings_store *cs)
 {
 	struct settings_file *cf = (struct settings_file *)cs;
 

tests/subsys/settings/file/include/settings_test_file.h

@@ -4,8 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-#ifndef _SETTINGS_TEST_FS_H
-#define _SETTINGS_TEST_FS_H
+#ifndef _SETTINGS_TEST_FILE_H
+#define _SETTINGS_TEST_FILE_H
 
 #include <stdio.h>
 #include <string.h>
@@ -62,4 +62,4 @@ void test_config_compress_file(void);
 }
 #endif
 
-#endif /* _SETTINGS_TEST_FS_H */
+#endif /* _SETTINGS_TEST_FILE_H */

tests/subsys/settings/file/src/settings_test_compress_file.c

@@ -36,7 +36,7 @@ ZTEST(settings_config_fs, test_config_compress_file)
 
 	rc = settings_file_src(&cf);
 	zassert_true(rc == 0, "can't register FS as configuration source");
-	settings_mount_fs_backend(&cf);
+	settings_mount_file_backend(&cf);
 
 	rc = settings_file_dst(&cf);
 	zassert_true(rc == 0,

tests/subsys/settings/file/src/settings_test_empty_file.c

@@ -27,7 +27,7 @@ ZTEST(settings_config_fs, test_config_empty_file)
 	rc = settings_file_src(&cf_running);
 	zassert_true(rc == 0, "can't register FS as configuration source");
 
-	settings_mount_fs_backend(&cf_mfg);
+	settings_mount_file_backend(&cf_mfg);
 	/*
 	 * No files
 	 */

tests/subsys/settings/file_littlefs/prj.conf

@@ -16,4 +16,4 @@ CONFIG_FILE_SYSTEM_LITTLEFS=y
 
 CONFIG_SETTINGS=y
 CONFIG_SETTINGS_RUNTIME=y
-CONFIG_SETTINGS_FS=y
+CONFIG_SETTINGS_FILE=y

tests/subsys/settings/file_littlefs/src/CMakeLists.txt

@@ -2,13 +2,13 @@
 # Copyright (c) 2019 Nordic Semiconductor ASA
 
 add_subdirectory(../../src settings_test_bindir)
-add_subdirectory(../../fs/src settings_test_fs_bindir)
+add_subdirectory(../../file/src settings_test_file_bindir)
 
 zephyr_include_directories(
 	${ZEPHYR_BASE}/subsys/settings/include
 	${ZEPHYR_BASE}/subsys/settings/src
-	${ZEPHYR_BASE}/tests/subsys/settings/fs/include
-	${ZEPHYR_BASE}/tests/subsys/settings/littlefs/src
+	${ZEPHYR_BASE}/tests/subsys/settings/file/include
+	${ZEPHYR_BASE}/tests/subsys/settings/file_littlefs/src
 	)
 
 

tests/subsys/settings/file_littlefs/src/settings_test.h

@@ -7,10 +7,10 @@
 #ifndef _SETTINGS_TEST_H
 #define _SETTINGS_TEST_H
 
-#include "settings_test_fs.h"
+#include "settings_test_file.h"
 
 #define TEST_FS_MPTR "/littlefs"
-#define TEST_CONFIG_DIR TEST_FS_MPTR""CONFIG_SETTINGS_FS_DIR
+#define TEST_CONFIG_DIR TEST_FS_MPTR""CONFIG_SETTINGS_FILE_DIR
 
 void *settings_config_setup(void);
 void settings_config_teardown(void *fixture);

tests/subsys/settings/file_littlefs/src/settings_test_littlefs.c

@@ -6,7 +6,7 @@
 #include <stdlib.h>
 #include <string.h>
 
-#include "settings_test_fs.h"
+#include "settings_test_file.h"
 #include "settings_test.h"
 #include "settings_priv.h"
 

tests/subsys/settings/file_littlefs/testcase.yaml

@@ -2,12 +2,12 @@
 # Copyright (c) 2019 Nordic Semiconductor ASA
 
 tests:
-  system.settings.littlefs.raw:
+  system.settings.file_littlefs.raw:
     platform_allow: nrf52840dk_nrf52840
-    tags: settings_fs settings_littlefs
+    tags: settings_file settings_file_littlefs
     extra_configs:
     - CONFIG_STDOUT_CONSOLE=y
     - CONFIG_ARM_MPU=n
-  system.settings.littlefs.raw_native_posix:
+  system.settings.file_littlefs.raw_native_posix:
     platform_allow: native_posix native_posix_64
-    tags: settings_fs settings_littlefs
+    tags: settings_file settings_file_littlefs

tests/subsys/settings/functional/file/CMakeLists.txt

@@ -6,7 +6,7 @@ project(functional_file)
 
 FILE(GLOB app_sources ../src/*.c)
 target_sources(app PRIVATE ${app_sources})
-target_sources(app PRIVATE settings_test_fs.c)
+target_sources(app PRIVATE settings_test_file.c)
 zephyr_include_directories(
 	${ZEPHYR_BASE}/subsys/settings/include
 	${ZEPHYR_BASE}/subsys/settings/src

tests/subsys/settings/functional/file/prj.conf

@@ -12,7 +12,7 @@ CONFIG_FILE_SYSTEM_LITTLEFS=y
 
 CONFIG_SETTINGS=y
 CONFIG_SETTINGS_RUNTIME=y
-CONFIG_SETTINGS_FS=y
+CONFIG_SETTINGS_FILE=y
 
-CONFIG_SETTINGS_FS_DIR="/ff/settings"
-CONFIG_SETTINGS_FS_FILE="/ff/settings/run"
+CONFIG_SETTINGS_FILE_DIR="/ff/settings"
+CONFIG_SETTINGS_FILE_PATH="/ff/settings/run"

tests/subsys/settings/functional/file/prj_native_posix.conf

@@ -9,7 +9,7 @@ CONFIG_FILE_SYSTEM_LITTLEFS=y
 
 CONFIG_SETTINGS=y
 CONFIG_SETTINGS_RUNTIME=y
-CONFIG_SETTINGS_FS=y
+CONFIG_SETTINGS_FILE=y
 
-CONFIG_SETTINGS_FS_DIR="/ff/settings"
-CONFIG_SETTINGS_FS_FILE="/ff/settings/run"
+CONFIG_SETTINGS_FILE_DIR="/ff/settings"
+CONFIG_SETTINGS_FILE_PATH="/ff/settings/run"

tests/subsys/settings/functional/file/prj_native_posix_64.conf

@@ -9,7 +9,7 @@ CONFIG_FILE_SYSTEM_LITTLEFS=y
 
 CONFIG_SETTINGS=y
 CONFIG_SETTINGS_RUNTIME=y
-CONFIG_SETTINGS_FS=y
+CONFIG_SETTINGS_FILE=y
 
-CONFIG_SETTINGS_FS_DIR="/ff/settings"
-CONFIG_SETTINGS_FS_FILE="/ff/settings/run"
+CONFIG_SETTINGS_FILE_DIR="/ff/settings"
+CONFIG_SETTINGS_FILE_PATH="/ff/settings/run"

tests/subsys/settings/functional/file/prj_qemu_x86.conf

@@ -10,7 +10,7 @@ CONFIG_FILE_SYSTEM_LITTLEFS=y
 
 CONFIG_SETTINGS=y
 CONFIG_SETTINGS_RUNTIME=y
-CONFIG_SETTINGS_FS=y
+CONFIG_SETTINGS_FILE=y
 
-CONFIG_SETTINGS_FS_DIR="/ff/settings"
-CONFIG_SETTINGS_FS_FILE="/ff/settings/run"
+CONFIG_SETTINGS_FILE_DIR="/ff/settings"
+CONFIG_SETTINGS_FILE_PATH="/ff/settings/run"

tests/subsys/settings/functional/src/settings_basic_test.c

@@ -21,7 +21,7 @@ LOG_MODULE_REGISTER(settings_basic_test);
 #if DT_HAS_CHOSEN(zephyr_settings_partition)
 #define TEST_FLASH_AREA_ID DT_FIXED_PARTITION_ID(DT_CHOSEN(zephyr_settings_partition))
 #endif
-#elif IS_ENABLED(CONFIG_SETTINGS_FS)
+#elif IS_ENABLED(CONFIG_SETTINGS_FILE)
 #include <zephyr/fs/fs.h>
 #include <zephyr/fs/littlefs.h>
 #else
@@ -38,7 +38,7 @@ LOG_MODULE_REGISTER(settings_basic_test);
  */
 ZTEST(settings_functional, test_clear_settings)
 {
-#if !IS_ENABLED(CONFIG_SETTINGS_FS)
+#if !IS_ENABLED(CONFIG_SETTINGS_FILE)
 	const struct flash_area *fap;
 	int rc;
 
@@ -65,7 +65,7 @@ ZTEST(settings_functional, test_clear_settings)
 	rc = fs_mount(&littlefs_mnt);
 	zassert_true(rc == 0, "mounting littlefs [%d]\n", rc);
 
-	rc = fs_unlink(CONFIG_SETTINGS_FS_FILE);
+	rc = fs_unlink(CONFIG_SETTINGS_FILE_PATH);
 	zassert_true(rc == 0 || rc == -ENOENT,
 		     "can't delete config file%d\n", rc);
 #endif