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