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	SOC_FLASH_0_ID   0
#define	SPI_FLASH_0_ID   1
#define	FLASH_AREA_LABEL_EXISTS(label)
#define	FLASH_AREA_LABEL_STR(lbl)
#define	FLASH_AREA_ID(label)
#define	FLASH_AREA_OFFSET(label)
#define	FLASH_AREA_SIZE(label)
#define	FIXED_PARTITION_EXISTS(label)   DT_FIXED_PARTITION_EXISTS(DT_NODELABEL(label))
#define	FIXED_PARTITION_ID(label)   DT_FIXED_PARTITION_ID(DT_NODELABEL(label))
#define	FIXED_PARTITION_OFFSET(label)   DT_REG_ADDR(DT_NODELABEL(label))
#define	FIXED_PARTITION_SIZE(label)   DT_REG_SIZE(DT_NODELABEL(label))
#define	FLASH_AREA_DEVICE(label)    DEVICE_DT_GET(DT_MTD_FROM_FIXED_PARTITION(DT_NODE_BY_FIXED_PARTITION_LABEL(label)))
#define	FIXED_PARTITION_DEVICE(label)    DEVICE_DT_GET(DT_MTD_FROM_FIXED_PARTITION(DT_NODELABEL(label)))

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

Functions
int	flash_area_open (uint8_t id, const struct flash_area **fa)
	Retrieve partitions flash area from the flash_map. More...
void	flash_area_close (const struct flash_area *fa)
	Close flash_area. More...
int	flash_area_read (const struct flash_area *fa, off_t off, void *dst, size_t len)
	Read flash area data. More...
int	flash_area_write (const struct flash_area *fa, off_t off, const void *src, size_t len)
	Write data to flash area. More...
int	flash_area_erase (const struct flash_area *fa, off_t off, size_t len)
	Erase flash area. More...
uint32_t	flash_area_align (const struct flash_area *fa)
	Get write block size of the flash area. More...
int	flash_area_get_sectors (int fa_id, uint32_t *count, struct flash_sector *sectors)
void	flash_area_foreach (flash_area_cb_t user_cb, void *user_data)
int	flash_area_has_driver (const struct flash_area *fa)
const struct device *	flash_area_get_device (const struct flash_area *fa)
uint8_t	flash_area_erased_val (const struct flash_area *fa)

Detailed Description

Abstraction over flash partitions/areas and their drivers.

Macro Definition Documentation

FIXED_PARTITION_DEVICE

#define FIXED_PARTITION_DEVICE

(

label

)

DEVICE_DT_GET(DT_MTD_FROM_FIXED_PARTITION(DT_NODELABEL(label)))

#include <include/zephyr/storage/flash_map.h>

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

)

DT_FIXED_PARTITION_EXISTS(DT_NODELABEL(label))

#include <include/zephyr/storage/flash_map.h>

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

)

DT_FIXED_PARTITION_ID(DT_NODELABEL(label))

#include <include/zephyr/storage/flash_map.h>

Get flash area ID from fixed-partition DTS node label

Parameters

label

DTS node label of a partition

Returns

flash area ID

FIXED_PARTITION_OFFSET

#define FIXED_PARTITION_OFFSET

(

label

)

DT_REG_ADDR(DT_NODELABEL(label))

#include <include/zephyr/storage/flash_map.h>

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

)

DT_REG_SIZE(DT_NODELABEL(label))

#include <include/zephyr/storage/flash_map.h>

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

)

DEVICE_DT_GET(DT_MTD_FROM_FIXED_PARTITION(DT_NODE_BY_FIXED_PARTITION_LABEL(label)))

#include <include/zephyr/storage/flash_map.h>

Get device pointer for device the area/partition resides on

Parameters

label

DTS node label of a partition

Returns

const struct device type pointer

FLASH_AREA_ID

#define FLASH_AREA_ID

(

label

)

#include <include/zephyr/storage/flash_map.h>

Value:

        __DEPRECATED_MACRO \
	DT_FIXED_PARTITION_ID(DT_NODE_BY_FIXED_PARTITION_LABEL(label))

FLASH_AREA_LABEL_EXISTS

#define FLASH_AREA_LABEL_EXISTS

(

label

)

#include <include/zephyr/storage/flash_map.h>

Value:

        __DEPRECATED_MACRO \
	DT_HAS_FIXED_PARTITION_LABEL(label)

FLASH_AREA_LABEL_STR

#define FLASH_AREA_LABEL_STR

(

lbl

)

#include <include/zephyr/storage/flash_map.h>

Value:

        __DEPRECATED_MACRO \
	DT_PROP(DT_NODE_BY_FIXED_PARTITION_LABEL(lbl), label)

FLASH_AREA_OFFSET

#define FLASH_AREA_OFFSET

(

label

)

#include <include/zephyr/storage/flash_map.h>

Value:

        __DEPRECATED_MACRO \
	DT_REG_ADDR(DT_NODE_BY_FIXED_PARTITION_LABEL(label))

FLASH_AREA_SIZE

#define FLASH_AREA_SIZE

(

label

)

#include <include/zephyr/storage/flash_map.h>

Value:

        __DEPRECATED_MACRO \
	DT_REG_SIZE(DT_NODE_BY_FIXED_PARTITION_LABEL(label))

SOC_FLASH_0_ID

#define SOC_FLASH_0_ID   0

#include <include/zephyr/storage/flash_map.h>

Provided for compatibility with MCUboot

SPI_FLASH_0_ID

#define SPI_FLASH_0_ID   1

#include <include/zephyr/storage/flash_map.h>

Provided for compatibility with MCUboot

Typedef Documentation

flash_area_cb_t

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

#include <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 <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 <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_erase()

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

#include <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 <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_foreach()

void flash_area_foreach	(	flash_area_cb_t	user_cb,
		void *	user_data
	)

#include <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 <include/zephyr/storage/flash_map.h>

Get driver for given flash area.

Parameters

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

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

#include <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 read
[out]	src	Buffer with data to be written
[in]	len	Number of bytes to write

Returns

0 on success, negative errno code on fail.