Flash

The hardware independent interface to flash memory that is used by applications.

Description

The API offers basic initialization, read, write, erase, sector erase, and other operations.

API

int hal_flash_ioctl(uint8_t flash_id, uint32_t cmd, void *args)
int hal_flash_read(uint8_t flash_id, uint32_t address, void *dst, uint32_t num_bytes)

Reads a block of data from flash.

Return

0 on success; SYS_EINVAL on bad argument error; SYS_EIO on flash driver error.

Parameters
  • flash_id: The ID of the flash device to read from.

  • address: The address to read from.

  • dst: A buffer to fill with data read from flash.

  • num_bytes: The number of bytes to read.

int hal_flash_write(uint8_t flash_id, uint32_t address, const void *src, uint32_t num_bytes)

Writes a block of data to flash.

Return

0 on success; SYS_EINVAL on bad argument error; SYS_EACCES if flash region is write protected; SYS_EIO on flash driver error.

Parameters
  • flash_id: The ID of the flash device to write to.

  • address: The address to write to.

  • src: A buffer containing the data to be written.

  • num_bytes: The number of bytes to write.

int hal_flash_erase_sector(uint8_t flash_id, uint32_t sector_address)

Erases a single flash sector.

Return

0 on success; SYS_EINVAL on bad argument error; SYS_EACCES if flash region is write protected; SYS_EIO on flash driver error.

Parameters
  • flash_id: The ID of the flash device to erase.

  • sector_address: An address within the sector to erase.

int hal_flash_erase(uint8_t flash_id, uint32_t address, uint32_t num_bytes)

Erases a contiguous sequence of flash sectors.

If the specified range does not correspond to a whole number of sectors, any partially-specified sectors are fully erased. For example, if a device has 1024-byte sectors, then these arguments: o address: 300 o num_bytes: 1000 cause the first two sectors to be erased in their entirety.

Return

0 on success; SYS_EINVAL on bad argument error; SYS_EACCES if flash region is write protected; SYS_EIO on flash driver error.

Parameters
  • flash_id: The ID of the flash device to erase.

  • address: An address within the sector to begin the erase at.

  • num_bytes: The length, in bytes, of the region to erase.

int hal_flash_isempty(uint8_t flash_id, uint32_t address, void *dst, uint32_t num_bytes)

Determines if the specified region of flash is completely unwritten.

Return

0 if any written bytes were detected; 1 if the region is completely unwritten; SYS_EINVAL on bad argument error; SYS_EIO on flash driver error.

Parameters
  • id: The ID of the flash hardware to inspect.

  • address: The starting address of the check.

  • dst: A buffer to hold the contents of the flash region. This must be at least num_bytes large.

  • num_bytes: The number of bytes to check.

int hal_flash_isempty_no_buf(uint8_t id, uint32_t address, uint32_t num_bytes)

Determines if the specified region of flash is completely unwritten.

This function is like hal_flash_isempty(), except the caller does not need to provide a buffer. Instead, a buffer of size MYNEWT_VAL(HAL_FLASH_VERIFY_BUF_SZ) is allocated on the stack.

Return

0 if any written bytes were detected; 1 if the region is completely unwritten; SYS_EINVAL on bad argument error; SYS_EIO on flash driver error.

Parameters
  • id: The ID of the flash hardware to inspect.

  • address: The starting address of the check.

  • num_bytes: The number of bytes of flash to check.

uint8_t hal_flash_align(uint8_t flash_id)

Determines the minimum write alignment of a flash device.

Return

The flash device’s minimum write alignment.

Parameters
  • id: The ID of the flash hardware to check.

uint8_t hal_flash_erased_val(uint8_t flash_id)

Determines the value of an erased byte for a particular flash device.

Return

The value of an erased byte.

Parameters
  • id: The ID of the flash hardware to check.

int hal_flash_init(void)

Initializes all flash devices in the system.

Return

0 on success; SYS_EIO on flash driver error.

int hal_flash_write_protect(uint8_t id, uint8_t protect)

Set or clears write protection.

This function allows to disable write to the device if for some reason (i.e. low power state) writes could result in data corruption.

Return

SYS_EINVAL - if flash id is not valid SYS_OK - on success

Parameters
  • id: The ID of the flash

  • protect: 1 - disable writes 0 - enable writes