FLASH Interface

FLASH Interface . More...

Data Structures
struct	flash_parameters
	Flash memory parameters. More...
struct	flash_pages_info

Macros
#define	FLASH_ERASE_C_EXPLICIT   0x01
	Set for ordinary Flash where erase is needed before write of random data.
#define	FLASH_ERASE_CAPS_UNSET   (int)-1
	Reserved for users as initializer for variables that will later store capabilities.
#define	FLASH_ERASE_C_SUPPORTED   0x02
#define	FLASH_ERASE_C_VAL_BIT   0x04
#define	FLASH_ERASE_UNIFORM_PAGE   0x08
#define	FLASH_EX_OP_VENDOR_BASE   0x8000
#define	FLASH_EX_OP_IS_VENDOR(c)

Typedefs
typedef bool(*	flash_page_cb) (const struct flash_pages_info *info, void *data)
	Callback type for iterating over flash pages present on a device.

Enumerations
enum	flash_ex_op_types { FLASH_EX_OP_RESET = 0 }
	Enumeration for extra flash operations. More...

Functions
static int	flash_params_get_erase_cap (const struct flash_parameters *p)
int	flash_read (const struct device *dev, off_t offset, void *data, size_t len)
	Read data from flash.
int	flash_write (const struct device *dev, off_t offset, const void *data, size_t len)
	Write buffer into flash memory.
int	flash_erase (const struct device *dev, off_t offset, size_t size)
	Erase part or all of a flash memory.
int	flash_get_size (const struct device *dev, uint64_t *size)
	Get device size in bytes.
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_flatten (const struct device *dev, off_t offset, size_t size)
	Erase part or all of a flash memory or level it.
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.
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.
size_t	flash_get_page_count (const struct device *dev)
	Get the total number of flash pages.
void	flash_page_foreach (const struct device *dev, flash_page_cb cb, void *data)
	Iterate over all flash pages on a device.
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_jedec_id (const struct device *dev, uint8_t *id)
	Read the JEDEC ID from a compatible flash device.
size_t	flash_get_write_block_size (const struct device *dev)
	Get the minimum write block size supported by the driver.
const struct flash_parameters *	flash_get_parameters (const struct device *dev)
	Get pointer to flash_parameters structure.
int	flash_ex_op (const struct device *dev, uint16_t code, const uintptr_t in, void *out)
	Execute flash extended operation on given device.
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.

Detailed Description

FLASH Interface .

Since

1.2

Version

1.0.0

Macro Definition Documentation

FLASH_ERASE_C_EXPLICIT

#define FLASH_ERASE_C_EXPLICIT   0x01

#include <zephyr/drivers/flash.h>

Set for ordinary Flash where erase is needed before write of random data.

FLASH_ERASE_C_SUPPORTED

#define FLASH_ERASE_C_SUPPORTED   0x02

#include <zephyr/drivers/flash.h>

FLASH_ERASE_C_VAL_BIT

#define FLASH_ERASE_C_VAL_BIT   0x04

#include <zephyr/drivers/flash.h>

FLASH_ERASE_CAPS_UNSET

#define FLASH_ERASE_CAPS_UNSET   (int)-1

#include <zephyr/drivers/flash.h>

Reserved for users as initializer for variables that will later store capabilities.

FLASH_ERASE_UNIFORM_PAGE

#define FLASH_ERASE_UNIFORM_PAGE   0x08

#include <zephyr/drivers/flash.h>

FLASH_EX_OP_IS_VENDOR

#define FLASH_EX_OP_IS_VENDOR

(

c

)

#include <zephyr/drivers/flash.h>

Value:

((c) & FLASH_EX_OP_VENDOR_BASE)

FLASH_EX_OP_VENDOR_BASE

#define FLASH_EX_OP_VENDOR_BASE   0x8000

#include <zephyr/drivers/flash.h>

Typedef Documentation

flash_page_cb

typedef bool(* flash_page_cb) (const struct flash_pages_info *info, void *data)

#include <zephyr/drivers/flash.h>

Callback type for iterating over flash pages present on a device.

The callback should return true to continue iterating, and false to halt.

Parameters

info	Information for current page
data	Private data for callback

Returns

True to continue iteration, false to halt iteration.

See also

flash_page_foreach()

Enumeration Type Documentation

flash_ex_op_types

enum flash_ex_op_types

#include <zephyr/drivers/flash.h>

Enumeration for extra flash operations.

Enumerator
FLASH_EX_OP_RESET

Function Documentation

flash_copy()

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 )

#include <zephyr/drivers/flash.h>

Copy flash memory from one device to another.

Copy a region of flash memory from one place to another. The source and destination flash devices may be the same or different devices. However, this function will fail if the source and destination devices are the same if memory regions overlap and are not identical.

The caller must supply a buffer of suitable size and ensure that the destination is erased beforehand, if necessary.

Note

If the source and destination devices are the same, and the source and destination offsets are also the same, this function succeeds without performing any copy operation.

Parameters

	src_dev	Source flash device.
	dst_dev	Destination flash device.
	src_offset	Offset within the source flash device.
	dst_offset	Offset within the destination flash device.
	size	Size of the region to copy, in bytes.
[out]	buf	Pointer to a buffer of size buf_size.
	buf_size	Size of the buffer pointed to by buf.

Return values

0	on success
-EINVAL	if an argument is invalid.
-EIO	if an I/O error occurs.
-ENODEV	if either src_dev or dst_dev are not ready.

flash_erase()

int flash_erase	(	const struct device *	dev,
		off_t	offset,
		size_t	size )

#include <zephyr/drivers/flash.h>

Erase part or all of a flash memory.

Acceptable values of erase size and offset are subject to hardware-specific multiples of page size and offset. Please check the API implemented by the underlying sub driver, for example by using flash_get_page_info_by_offs() if that is supported by your flash driver.

Any necessary erase protection management is performed by the driver erase implementation itself.

The function should be used only for devices that are really explicit erase devices; in case when code relies on erasing device, i.e. setting it to erase-value, prior to some operations, but should work with explicit erase and RAM non-volatile devices, then flash_flatten should rather be used.

Parameters

dev	: flash device
offset	: erase area starting offset
size	: size of area to be erased

Returns

0 on success, negative errno code on fail.

See also

flash_flatten()

flash_get_page_info_by_offs()

flash_get_page_info_by_idx()

flash_ex_op()

int flash_ex_op	(	const struct device *	dev,
		uint16_t	code,
		const uintptr_t	in,
		void *	out )

#include <zephyr/drivers/flash.h>

Execute flash extended operation on given device.

Besides of standard flash operations like write or erase, flash controllers also support additional features like write protection or readout protection. These features are not available in every flash controller, what's more controllers can implement it in a different way.

It doesn't make sense to add a separate flash API function for every flash controller feature, because it could be unique (supported on small number of flash controllers) or the API won't be able to represent the same feature on every flash controller.

Parameters

dev	Flash device
code	Operation which will be executed on the device.
in	Pointer to input data used by operation. If operation doesn't need any input data it could be NULL.
out	Pointer to operation output data. If operation doesn't produce any output it could be NULL.

Return values

0	on success.
-ENOTSUP	if given device doesn't support extended operation.
-ENOSYS	if support for extended operations is not enabled in Kconfig
negative	value on extended operation errors.

flash_fill()

int flash_fill	(	const struct device *	dev,
		uint8_t	val,
		off_t	offset,
		size_t	size )

#include <zephyr/drivers/flash.h>

Fill selected range of device with specified value.

Utility function that allows to fill specified range on a device with provided value. The offset and size of range need to be aligned to a write block size of a device.

Parameters

dev	: flash device
val	: value to use for filling the range
offset	: offset of the range to fill
size	: size of the range

Returns

0 on success, negative errno code on fail.

flash_flatten()

int flash_flatten	(	const struct device *	dev,
		off_t	offset,
		size_t	size )

#include <zephyr/drivers/flash.h>

Erase part or all of a flash memory or level it.

If device is explicit erase type device or device driver provides erase callback, the callback of the device is called, in which it behaves the same way as flash_erase. If a device does not require explicit erase, either because it has no erase at all or has auto-erase/erase-on-write, and does not provide erase callback then erase is emulated by leveling selected device memory area with erase_value assigned to device.

Erase page offset and size are constrains of paged, explicit erase devices, but can be relaxed with devices without such requirement, which means that it is up to user code to make sure they are correct as the function will return on, if these constrains are not met, -EINVAL for paged device, but may succeed on non-explicit erase devices. For RAM non-volatile devices the erase pages are emulated, at this point, to allow smooth transition for code relying on device being paged to function properly; but this is completely software constrain.

Generally: if your code previously required device to be erase prior to some actions to work, replace flash_erase calls with this function; but if your code can work with non-volatile RAM type devices, without emulating erase, you should rather have different path of execution for page-erase, i.e. Flash, devices and call flash_erase for them.

Parameters

dev	: flash device
offset	: erase area starting offset
size	: size of area to be erased

Returns

0 on success, negative errno code on fail.

See also

flash_erase()

flash_get_page_count()

size_t flash_get_page_count

(

const struct device *

dev

)

#include <zephyr/drivers/flash.h>

Get the total number of flash pages.

Parameters

dev	flash device

Returns

Number of flash pages.

flash_get_page_info_by_idx()

int flash_get_page_info_by_idx	(	const struct device *	dev,
		uint32_t	page_index,
		struct flash_pages_info *	info )

#include <zephyr/drivers/flash.h>

Get the size and start offset of flash page of certain index.

Parameters

dev	flash device
page_index	Index of the page. Index are counted from 0.
info	Page Info structure to be filled

Returns

0 on success, -EINVAL if page of the index doesn't exist.

flash_get_page_info_by_offs()

int flash_get_page_info_by_offs	(	const struct device *	dev,
		off_t	offset,
		struct flash_pages_info *	info )

#include <zephyr/drivers/flash.h>

Get the size and start offset of flash page at certain flash offset.

Parameters

dev	flash device
offset	Offset within the page
info	Page Info structure to be filled

Returns

0 on success, -EINVAL if page of the offset doesn't exist.

flash_get_parameters()

const struct flash_parameters * flash_get_parameters

(

const struct device *

dev

)

#include <zephyr/drivers/flash.h>

Get pointer to flash_parameters structure.

Returned pointer points to a structure that should be considered constant through a runtime, regardless if it is defined in RAM or Flash. Developer is free to cache the structure pointer or copy its contents.

Returns

pointer to flash_parameters structure characteristic for the device.

flash_get_size()

int flash_get_size	(	const struct device *	dev,
		uint64_t *	size )

#include <zephyr/drivers/flash.h>

Get device size in bytes.

Returns total logical device size in bytes. Not all devices may support returning size, specifically those with non uniform page layouts or banked, in which case the function will return -ENOTSUP, and user has to rely on Flash page layout functions enabled by CONFIG_FLASH_PAGE_LAYOUT.

Parameters

[in]	dev	flash device.
[out]	size	device size in bytes.

Returns

0 on success, negative errno code on error.

flash_get_write_block_size()

size_t flash_get_write_block_size

(

const struct device *

dev

)

#include <zephyr/drivers/flash.h>

Get the minimum write block size supported by the driver.

The write block size supported by the driver might differ from the write block size of memory used because the driver might implements write-modify algorithm.

Parameters

dev	flash device

Returns

write block size in bytes.

flash_page_foreach()

void flash_page_foreach	(	const struct device *	dev,
		flash_page_cb	cb,
		void *	data )

#include <zephyr/drivers/flash.h>

Iterate over all flash pages on a device.

This routine iterates over all flash pages on the given device, ordered by increasing start offset. For each page, it invokes the given callback, passing it the page's information and a private data object.

Parameters

dev	Device whose pages to iterate over
cb	Callback to invoke for each flash page
data	Private data for callback function

flash_params_get_erase_cap()

static int flash_params_get_erase_cap ( const struct flash_parameters * p )

inlinestatic

#include <zephyr/drivers/flash.h>

flash_read()

int flash_read	(	const struct device *	dev,
		off_t	offset,
		void *	data,
		size_t	len )

#include <zephyr/drivers/flash.h>

Read data from flash.

All flash drivers support reads without alignment restrictions on the read offset, the read size, or the destination address.

Parameters

dev	: flash dev
offset	: Offset (byte aligned) to read
data	: Buffer to store read data
len	: Number of bytes to read.

Returns

0 on success, negative errno code on fail.

flash_read_jedec_id()

int flash_read_jedec_id	(	const struct device *	dev,
		uint8_t *	id )

#include <zephyr/drivers/flash.h>

Read the JEDEC ID from a compatible flash device.

Parameters

dev	device from which id will be read
id	pointer to a buffer of at least 3 bytes into which id will be stored

Return values

0	on successful store of 3-byte JEDEC id
-ENOTSUP	if flash driver doesn't support this function
negative	values for other errors

flash_sfdp_read()

int flash_sfdp_read	(	const struct device *	dev,
		off_t	offset,
		void *	data,
		size_t	len )

#include <zephyr/drivers/flash.h>

Read data from Serial Flash Discoverable Parameters.

This routine reads data from a serial flash device compatible with the JEDEC JESD216 standard for encoding flash memory characteristics.

Availability of this API is conditional on selecting CONFIG_FLASH_JESD216_API and support of that functionality in the driver underlying dev.

Parameters

dev	device from which parameters will be read
offset	address within the SFDP region containing data of interest
data	where the data to be read will be placed
len	the number of bytes of data to be read

Return values

0	on success
-ENOTSUP	if the flash driver does not support SFDP access
negative	values for other errors.

flash_write()

int flash_write	(	const struct device *	dev,
		off_t	offset,
		const void *	data,
		size_t	len )

#include <zephyr/drivers/flash.h>

Write buffer into flash memory.

All flash drivers support a source buffer located either in RAM or SoC flash, without alignment restrictions on the source address. Write size and offset must be multiples of the minimum write block size supported by the driver.

Any necessary write protection management is performed by the driver write implementation itself.

Parameters

dev	: flash device
offset	: starting offset for the write
data	: data to write
len	: Number of bytes to write

Returns

0 on success, negative errno code on fail.