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
	Provided for compatibility with MCUboot.

#define	SPI_FLASH_0_ID 1
	Provided for compatibility with MCUboot.

#define	FIXED_PARTITION_EXISTS(label) DT_FIXED_PARTITION_EXISTS(DT_NODELABEL(label))
	Returns non-0 value if fixed-partition of given DTS node label exists.

#define	FIXED_PARTITION_ID(label) DT_FIXED_PARTITION_ID(DT_NODELABEL(label))
	Get flash area ID from fixed-partition DTS node label.

#define	FIXED_PARTITION_OFFSET(label) DT_REG_ADDR(DT_NODELABEL(label))
	Get fixed-partition offset from DTS node label.

#define	FIXED_PARTITION_NODE_OFFSET(node) DT_REG_ADDR(node)
	Get fixed-partition offset from DTS node.

#define	FIXED_PARTITION_SIZE(label) DT_REG_SIZE(DT_NODELABEL(label))
	Get fixed-partition size for DTS node label.

#define	FIXED_PARTITION_NODE_SIZE(node) DT_REG_SIZE(node)
	Get fixed-partition size for DTS node.

#define	FLASH_AREA_DEVICE(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.

#define	FIXED_PARTITION_DEVICE(label) DEVICE_DT_GET(DT_MTD_FROM_FIXED_PARTITION(DT_NODELABEL(label)))
	Get device pointer for device the area/partition resides on.

#define	FIXED_PARTITION_NODE_DEVICE(node) DEVICE_DT_GET(DT_MTD_FROM_FIXED_PARTITION(node))
	Get device pointer for device the area/partition resides on.

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.

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.

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.

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_DEVICE

#define FIXED_PARTITION_DEVICE ( label ) DEVICE_DT_GET(DT_MTD_FROM_FIXED_PARTITION(DT_NODELABEL(label)))

#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 <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 <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_NODE_DEVICE

#define FIXED_PARTITION_NODE_DEVICE ( node ) DEVICE_DT_GET(DT_MTD_FROM_FIXED_PARTITION(node))

#include <zephyr/storage/flash_map.h>

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 ) DT_REG_ADDR(node)

#include <zephyr/storage/flash_map.h>

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 ) DT_REG_SIZE(node)

#include <zephyr/storage/flash_map.h>

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 ) DT_REG_ADDR(DT_NODELABEL(label))

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

◆ SOC_FLASH_0_ID

#define SOC_FLASH_0_ID 0

#include <zephyr/storage/flash_map.h>

Provided for compatibility with MCUboot.

◆ SPI_FLASH_0_ID

#define SPI_FLASH_0_ID 1

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

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ FIXED_PARTITION_DEVICE

◆ FIXED_PARTITION_EXISTS

◆ FIXED_PARTITION_ID

◆ FIXED_PARTITION_NODE_DEVICE

◆ FIXED_PARTITION_NODE_OFFSET

◆ FIXED_PARTITION_NODE_SIZE

◆ FIXED_PARTITION_OFFSET

◆ FIXED_PARTITION_SIZE

◆ FLASH_AREA_DEVICE

◆ SOC_FLASH_0_ID

◆ SPI_FLASH_0_ID

Typedef Documentation

◆ flash_area_cb_t

Function Documentation

◆ flash_area_align()

◆ flash_area_close()

◆ flash_area_erase()

◆ flash_area_erased_val()

◆ flash_area_foreach()

◆ flash_area_get_device()

◆ flash_area_get_sectors()

◆ flash_area_has_driver()

◆ flash_area_open()

◆ flash_area_read()

◆ flash_area_write()