Zephyr Project API 4.2.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
flash.h
Go to the documentation of this file.
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
13#ifndef ZEPHYR_INCLUDE_DRIVERS_FLASH_H_
14#define ZEPHYR_INCLUDE_DRIVERS_FLASH_H_
15
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
31extern "C" {
32#endif
33
34#if defined(CONFIG_FLASH_PAGE_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
67 const size_t write_block_size;
68
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;
84};
85
87#define FLASH_ERASE_C_EXPLICIT 0x01
91#define FLASH_ERASE_CAPS_UNSET (int)-1
92/* The values below are now reserved but not used */
93#define FLASH_ERASE_C_SUPPORTED 0x02
94#define FLASH_ERASE_C_VAL_BIT 0x04
95#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 */
111static inline
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);
120#endif
121#endif
122 return 0;
123}
124
146typedef int (*flash_api_read)(const struct device *dev, off_t offset,
147 void *data,
148 size_t len);
157typedef int (*flash_api_write)(const struct device *dev, off_t offset,
158 const void *data, size_t len);
159
173typedef int (*flash_api_erase)(const struct device *dev, off_t offset,
174 size_t size);
175
186typedef int (*flash_api_get_size)(const struct device *dev, uint64_t *size);
187
188typedef const struct flash_parameters* (*flash_api_get_parameters)(const struct device *dev);
189
190#if defined(CONFIG_FLASH_PAGE_LAYOUT)
212typedef 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
217typedef int (*flash_api_sfdp_read)(const struct device *dev, off_t offset,
218 void *data, size_t len);
219typedef int (*flash_api_read_jedec_id)(const struct device *dev, uint8_t *id);
220typedef int (*flash_api_ex_op)(const struct device *dev, uint16_t code,
221 const uintptr_t in, void *out);
222
223__subsystem struct flash_driver_api {
229#if defined(CONFIG_FLASH_PAGE_LAYOUT)
231#endif /* CONFIG_FLASH_PAGE_LAYOUT */
232#if defined(CONFIG_FLASH_JESD216_API)
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
263__syscall int flash_read(const struct device *dev, off_t offset, void *data,
264 size_t len);
265
266static 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
294__syscall int flash_write(const struct device *dev, off_t offset,
295 const void *data,
296 size_t len);
297
298static 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
338__syscall int flash_erase(const struct device *dev, off_t offset, size_t size);
339
340static 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
368__syscall int flash_get_size(const struct device *dev, uint64_t *size);
369
370static 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
397__syscall int flash_fill(const struct device *dev, uint8_t val, off_t offset, size_t size);
398
436__syscall int flash_flatten(const struct device *dev, off_t offset, size_t size);
437
439 off_t start_offset; /* offset from the base of flash address */
440 size_t size;
442};
443
444#if defined(CONFIG_FLASH_PAGE_LAYOUT)
454__syscall int flash_get_page_info_by_offs(const struct device *dev,
455 off_t offset,
456 struct flash_pages_info *info);
457
467__syscall int flash_get_page_info_by_idx(const struct device *dev,
468 uint32_t page_index,
469 struct flash_pages_info *info);
470
478__syscall size_t flash_get_page_count(const struct device *dev);
479
490typedef bool (*flash_page_cb)(const struct flash_pages_info *info, void *data);
491
504void 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)
529__syscall int flash_sfdp_read(const struct device *dev, off_t offset,
530 void *data, size_t len);
531
532static 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
557__syscall int flash_read_jedec_id(const struct device *dev, uint8_t *id);
558
559static 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
584__syscall size_t flash_get_write_block_size(const struct device *dev);
585
586static 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
606__syscall const struct flash_parameters *flash_get_parameters(const struct device *dev);
607
608static 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
641__syscall int flash_ex_op(const struct device *dev, uint16_t code,
642 const uintptr_t in, void *out);
643
672__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#define FLASH_EX_OP_VENDOR_BASE 0x8000
689#define FLASH_EX_OP_IS_VENDOR(c) ((c) & FLASH_EX_OP_VENDOR_BASE)
690
695 /*
696 * Reset flash device.
697 */
699};
700
701static 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
731#include <zephyr/syscalls/flash.h>
732
733#endif /* ZEPHYR_INCLUDE_DRIVERS_FLASH_H_ */
System error numbers.
int flash_fill(const struct device *dev, uint8_t val, off_t offset, size_t size)
Fill selected range of device with specified value.
int flash_erase(const struct device *dev, off_t offset, size_t size)
Erase part or all of a flash memory.
const struct flash_parameters * flash_get_parameters(const struct device *dev)
Get pointer to flash_parameters structure.
int flash_flatten(const struct device *dev, off_t offset, size_t size)
Erase part or all of a flash memory or level it.
void flash_page_foreach(const struct device *dev, flash_page_cb cb, void *data)
Iterate over all flash pages on a device.
bool(* flash_page_cb)(const struct flash_pages_info *info, void *data)
Callback type for iterating over flash pages present on a device.
Definition flash.h:490
int flash_get_size(const struct device *dev, uint64_t *size)
Get device size in bytes.
int flash_ex_op(const struct device *dev, uint16_t code, const uintptr_t in, void *out)
Execute flash extended operation on given device.
#define FLASH_ERASE_C_EXPLICIT
Set for ordinary Flash where erase is needed before write of random data.
Definition flash.h:87
int flash_write(const struct device *dev, off_t offset, const void *data, size_t len)
Write buffer into flash memory.
int flash_copy(const struct device *src_dev, off_t src_offset, const struct device *dst_dev, off_t dst_offset, off_t size, uint8_t *buf, size_t buf_size)
Copy flash memory from one device to another.
int flash_sfdp_read(const struct device *dev, off_t offset, void *data, size_t len)
Read data from Serial Flash Discoverable Parameters.
int flash_read(const struct device *dev, off_t offset, void *data, size_t len)
Read data from flash.
size_t flash_get_write_block_size(const struct device *dev)
Get the minimum write block size supported by the driver.
int flash_get_page_info_by_idx(const struct device *dev, uint32_t page_index, struct flash_pages_info *info)
Get the size and start offset of flash page of certain index.
static int flash_params_get_erase_cap(const struct flash_parameters *p)
Definition flash.h:112
int flash_read_jedec_id(const struct device *dev, uint8_t *id)
Read the JEDEC ID from a compatible flash device.
flash_ex_op_types
Enumeration for extra flash operations.
Definition flash.h:694
size_t flash_get_page_count(const struct device *dev)
Get the total number of flash pages.
int flash_get_page_info_by_offs(const struct device *dev, off_t offset, struct flash_pages_info *info)
Get the size and start offset of flash page at certain flash offset.
@ FLASH_EX_OP_RESET
Definition flash.h:698
int(* flash_api_read_jedec_id)(const struct device *dev, uint8_t *id)
Definition flash.h:219
int(* flash_api_erase)(const struct device *dev, off_t offset, size_t size)
Flash erase implementation handler type.
Definition flash.h:173
const struct flash_parameters *(* flash_api_get_parameters)(const struct device *dev)
Definition flash.h:188
int(* flash_api_read)(const struct device *dev, off_t offset, void *data, size_t len)
Flash read implementation handler type.
Definition flash.h:146
void(* flash_api_pages_layout)(const struct device *dev, const struct flash_pages_layout **layout, size_t *layout_size)
Retrieve a flash device's layout.
Definition flash.h:212
int(* flash_api_get_size)(const struct device *dev, uint64_t *size)
Get device size in bytes.
Definition flash.h:186
int(* flash_api_sfdp_read)(const struct device *dev, off_t offset, void *data, size_t len)
Definition flash.h:217
int(* flash_api_ex_op)(const struct device *dev, uint16_t code, const uintptr_t in, void *out)
Definition flash.h:220
int(* flash_api_write)(const struct device *dev, off_t offset, const void *data, size_t len)
Flash write implementation handler type.
Definition flash.h:157
#define ENOSYS
Function not implemented.
Definition errno.h:82
#define ENOTSUP
Unsupported value.
Definition errno.h:114
#define NULL
Definition iar_missing_defs.h:20
__INTPTR_TYPE__ off_t
Definition types.h:36
#define bool
Definition stdbool.h:13
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
__UINT64_TYPE__ uint64_t
Definition stdint.h:91
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
__UINTPTR_TYPE__ uintptr_t
Definition stdint.h:105
__UINT16_TYPE__ uint16_t
Definition stdint.h:89
Runtime device structure (in ROM) per driver instance.
Definition device.h:510
void * data
Address of the device instance private data.
Definition device.h:520
const void * api
Address of the API structure exposed by the device instance.
Definition device.h:516
Definition flash.h:223
flash_api_sfdp_read sfdp_read
Definition flash.h:233
flash_api_get_parameters get_parameters
Definition flash.h:227
flash_api_pages_layout page_layout
Definition flash.h:230
flash_api_read read
Definition flash.h:224
flash_api_get_size get_size
Definition flash.h:228
flash_api_write write
Definition flash.h:225
flash_api_erase erase
Definition flash.h:226
flash_api_read_jedec_id read_jedec_id
Definition flash.h:234
Definition flash.h:438
size_t size
Definition flash.h:440
off_t start_offset
Definition flash.h:439
uint32_t index
Definition flash.h:441
Definition flash.h:35
size_t pages_size
Definition flash.h:37
size_t pages_count
Definition flash.h:36
Flash memory parameters.
Definition flash.h:65
uint8_t erase_value
Value the device is filled in erased areas.
Definition flash.h:83
const size_t write_block_size
Minimal write alignment and size.
Definition flash.h:67