Zephyr API Documentation 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
14#ifndef ZEPHYR_INCLUDE_DRIVERS_FLASH_H_
15#define ZEPHYR_INCLUDE_DRIVERS_FLASH_H_
16
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
32extern "C" {
33#endif
34
35#if defined(CONFIG_FLASH_PAGE_LAYOUT)
37 size_t pages_count; /* count of pages sequence of the same size */
38 size_t pages_size;
39};
40#endif /* CONFIG_FLASH_PAGE_LAYOUT */
41
45
60
68 const size_t write_block_size;
69
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;
85};
86
88#define FLASH_ERASE_C_EXPLICIT 0x01
92#define FLASH_ERASE_CAPS_UNSET (int)-1
93/* The values below are now reserved but not used */
94#define FLASH_ERASE_C_SUPPORTED 0x02
95#define FLASH_ERASE_C_VAL_BIT 0x04
96#define FLASH_ERASE_UNIFORM_PAGE 0x08
97
112static inline
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);
121#endif
122#endif
123 return 0;
124}
125
129
134
147typedef int (*flash_api_read)(const struct device *dev, off_t offset,
148 void *data,
149 size_t len);
158typedef int (*flash_api_write)(const struct device *dev, off_t offset,
159 const void *data, size_t len);
160
174typedef int (*flash_api_erase)(const struct device *dev, off_t offset,
175 size_t size);
176
187typedef int (*flash_api_get_size)(const struct device *dev, uint64_t *size);
188
189typedef const struct flash_parameters* (*flash_api_get_parameters)(const struct device *dev);
190
191#if defined(CONFIG_FLASH_PAGE_LAYOUT)
213typedef 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
218typedef int (*flash_api_sfdp_read)(const struct device *dev, off_t offset,
219 void *data, size_t len);
220typedef int (*flash_api_read_jedec_id)(const struct device *dev, uint8_t *id);
221typedef int (*flash_api_ex_op)(const struct device *dev, uint16_t code,
222 const uintptr_t in, void *out);
223
224__subsystem struct flash_driver_api {
230#if defined(CONFIG_FLASH_PAGE_LAYOUT)
232#endif /* CONFIG_FLASH_PAGE_LAYOUT */
233#if defined(CONFIG_FLASH_JESD216_API)
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
245
250
264__syscall int flash_read(const struct device *dev, off_t offset, void *data,
265 size_t len);
266
267static 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
295__syscall int flash_write(const struct device *dev, off_t offset,
296 const void *data,
297 size_t len);
298
299static 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
339__syscall int flash_erase(const struct device *dev, off_t offset, size_t size);
340
341static 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
369__syscall int flash_get_size(const struct device *dev, uint64_t *size);
370
371static 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
398__syscall int flash_fill(const struct device *dev, uint8_t val, off_t offset, size_t size);
399
437__syscall int flash_flatten(const struct device *dev, off_t offset, size_t size);
438
440 off_t start_offset; /* offset from the base of flash address */
441 size_t size;
443};
444
445#if defined(CONFIG_FLASH_PAGE_LAYOUT)
455__syscall int flash_get_page_info_by_offs(const struct device *dev,
456 off_t offset,
457 struct flash_pages_info *info);
458
468__syscall int flash_get_page_info_by_idx(const struct device *dev,
469 uint32_t page_index,
470 struct flash_pages_info *info);
471
479__syscall size_t flash_get_page_count(const struct device *dev);
480
491typedef bool (*flash_page_cb)(const struct flash_pages_info *info, void *data);
492
505void 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)
530__syscall int flash_sfdp_read(const struct device *dev, off_t offset,
531 void *data, size_t len);
532
533static 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
558__syscall int flash_read_jedec_id(const struct device *dev, uint8_t *id);
559
560static 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
585__syscall size_t flash_get_write_block_size(const struct device *dev);
586
587static 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
607__syscall const struct flash_parameters *flash_get_parameters(const struct device *dev);
608
609static 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
642__syscall int flash_ex_op(const struct device *dev, uint16_t code,
643 const uintptr_t in, void *out);
644
673__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#define FLASH_EX_OP_VENDOR_BASE 0x8000
690#define FLASH_EX_OP_IS_VENDOR(c) ((c) & FLASH_EX_OP_VENDOR_BASE)
691
696 /*
697 * Reset flash device.
698 */
700};
701
702static 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
731
732#include <zephyr/syscalls/flash.h>
733
734#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:491
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:88
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)
Parser for flash_parameters for retrieving erase capabilities.
Definition flash.h:113
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:695
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:699
int(* flash_api_read_jedec_id)(const struct device *dev, uint8_t *id)
Definition flash.h:220
int(* flash_api_erase)(const struct device *dev, off_t offset, size_t size)
Flash erase implementation handler type.
Definition flash.h:174
const struct flash_parameters *(* flash_api_get_parameters)(const struct device *dev)
Definition flash.h:189
int(* flash_api_read)(const struct device *dev, off_t offset, void *data, size_t len)
Flash read implementation handler type.
Definition flash.h:147
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:213
int(* flash_api_get_size)(const struct device *dev, uint64_t *size)
Get device size in bytes.
Definition flash.h:187
int(* flash_api_sfdp_read)(const struct device *dev, off_t offset, void *data, size_t len)
Definition flash.h:218
int(* flash_api_ex_op)(const struct device *dev, uint16_t code, const uintptr_t in, void *out)
Definition flash.h:221
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:158
#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:224
flash_api_sfdp_read sfdp_read
Definition flash.h:234
flash_api_get_parameters get_parameters
Definition flash.h:228
flash_api_pages_layout page_layout
Definition flash.h:231
flash_api_read read
Definition flash.h:225
flash_api_get_size get_size
Definition flash.h:229
flash_api_write write
Definition flash.h:226
flash_api_erase erase
Definition flash.h:227
flash_api_read_jedec_id read_jedec_id
Definition flash.h:235
Definition flash.h:439
size_t size
Definition flash.h:441
off_t start_offset
Definition flash.h:440
uint32_t index
Definition flash.h:442
Definition flash.h:36
size_t pages_size
Definition flash.h:38
size_t pages_count
Definition flash.h:37
Flash memory parameters.
Definition flash.h:66
uint8_t erase_value
Value the device is filled in erased areas.
Definition flash.h:84
const size_t write_block_size
Minimal write alignment and size.
Definition flash.h:68