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!

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_RAW_BLOCKSIZE
 For raw writings to the flash, this constant must define the minimum write length allowed by the MCU.
 
#define FLASHPAGE_RAW_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. More...
 

Enumerations

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

Functions

static void * flashpage_addr (int page)
 Translate the given page number into the page's starting address. More...
 
static int flashpage_page (void *addr)
 Translate the given address into the corresponding page number. More...
 
void flashpage_write (int page, void *data)
 Write the given page with the given data. More...
 
void flashpage_write_raw (void *target_addr, void *data, size_t len)
 Write any number of data bytes to a given location in the flash memory. More...
 
void flashpage_read (int page, void *data)
 Read the given page into the given memory location. More...
 
int flashpage_verify (int page, void *data)
 Verify the given page against the given data. More...
 
int flashpage_write_and_verify (int page, void *data)
 Write the given page and verify the results. More...
 

Macro Definition Documentation

◆ FLASHPAGE_RAW_ALIGNMENT

#define FLASHPAGE_RAW_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 73 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 90 of file flashpage.h.

Function Documentation

◆ flashpage_addr()

static void* flashpage_addr ( int  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 105 of file flashpage.h.

◆ flashpage_page()

static int flashpage_page ( 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 121 of file flashpage.h.

◆ flashpage_read()

void flashpage_read ( int  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_verify()

int flashpage_verify ( int  page,
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 ( int  page,
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.

◆ flashpage_write_and_verify()

int flashpage_write_and_verify ( int  page,
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_raw()

void flashpage_write_raw ( void *  target_addr,
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_RAW_ALIGN. len must be a multiple of FLASHPAGE_RAW_BLOCKSIZE. 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_RAW_ALIGNMENT.
[in]datadata to write to the address. MUST be aligned to FLASHPAGE_RAW_ALIGNMENT.
[in]lenlength of the data to be written. It MUST be multiple of FLASHPAGE_RAW_BLOCKSIZE. Also, ensure it doesn't exceed the actual flash memory size.