Flash page driver

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. This variable must be defined for that purpose, according to the MCU align requirements.

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

Functions
static void *	flashpage_addr (unsigned page)
	Translate the given page number into the page's starting address. More...
static unsigned	flashpage_page (void *addr)
	Translate the given address into the corresponding page number. More...
void	flashpage_erase (unsigned page)
	Erase the given page. More...
void	flashpage_write_page (unsigned page, const void *data)
	Write the given page with the given data. More...
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. More...
void	flashpage_read (unsigned page, void *data)
	Read the given page into the given memory location. More...
int	flashpage_verify (unsigned page, const void *data)
	Verify the given page against the given data. More...
int	flashpage_write_and_verify (unsigned page, const void *data)
	Write the given page and verify the results. More...

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 102 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]

page

page number to get the address of

Returns

starting memory address of the given page

Definition at line 117 of file flashpage.h.

flashpage_erase()

void flashpage_erase

(

unsigned

page

)

Erase the given page.

Parameters

[in]

page

Page to erase

flashpage_page()

static unsigned 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]

addr

address inside the targeted page

Returns

page containing the given address

Definition at line 133 of file flashpage.h.

flashpage_read()

void flashpage_read	(	unsigned	page,
		void *	data
	)

Read the given page into the given memory location.

Parameters

[in]	page	page to read
[out]	data	memory to write the page to, MUST be FLASHPAGE_SIZE byte

flashpage_verify()

int flashpage_verify	(	unsigned	page,
		const void *	data
	)

Verify the given page against the given data.

Parameters

[in]	page	page to verify
[in]	data	data 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_addr	address in flash to write to. MUST be aligned to FLASHPAGE_WRITE_BLOCK_ALIGNMENT.
[in]	data	data to write to the address. MUST be aligned to FLASHPAGE_WRITE_BLOCK_ALIGNMENT.
[in]	len	length 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]	page	page to write
[in]	data	data 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]	page	page to write
[in]	data	data to write to the page, MUST be FLASHPAGE_SIZE byte. Set to NULL for page erase only.