1 /*
2 * Copyright (c) 2017-2024 Nordic Semiconductor ASA
3 * Copyright (c) 2016 Intel Corporation
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 */
7
8 /**
9 * @file
10 * @brief Public API for FLASH drivers
11 */
12
13 #ifndef ZEPHYR_INCLUDE_DRIVERS_FLASH_H_
14 #define ZEPHYR_INCLUDE_DRIVERS_FLASH_H_
15
16 /**
17 * @brief FLASH internal Interface
18 * @defgroup flash_internal_interface FLASH internal Interface
19 * @ingroup io_interfaces
20 * @{
21 */
22
23 #include <errno.h>
24
25 #include <zephyr/types.h>
26 #include <stddef.h>
27 #include <sys/types.h>
28 #include <zephyr/device.h>
29
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33
34 #if defined(CONFIG_FLASH_PAGE_LAYOUT)
35 struct flash_pages_layout {
36 size_t pages_count; /* count of pages sequence of the same size */
37 size_t pages_size;
38 };
39 #endif /* CONFIG_FLASH_PAGE_LAYOUT */
40
41 /**
42 * @}
43 */
44
45 /**
46 * @brief FLASH Interface
47 * @defgroup flash_interface FLASH Interface
48 * @since 1.2
49 * @version 1.0.0
50 * @ingroup io_interfaces
51 * @{
52 */
53
54 /**
55 * Flash memory parameters. Contents of this structure suppose to be
56 * filled in during flash device initialization and stay constant
57 * through a runtime.
58 */
59 struct flash_parameters {
60 /** Minimal write alignment and size */
61 const size_t write_block_size;
62
63 /** @cond INTERNAL_HIDDEN */
64 /* User code should call flash_params_get_ functions on flash_parameters
65 * to get capabilities, rather than accessing object contents directly.
66 */
67 struct {
68 /* Device has no explicit erase, so it either erases on
69 * write or does not require it at all.
70 * This also includes devices that support erase but
71 * do not require it.
72 */
73 bool no_explicit_erase: 1;
74 } caps;
75 /** @endcond */
76 /** Value the device is filled in erased areas */
77 uint8_t erase_value;
78 };
79
80 /** Set for ordinary Flash where erase is needed before write of random data */
81 #define FLASH_ERASE_C_EXPLICIT 0x01
82 /** Reserved for users as initializer for variables that will later store
83 * capabilities.
84 */
85 #define FLASH_ERASE_CAPS_UNSET (int)-1
86 /* The values below are now reserved but not used */
87 #define FLASH_ERASE_C_SUPPORTED 0x02
88 #define FLASH_ERASE_C_VAL_BIT 0x04
89 #define FLASH_ERASE_UNIFORM_PAGE 0x08
90
91
92 /* @brief Parser for flash_parameters for retrieving erase capabilities
93 *
94 * The functions parses flash_parameters type object and returns combination
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
98 * capabilities, the function may return 0 if these been disabled or not
99 * implemented by driver.
100 *
101 * @param p pointer to flash_parameters type object
102 *
103 * @return 0 or combination of FLASH_ERASE_C_ capabilities.
104 */
105 static inline
flash_params_get_erase_cap(const struct flash_parameters * p)106 int flash_params_get_erase_cap(const struct flash_parameters *p)
107 {
108 #if defined(CONFIG_FLASH_HAS_EXPLICIT_ERASE)
109 #if defined(CONFIG_FLASH_HAS_NO_EXPLICIT_ERASE)
110 return (p->caps.no_explicit_erase) ? 0 : FLASH_ERASE_C_EXPLICIT;
111 #else
112 ARG_UNUSED(p);
113 return FLASH_ERASE_C_EXPLICIT;
114 #endif
115 #endif
116 return 0;
117 }
118
119 /**
120 * @}
121 */
122
123 /**
124 * @addtogroup flash_internal_interface
125 * @{
126 */
127
128 typedef int (*flash_api_read)(const struct device *dev, off_t offset,
129 void *data,
130 size_t len);
131 /**
132 * @brief Flash write implementation handler type
133 *
134 * @note Any necessary write protection management must be performed by
135 * the driver, with the driver responsible for ensuring the "write-protect"
136 * after the operation completes (successfully or not) matches the write-protect
137 * state when the operation was started.
138 */
139 typedef int (*flash_api_write)(const struct device *dev, off_t offset,
140 const void *data, size_t len);
141
142 /**
143 * @brief Flash erase implementation handler type
144 *
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
148 * state when the operation was started.
149 *
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
152 * work more effectively, or if device has a support for internal fill
153 * operation the erase in driver uses.
154 */
155 typedef int (*flash_api_erase)(const struct device *dev, off_t offset,
156 size_t size);
157
158 typedef const struct flash_parameters* (*flash_api_get_parameters)(const struct device *dev);
159
160 #if defined(CONFIG_FLASH_PAGE_LAYOUT)
161 /**
162 * @brief Retrieve a flash device's layout.
163 *
164 * A flash device layout is a run-length encoded description of the
165 * pages on the device. (Here, "page" means the smallest erasable
166 * area on the flash device.)
167 *
168 * For flash memories which have uniform page sizes, this routine
169 * returns an array of length 1, which specifies the page size and
170 * number of pages in the memory.
171 *
172 * Layouts for flash memories with nonuniform page sizes will be
173 * returned as an array with multiple elements, each of which
174 * describes a group of pages that all have the same size. In this
175 * case, the sequence of array elements specifies the order in which
176 * these groups occur on the device.
177 *
178 * @param dev Flash device whose layout to retrieve.
179 * @param layout The flash layout will be returned in this argument.
180 * @param layout_size The number of elements in the returned layout.
181 */
182 typedef void (*flash_api_pages_layout)(const struct device *dev,
183 const struct flash_pages_layout **layout,
184 size_t *layout_size);
185 #endif /* CONFIG_FLASH_PAGE_LAYOUT */
186
187 typedef int (*flash_api_sfdp_read)(const struct device *dev, off_t offset,
188 void *data, size_t len);
189 typedef int (*flash_api_read_jedec_id)(const struct device *dev, uint8_t *id);
190 typedef int (*flash_api_ex_op)(const struct device *dev, uint16_t code,
191 const uintptr_t in, void *out);
192
193 __subsystem struct flash_driver_api {
194 flash_api_read read;
195 flash_api_write write;
196 flash_api_erase erase;
197 flash_api_get_parameters get_parameters;
198 #if defined(CONFIG_FLASH_PAGE_LAYOUT)
199 flash_api_pages_layout page_layout;
200 #endif /* CONFIG_FLASH_PAGE_LAYOUT */
201 #if defined(CONFIG_FLASH_JESD216_API)
202 flash_api_sfdp_read sfdp_read;
203 flash_api_read_jedec_id read_jedec_id;
204 #endif /* CONFIG_FLASH_JESD216_API */
205 #if defined(CONFIG_FLASH_EX_OP_ENABLED)
206 flash_api_ex_op ex_op;
207 #endif /* CONFIG_FLASH_EX_OP_ENABLED */
208 };
209
210 /**
211 * @}
212 */
213
214 /**
215 * @addtogroup flash_interface
216 * @{
217 */
218
219 /**
220 * @brief Read data from flash
221 *
222 * All flash drivers support reads without alignment restrictions on
223 * the read offset, the read size, or the destination address.
224 *
225 * @param dev : flash dev
226 * @param offset : Offset (byte aligned) to read
227 * @param data : Buffer to store read data
228 * @param len : Number of bytes to read.
229 *
230 * @return 0 on success, negative errno code on fail.
231 */
232 __syscall int flash_read(const struct device *dev, off_t offset, void *data,
233 size_t len);
234
z_impl_flash_read(const struct device * dev,off_t offset,void * data,size_t len)235 static inline int z_impl_flash_read(const struct device *dev, off_t offset,
236 void *data,
237 size_t len)
238 {
239 const struct flash_driver_api *api =
240 (const struct flash_driver_api *)dev->api;
241
242 return api->read(dev, offset, data, len);
243 }
244
245 /**
246 * @brief Write buffer into flash memory.
247 *
248 * All flash drivers support a source buffer located either in RAM or
249 * SoC flash, without alignment restrictions on the source address.
250 * Write size and offset must be multiples of the minimum write block size
251 * supported by the driver.
252 *
253 * Any necessary write protection management is performed by the driver
254 * write implementation itself.
255 *
256 * @param dev : flash device
257 * @param offset : starting offset for the write
258 * @param data : data to write
259 * @param len : Number of bytes to write
260 *
261 * @return 0 on success, negative errno code on fail.
262 */
263 __syscall int flash_write(const struct device *dev, off_t offset,
264 const void *data,
265 size_t len);
266
z_impl_flash_write(const struct device * dev,off_t offset,const void * data,size_t len)267 static inline int z_impl_flash_write(const struct device *dev, off_t offset,
268 const void *data, size_t len)
269 {
270 const struct flash_driver_api *api =
271 (const struct flash_driver_api *)dev->api;
272 int rc;
273
274 rc = api->write(dev, offset, data, len);
275
276 return rc;
277 }
278
279 /**
280 * @brief Erase part or all of a flash memory
281 *
282 * Acceptable values of erase size and offset are subject to
283 * hardware-specific multiples of page size and offset. Please check
284 * the API implemented by the underlying sub driver, for example by
285 * using flash_get_page_info_by_offs() if that is supported by your
286 * flash driver.
287 *
288 * Any necessary erase protection management is performed by the driver
289 * erase implementation itself.
290 *
291 * The function should be used only for devices that are really
292 * explicit erase devices; in case when code relies on erasing
293 * device, i.e. setting it to erase-value, prior to some operations,
294 * but should work with explicit erase and RAM non-volatile devices,
295 * then flash_flatten should rather be used.
296 *
297 * @param dev : flash device
298 * @param offset : erase area starting offset
299 * @param size : size of area to be erased
300 *
301 * @return 0 on success, negative errno code on fail.
302 *
303 * @see flash_flatten()
304 * @see flash_get_page_info_by_offs()
305 * @see flash_get_page_info_by_idx()
306 */
307 __syscall int flash_erase(const struct device *dev, off_t offset, size_t size);
308
z_impl_flash_erase(const struct device * dev,off_t offset,size_t size)309 static inline int z_impl_flash_erase(const struct device *dev, off_t offset,
310 size_t size)
311 {
312 int rc = -ENOSYS;
313
314 const struct flash_driver_api *api =
315 (const struct flash_driver_api *)dev->api;
316
317 if (api->erase != NULL) {
318 rc = api->erase(dev, offset, size);
319 }
320
321 return rc;
322 }
323
324 /**
325 * @brief Fill selected range of device with specified value
326 *
327 * Utility function that allows to fill specified range on a device with
328 * provided value. The @p offset and @p size of range need to be aligned to
329 * a write block size of a device.
330 *
331 * @param dev : flash device
332 * @param val : value to use for filling the range
333 * @param offset : offset of the range to fill
334 * @param size : size of the range
335 *
336 * @return 0 on success, negative errno code on fail.
337 *
338 */
339 __syscall int flash_fill(const struct device *dev, uint8_t val, off_t offset, size_t size);
340
341 /**
342 * @brief Erase part or all of a flash memory or level it
343 *
344 * If device is explicit erase type device or device driver provides erase
345 * callback, the callback of the device is called, in which it behaves
346 * the same way as flash_erase.
347 * If a device does not require explicit erase, either because
348 * it has no erase at all or has auto-erase/erase-on-write,
349 * and does not provide erase callback then erase is emulated by
350 * leveling selected device memory area with erase_value assigned to
351 * device.
352 *
353 * Erase page offset and size are constrains of paged, explicit erase devices,
354 * but can be relaxed with devices without such requirement, which means that
355 * it is up to user code to make sure they are correct as the function
356 * will return on, if these constrains are not met, -EINVAL for
357 * paged device, but may succeed on non-explicit erase devices.
358 * For RAM non-volatile devices the erase pages are emulated,
359 * at this point, to allow smooth transition for code relying on
360 * device being paged to function properly; but this is completely
361 * software constrain.
362 *
363 * Generally: if your code previously required device to be erase
364 * prior to some actions to work, replace flash_erase calls with this
365 * function; but if your code can work with non-volatile RAM type devices,
366 * without emulating erase, you should rather have different path
367 * of execution for page-erase, i.e. Flash, devices and call
368 * flash_erase for them.
369 *
370 * @param dev : flash device
371 * @param offset : erase area starting offset
372 * @param size : size of area to be erased
373 *
374 * @return 0 on success, negative errno code on fail.
375 *
376 * @see flash_erase()
377 */
378 __syscall int flash_flatten(const struct device *dev, off_t offset, size_t size);
379
380 struct flash_pages_info {
381 off_t start_offset; /* offset from the base of flash address */
382 size_t size;
383 uint32_t index;
384 };
385
386 #if defined(CONFIG_FLASH_PAGE_LAYOUT)
387 /**
388 * @brief Get the size and start offset of flash page at certain flash offset.
389 *
390 * @param dev flash device
391 * @param offset Offset within the page
392 * @param info Page Info structure to be filled
393 *
394 * @return 0 on success, -EINVAL if page of the offset doesn't exist.
395 */
396 __syscall int flash_get_page_info_by_offs(const struct device *dev,
397 off_t offset,
398 struct flash_pages_info *info);
399
400 /**
401 * @brief Get the size and start offset of flash page of certain index.
402 *
403 * @param dev flash device
404 * @param page_index Index of the page. Index are counted from 0.
405 * @param info Page Info structure to be filled
406 *
407 * @return 0 on success, -EINVAL if page of the index doesn't exist.
408 */
409 __syscall int flash_get_page_info_by_idx(const struct device *dev,
410 uint32_t page_index,
411 struct flash_pages_info *info);
412
413 /**
414 * @brief Get the total number of flash pages.
415 *
416 * @param dev flash device
417 *
418 * @return Number of flash pages.
419 */
420 __syscall size_t flash_get_page_count(const struct device *dev);
421
422 /**
423 * @brief Callback type for iterating over flash pages present on a device.
424 *
425 * The callback should return true to continue iterating, and false to halt.
426 *
427 * @param info Information for current page
428 * @param data Private data for callback
429 * @return True to continue iteration, false to halt iteration.
430 * @see flash_page_foreach()
431 */
432 typedef bool (*flash_page_cb)(const struct flash_pages_info *info, void *data);
433
434 /**
435 * @brief Iterate over all flash pages on a device
436 *
437 * This routine iterates over all flash pages on the given device,
438 * ordered by increasing start offset. For each page, it invokes the
439 * given callback, passing it the page's information and a private
440 * data object.
441 *
442 * @param dev Device whose pages to iterate over
443 * @param cb Callback to invoke for each flash page
444 * @param data Private data for callback function
445 */
446 void flash_page_foreach(const struct device *dev, flash_page_cb cb,
447 void *data);
448 #endif /* CONFIG_FLASH_PAGE_LAYOUT */
449
450 #if defined(CONFIG_FLASH_JESD216_API)
451 /**
452 * @brief Read data from Serial Flash Discoverable Parameters
453 *
454 * This routine reads data from a serial flash device compatible with
455 * the JEDEC JESD216 standard for encoding flash memory
456 * characteristics.
457 *
458 * Availability of this API is conditional on selecting
459 * @c CONFIG_FLASH_JESD216_API and support of that functionality in
460 * the driver underlying @p dev.
461 *
462 * @param dev device from which parameters will be read
463 * @param offset address within the SFDP region containing data of interest
464 * @param data where the data to be read will be placed
465 * @param len the number of bytes of data to be read
466 *
467 * @retval 0 on success
468 * @retval -ENOTSUP if the flash driver does not support SFDP access
469 * @retval negative values for other errors.
470 */
471 __syscall int flash_sfdp_read(const struct device *dev, off_t offset,
472 void *data, size_t len);
473
z_impl_flash_sfdp_read(const struct device * dev,off_t offset,void * data,size_t len)474 static inline int z_impl_flash_sfdp_read(const struct device *dev,
475 off_t offset,
476 void *data, size_t len)
477 {
478 int rv = -ENOTSUP;
479 const struct flash_driver_api *api =
480 (const struct flash_driver_api *)dev->api;
481
482 if (api->sfdp_read != NULL) {
483 rv = api->sfdp_read(dev, offset, data, len);
484 }
485 return rv;
486 }
487
488 /**
489 * @brief Read the JEDEC ID from a compatible flash device.
490 *
491 * @param dev device from which id will be read
492 * @param id pointer to a buffer of at least 3 bytes into which id
493 * will be stored
494 *
495 * @retval 0 on successful store of 3-byte JEDEC id
496 * @retval -ENOTSUP if flash driver doesn't support this function
497 * @retval negative values for other errors
498 */
499 __syscall int flash_read_jedec_id(const struct device *dev, uint8_t *id);
500
z_impl_flash_read_jedec_id(const struct device * dev,uint8_t * id)501 static inline int z_impl_flash_read_jedec_id(const struct device *dev,
502 uint8_t *id)
503 {
504 int rv = -ENOTSUP;
505 const struct flash_driver_api *api =
506 (const struct flash_driver_api *)dev->api;
507
508 if (api->read_jedec_id != NULL) {
509 rv = api->read_jedec_id(dev, id);
510 }
511 return rv;
512 }
513 #endif /* CONFIG_FLASH_JESD216_API */
514
515 /**
516 * @brief Get the minimum write block size supported by the driver
517 *
518 * The write block size supported by the driver might differ from the write
519 * block size of memory used because the driver might implements write-modify
520 * algorithm.
521 *
522 * @param dev flash device
523 *
524 * @return write block size in bytes.
525 */
526 __syscall size_t flash_get_write_block_size(const struct device *dev);
527
z_impl_flash_get_write_block_size(const struct device * dev)528 static inline size_t z_impl_flash_get_write_block_size(const struct device *dev)
529 {
530 const struct flash_driver_api *api =
531 (const struct flash_driver_api *)dev->api;
532
533 return api->get_parameters(dev)->write_block_size;
534 }
535
536
537 /**
538 * @brief Get pointer to flash_parameters structure
539 *
540 * Returned pointer points to a structure that should be considered
541 * constant through a runtime, regardless if it is defined in RAM or
542 * Flash.
543 * Developer is free to cache the structure pointer or copy its contents.
544 *
545 * @return pointer to flash_parameters structure characteristic for
546 * the device.
547 */
548 __syscall const struct flash_parameters *flash_get_parameters(const struct device *dev);
549
z_impl_flash_get_parameters(const struct device * dev)550 static inline const struct flash_parameters *z_impl_flash_get_parameters(const struct device *dev)
551 {
552 const struct flash_driver_api *api =
553 (const struct flash_driver_api *)dev->api;
554
555 return api->get_parameters(dev);
556 }
557
558 /**
559 * @brief Execute flash extended operation on given device
560 *
561 * Besides of standard flash operations like write or erase, flash controllers
562 * also support additional features like write protection or readout
563 * protection. These features are not available in every flash controller,
564 * what's more controllers can implement it in a different way.
565 *
566 * It doesn't make sense to add a separate flash API function for every flash
567 * controller feature, because it could be unique (supported on small number of
568 * flash controllers) or the API won't be able to represent the same feature on
569 * every flash controller.
570 *
571 * @param dev Flash device
572 * @param code Operation which will be executed on the device.
573 * @param in Pointer to input data used by operation. If operation doesn't
574 * need any input data it could be NULL.
575 * @param out Pointer to operation output data. If operation doesn't produce
576 * any output it could be NULL.
577 *
578 * @retval 0 on success.
579 * @retval -ENOTSUP if given device doesn't support extended operation.
580 * @retval -ENOSYS if support for extended operations is not enabled in Kconfig
581 * @retval negative value on extended operation errors.
582 */
583 __syscall int flash_ex_op(const struct device *dev, uint16_t code,
584 const uintptr_t in, void *out);
585
586 /*
587 * Extended operation interface provides flexible way for supporting flash
588 * controller features. Code space is divided equally into Zephyr codes
589 * (MSb == 0) and vendor codes (MSb == 1). This way we can easily add extended
590 * operations to the drivers without cluttering the API or problems with API
591 * incompatibility. Extended operation can be promoted from vendor codes to
592 * Zephyr codes if the feature is available in most flash controllers and
593 * can be represented in the same way.
594 *
595 * It's not forbidden to have operation in Zephyr codes and vendor codes for
596 * the same functionality. In this case, vendor operation could provide more
597 * specific access when abstraction in Zephyr counterpart is insufficient.
598 */
599 #define FLASH_EX_OP_VENDOR_BASE 0x8000
600 #define FLASH_EX_OP_IS_VENDOR(c) ((c) & FLASH_EX_OP_VENDOR_BASE)
601
602 /**
603 * @brief Enumeration for extra flash operations
604 */
605 enum flash_ex_op_types {
606 /*
607 * Reset flash device.
608 */
609 FLASH_EX_OP_RESET = 0,
610 };
611
z_impl_flash_ex_op(const struct device * dev,uint16_t code,const uintptr_t in,void * out)612 static inline int z_impl_flash_ex_op(const struct device *dev, uint16_t code,
613 const uintptr_t in, void *out)
614 {
615 #if defined(CONFIG_FLASH_EX_OP_ENABLED)
616 const struct flash_driver_api *api =
617 (const struct flash_driver_api *)dev->api;
618
619 if (api->ex_op == NULL) {
620 return -ENOTSUP;
621 }
622
623 return api->ex_op(dev, code, in, out);
624 #else
625 ARG_UNUSED(dev);
626 ARG_UNUSED(code);
627 ARG_UNUSED(in);
628 ARG_UNUSED(out);
629
630 return -ENOSYS;
631 #endif /* CONFIG_FLASH_EX_OP_ENABLED */
632 }
633
634 #ifdef __cplusplus
635 }
636 #endif
637
638 /**
639 * @}
640 */
641
642 #include <zephyr/syscalls/flash.h>
643
644 #endif /* ZEPHYR_INCLUDE_DRIVERS_FLASH_H_ */
645
