Flash map

The <storage/flash_map.h> API allows accessing information about device flash partitions via flash_area structures.

Each struct flash_area describes a flash partition. The API provides access to a “flash map”, which contains predefined flash areas accessible via globally unique ID numbers. You can also create flash_area structures at runtime for application-specific purposes.

The flash_area structure contains the name of the flash device the partition is part of; this name can be passed to device_get_binding() to get the corresponding device structure which can be read and written to using the flash API. The flash_area also contains the start offset and size of the partition within the flash memory the device represents.

The flash_map.h API provides functions for operating on a flash_area. The main examples are flash_area_read() and flash_area_write(). These functions are basically wrappers around the flash API with input parameter range checks. Not all flash APIs have flash_map.h wrappers, but flash_area_get_device() allows easily retrieving the struct device from a struct flash_area.

Use flash_area_open() to access a struct flash_area. This function takes a flash area ID number and returns a pointer to the flash area structure. The ID number for a flash area can be obtained from a human-readable “label” using FLASH_AREA_ID; these labels are obtained from the devicetree as described below.

Relationship with Devicetree

The flash_map.h API uses data generated from the Devicetree API, in particular its Fixed flash partitions. Zephyr additionally has some partitioning conventions used for Device Firmware Upgrade via the MCUboot bootloader, as well as defining partitions usable by file systems or other nonvolatile storage.

Here is an example devicetree fragment which uses fixed flash partitions for both MCUboot and a storage partition. Some details were left out for clarity.

/ {
	soc {
		flashctrl: flash-controller@deadbeef {
			flash0: flash@0 {
				compatible = "soc-nv-flash";
				reg = <0x0 0x100000>;

				partitions {
					compatible = "fixed-partitions";
					#address-cells = <0x1>;
					#size-cells = <0x1>;

					boot_partition: partition@0 {
						label = "mcuboot";
						reg = <0x0 0x10000>;
						read-only;
					};
					storage_partition: partition@1e000 {
						label = "storage";
						reg = <0x1e000 0x2000>;
					};
					slot0_partition: partition@20000 {
						label = "image-0";
						reg = <0x20000 0x60000>;
					};
					slot1_partition: partition@80000 {
						label = "image-1";
						reg = <0x80000 0x60000>;
					};
					scratch_partition: partition@e0000 {
						label = "image-scratch";
						reg = <0xe0000 0x20000>;
					};
				};
			};
		};
	};
};

Rule for offsets is that each partition offset shall be expressed in relation to the flash memory beginning address to which the partition belong.

The boot_partition, slot0_partition, slot1_partition, and scratch_partition nodes are defined for MCUboot, though not all MCUboot configurations require all of them to be defined. See the MCUboot documentation for more details.

The storage_partition node is defined for use by a file system or other nonvolatile storage API.

To get a numeric flash area ID from one of the child nodes of the partitions node:

  1. take the node’s label property value

  2. lowercase it

  3. convert all special characters to underscores (_)

  4. pass the result without quotes to FLASH_AREA_ID()

For example, the flash_area ID number for slot0_partition is FLASH_AREA_ID(image_0).

The same rules apply for other macros which take a “label”, such as FLASH_AREA_OFFSET and FLASH_AREA_SIZE. For example, FLASH_AREA_OFFSET(image_0) would return the start offset for slot0_partition within its flash device. This is determined by the node’s reg property, and in this case is 0x20000.

To get a pointer to the flash area structure and do something with it starting with a devicetree label like "image-0", use something like this:

struct flash_area *my_area;
int err = flash_area_open(FLASH_AREA_ID(image_0), &my_area);

if (err != 0) {
     handle_the_error(err);
} else {
     flash_area_read(my_area, ...);
}

API Reference

group flash_area_api

Abstraction over flash partitions/areas and their drivers.

Defines

SOC_FLASH_0_ID

Provided for compatibility with MCUboot

SPI_FLASH_0_ID

Provided for compatibility with MCUboot

FLASH_AREA_LABEL_EXISTS(label)
FLASH_AREA_LABEL_STR(lbl)
FLASH_AREA_ID(label)
FLASH_AREA_OFFSET(label)
FLASH_AREA_SIZE(label)
FLASH_AREA_DEVICE(label)

Get device pointer for device the area/partition resides on

Parameters

  • label – partition label

Returns

const struct device type pointer

Typedefs

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

Flash map iteration callback

Param fa

flash area

Param 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.

Parameters

  • id – [in] ID of the flash partition.

  • fa – [out] 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.

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

  • fa – [in] 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.

Parameters

  • fa – [in] Flash area

  • off – [in] Offset relative from beginning of flash area to read

  • dst – [out] Buffer to store read data

  • len – [in] Number of bytes to read

Returns

0 on success, negative errno code on fail.

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.

Parameters

  • fa – [in] Flash area

  • off – [in] Offset relative from beginning of flash area to read

  • src – [out] Buffer with data to be written

  • len – [in] Number of bytes to write

Returns

0 on success, negative errno code on fail.

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.

Parameters

  • fa – [in] Flash area

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

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

Returns

0 on success, negative errno code on fail.

uint32_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.

Parameters

  • fa – [in] Flash area

Returns

Alignment restriction for flash writes in [B].

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

Retrieve info about sectors within the area.

Parameters

  • fa_id – [in] Given flash area ID

  • sectors – [out] buffer for sectors data

  • count – [inout] 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.

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.

Parameters

  • fa – [in] Flash area.

Returns

1 On success. -ENODEV if no driver match.

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

Get driver for given flash area.

Parameters

  • fa – Flash area.

Returns

device driver.

uint8_t flash_area_erased_val(const struct flash_area *fa)

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.

struct flash_area
#include <flash_map.h>

Flash partition.

This structure represents a fixed-size partition on a flash device. Each partition contains one or more flash sectors.

Public Members

uint8_t fa_id

ID number

uint8_t fa_device_id

Provided for compatibility with MCUboot

off_t fa_off

Start offset from the beginning of the flash device

size_t fa_size

Total size

const char *fa_dev_name

Name of the flash device, suitable for passing to device_get_binding().

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

Public Members

off_t fs_off

Sector offset from the beginning of the flash device

size_t fs_size

Sector size in bytes