include/drivers/flash: deprecation of flash_write_protection_set()

The API is deprecated as it was decided to build in the flash protection
service into write and erase procedures.
This is solution chosen for fix following issue:
  When two or more threads writes to flash device it is
  possible that flash protection will be enabled by one of
  threads despite another thread(s) still needs it disabled.

fixes #3127

Signed-off-by: Andrzej Puzdrowski <andrzej.puzdrowski@nordicsemi.no>

include/drivers/flash.h

@@ -69,10 +69,29 @@ struct flash_parameters {
 typedef int (*flash_api_read)(const struct device *dev, off_t offset,
 			      void *data,
 			      size_t len);
+/**
+ * @brief Flash write implementation handler type
+ *
+ * @note Any necessary write protection management must be performed by
+ * the driver, with the driver responsible for ensuring the "write-protect"
+ * after the operation completes (successfully or not) matches the write-protect
+ * state when the operation was started.
+ */
 typedef int (*flash_api_write)(const struct device *dev, off_t offset,
 			       const void *data, size_t len);
+
+/**
+ * @brief Flash erase implementation handler type
+ *
+ * @note Any necessary erase protection management must be performed by
+ * the driver, with the driver responsible for ensuring the "erase-protect"
+ * after the operation completes (successfully or not) matches the erase-protect
+ * state when the operation was started.
+ */
 typedef int (*flash_api_erase)(const struct device *dev, off_t offset,
 			       size_t size);
+
+/*  This API is deprecated and will be removed in Zephyr 2.8. */
 typedef int (*flash_api_write_protection)(const struct device *dev,
 					  bool enable);
 typedef const struct flash_parameters* (*flash_api_get_parameters)(const struct device *dev);
@@ -166,8 +185,8 @@ static inline int z_impl_flash_read(const struct device *dev, off_t offset,
  *  Write size and offset must be multiples of the minimum write block size
  *  supported by the driver.
  *
- *  Prior to the invocation of this API, the flash_write_protection_set needs
- *  to be called first to disable the write protection.
+ *  Any necessary write protection management is performed by the driver
+ *  write implementation itself.
  *
  *  @param  dev             : flash device
  *  @param  offset          : starting offset for the write
@@ -217,8 +236,8 @@ static inline int z_impl_flash_write(const struct device *dev, off_t offset,
  *  using flash_get_page_info_by_offs() if that is supported by your
  *  flash driver.
  *
- *  Prior to the invocation of this API, the flash_write_protection_set needs
- *  to be called first to disable the write protection.
+ *  Any necessary erase protection management is performed by the driver
+ *  erase implementation itself.
  *
  *  @param  dev             : flash device
  *  @param  offset          : erase area starting offset
@@ -262,36 +281,20 @@ static inline int z_impl_flash_erase(const struct device *dev, off_t offset,
 /**
  *  @brief  Enable or disable write protection for a flash memory
  *
- *  This API is required to be called before the invocation of write or erase
- *  API. Any calls to flash_write() or flash_erase() that do not first disable
- *  write protection using this function result in undefined behavior.
- *  Usage Example:
- *  @code
- *   flash_write_protection_set(flash_dev, false);
- *   flash_erase(flash_dev, page_offset, page_size);
- *
- *   flash_write_protection_set(flash_dev, false);
- *   flash_write(flash_dev, offset, data, sizeof(data));
- *
- *   flash_write_protection_set(flash_dev, true); // enable is recommended
- *  @endcode
- *
- *  Please note that on some flash components, the write protection is
- *  automatically turned on again by the device after the completion of each
- *  call to flash_write or flash_erase(). Therefore, portable programs must
- *  disable write protection using this function before each call to
- *  flash_erase() or flash_write().
- *
- *  For some flash devices, this function may implement a no-operation, as some
- *  flash hardware does not support write protection, or may not support it in
- *  a manner that is compatible with this API. For these drivers, this function
- *  always returns success.
+ *  This API is deprecated and will be removed in Zephyr 2.8.
+ *  It will be keep as No-Operation until removal.
+ *  Flash write/erase protection management has been moved to write and erase
+ *  operations implementations in flash driver shims. For Out-of-tree drivers
+ *  which are not updated yet flash write/erase protection management is done
+ *  in flash_erase() and flash_write() using deprecated <p>write_protection</p>
+ *  shim handler.
  *
  *  @param  dev             : flash device
  *  @param  enable          : enable or disable flash write protection
  *
  *  @return  0 on success, negative errno code on fail.
  */
+__deprecated
 __syscall int flash_write_protection_set(const struct device *dev,
 					 bool enable);