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 */
85 #define FLASH_ERASE_CAPS_UNSET		(int)-1
110 	return (p->caps.no_explicit_erase) ? 0 : FLASH_ERASE_C_EXPLICIT;  in flash_params_get_erase_cap()
128 typedef int (*flash_api_read)(const struct device *dev, off_t offset,
135  * the driver, with the driver responsible for ensuring the "write-protect"
136  * after the operation completes (successfully or not) matches the write-protect
139 typedef int (*flash_api_write)(const struct device *dev, off_t offset,
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
155 typedef int (*flash_api_erase)(const struct device *dev, off_t offset,
156 			       size_t size);
159  * @brief Get device size in bytes.
161  * Returns total logical device size in bytes.
163  * @param[in] dev	flash device.
164  * @param[out] size	device size in bytes.
168 typedef int (*flash_api_get_size)(const struct device *dev, uint64_t *size);
170 typedef const struct flash_parameters* (*flash_api_get_parameters)(const struct device *dev);
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
190  * @param dev         Flash device whose layout to retrieve.
194 typedef void (*flash_api_pages_layout)(const struct device *dev,
199 typedef int (*flash_api_sfdp_read)(const struct device *dev, off_t offset,
201 typedef int (*flash_api_read_jedec_id)(const struct device *dev, uint8_t *id);
202 typedef int (*flash_api_ex_op)(const struct device *dev, uint16_t code,
236  *  the read offset, the read size, or the destination address.
238  *  @param  dev             : flash dev
245 __syscall int flash_read(const struct device *dev, off_t offset, void *data,
248 static inline int z_impl_flash_read(const struct device *dev, off_t offset,  in z_impl_flash_read()  argument
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
269  *  @param  dev             : flash device
276 __syscall int flash_write(const struct device *dev, off_t offset,
280 static inline int z_impl_flash_write(const struct device *dev, off_t offset,  in z_impl_flash_write()  argument
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()
295  *  Acceptable values of erase size and offset are subject to
296  *  hardware-specific multiples of page size and offset. Please check
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,
310  *  @param  dev             : flash device
312  *  @param  size            : size of area to be erased
320 __syscall int flash_erase(const struct device *dev, off_t offset, size_t size);
322 static inline int z_impl_flash_erase(const struct device *dev, off_t offset,  in z_impl_flash_erase()  argument
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
345  * @param[in] dev	flash device.
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.
371  * @param  dev             : flash 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);
388  *  it has no erase at all or has auto-erase/erase-on-write,
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,
405  *  function; but if your code can work with non-volatile RAM type devices,
407  *  of execution for page-erase, i.e. Flash, devices and call
410  *  @param  dev             : flash device
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.
430  *  @param  dev flash device
434  *  @return  0 on success, -EINVAL if page of the offset doesn't exist.
436 __syscall int flash_get_page_info_by_offs(const struct device *dev,
441  *  @brief  Get the size and start offset of flash page of certain index.
443  *  @param  dev flash device
447  *  @return  0 on success, -EINVAL  if page of the index doesn't exist.
449 __syscall int flash_get_page_info_by_idx(const struct device *dev,
456  *  @param  dev flash device
460 __syscall size_t flash_get_page_count(const struct device *dev);
482  * @param dev Device whose pages to iterate over
486 void flash_page_foreach(const struct device *dev, flash_page_cb cb,
500  * the driver underlying @p dev.
502  * @param dev device from which parameters will be read
508  * @retval -ENOTSUP if the flash driver does not support SFDP access
511 __syscall int flash_sfdp_read(const struct device *dev, off_t offset,
514 static inline int z_impl_flash_sfdp_read(const struct device *dev,  in z_impl_flash_sfdp_read()  argument
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()
531  * @param dev device from which id will be read
535  * @retval 0 on successful store of 3-byte JEDEC id
536  * @retval -ENOTSUP if flash driver doesn't support this function
539 __syscall int flash_read_jedec_id(const struct device *dev, uint8_t *id);
541 static inline int z_impl_flash_read_jedec_id(const struct device *dev,  in z_impl_flash_read_jedec_id()  argument
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
562  *  @param  dev flash device
564  *  @return  write block size in bytes.
566 __syscall size_t flash_get_write_block_size(const struct device *dev);
568 static inline size_t z_impl_flash_get_write_block_size(const struct device *dev)  in z_impl_flash_get_write_block_size()  argument
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()
588 __syscall const struct flash_parameters *flash_get_parameters(const struct device *dev);
590 static inline const struct flash_parameters *z_impl_flash_get_parameters(const struct device *dev)  in z_impl_flash_get_parameters()  argument
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()
611  *  @param dev Flash device
619  *  @retval -ENOTSUP if given device doesn't support extended operation.
620  *  @retval -ENOSYS if support for extended operations is not enabled in Kconfig
623 __syscall int flash_ex_op(const struct device *dev, uint16_t code,
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,
683 static inline int z_impl_flash_ex_op(const struct device *dev, uint16_t code,  in z_impl_flash_ex_op()  argument
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()
696 	ARG_UNUSED(dev);  in z_impl_flash_ex_op()
701 	return -ENOSYS;  in z_impl_flash_ex_op()