flash area Interface

Abstraction over flash partitions/areas and their drivers. More...

Data Structures
struct	flash_area
	Flash partition. More...
struct	flash_sector
	Structure for transfer flash sector boundaries. More...

Macros
#define	PARTITION_EXISTS(label)
	Returns non-0 value if partition of given DTS node label exists.
#define	FIXED_PARTITION_EXISTS(label)
	Deprecated macro, replace with PARTITION_EXISTS(), this cannot use __DEPRECATED_MACRO as it causes usage of the macro to fail with compiler errors.
#define	PARTITION_ID(label)
	Get flash area ID from partition DTS node label.
#define	FIXED_PARTITION_ID(label)
	Deprecated macro, replace with PARTITION_ID().
#define	PARTITION_OFFSET(label)
	Get partition offset from DTS node label.
#define	FIXED_PARTITION_OFFSET(label)
	Deprecated macro, replace with PARTITION_OFFSET().
#define	PARTITION_ADDRESS(label)
	Get partition address from DTS node label.
#define	FIXED_PARTITION_ADDRESS(label)
	Deprecated macro, replace with PARTITION_ADDRESS().
#define	PARTITION_NODE_ADDRESS(node)
	Get partition address from DTS node.
#define	FIXED_PARTITION_NODE_ADDRESS(node)
	Deprecated macro, replace with PARTITION_NODE_ADDRESS().
#define	PARTITION_NODE_OFFSET(node)
	Get partition offset from DTS node.
#define	FIXED_PARTITION_NODE_OFFSET(label)
	Deprecated macro, replace with PARTITION_NODE_OFFSET().
#define	PARTITION_SIZE(label)
	Get partition size for DTS node label.
#define	FIXED_PARTITION_SIZE(label)
	Deprecated macro, replace with PARTITION_SIZE().
#define	PARTITION_NODE_SIZE(node)
	Get fixed-partition size for DTS node.
#define	FIXED_PARTITION_NODE_SIZE(node)
	Deprecated macro, replace with PARTITION_NODE_SIZE().
#define	FLASH_AREA_DEVICE(label)
	Get device pointer for device the area/partition resides on.
#define	PARTITION_DEVICE(label)
	Get device pointer for device the area/partition resides on.
#define	FIXED_PARTITION_DEVICE(label)
	Deprecated macro, replace with PARTITION_DEVICE().
#define	PARTITION_NODE_DEVICE(node)
	Get device pointer for device the area/partition resides on.
#define	FIXED_PARTITION_NODE_DEVICE(node)
	Deprecated macro, replace with PARTITION_NODE_DEVICE().
#define	PARTITION_MTD(label)
	Get the node identifier of the flash controller the area/partition resides on.
#define	FIXED_PARTITION_MTD(label)
	Deprecated macro, replace with PARTITION_OFFSET().
#define	PARTITION_NODE_MTD(node)
	Get the node identifier of the flash controller the area/partition resides on.
#define	FIXED_PARTITION_NODE_MTD(node)
	Deprecated macro, replace with PARTITION_NODE_MTD().
#define	PARTITION(label)
	Get pointer to flash_area object by partition label.
#define	FIXED_PARTITION(label)
	Deprecated macro, replace with PARTITION().
#define	PARTITION_BY_NODE(node)
	Get pointer to flash_area object by partition node in DTS.
#define	FIXED_PARTITION_BY_NODE(node)
	Deprecated macro, replace with PARTITION_OFFSET().

Typedefs
typedef void(*	flash_area_cb_t) (const struct flash_area *fa, void *user_data)
	Flash map iteration callback.

Functions
int	flash_area_open (uint8_t id, const struct flash_area **fa)
	Retrieve partitions flash area from the flash_map.
void	flash_area_close (const struct flash_area *fa)
	Close flash_area.
static ALWAYS_INLINE bool	flash_area_device_is_ready (const struct flash_area *fa)
	Verify that a device assigned to flash area is ready for use.
int	flash_area_read (const struct flash_area *fa, off_t off, void *dst, size_t len)
	Read flash area data.
int	flash_area_write (const struct flash_area *fa, off_t off, const void *src, size_t len)
	Write data to flash area.
int	flash_area_copy (const struct flash_area *src_fa, off_t src_off, const struct flash_area *dst_fa, off_t dst_off, off_t len, uint8_t *buf, size_t buf_size)
	Copy flash memory from one flash area to another.
int	flash_area_erase (const struct flash_area *fa, off_t off, size_t len)
	Erase flash area.
int	flash_area_flatten (const struct flash_area *fa, off_t off, size_t len)
	Erase flash area or fill with erase-value.
uint32_t	flash_area_align (const struct flash_area *fa)
	Get write block size of the flash area.
int	flash_area_get_sectors (int fa_id, uint32_t *count, struct flash_sector *sectors)
	Retrieve info about sectors within the area.
int	flash_area_sectors (const struct flash_area *fa, uint32_t *count, struct flash_sector *sectors)
	Retrieve info about sectors within the area.
void	flash_area_foreach (flash_area_cb_t user_cb, void *user_data)
	Iterate over flash map.
int	flash_area_has_driver (const struct flash_area *fa)
	Check whether given flash area has supporting flash driver in the system.
const struct device *	flash_area_get_device (const struct flash_area *fa)
	Get driver for given flash area.
uint8_t	flash_area_erased_val (const struct flash_area *fa)
	Get the value expected to be read when accessing any erased flash byte.

Detailed Description

Abstraction over flash partitions/areas and their drivers.

Since

1.11

Version

1.1.1

Macro Definition Documentation

FIXED_PARTITION

#define FIXED_PARTITION

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION(label) __DEPRECATED_MACRO

Deprecated macro, replace with PARTITION().

FIXED_PARTITION_ADDRESS

#define FIXED_PARTITION_ADDRESS

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_ADDRESS(label) __DEPRECATED_MACRO

Deprecated macro, replace with PARTITION_ADDRESS().

FIXED_PARTITION_BY_NODE

#define FIXED_PARTITION_BY_NODE

(

node

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_BY_NODE(node) __DEPRECATED_MACRO

Deprecated macro, replace with PARTITION_OFFSET().

FIXED_PARTITION_DEVICE

#define FIXED_PARTITION_DEVICE

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_DEVICE(label) __DEPRECATED_MACRO

Deprecated macro, replace with PARTITION_DEVICE().

FIXED_PARTITION_EXISTS

#define FIXED_PARTITION_EXISTS

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_EXISTS(label)

Deprecated macro, replace with PARTITION_EXISTS(), this cannot use __DEPRECATED_MACRO as it causes usage of the macro to fail with compiler errors.

FIXED_PARTITION_ID

#define FIXED_PARTITION_ID

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_ID(label) __DEPRECATED_MACRO

Deprecated macro, replace with PARTITION_ID().

FIXED_PARTITION_MTD

#define FIXED_PARTITION_MTD

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_MTD(label) __DEPRECATED_MACRO

Deprecated macro, replace with PARTITION_OFFSET().

FIXED_PARTITION_NODE_ADDRESS

#define FIXED_PARTITION_NODE_ADDRESS

(

node

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_NODE_ADDRESS(node) __DEPRECATED_MACRO

Deprecated macro, replace with PARTITION_NODE_ADDRESS().

FIXED_PARTITION_NODE_DEVICE

#define FIXED_PARTITION_NODE_DEVICE

(

node

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_NODE_DEVICE(node) __DEPRECATED_MACRO

Deprecated macro, replace with PARTITION_NODE_DEVICE().

FIXED_PARTITION_NODE_MTD

#define FIXED_PARTITION_NODE_MTD

(

node

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_NODE_MTD(node) __DEPRECATED_MACRO

Deprecated macro, replace with PARTITION_NODE_MTD().

FIXED_PARTITION_NODE_OFFSET

#define FIXED_PARTITION_NODE_OFFSET

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_NODE_OFFSET(label) __DEPRECATED_MACRO

Deprecated macro, replace with PARTITION_NODE_OFFSET().

FIXED_PARTITION_NODE_SIZE

#define FIXED_PARTITION_NODE_SIZE

(

node

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_NODE_SIZE(node) __DEPRECATED_MACRO

Deprecated macro, replace with PARTITION_NODE_SIZE().

FIXED_PARTITION_OFFSET

#define FIXED_PARTITION_OFFSET

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_OFFSET(label) __DEPRECATED_MACRO

Deprecated macro, replace with PARTITION_OFFSET().

FIXED_PARTITION_SIZE

#define FIXED_PARTITION_SIZE

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_SIZE(label) __DEPRECATED_MACRO

Deprecated macro, replace with PARTITION_SIZE().

FLASH_AREA_DEVICE

#define FLASH_AREA_DEVICE

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

COND_CODE_1(DT_NODE_HAS_COMPAT(DT_NODELABEL(label), zephyr_mapped_partition),   \
            (DEVICE_DT_GET(DT_MTD_FROM_MAPPED_PARTITION(                        \
                                DT_NODE_BY_MAPPED_PARTITION_LABEL(label)))),    \
            (DEVICE_DT_GET(DT_MTD_FROM_FIXED_PARTITION(                         \
                                DT_NODE_BY_FIXED_PARTITION_LABEL(label)))))

Get device pointer for device the area/partition resides on.

Parameters

label

DTS node label of a partition

Returns

const struct device type pointer

PARTITION

#define PARTITION

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_BY_NODE(DT_NODELABEL(label))

Get pointer to flash_area object by partition label.

Parameters

label

DTS node label of a partition

Returns

Pointer to flash_area type object representing partition

PARTITION_ADDRESS

#define PARTITION_ADDRESS

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_NODE_ADDRESS(DT_NODELABEL(label))

Get partition address from DTS node label.

Parameters

label

DTS node label of a partition

Returns

address, as defined for the partition in DTS.

PARTITION_BY_NODE

#define PARTITION_BY_NODE

(

node

)

#include <zephyr/storage/flash_map.h>

Value:

COND_CODE_1(DT_NODE_HAS_COMPAT(node, zephyr_mapped_partition),  \
            (MAPPED_PARTITION_1(node)),                         \
            (FIXED_PARTITION_1(node)))

Get pointer to flash_area object by partition node in DTS.

Parameters

node	DTS node of a partition

Returns

Pointer to flash_area type object representing partition

PARTITION_DEVICE

#define PARTITION_DEVICE

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_NODE_DEVICE(DT_NODELABEL(label))

Get device pointer for device the area/partition resides on.

Parameters

label

DTS node label of a partition

Returns

Pointer to a device.

PARTITION_EXISTS

#define PARTITION_EXISTS

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

DT_PARTITION_EXISTS(DT_NODELABEL(label))

Returns non-0 value if partition of given DTS node label exists.

Parameters

label

DTS node label

Returns

non-0 if partition node exists and is enabled; 0 if node does not exist, is not enabled or is not partition.

PARTITION_ID

#define PARTITION_ID

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

COND_CODE_1(DT_NODE_HAS_COMPAT(DT_NODELABEL(label), zephyr_mapped_partition),   \
            (DT_MAPPED_PARTITION_ID(DT_NODELABEL(label))),                      \
            (DT_FIXED_PARTITION_ID(DT_NODELABEL(label))))

Get flash area ID from partition DTS node label.

Parameters

label

DTS node label of a partition

Returns

flash area ID

PARTITION_MTD

#define PARTITION_MTD

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_NODE_MTD(DT_NODELABEL(label))

Get the node identifier of the flash controller the area/partition resides on.

Parameters

label

DTS node label of a partition

Returns

Pointer to a device.

PARTITION_NODE_ADDRESS

#define PARTITION_NODE_ADDRESS

(

node

)

#include <zephyr/storage/flash_map.h>

Value:

COND_CODE_1(DT_NODE_HAS_COMPAT(node, zephyr_mapped_partition),          \
            (DT_MAPPED_PARTITION_ADDR(node)),                           \
            (COND_CODE_1(DT_FIXED_SUBPARTITION_EXISTS(node),            \
                         (DT_FIXED_SUBPARTITION_ADDR(node)),            \
                         (DT_FIXED_PARTITION_ADDR(node)))))

Get partition address from DTS node.

Parameters

node	DTS node of a partition

Returns

address, as defined for the partition in DTS.

PARTITION_NODE_DEVICE

#define PARTITION_NODE_DEVICE

(

node

)

#include <zephyr/storage/flash_map.h>

Value:

COND_CODE_1(DT_NODE_HAS_COMPAT(node, zephyr_mapped_partition),                  \
            (DEVICE_DT_GET(DT_MTD_FROM_MAPPED_PARTITION(node))),                \
            (DEVICE_DT_GET(COND_CODE_1(DT_FIXED_SUBPARTITION_EXISTS(node),      \
                           (DT_MTD_FROM_FIXED_SUBPARTITION(node)),              \
                           (DT_MTD_FROM_FIXED_PARTITION(node))))))

Get device pointer for device the area/partition resides on.

Parameters

node	DTS node of a partition

Returns

Pointer to a device.

PARTITION_NODE_MTD

#define PARTITION_NODE_MTD

(

node

)

#include <zephyr/storage/flash_map.h>

Value:

COND_CODE_1(DT_NODE_HAS_COMPAT(node, zephyr_mapped_partition),          \
            (DT_MTD_FROM_MAPPED_PARTITION(node)),                       \
            (COND_CODE_1(DT_FIXED_SUBPARTITION_EXISTS(node),            \
                         (DT_MTD_FROM_FIXED_SUBPARTITION(node)),        \
                         (DT_MTD_FROM_FIXED_PARTITION(node)))))

Get the node identifier of the flash controller the area/partition resides on.

Parameters

node	DTS node of a partition

Returns

Pointer to a device.

PARTITION_NODE_OFFSET

#define PARTITION_NODE_OFFSET

(

node

)

#include <zephyr/storage/flash_map.h>

Value:

COND_CASE_1(DT_NODE_HAS_COMPAT(node, zephyr_mapped_partition),                          \
            (DT_MAPPED_PARTITION_OFFSET(node)),                                         \
            DT_FIXED_SUBPARTITION_EXISTS(node),                                         \
            (DT_PROP_BY_IDX(DT_PARENT(node), reg, 0) + DT_PROP_BY_IDX(node, reg, 0)),   \
            ((DT_PROP_BY_IDX(node, reg, 0))))

Get partition offset from DTS node.

Note: This only works from a top level fixed-partitions node, top level fixed-subpartitions node or fixed-partitions node inside of 1 layer of a fixed-subpartitions node, it will not work for multiple layers of fixed-subpartitions nodes, though this works on all instances of zephyr,mapped-partition nodes.

Parameters

node	DTS node of a partition

Returns

offset, as defined for the partition in DTS.

PARTITION_NODE_SIZE

#define PARTITION_NODE_SIZE

(

node

)

#include <zephyr/storage/flash_map.h>

Value:

DT_REG_SIZE(node)

Get fixed-partition size for DTS node.

Parameters

node	DTS node of a partition

Returns

size, as defined for the partition in DTS.

PARTITION_OFFSET

#define PARTITION_OFFSET

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

PARTITION_NODE_OFFSET(DT_NODELABEL(label))

Get partition offset from DTS node label.

Note: This only works from a top level fixed-partitions node, top level fixed-subpartitions node or fixed-partitions node inside of 1 layer of a fixed-subpartitions node, it will not work for multiple layers of fixed-subpartitions nodes, though this works on all instances of zephyr,mapped-partition nodes.

Parameters

label

DTS node label of a partition

Returns

offset, as defined for the partition in DTS.

PARTITION_SIZE

#define PARTITION_SIZE

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

DT_REG_SIZE(DT_NODELABEL(label))

Get partition size for DTS node label.

Parameters

label

DTS node label

Returns

size, as defined for the partition in DTS.

Typedef Documentation

flash_area_cb_t

typedef void(* flash_area_cb_t) (const struct flash_area *fa, void *user_data)

#include <zephyr/storage/flash_map.h>

Flash map iteration callback.

Parameters

fa	flash area
user_data	User supplied data

Function Documentation

flash_area_align()

uint32_t flash_area_align

(

const struct flash_area *

fa

)

#include <zephyr/storage/flash_map.h>

Get write block size of the flash area.

Currently write block size might be treated as read block size, although most of drivers supports unaligned readout.

Parameters

[in]

fa

Flash area

Returns

Alignment restriction for flash writes in [B].

flash_area_close()

void flash_area_close

(

const struct flash_area *

fa

)

#include <zephyr/storage/flash_map.h>

Close flash_area.

Reserved for future usage and external projects compatibility reason. Currently is NOP.

Parameters

[in]

fa

Flash area to be closed.

flash_area_copy()

int flash_area_copy	(	const struct flash_area *	src_fa,
		off_t	src_off,
		const struct flash_area *	dst_fa,
		off_t	dst_off,
		off_t	len,
		uint8_t *	buf,
		size_t	buf_size )

#include <zephyr/storage/flash_map.h>

Copy flash memory from one flash area to another.

Copy data to flash area. Area boundaries are asserted before copy request.

For more information, see flash_copy().

Parameters

[in]	src_fa	Source Flash area
[in]	src_off	Offset relative from beginning of source flash area.
[in]	dst_fa	Destination Flash area
[in]	dst_off	Offset relative from beginning of destination flash area.
[in]	len	Number of bytes to copy, in bytes.
[out]	buf	Pointer to a buffer of size buf_size.
[in]	buf_size	Size of the buffer pointed to by buf.

Returns

0 on success, negative errno code on fail.

flash_area_device_is_ready()

ALWAYS_INLINE bool flash_area_device_is_ready ( const struct flash_area * fa )

static

#include <zephyr/storage/flash_map.h>

Verify that a device assigned to flash area is ready for use.

Indicates whether the provided flash area has a device known to be in a state where it can be used with Flash Map API.

This can be used with struct flash_area pointers captured from PARTITION(). At minimum this means that the device has been successfully initialized.

Parameters

fa	pointer to flash_area object to check.

Return values

true	If the device is ready for use.
false	If the device is not ready for use or if a NULL pointer is passed as flash area pointer or device pointer within flash area object is NULL.

flash_area_erase()

int flash_area_erase	(	const struct flash_area *	fa,
		off_t	off,
		size_t	len )

#include <zephyr/storage/flash_map.h>

Erase flash area.

Erase given flash area range. Area boundaries are asserted before erase request. API has the same limitation regard erase-block alignment and size as wrapped flash driver.

Parameters

[in]	fa	Flash area
[in]	off	Offset relative from beginning of flash area.
[in]	len	Number of bytes to be erase

Returns

0 on success, negative errno code on fail.

flash_area_erased_val()

uint8_t flash_area_erased_val

(

const struct flash_area *

fa

)

#include <zephyr/storage/flash_map.h>

Get the value expected to be read when accessing any erased flash byte.

This API is compatible with the MCUBoot's porting layer.

Parameters

fa	Flash area.

Returns

Byte value of erase memory.

flash_area_flatten()

int flash_area_flatten	(	const struct flash_area *	fa,
		off_t	off,
		size_t	len )

#include <zephyr/storage/flash_map.h>

Erase flash area or fill with erase-value.

On program-erase devices this function behaves exactly like flash_area_erase. On RAM non-volatile device it will call erase, if driver provides such callback, or will fill given range with erase-value defined by driver. This function should be only used by code that has not been written to directly support devices that do not require erase and rely on device being erased prior to some operations. Note that emulated erase, on devices that do not require, is done via write, which affects endurance of device.

See also

flash_area_erase()

flash_flatten()

Parameters

[in]	fa	Flash area
[in]	off	Offset relative from beginning of flash area.
[in]	len	Number of bytes to be erase

Returns

0 on success, negative errno code on fail.

flash_area_foreach()

void flash_area_foreach	(	flash_area_cb_t	user_cb,
		void *	user_data )

#include <zephyr/storage/flash_map.h>

Iterate over flash map.

Parameters

user_cb	User callback
user_data	User supplied data

flash_area_get_device()

const struct device * flash_area_get_device

(

const struct flash_area *

fa

)

#include <zephyr/storage/flash_map.h>

Get driver for given flash area.

Parameters

[in]

fa

Flash area.

Returns

device driver.

flash_area_get_sectors()

int flash_area_get_sectors	(	int	fa_id,
		uint32_t *	count,
		struct flash_sector *	sectors )

#include <zephyr/storage/flash_map.h>

Retrieve info about sectors within the area.

Parameters

[in]	fa_id	Given flash area ID
[in,out]	count	On input Capacity of sectors, on output number of sectors Retrieved.
[out]	sectors	buffer for sectors data

Returns

0 on success, negative errno code on fail. Especially returns -ENOMEM if There are too many flash pages on the flash_area to fit in the array.

flash_area_has_driver()

int flash_area_has_driver

(

const struct flash_area *

fa

)

#include <zephyr/storage/flash_map.h>

Check whether given flash area has supporting flash driver in the system.

Parameters

[in]

fa

Flash area.

Returns

1 On success. -ENODEV if no driver match.

flash_area_open()

int flash_area_open	(	uint8_t	id,
		const struct flash_area **	fa )

#include <zephyr/storage/flash_map.h>

Retrieve partitions flash area from the flash_map.

Function Retrieves flash_area from flash_map for given partition.

Parameters

[in]	id	ID of the flash partition.
[out]	fa	Pointer which has to reference flash_area. If ID is unknown, it will be NULL on output.

Returns

0 on success, -EACCES if the flash_map is not available , -ENOENT if ID is unknown, -ENODEV if there is no driver attached to the area.

flash_area_read()

int flash_area_read	(	const struct flash_area *	fa,
		off_t	off,
		void *	dst,
		size_t	len )

#include <zephyr/storage/flash_map.h>

Read flash area data.

Read data from flash area. Area readout boundaries are asserted before read request. API has the same limitation regard read-block alignment and size as wrapped flash driver.

Parameters

[in]	fa	Flash area
[in]	off	Offset relative from beginning of flash area to read
[out]	dst	Buffer to store read data
[in]	len	Number of bytes to read

Returns

0 on success, negative errno code on fail.

flash_area_sectors()

int flash_area_sectors	(	const struct flash_area *	fa,
		uint32_t *	count,
		struct flash_sector *	sectors )

#include <zephyr/storage/flash_map.h>

Retrieve info about sectors within the area.

Parameters

[in]	fa	pointer to flash area object.
[in,out]	count	On input Capacity of sectors, on output number of sectors retrieved.
[out]	sectors	buffer for sectors data

Returns

0 on success, negative errno code on fail. Especially returns -ENOMEM if There are too many flash pages on the flash_area to fit in the array.

flash_area_write()

int flash_area_write	(	const struct flash_area *	fa,
		off_t	off,
		const void *	src,
		size_t	len )

#include <zephyr/storage/flash_map.h>

Write data to flash area.

Write data to flash area. Area write boundaries are asserted before write request. API has the same limitation regard write-block alignment and size as wrapped flash driver.

Parameters

[in]	fa	Flash area
[in]	off	Offset relative from beginning of flash area to write
[in]	src	Buffer with data to be written
[in]	len	Number of bytes to write

Returns

0 on success, negative errno code on fail.