This is the documentation for the latest (master) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

Flash

Overview

API Reference

group flash_interface

FLASH Interface.

Typedefs

typedef int (*flash_api_read)(struct device *dev, off_t offset, void *data, size_t len)
typedef int (*flash_api_write)(struct device *dev, off_t offset, const void *data, size_t len)
typedef int (*flash_api_erase)(struct device *dev, off_t offset, size_t size)
typedef int (*flash_api_write_protection)(struct device *dev, bool enable)
typedef void (*flash_api_pages_layout)(struct device *dev, const struct flash_pages_layout **layout, size_t *layout_size)

Retrieve a flash device’s layout.

A flash device layout is a run-length encoded description of the pages on the device. (Here, “page” means the smallest erasable area on the flash device.)

For flash memories which have uniform page sizes, this routine returns an array of length 1, which specifies the page size and number of pages in the memory.

Layouts for flash memories with nonuniform page sizes will be returned as an array with multiple elements, each of which describes a group of pages that all have the same size. In this case, the sequence of array elements specifies the order in which these groups occur on the device.

Parameters
  • dev: Flash device whose layout to retrieve.

  • layout: The flash layout will be returned in this argument.

  • layout_size: The number of elements in the returned layout.

typedef bool (*flash_page_cb)(const struct flash_pages_info *info, void *data)

Callback type for iterating over flash pages present on a device.

The callback should return true to continue iterating, and false to halt.

Return

True to continue iteration, false to halt iteration.

See

flash_page_foreach()

Parameters
  • info: Information for current page

  • data: Private data for callback

Functions

int flash_read(struct device *dev, off_t offset, void *data, size_t len)

Read data from flash.

Most of flash drivers support unaligned flash access, but some have restrictions on the read offset or/and the read size. Please refer to the driver implementation to get details on the read alignment requirement.

Return

0 on success, negative errno code on fail.

Parameters
  • dev: : flash dev

  • offset: : Offset (byte aligned) to read

  • data: : Buffer to store read data

  • len: : Number of bytes to read.

int flash_write(struct device *dev, off_t offset, const void *data, size_t len)

Write buffer into flash memory.

Prior to the invocation of this API, the flash_write_protection_set needs to be called first to disable the write protection.

Return

0 on success, negative errno code on fail.

Parameters
  • dev: : flash device

  • offset: : starting offset for the write

  • data: : data to write

  • len: : Number of bytes to write

int flash_erase(struct device *dev, off_t offset, size_t size)

Erase part or all of a flash memory.

Acceptable values of erase size and offset are subject to hardware-specific multiples of page size and offset. Please check the API implemented by the underlying sub driver, for example by using flash_get_page_info_by_offs() if that is supported by your flash driver.

Prior to the invocation of this API, the flash_write_protection_set needs to be called first to disable the write protection.

Return

0 on success, negative errno code on fail.

See

flash_get_page_info_by_offs()

See

flash_get_page_info_by_idx()

Parameters
  • dev: : flash device

  • offset: : erase area starting offset

  • size: : size of area to be erased

int flash_write_protection_set(struct device *dev, bool enable)

Enable or disable write protection for a flash memory.

This API is required to be called before the invocation of write or erase API. Any calls to flash_write() or flash_erase() that do not first disable write protection using this function result in undefined behavior. Usage Example:

flash_write_protection_set(flash_dev, false);
flash_erase(flash_dev, page_offset, page_size);

flash_write_protection_set(flash_dev, false);
flash_write(flash_dev, offset, data, sizeof(data));

flash_write_protection_set(flash_dev, true); // enable is recommended

Please note that on some flash components, the write protection is automatically turned on again by the device after the completion of each call to flash_write or flash_erase(). Therefore, portable programs must disable write protection using this function before each call to flash_erase() or flash_write().

For some flash devices, this function may implement a no-operation, as some flash hardware does not support write protection, or may not support it in a manner that is compatible with this API. For these drivers, this function always returns success.

Return

0 on success, negative errno code on fail.

Parameters
  • dev: : flash device

  • enable: : enable or disable flash write protection

int flash_get_page_info_by_offs(struct device *dev, off_t offset, struct flash_pages_info *info)

Get the size and start offset of flash page at certain flash offset.

Return

0 on success, -EINVAL if page of the offset doesn’t exist.

Parameters
  • dev: flash device

  • offset: Offset within the page

  • info: Page Info structure to be filled

int flash_get_page_info_by_idx(struct device *dev, u32_t page_index, struct flash_pages_info *info)

Get the size and start offset of flash page of certain index.

Return

0 on success, -EINVAL if page of the index doesn’t exist.

Parameters
  • dev: flash device

  • page_index: Index of the page. Index are counted from 0.

  • info: Page Info structure to be filled

size_t flash_get_page_count(struct device *dev)

Get the total number of flash pages.

Return

Number of flash pages.

Parameters
  • dev: flash device

void flash_page_foreach(struct device *dev, flash_page_cb cb, void *data)

Iterate over all flash pages on a device.

This routine iterates over all flash pages on the given device, ordered by increasing start offset. For each page, it invokes the given callback, passing it the page’s information and a private data object.

Parameters
  • dev: Device whose pages to iterate over

  • cb: Callback to invoke for each flash page

  • data: Private data for callback function

size_t flash_get_write_block_size(struct device *dev)

Get the minimum write block size supported by the driver.

The write block size supported by the driver might differ from the write block size of memory used because the driver might implements write-modify algorithm.

Return

write block size in bytes.

Parameters
  • dev: flash device