[nrf fromtree] drivers/flash: Add explicit_erase property

The commit adds and no_explicit_erase capability to flash_parameters,
that indicates whether device is program-erase type device; such
devices, like Flash type devices, require erase prior to writing
random data at any previously programmed location.
This capability should only be set by drivers.

The flash_params_get_erase_cap() function has been added, for parsing
flash_parameters object to obtain erase capabilities of device.
The function returns capabilities as combination of bits representing
them. Currently it will return:
 0 -- no erase capabilities
 FLASH_ERASE_C_EXPLICIT -- erase required before write of random data.
Additional capabilities have been reserved but are not yet used.

There are following Kconfig options added:
 FLASH_HAS_EXPLICIT_ERASE
 FLASH_HAS_NO_EXPLICIT_ERASE
that should be selected by device driver to indicate whether
devices served by driver needs erase prior to write.
The above Kconfigs are used to figure out whether app is built
for hardware that requires erase prior to write.
They can be also used to detect that it is attempted to build
some subsystem that will not work with provided hardware, for example
file system that has not been prepared to work with devices that
do not require erase.

Signed-off-by: Dominik Ermel <[email protected]>
(cherry picked from commit b3c9f95)

Author: de-nordic

drivers/flash/Kconfig

@@ -17,6 +17,56 @@ config FLASH_HAS_EX_OP
 	  This option is selected by drivers that support flash extended
 	  operations.
 
+config FLASH_HAS_EXPLICIT_ERASE
+	bool
+	help
+	  Device has does not do erase-on-write (erase-on-program, auto-erase
+	  on write) and requires explicit erase procedure to be programmed
+	  with random value, in place where it has already been programmed with
+	  some other value, as program can only change bits from erased-value
+	  to the opposite.
+	  All pure Flash devices are evolution of EEPROM where erase has
+	  been separated from write, EEPROM has erase-on-write, giving
+	  it advantage of higher write speeds at a cost of larger erase block.
+	  Note that explicit-erase capability does not warrants that
+	  write without erase is not allowed, taking the above restrictions,
+	  it only states that write of a random information will require
+	  erase.
+	  Erase is usually performed in pages, as we have chosen to name
+	  the unit in Zephyr, that may have different naming in device
+	  specifications, like pages, sectors or blocks, and may vary
+	  in size, depending how they are named by vendor.
+	  This option should be selected by drivers that serve devices with
+	  such characteristic and is used and may be used by users to provide
+	  paths in code that only serve such devices, and could be
+	  optimized-out by compiler in case where there is no such device in
+	  a system.
+
+config FLASH_HAS_NO_EXPLICIT_ERASE
+	bool
+	help
+	  Device does not require explicit erase before programming
+	  a new random value at any location that has been previously
+	  programmed with some other value.
+	  Note that the device may have erase-on-write (auto-erase),
+	  as for example in EEPROM devices, but may also have no erase
+	  at all.
+	  A device driver may still provide erase callback,
+	  especially if it is able to perform erase to accelerate
+	  further writes or is able to fill the area requested for
+	  erase, with single value, faster than consecutive writes
+	  that would be used to emulate erase.
+	  This option should be selected by drivers that serve
+	  devices with such characteristic and is used and may be
+	  used by users to provide paths in code that only serve
+	  such devices, and could be optimized-out by compiler in
+	  case where there is no such device in a system.
+	  This option should be selected for any device that
+	  can change storage bits, by write, from any value to opposite
+	  value at any time.
+	  When your driver sets this option you also need to set
+	  no_explicit_erase capability in your drivers flash_parameters.
+
 config FLASH_HAS_PAGE_LAYOUT
 	bool
 	help
@@ -77,13 +127,17 @@ config FLASH_SHELL_BUFFER_SIZE
 
 endif # FLASH_SHELL
 
+
+if FLASH_HAS_PAGE_LAYOUT
+
 config FLASH_PAGE_LAYOUT
 	bool "API for retrieving the layout of pages"
-	depends on FLASH_HAS_PAGE_LAYOUT
-	default y
+	default FLASH_HAS_PAGE_LAYOUT
 	help
 	  Enables API for retrieving the layout of flash memory pages.
 
+endif
+
 config FLASH_EX_OP_ENABLED
 	bool "API for extended flash operations"
 	depends on FLASH_HAS_EX_OP

include/zephyr/drivers/flash.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017 Nordic Semiconductor ASA
+ * Copyright (c) 2017-2024 Nordic Semiconductor ASA
  * Copyright (c) 2016 Intel Corporation
  *
  * SPDX-License-Identifier: Apache-2.0
@@ -58,9 +58,59 @@ struct flash_pages_layout {
  */
 struct flash_parameters {
 	const size_t write_block_size;
+	/* Device capabilities. Only drivers are supposed to set the
+	 * capabilities directly, users need to call the FLASH_CAPS_
+	 * macros on pointer to flash_parameters to get capabilities.
+	 */
+	struct {
+		/* Device has no explicit erase, so it either erases on
+		 * write or does not require it at all.
+		 * This also includes devices that support erase but
+		 * do not require it.
+		 */
+		bool no_explicit_erase: 1;
+	} caps;
 	uint8_t erase_value; /* Byte value of erased flash */
 };
 
+/** Set for ordinary Flash where erase is needed before write of random data */
+#define FLASH_ERASE_C_EXPLICIT		0x01
+/** Reserved for users as initializer for variables that will later store
+ * capabilities.
+ */
+#define FLASH_ERASE_CAPS_UNSET		(int)-1
+/* The values below are now reserved but not used */
+#define FLASH_ERASE_C_SUPPORTED		0x02
+#define FLASH_ERASE_C_VAL_BIT		0x04
+#define FLASH_ERASE_UNIFORM_PAGE	0x08
+
+
+/* @brief Parser for flash_parameters for retrieving erase capabilities
+ *
+ * The functions parses flash_parameters type object and returns combination
+ * of erase capabilities of 0 if device does not have any.
+ * Not that in some cases availability of erase may be dependent on driver
+ * options, so even if by hardware design a device provides some erase
+ * capabilities, the function may return 0 if these been disabled or not
+ * implemented by driver.
+ *
+ * @param p		pointer to flash_parameters type object
+ *
+ * @return 0 or combination of FLASH_ERASE_C_ capabilities.
+ */
+static inline
+int flash_params_get_erase_cap(const struct flash_parameters *p)
+{
+#if defined(CONFIG_FLASH_HAS_EXPLICIT_ERASE)
+#if defined(CONFIG_FLASH_HAS_NO_EXPLICIT_ERASE)
+	return (p->caps.no_explicit_erase) ? 0 : FLASH_ERASE_C_EXPLICIT;
+#else
+	return FLASH_ERASE_C_EXPLICIT;
+#endif
+#endif
+	return 0;
+}
+
 /**
  * @}
  */