Flash¶

The internal flash memory can be erased and written to via the flash API.

The API is asynchronous, the actual writing happens in the background. The calls can fail directly or during the flash write. The data buffer need to be available while mira_flash_is_working() returns MIRA_TRUE.

Writing to the flash is done from a process in a manner like this:

do {
    mira_status_t retval = mira_flash_erase_page(offset);
    if (retval == MIRA_ERROR_RESOURCE_NOT_AVAILABLE) {
        // This is a temporarely failure, retry later:
        PROCESS_YIELD();
        continue;
    }
    if (retval != MIRA_SUCCESS) {
        printf("Failed to erase (retval=%d)!\n", retval);
        break; // leave the loop, this will never succeed.
    }
    // Wait for the operation to complete:
    PROCESS_WAIT_WHILE(mira_flash_is_working() == MIRA_TRUE);

    // Retry if the operation failed:
} while (mira_flash_succeeded() == MIRA_FALSE);

Functions¶

mira_flash_write¶

mira_status_t mira_flash_write(uint32_t offset, const void *data, uint32_t len);

Write data to the internal flash memory.

The write happens asynchroniously. The data buffer need to be valid until mira_flash_is_working() returns MIRA_FALSE.

To check that the write succeeded, call mira_flash_succeeded().

Note

This is only implemented for NRF52 MCUs.

Parameters¶

Name	Description
offset	the offset from the start in the flash memory. Needs to be aligned to four bytes.
data	what to write. Needs to be aligned to four bytes.
len	how much to write.

Return value¶

Name	Description
MIRA_SUCCESS	when the write has been scheduled.
MIRA_ERROR_NO_MEMORY	the internal work queue is full, try again later.
MIRA_ERROR_INVALID_VALUE	offset or len out of bounds.
MIRA_ERROR_NOT_IMPLEMENTED	not implemented for the MCU.
MIRA_ERROR_RESOURCE_NOT_AVAILABLE	the previous operation hasn't completed.

mira_flash_erase_page¶

mira_status_t mira_flash_erase_page(uint32_t offset);

Clear an internal flash memory page.

The erase happens asynchroniously. The caller should wait for mira_flash_is_working() to return MIRA_FALSE.

To check that the erase succeeded, call mira_flash_succeeded().

Note

This is only implemented for NRF52 MCUs.

Parameters¶

Name	Description
offset	the offset from the start in the flash memory to the page to erase.

Return value¶

Name	Description
MIRA_SUCCESS	the write has been scheduled.
MIRA_ERROR_NO_MEMORY	the internal work queue is full, try again later.
MIRA_ERROR_INVALID_VALUE	offset out of bounds.
MIRA_ERROR_NOT_IMPLEMENTED	not implemented for the MCU.
MIRA_ERROR_RESOURCE_NOT_AVAILABLE	the previous operation hasn't completed.

mira_flash_is_working¶

mira_bool_t mira_flash_is_working(void);

If a flash operation is currently working.

Return value¶

Name	Description
MIRA_FALSE	No flash operation is currently executing.
MIRA_TRUE	There is a flash operation which is currently executing.

mira_flash_succeeded¶

mira_bool_t mira_flash_succeeded(void);

Did the latest flash operation complete correctly?

Return value¶

Name	Description
MIRA_FALSE	The flash operation failed, retry it.
MIRA_TRUE	The flash operation succeeded.

mira_flash_get_page_size¶

uint32_t mira_flash_get_page_size(void);

Get the size of the flash memory's pages.