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	FIXED_PARTITION_EXISTS(label)
	Returns non-0 value if fixed-partition of given DTS node label exists.
#define	FIXED_PARTITION_ID(label)
	Get flash area ID from fixed-partition DTS node label.
#define	FIXED_PARTITION_OFFSET(label)
	Get fixed-partition offset from DTS node label.
#define	FIXED_PARTITION_NODE_OFFSET(node)
	Get fixed-partition offset from DTS node.
#define	FIXED_PARTITION_SIZE(label)
	Get fixed-partition size for DTS node label.
#define	FIXED_PARTITION_NODE_SIZE(node)
	Get fixed-partition size for DTS node.
#define	FLASH_AREA_DEVICE(label)
	Get device pointer for device the area/partition resides on.
#define	FIXED_PARTITION_DEVICE(label)
	Get device pointer for device the area/partition resides on.
#define	FIXED_PARTITION_NODE_DEVICE(node)
	Get device pointer for device the area/partition resides on.
#define	FIXED_PARTITION(label)
	Get pointer to flash_area object by partition label.
#define	FIXED_PARTITION_1(node)
#define	FIXED_PARTITION_0(ord)

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_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.0.0

Macro Definition Documentation

FIXED_PARTITION

#define FIXED_PARTITION

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

FIXED_PARTITION_1(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

FIXED_PARTITION_0

#define FIXED_PARTITION_0

(

ord

)

#include <zephyr/storage/flash_map.h>

Value:

        ((const struct flash_area *)&DT_CAT(global_fixed_partition_ORD_, ord))

FIXED_PARTITION_1

#define FIXED_PARTITION_1

(

node

)

#include <zephyr/storage/flash_map.h>

Value:

FIXED_PARTITION_0(DT_DEP_ORD(node))

FIXED_PARTITION_DEVICE

#define FIXED_PARTITION_DEVICE

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

        DEVICE_DT_GET(DT_MTD_FROM_FIXED_PARTITION(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.

FIXED_PARTITION_EXISTS

#define FIXED_PARTITION_EXISTS

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

DT_FIXED_PARTITION_EXISTS(DT_NODELABEL(label))

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

Parameters

label

DTS node label

Returns

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

FIXED_PARTITION_ID

#define FIXED_PARTITION_ID

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

DT_FIXED_PARTITION_ID(DT_NODELABEL(label))

Get flash area ID from fixed-partition DTS node label.

Parameters

label

DTS node label of a partition

Returns

flash area ID

FIXED_PARTITION_NODE_DEVICE

#define FIXED_PARTITION_NODE_DEVICE

(

node

)

#include <zephyr/storage/flash_map.h>

Value:

        DEVICE_DT_GET(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.

FIXED_PARTITION_NODE_OFFSET

#define FIXED_PARTITION_NODE_OFFSET

(

node

)

#include <zephyr/storage/flash_map.h>

Value:

DT_REG_ADDR(node)

Get fixed-partition offset from DTS node.

Parameters

node	DTS node of a partition

Returns

fixed-partition offset, as defined for the partition in DTS.

FIXED_PARTITION_NODE_SIZE

#define FIXED_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

fixed-partition size, as defined for the partition in DTS.

FIXED_PARTITION_OFFSET

#define FIXED_PARTITION_OFFSET

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

DT_REG_ADDR(DT_NODELABEL(label))

Get fixed-partition offset from DTS node label.

Parameters

label

DTS node label of a partition

Returns

fixed-partition offset, as defined for the partition in DTS.

FIXED_PARTITION_SIZE

#define FIXED_PARTITION_SIZE

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

DT_REG_SIZE(DT_NODELABEL(label))

Get fixed-partition size for DTS node label.

Parameters

label

DTS node label

Returns

fixed-partition offset, as defined for the partition in DTS.

FLASH_AREA_DEVICE

#define FLASH_AREA_DEVICE

(

label

)

#include <zephyr/storage/flash_map.h>

Value:

        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

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_device_is_ready()

static 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 FIXED_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
[out]	sectors	buffer for sectors data
[in,out]	count	On input Capacity of sectors, on output number of sectors Retrieved.

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.
[out]	sectors	buffer for sectors data
[in,out]	count	On input Capacity of sectors, on output number of sectors retrieved.

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.