Flash map (flash_map)

Flash map is a way for storing flash partitioning information in one central location in flash_area structures array form.

Flash map is generated from DTS based on content of Legacy flash partitions nodes. The flash_area API provides a way to access data in the flash map. The flash_area_open() API is the interface for obtaining the flash partitions flash_area from the flash map.

Flash Area API (flash_area)

The flash_area concept combines methods for operating on a flash chunk together with a description of this chunk. Its methods are basically wrappers around the flash API, with input parameter range checks. Not all flash operation are wrapped so an API call to retrieve the flash area driver is included as well. The flash area methods are designed to be used along with the flash_area structures of flash_map and user-specific flash_areas, with the exception of the area_open API used to fetch a flash_area from the flash_map.

API Reference

flash_area API

group flash_area_api

Abstraction over flash area and its driver which helps to operate on flash regions easily and effectively.

Defines

SOC_FLASH_0_ID

Provides abstraction of flash regions for type of use, for example, where’s my image?

System will contain a map which contains flash areas. Every region will contain flash identifier, offset within flash, and length.

  1. This system map could be in a file within filesystem (Initializer must know/figure out where the filesystem is at).

  2. Map could be at fixed location for project (compiled to code)

  3. Map could be at specific place in flash (put in place at mfg time).

Note that the map you use must be valid for BSP it’s for, match the linker scripts when platform executes from flash, and match the target offset specified in download script.

SPI_FLASH_0_ID
FLASH_AREA_LABEL_EXISTS(label)
FLASH_AREA_ID(label)
FLASH_AREA_OFFSET(label)
FLASH_AREA_SIZE(label)

Typedefs

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

Flash map iteration callback

Parameters

  • fa: flash area

  • user_data: User supplied data

Functions

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

Retrieve partitions flash area from the flash_map.

Function Retrieves flash_area from flash_map for given partition.

Return

0 on success, -EACCES if the flash_map is not available , -ENOENT if ID is unknown.

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.

void flash_area_close(const struct flash_area *fa)

Close flash_area.

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

Parameters

  • [in] fa: Flash area to be closed.

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

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.

Return

0 on success, negative errno code on fail.

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

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

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.

Return

0 on success, negative errno code on fail.

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

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

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.

Return

0 on success, negative errno code on fail.

Parameters

  • [in] fa: Flash area

  • [in] off: Offset relative from beginning of flash area.

  • [in] len: Number of bytes to be erase

uint8_t flash_area_align(const struct flash_area *fa)

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.

Return

Alignment restriction for flash writes in [B].

Parameters

  • [in] fa: Flash area

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

Retrieve info about sectors within the area.

Return

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.

Parameters

  • [in] fa_id: Given flash area ID

  • [out] sectors: buffer for sectors data

  • [inout] count: On input Capacity of sectors, on output number of sectors Retrieved.

void flash_area_foreach(flash_area_cb_t user_cb, void *user_data)

Iterate over flash map

Parameters

  • user_cb: User callback

  • user_data: User supplied data

int flash_area_has_driver(const struct flash_area *fa)

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

Return

1 On success. -ENODEV if no driver match.

Parameters

  • [in] fa: Flash area.

const struct device *flash_area_get_device(const struct flash_area *fa)

Get driver for given flash area.

Return

device driver.

Parameters

  • fa: Flash area.

struct flash_area
#include <flash_map.h>

Structure for store flash partition data.

It is used as the flash_map array entry or stand-alone user data. Structure contains all data needed to operate on the flash partitions.

struct flash_sector
#include <flash_map.h>

Structure for transfer flash sector boundaries.

This template is used for presentation of flash memory structure. It consumes much less RAM than flash_area