Loading...
Searching...
No Matches

Low-level flash page interface. More...

Detailed Description

Low-level flash page interface.

This interface provides a very simple and straight forward way for writing a MCU's internal flash. This interface is only capable of reading, verifying, and writing complete flash pages, it has no support for partial flash access. This enables for very slim and efficient implementations.

A module for more fine-grained access of memory locations can easily be programmed on top of this interface.

Note
Flash memory has only a limited amount of erase cycles (mostly around 10K times), so using this interface in some kind of loops can damage you MCU!

(Low-) Power Implications

The flashpage driver implementation should make sure, that the CPU uses no additional energy while the flashpage driver is inactive. This means, that any particular CPU peripherals used for reading and writing flash pages should be disabled before the read and write functions return.

If an implementation puts the calling thread to sleep for a duration of time, the implementation might need to take care of blocking certain power modes.

Files

file  flashpage.h
 Low-level flash page peripheral driver interface.
 

Macros

#define CPU_FLASH_BASE   (0)
 Per default, we expect the internal flash to start at address 0.
 
#define FLASHPAGE_WRITE_BLOCK_SIZE
 For raw writings to the flash, this constant must define the minimum write length allowed by the MCU.
 
#define FLASHPAGE_WRITE_BLOCK_ALIGNMENT
 The buffers to be written to the flash MUST be aligned, as well as the address on which the buffer is written to the flash.
 
#define FLASHPAGE_ERASE_STATE   (0xFFU)
 State of an erased byte in memory.
 
#define PERIPH_FLASHPAGE_CUSTOM_PAGESIZES
 Defined to signal that the peripheral has non-uniform flash page sizes.
 
#define PERIPH_FLASHPAGE_NEEDS_FLASHPAGE_ADDR
 If non-uniform flash page sizes are required, defined to signal that the peripheral does not implement a custom flashpage_addr function and instead relies on the generic helper function that relies on flashpage_size.
 
#define PERIPH_FLASHPAGE_NEEDS_FLASHPAGE_PAGE
 If non-uniform flash page sizes are required, defined to signal that the peripheral does not implement a custom flashpage_page function and instead relies on the generic helper function that relies on flashpage_size.
 
#define FLASH_WRITABLE_INIT(name, size)
 Define an array in flash memory.
 

Enumerations

enum  { FLASHPAGE_OK = 0 , FLASHPAGE_NOMATCH = -1 }
 Return values used in this interface. More...
 

Functions

static size_t flashpage_size (unsigned page)
 Get the page size of the given page number.
 
static void * flashpage_addr (unsigned page)
 Translate the given page number into the page's starting address.
 
static unsigned flashpage_page (const void *addr)
 Translate the given address into the corresponding page number.
 
void flashpage_erase (unsigned page)
 Erase the given page.
 
unsigned flashpage_first_free (void)
 Get number of first free flashpage.
 
unsigned flashpage_last_free (void)
 Get number of last free flashpage.
 
void flashpage_write_page (unsigned page, const void *data)
 Write the given page with the given data.
 
void flashpage_write (void *target_addr, const void *data, size_t len)
 Write any number of data bytes to a given location in the flash memory.
 
void flashpage_read (unsigned page, void *data)
 Read the given page into the given memory location.
 
int flashpage_verify (unsigned page, const void *data)
 Verify the given page against the given data.
 
int flashpage_write_and_verify (unsigned page, const void *data)
 Write the given page and verify the results.
 

Macro Definition Documentation

◆ CPU_FLASH_BASE

#define CPU_FLASH_BASE   (0)

Per default, we expect the internal flash to start at address 0.

Definition at line 65 of file flashpage.h.

◆ FLASH_WRITABLE_INIT

#define FLASH_WRITABLE_INIT (   name,
  size 
)
Value:
__attribute__((aligned(FLASHPAGE_SIZE))) \
__attribute__((section(".flash_writable." #name))) \
static const uint8_t name [size * FLASHPAGE_SIZE]
#define FLASHPAGE_SIZE
Flash page configuration.
Definition cpu_conf.h:50

Define an array in flash memory.

This macro defines an array stored in the ".flash_writable" section which is part of flash memory. With this macro it is possible to reserve flash memory at build time.

E.g. FLASH_WRITABLE_INIT(a, 2); will create a array with name 'a' of size 2 * FLASHPAGE_SIZE which is stored in flash memory and takes up 2 flash pages.

Symbols created by using this macro are sorted in ascending order by name. Therefore, &a < &b where a and b are arrays created using this macro.

Parameters
[in]namename of the array
[in]sizesize of the array in unit of FLASHPAGE_SIZE

Definition at line 173 of file flashpage.h.

◆ FLASHPAGE_ERASE_STATE

#define FLASHPAGE_ERASE_STATE   (0xFFU)

State of an erased byte in memory.

Definition at line 95 of file flashpage.h.

◆ FLASHPAGE_WRITE_BLOCK_ALIGNMENT

#define FLASHPAGE_WRITE_BLOCK_ALIGNMENT

The buffers to be written to the flash MUST be aligned, as well as the address on which the buffer is written to the flash.

This variable must be defined for that purpose, according to the MCU align requirements.

Definition at line 86 of file flashpage.h.

◆ FLASHPAGE_WRITE_BLOCK_SIZE

#define FLASHPAGE_WRITE_BLOCK_SIZE

For raw writings to the flash, this constant must define the minimum write length allowed by the MCU.

Definition at line 74 of file flashpage.h.

◆ PERIPH_FLASHPAGE_CUSTOM_PAGESIZES

#define PERIPH_FLASHPAGE_CUSTOM_PAGESIZES

Defined to signal that the peripheral has non-uniform flash page sizes.

These devices do not define FLASHPAGE_SIZE and do not implement the pagewise api.

Definition at line 106 of file flashpage.h.

◆ PERIPH_FLASHPAGE_NEEDS_FLASHPAGE_ADDR

#define PERIPH_FLASHPAGE_NEEDS_FLASHPAGE_ADDR

If non-uniform flash page sizes are required, defined to signal that the peripheral does not implement a custom flashpage_addr function and instead relies on the generic helper function that relies on flashpage_size.

Definition at line 118 of file flashpage.h.

◆ PERIPH_FLASHPAGE_NEEDS_FLASHPAGE_PAGE

#define PERIPH_FLASHPAGE_NEEDS_FLASHPAGE_PAGE

If non-uniform flash page sizes are required, defined to signal that the peripheral does not implement a custom flashpage_page function and instead relies on the generic helper function that relies on flashpage_size.

Definition at line 130 of file flashpage.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Return values used in this interface.

Enumerator
FLASHPAGE_OK 

everything succeeded

FLASHPAGE_NOMATCH 

page differs from target data

Definition at line 136 of file flashpage.h.

Function Documentation

◆ flashpage_addr()

static void * flashpage_addr ( unsigned  page)
inlinestatic

Translate the given page number into the page's starting address.

Note
The given page MUST be valid, otherwise the returned address points to an undefined memory location!
Parameters
[in]pagepage number to get the address of
Returns
starting memory address of the given page

Definition at line 202 of file flashpage.h.

◆ flashpage_erase()

void flashpage_erase ( unsigned  page)

Erase the given page.

Parameters
[in]pagePage to erase

◆ flashpage_first_free()

unsigned flashpage_first_free ( void  )

Get number of first free flashpage.

Deprecated:
Use FLASH_WRITABLE_INIT instead, which is usable in modules as well as applications. The function will be removed after the 2022.04 release.

If riotboot is used in two slot mode, this number will change across firmware updates as the firmware slots alternate.

◆ flashpage_last_free()

unsigned flashpage_last_free ( void  )

Get number of last free flashpage.

Deprecated:
Use FLASH_WRITABLE_INIT instead, which is usable in modules as well as applications. The function will be removed after the 2022.04 release.

If riotboot is used in two slot mode, this number will change across firmware updates as the firmware slots alternate.

◆ flashpage_page()

static unsigned flashpage_page ( const void *  addr)
inlinestatic

Translate the given address into the corresponding page number.

The given address can be any address inside a page.

Note
The given address MUST be a valid flash address!
Parameters
[in]addraddress inside the targeted page
Returns
page containing the given address

Definition at line 218 of file flashpage.h.

◆ flashpage_read()

void flashpage_read ( unsigned  page,
void *  data 
)

Read the given page into the given memory location.

Parameters
[in]pagepage to read
[out]datamemory to write the page to, MUST be FLASHPAGE_SIZE byte

◆ flashpage_size()

static size_t flashpage_size ( unsigned  page)
inlinestatic

Get the page size of the given page number.

Parameters
[in]pagepage number to get the size for
Returns
Page size of the given page

Definition at line 186 of file flashpage.h.

◆ flashpage_verify()

int flashpage_verify ( unsigned  page,
const void *  data 
)

Verify the given page against the given data.

Parameters
[in]pagepage to verify
[in]datadata to compare page against, MUST be FLASHPAGE_SIZE byte of data
Returns
FLASHPAGE_OK if data in the page is identical to data
FLASHPAGE_NOMATCH if data and page content diverge

◆ flashpage_write()

void flashpage_write ( void *  target_addr,
const void *  data,
size_t  len 
)

Write any number of data bytes to a given location in the flash memory.

Warning
Make sure the targeted memory area is erased before calling this function

Both target address and data address must be aligned to FLASHPAGE_BLOCK_ALIGN. len must be a multiple of FLASHPAGE_WRITE_BLOCK_SIZE. This function doesn't erase any area in flash, thus be sure the targeted memory area is erased before writing on it (using the flashpage_write function).

Parameters
[in]target_addraddress in flash to write to. MUST be aligned to FLASHPAGE_WRITE_BLOCK_ALIGNMENT.
[in]datadata to write to the address. MUST be aligned to FLASHPAGE_WRITE_BLOCK_ALIGNMENT.
[in]lenlength of the data to be written. It MUST be multiple of FLASHPAGE_WRITE_BLOCK_SIZE. Also, ensure it doesn't exceed the actual flash memory size.

◆ flashpage_write_and_verify()

int flashpage_write_and_verify ( unsigned  page,
const void *  data 
)

Write the given page and verify the results.

This is a convenience function wrapping flashpage_write and flashpage_verify.

Parameters
[in]pagepage to write
[in]datadata to write to the page, MUST be FLASHPAGE_SIZE byte.
Returns
FLASHPAGE_OK on success
FLASHPAGE_NOMATCH if data and page content diverge

◆ flashpage_write_page()

void flashpage_write_page ( unsigned  page,
const void *  data 
)

Write the given page with the given data.

Parameters
[in]pagepage to write
[in]datadata to write to the page, MUST be FLASHPAGE_SIZE byte. Set to NULL for page erase only.