2  * Copyright (c) 2017-2024 Nordic Semiconductor ASA
5  * SPDX-License-Identifier: Apache-2.0
36 	size_t pages_count; /* count of pages sequence of the same size */
60 	/** Minimal write alignment and size */
68 		/* Device has no explicit erase, so it either erases on
70 		 * This also includes devices that support erase but
80 /** Set for ordinary Flash where erase is needed before write of random data */
85 #define FLASH_ERASE_CAPS_UNSET		(int)-1
92 /* @brief Parser for flash_parameters for retrieving erase capabilities
95  * of erase capabilities of 0 if device does not have any.
96  * Not that in some cases availability of erase may be dependent on driver
97  * options, so even if by hardware design a device provides some erase
110 	return (p->caps.no_explicit_erase) ? 0 : FLASH_ERASE_C_EXPLICIT;  in flash_params_get_erase_cap()
135  * the driver, with the driver responsible for ensuring the "write-protect"
136  * after the operation completes (successfully or not) matches the write-protect
143  * @brief Flash erase implementation handler type
145  * @note Any necessary erase protection management must be performed by
146  * the driver, with the driver responsible for ensuring the "erase-protect"
147  * after the operation completes (successfully or not) matches the erase-protect
150  * The callback is optional for RAM non-volatile devices, which do not
151  * require erase by design, but may be provided if it allows device to
153  * operation the erase in driver uses.
156 			       size_t size);
159  * @brief Get device size in bytes.
161  * Returns total logical device size in bytes.
164  * @param[out] size	device size in bytes.
168 typedef int (*flash_api_get_size)(const struct device *dev, uint64_t *size);
176  * A flash device layout is a run-length encoded description of the
181  * returns an array of length 1, which specifies the page size and
186  * describes a group of pages that all have the same size. In this
208 	flash_api_erase erase;  member
236  *  the read offset, the read size, or the destination address.
253 		(const struct flash_driver_api *)dev->api;  in z_impl_flash_read()
255 	return api->read(dev, offset, data, len);  in z_impl_flash_read()
263  *  Write size and offset must be multiples of the minimum write block size
284 		(const struct flash_driver_api *)dev->api;  in z_impl_flash_write()
287 	rc = api->write(dev, offset, data, len);  in z_impl_flash_write()
293  *  @brief  Erase part or all of a flash memory
295  *  Acceptable values of erase size and offset are subject to
296  *  hardware-specific multiples of page size and offset. Please check
301  *  Any necessary erase protection management is performed by the driver
302  *  erase implementation itself.
305  *  explicit erase devices; in case when code relies on erasing
306  *  device, i.e. setting it to erase-value, prior to some operations,
307  *  but should work with explicit erase and RAM non-volatile devices,
311  *  @param  offset          : erase area starting offset
312  *  @param  size            : size of area to be erased
320 __syscall int flash_erase(const struct device *dev, off_t offset, size_t size);
323 				     size_t size)  in z_impl_flash_erase()  argument
325 	int rc = -ENOSYS;  in z_impl_flash_erase()
328 		(const struct flash_driver_api *)dev->api;  in z_impl_flash_erase()
330 	if (api->erase != NULL) {  in z_impl_flash_erase()
331 		rc = api->erase(dev, offset, size);  in z_impl_flash_erase()
338  * @brief Get device size in bytes.
340  * Returns total logical device size in bytes. Not all devices may support
341  * returning size, specifically those with non uniform page layouts or banked,
342  * in which case the function will return -ENOTSUP, and user has to rely
346  * @param[out] size	device size in bytes.
350 __syscall int flash_get_size(const struct device *dev, uint64_t *size);
352 static inline int z_impl_flash_get_size(const struct device *dev, uint64_t *size)  in z_impl_flash_get_size()  argument
354 	int rc = -ENOSYS;  in z_impl_flash_get_size()
355 	const struct flash_driver_api *api = (const struct flash_driver_api *)dev->api;  in z_impl_flash_get_size()
357 	if (api->get_size != NULL) {  in z_impl_flash_get_size()
358 		rc = api->get_size(dev, size);  in z_impl_flash_get_size()
368  * provided value. The @p offset and @p size of range need to be aligned to
369  * a write block size of a device.
374  * @param  size            : size of the range
379 __syscall int flash_fill(const struct device *dev, uint8_t val, off_t offset, size_t size);
382  *  @brief  Erase part or all of a flash memory or level it
384  *  If device is explicit erase type device or device driver provides erase
387  *  If a device does not require explicit erase, either because
388  *  it has no erase at all or has auto-erase/erase-on-write,
389  *  and does not provide erase callback then erase is emulated by
393  *  Erase page offset and size are constrains of paged, explicit erase devices,
396  *  will return on, if these constrains are not met, -EINVAL for
397  *  paged device, but may succeed on non-explicit erase devices.
398  *  For RAM non-volatile devices the erase pages are emulated,
403  *  Generally: if your code previously required device to be erase
405  *  function; but if your code can work with non-volatile RAM type devices,
406  *  without emulating erase, you should rather have different path
407  *  of execution for page-erase, i.e. Flash, devices and call
411  *  @param  offset          : erase area starting offset
412  *  @param  size            : size of area to be erased
418 __syscall int flash_flatten(const struct device *dev, off_t offset, size_t size);
422 	size_t size;  member
428  *  @brief  Get the size and start offset of flash page at certain flash offset.
434  *  @return  0 on success, -EINVAL if page of the offset doesn't exist.
441  *  @brief  Get the size and start offset of flash page of certain index.
447  *  @return  0 on success, -EINVAL  if page of the index doesn't exist.
508  * @retval -ENOTSUP if the flash driver does not support SFDP access
518 	int rv = -ENOTSUP;  in z_impl_flash_sfdp_read()
520 		(const struct flash_driver_api *)dev->api;  in z_impl_flash_sfdp_read()
522 	if (api->sfdp_read != NULL) {  in z_impl_flash_sfdp_read()
523 		rv = api->sfdp_read(dev, offset, data, len);  in z_impl_flash_sfdp_read()
535  * @retval 0 on successful store of 3-byte JEDEC id
536  * @retval -ENOTSUP if flash driver doesn't support this function
544 	int rv = -ENOTSUP;  in z_impl_flash_read_jedec_id()
546 		(const struct flash_driver_api *)dev->api;  in z_impl_flash_read_jedec_id()
548 	if (api->read_jedec_id != NULL) {  in z_impl_flash_read_jedec_id()
549 		rv = api->read_jedec_id(dev, id);  in z_impl_flash_read_jedec_id()
556  *  @brief  Get the minimum write block size supported by the driver
558  *  The write block size supported by the driver might differ from the write
559  *  block size of memory used because the driver might implements write-modify
564  *  @return  write block size in bytes.
571 		(const struct flash_driver_api *)dev->api;  in z_impl_flash_get_write_block_size()
573 	return api->get_parameters(dev)->write_block_size;  in z_impl_flash_get_write_block_size()
593 		(const struct flash_driver_api *)dev->api;  in z_impl_flash_get_parameters()
595 	return api->get_parameters(dev);  in z_impl_flash_get_parameters()
601  *  Besides of standard flash operations like write or erase, flash controllers
619  *  @retval -ENOTSUP if given device doesn't support extended operation.
620  *  @retval -ENOSYS if support for extended operations is not enabled in Kconfig
634  * The caller must supply a buffer of suitable size and ensure that the
645  * @param size Size of the region to copy, in bytes.
646  * @param[out] buf Pointer to a buffer of size @a buf_size.
647  * @param buf_size Size of the buffer pointed to by @a buf.
650  * @retval -EINVAL if an argument is invalid.
651  * @retval -EIO if an I/O error occurs.
652  * @retval -ENODEV if either @a src_dev or @a dst_dev are not ready.
655 			 const struct device *dst_dev, off_t dst_offset, off_t size, uint8_t *buf,
688 		(const struct flash_driver_api *)dev->api;  in z_impl_flash_ex_op()
690 	if (api->ex_op == NULL) {  in z_impl_flash_ex_op()
691 		return -ENOTSUP;  in z_impl_flash_ex_op()
694 	return api->ex_op(dev, code, in, out);  in z_impl_flash_ex_op()
701 	return -ENOSYS;  in z_impl_flash_ex_op()