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_sector_info(uint8_t flash_id, int sector_index, uint32_t *start_address, uint32_t *size)

Return information about flash sector.

Parameters:

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

  • sector_index – The sector number to get information about.

  • start_address – A buffer to fill with start address of the sector.

  • size – A buffer for sector size.

Returns:

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

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

Reads a block of data from flash.

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.

Returns:

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

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.

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.

Returns:

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

int hal_flash_erase_sector(uint8_t flash_id, uint32_t sector_address)

Erases a single flash sector.

Parameters:

  • flash_id – The ID of the flash device to erase.

  • sector_address – An address within the sector to erase.

Returns:

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

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.

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.

Returns:

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

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.

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.

Returns:

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.

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.

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.

Returns:

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.

uint8_t hal_flash_align(uint8_t flash_id)

Determines the minimum write alignment of a flash device.

Parameters:

  • id – The ID of the flash hardware to check.

Returns:

The flash device’s minimum write alignment.

uint8_t hal_flash_erased_val(uint8_t flash_id)

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

Parameters:

  • id – The ID of the flash hardware to check.

Returns:

The value of an erased byte.

int hal_flash_init(void)

Initializes all flash devices in the system.

Returns:

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.

Parameters:

  • id – The ID of the flash

  • protect – 1 - disable writes 0 - enable writes

Returns:

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