Zephyr API Documentation  3.7.0-rc3
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
61 const size_t write_block_size;
62
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;
78};
79
81#define FLASH_ERASE_C_EXPLICIT 0x01
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 */
105static inline
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);
114#endif
115#endif
116 return 0;
117}
118
128typedef int (*flash_api_read)(const struct device *dev, off_t offset,
129 void *data,
130 size_t len);
139typedef int (*flash_api_write)(const struct device *dev, off_t offset,
140 const void *data, size_t len);
141
155typedef int (*flash_api_erase)(const struct device *dev, off_t offset,
156 size_t size);
157
158typedef const struct flash_parameters* (*flash_api_get_parameters)(const struct device *dev);
159
160#if defined(CONFIG_FLASH_PAGE_LAYOUT)
182typedef 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
187typedef int (*flash_api_sfdp_read)(const struct device *dev, off_t offset,
188 void *data, size_t len);
189typedef int (*flash_api_read_jedec_id)(const struct device *dev, uint8_t *id);
190typedef 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 {
198#if defined(CONFIG_FLASH_PAGE_LAYOUT)
200#endif /* CONFIG_FLASH_PAGE_LAYOUT */
201#if defined(CONFIG_FLASH_JESD216_API)
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
232__syscall int flash_read(const struct device *dev, off_t offset, void *data,
233 size_t len);
234
235static 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
263__syscall int flash_write(const struct device *dev, off_t offset,
264 const void *data,
265 size_t len);
266
267static 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
307__syscall int flash_erase(const struct device *dev, off_t offset, size_t size);
308
309static 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
339__syscall int flash_fill(const struct device *dev, uint8_t val, off_t offset, size_t size);
340
378__syscall int flash_flatten(const struct device *dev, off_t offset, size_t size);
379
381 off_t start_offset; /* offset from the base of flash address */
382 size_t size;
384};
385
386#if defined(CONFIG_FLASH_PAGE_LAYOUT)
396__syscall int flash_get_page_info_by_offs(const struct device *dev,
397 off_t offset,
398 struct flash_pages_info *info);
399
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
420__syscall size_t flash_get_page_count(const struct device *dev);
421
432typedef bool (*flash_page_cb)(const struct flash_pages_info *info, void *data);
433
446void 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)
471__syscall int flash_sfdp_read(const struct device *dev, off_t offset,
472 void *data, size_t len);
473
474static 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
499__syscall int flash_read_jedec_id(const struct device *dev, uint8_t *id);
500
501static 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
526__syscall size_t flash_get_write_block_size(const struct device *dev);
527
528static 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
548__syscall const struct flash_parameters *flash_get_parameters(const struct device *dev);
549
550static 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
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
606 /*
607 * Reset flash device.
608 */
610};
611
612static 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
642#include <zephyr/syscalls/flash.h>
643
644#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:432
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:81
int flash_write(const struct device *dev, off_t offset, const void *data, size_t len)
Write buffer into flash memory.
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:106
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:605
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:609
int(* flash_api_read_jedec_id)(const struct device *dev, uint8_t *id)
Definition: flash.h:189
int(* flash_api_erase)(const struct device *dev, off_t offset, size_t size)
Flash erase implementation handler type.
Definition: flash.h:155
const struct flash_parameters *(* flash_api_get_parameters)(const struct device *dev)
Definition: flash.h:158
int(* flash_api_read)(const struct device *dev, off_t offset, void *data, size_t len)
Definition: flash.h:128
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:182
int(* flash_api_sfdp_read)(const struct device *dev, off_t offset, void *data, size_t len)
Definition: flash.h:187
int(* flash_api_ex_op)(const struct device *dev, uint16_t code, const uintptr_t in, void *out)
Definition: flash.h:190
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:139
#define ENOSYS
Function not implemented.
Definition: errno.h:82
#define ENOTSUP
Unsupported value.
Definition: errno.h:114
__INTPTR_TYPE__ off_t
Definition: types.h:36
#define bool
Definition: stdbool.h:13
__UINT32_TYPE__ uint32_t
Definition: stdint.h:90
__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:403
void * data
Address of the device instance private data.
Definition: device.h:413
const void * api
Address of the API structure exposed by the device instance.
Definition: device.h:409
Definition: flash.h:193
flash_api_sfdp_read sfdp_read
Definition: flash.h:202
flash_api_get_parameters get_parameters
Definition: flash.h:197
flash_api_pages_layout page_layout
Definition: flash.h:199
flash_api_read read
Definition: flash.h:194
flash_api_write write
Definition: flash.h:195
flash_api_erase erase
Definition: flash.h:196
flash_api_read_jedec_id read_jedec_id
Definition: flash.h:203
Definition: flash.h:380
size_t size
Definition: flash.h:382
off_t start_offset
Definition: flash.h:381
uint32_t index
Definition: flash.h:383
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:59
uint8_t erase_value
Value the device is filled in erased areas.
Definition: flash.h:77
const size_t write_block_size
Minimal write alignment and size.
Definition: flash.h:61