Flash

Overview

Flash offset concept

Offsets used by the user API are expressed in relation to the flash memory beginning address. This rule shall be applied to all flash controller regular memory that layout is accessible via API for retrieving the layout of pages (see CONFIG_FLASH_PAGE_LAYOUT).

An exception from the rule may be applied to a vendor-specific flash dedicated-purpose region (such a region obviously can’t be covered under API for retrieving the layout of pages).

User API Reference

group flash_interface

FLASH Interface.

Since

1.2

Version

1.0.0

Defines

FLASH_ERASE_C_EXPLICIT

Set for ordinary Flash where erase is needed before write of random data.

FLASH_ERASE_CAPS_UNSET

Reserved for users as initializer for variables that will later store capabilities.

FLASH_ERASE_C_SUPPORTED
FLASH_ERASE_C_VAL_BIT
FLASH_ERASE_UNIFORM_PAGE
FLASH_EX_OP_VENDOR_BASE
FLASH_EX_OP_IS_VENDOR(c)

Typedefs

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.

Param info:

Information for current page

Param data:

Private data for callback

Return:

True to continue iteration, false to halt iteration.

Enums

enum flash_ex_op_types

Enumeration for extra flash operations.

Values:

enumerator FLASH_EX_OP_RESET = 0

Functions

static inline int flash_params_get_erase_cap(const struct flash_parameters *p)
int flash_read(const struct device *dev, off_t offset, void *data, size_t len)

Read data from flash.

All flash drivers support reads without alignment restrictions on the read offset, the read size, or the destination address.

Parameters:
  • dev – : flash dev

  • offset – : Offset (byte aligned) to read

  • data – : Buffer to store read data

  • len – : Number of bytes to read.

Returns:

0 on success, negative errno code on fail.

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

Write buffer into flash memory.

All flash drivers support a source buffer located either in RAM or SoC flash, without alignment restrictions on the source address. Write size and offset must be multiples of the minimum write block size supported by the driver.

Any necessary write protection management is performed by the driver write implementation itself.

Parameters:
  • dev – : flash device

  • offset – : starting offset for the write

  • data – : data to write

  • len – : Number of bytes to write

Returns:

0 on success, negative errno code on fail.

int flash_erase(const 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.

Any necessary erase protection management is performed by the driver erase implementation itself.

The function should be used only for devices that are really explicit erase devices; in case when code relies on erasing device, i.e. setting it to erase-value, prior to some operations, but should work with explicit erase and RAM non-volatile devices, then flash_flatten should rather be used.

See also

flash_flatten()

Parameters:
  • dev – : flash device

  • offset – : erase area starting offset

  • size – : size of area to be erased

Returns:

0 on success, negative errno code on fail.

int flash_fill(const struct device *dev, uint8_t val, off_t offset, size_t size)

Fill selected range of device with specified value.

Utility function that allows to fill specified range on a device with provided value. The offset and size of range need to be aligned to a write block size of a device.

Parameters:
  • dev – : flash device

  • val – : value to use for filling the range

  • offset – : offset of the range to fill

  • size – : size of the range

Returns:

0 on success, negative errno code on fail.

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

Erase part or all of a flash memory or level it.

If device is explicit erase type device or device driver provides erase callback, the callback of the device is called, in which it behaves the same way as flash_erase. If a device does not require explicit erase, either because it has no erase at all or has auto-erase/erase-on-write, and does not provide erase callback then erase is emulated by leveling selected device memory area with erase_value assigned to device.

Erase page offset and size are constrains of paged, explicit erase devices, but can be relaxed with devices without such requirement, which means that it is up to user code to make sure they are correct as the function will return on, if these constrains are not met, -EINVAL for paged device, but may succeed on non-explicit erase devices. For RAM non-volatile devices the erase pages are emulated, at this point, to allow smooth transition for code relying on device being paged to function properly; but this is completely software constrain.

Generally: if your code previously required device to be erase prior to some actions to work, replace flash_erase calls with this function; but if your code can work with non-volatile RAM type devices, without emulating erase, you should rather have different path of execution for page-erase, i.e. Flash, devices and call flash_erase for them.

See also

flash_erase()

Parameters:
  • dev – : flash device

  • offset – : erase area starting offset

  • size – : size of area to be erased

Returns:

0 on success, negative errno code on fail.

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

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

Parameters:
  • dev – flash device

  • offset – Offset within the page

  • info – Page Info structure to be filled

Returns:

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

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

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

Parameters:
  • dev – flash device

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

  • info – Page Info structure to be filled

Returns:

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

size_t flash_get_page_count(const struct device *dev)

Get the total number of flash pages.

Parameters:
  • dev – flash device

Returns:

Number of flash pages.

void flash_page_foreach(const 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

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

Read data from Serial Flash Discoverable Parameters.

This routine reads data from a serial flash device compatible with the JEDEC JESD216 standard for encoding flash memory characteristics.

Availability of this API is conditional on selecting CONFIG_FLASH_JESD216_API and support of that functionality in the driver underlying dev.

Parameters:
  • dev – device from which parameters will be read

  • offset – address within the SFDP region containing data of interest

  • data – where the data to be read will be placed

  • len – the number of bytes of data to be read

Return values:
  • 0 – on success

  • -ENOTSUP – if the flash driver does not support SFDP access

  • negative – values for other errors.

int flash_read_jedec_id(const struct device *dev, uint8_t *id)

Read the JEDEC ID from a compatible flash device.

Parameters:
  • dev – device from which id will be read

  • id – pointer to a buffer of at least 3 bytes into which id will be stored

Return values:
  • 0 – on successful store of 3-byte JEDEC id

  • -ENOTSUP – if flash driver doesn’t support this function

  • negative – values for other errors

size_t flash_get_write_block_size(const 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.

Parameters:
  • dev – flash device

Returns:

write block size in bytes.

const struct flash_parameters *flash_get_parameters(const struct device *dev)

Get pointer to flash_parameters structure.

Returned pointer points to a structure that should be considered constant through a runtime, regardless if it is defined in RAM or Flash. Developer is free to cache the structure pointer or copy its contents.

Returns:

pointer to flash_parameters structure characteristic for the device.

int flash_ex_op(const struct device *dev, uint16_t code, const uintptr_t in, void *out)

Execute flash extended operation on given device.

Besides of standard flash operations like write or erase, flash controllers also support additional features like write protection or readout protection. These features are not available in every flash controller, what’s more controllers can implement it in a different way.

It doesn’t make sense to add a separate flash API function for every flash controller feature, because it could be unique (supported on small number of flash controllers) or the API won’t be able to represent the same feature on every flash controller.

Parameters:
  • dev – Flash device

  • code – Operation which will be executed on the device.

  • in – Pointer to input data used by operation. If operation doesn’t need any input data it could be NULL.

  • out – Pointer to operation output data. If operation doesn’t produce any output it could be NULL.

Return values:
  • 0 – on success.

  • -ENOTSUP – if given device doesn’t support extended operation.

  • -ENOSYS – if support for extended operations is not enabled in Kconfig

  • negative – value on extended operation errors.

struct flash_parameters
#include <flash.h>

Flash memory parameters.

Contents of this structure suppose to be filled in during flash device initialization and stay constant through a runtime.

Public Members

const size_t write_block_size

Minimal write alignment and size.

uint8_t erase_value

Value the device is filled in erased areas.

struct flash_pages_info
#include <flash.h>

Implementation interface API Reference

group flash_internal_interface

FLASH internal Interface.

Typedefs

typedef int (*flash_api_read)(const struct device *dev, off_t offset, void *data, size_t len)
typedef int (*flash_api_write)(const struct device *dev, off_t offset, const void *data, size_t len)

Flash write implementation handler type.

Note

Any necessary write protection management must be performed by the driver, with the driver responsible for ensuring the “write-protect” after the operation completes (successfully or not) matches the write-protect state when the operation was started.

typedef int (*flash_api_erase)(const struct device *dev, off_t offset, size_t size)

Flash erase implementation handler type.

The callback is optional for RAM non-volatile devices, which do not require erase by design, but may be provided if it allows device to work more effectively, or if device has a support for internal fill operation the erase in driver uses.

Note

Any necessary erase protection management must be performed by the driver, with the driver responsible for ensuring the “erase-protect” after the operation completes (successfully or not) matches the erase-protect state when the operation was started.

typedef const struct flash_parameters *(*flash_api_get_parameters)(const struct device *dev)
typedef void (*flash_api_pages_layout)(const 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.

Param dev:

Flash device whose layout to retrieve.

Param layout:

The flash layout will be returned in this argument.

Param layout_size:

The number of elements in the returned layout.

typedef int (*flash_api_sfdp_read)(const struct device *dev, off_t offset, void *data, size_t len)
typedef int (*flash_api_read_jedec_id)(const struct device *dev, uint8_t *id)
typedef int (*flash_api_ex_op)(const struct device *dev, uint16_t code, const uintptr_t in, void *out)
struct flash_pages_layout
#include <flash.h>
struct flash_driver_api
#include <flash.h>