samples: settings: provisioned flash

Adds an overlay, code and documentation to the sample that allows user
to test an independently provisioned settings partition on QEMU.

Also provides instructions how to achieve the same on real devices.

Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>

samples/subsys/settings/README.rst

@@ -100,3 +100,58 @@ Sample Output
  <gamma> = 0 (default)
  save <gamma> key directly: OK.
  ...
+
+Provisioning of Settings
+************************
+
+Settings will often have to be provisioned separately from the application
+itself, e.g. because the settings are specific to a particular device or because
+the settings are sensitive and should not be included in the application binary.
+
+The settings subsystem supports this use case by allowing settings to be
+provisioned from a separate image.
+
+To demonstrate this feature, the sample can be built with the
+``CONFIG_FLASH_SIMULATOR_PROVISION`` option on QEMU. This will simulate a flash
+partition with a fixed memory layout and load the settings from a separate image
+at runtime into QEMU memory.
+
+To build and run the sample on QEMU, follow these steps:
+
+1. Build the sample for the qemu_x86 board with the default settings from
+ qemu_x86.conf (i.e. with the NVS settings backend enabled.) and this
+ overlay:
+
+.. zephyr-app-commands::
+ :zephyr-app: samples/subsys/settings
+ :board: qemu_x86
+ :goals: run
+ :conf: overlay-provisioning.conf
+ :compact:
+
+2. Place the sample soc-nv-flash-image.hex file in the build directory:
+
+ .. code-block:: shell
+ cp samples/subsys/settings/soc-nv-flash-image.hex build/zephyr
+
+3. Start the QEMU emulator with the following command:
+
+.. zephyr-app-commands::
+ :zephyr-app: samples/subsys/settings
+ :goals: run
+ :compact:
+
+To achieve the same with a real device, a separate flash image can be prepared
+that conforms to the selected memory backend and is flashed separately to the
+appropriate flash memory location.
+
+A tool to generate arbitrary NVS partition content is currently in preparation
+and will be contributed soon. In the meantime you can extract the flash content
+from a test device, store it to a binary file and convert it to a hex file using
+the ``objcpy`` tool:
+
+ .. code-block:: shell
+ objcopy -O ihex --change-section-address SOC_NV_FLASH=<your flash base address> \
+ <extracted-flash-mem-region>.bin build/zephyr/soc-nv-flash-image.hex
+
+And then flash the hex file to the device without erasing existing flash content.

samples/subsys/settings/overlay-provisioning.conf

@@ -0,0 +1,7 @@
+# See the sample's README for more information on how
+# to provision settings from a separate flash image.
+CONFIG_FLASH_SIMULATOR_PROVISION=y
+
+CONFIG_DEBUG=y
+CONFIG_DEBUG_OPTIMIZATIONS=y
+CONFIG_DEBUG_THREAD_INFO=y