Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

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 deviceflash_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
labelDTS 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
labelDTS 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
labelDTS 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
nodeDTS 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
nodeDTS 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
nodeDTS 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
labelDTS 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
labelDTS 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
labelDTS 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
faflash area
user_dataUser 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]faFlash 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]faFlash 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]faFlash area
[in]offOffset relative from beginning of flash area.
[in]lenNumber 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
faFlash 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_cbUser callback
user_dataUser 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]faFlash 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_idGiven flash area ID
[out]sectorsbuffer for sectors data
[in,out]countOn 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]faFlash 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]idID of the flash partition.
[out]faPointer 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]faFlash area
[in]offOffset relative from beginning of flash area to read
[out]dstBuffer to store read data
[in]lenNumber 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]faFlash area
[in]offOffset relative from beginning of flash area to write
[in]srcBuffer with data to be written
[in]lenNumber of bytes to write
Returns
0 on success, negative errno code on fail.