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