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.

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 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]	name	name of the array
[in]	size	size 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] page page 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] page Page to erase

◆ 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] addr address 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]	page	page to read
[out]	data	memory 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] page page 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]	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.

Detailed Description

(Low-) Power Implications

Files

Macros

Enumerations

Functions

Macro Definition Documentation

◆ CPU_FLASH_BASE

◆ FLASH_WRITABLE_INIT

◆ FLASHPAGE_ERASE_STATE

◆ FLASHPAGE_WRITE_BLOCK_ALIGNMENT

◆ FLASHPAGE_WRITE_BLOCK_SIZE

◆ PERIPH_FLASHPAGE_CUSTOM_PAGESIZES

◆ PERIPH_FLASHPAGE_NEEDS_FLASHPAGE_ADDR

◆ PERIPH_FLASHPAGE_NEEDS_FLASHPAGE_PAGE

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ flashpage_addr()

◆ flashpage_erase()

◆ flashpage_page()

◆ flashpage_read()

◆ flashpage_size()

◆ flashpage_verify()

◆ flashpage_write()

◆ flashpage_write_and_verify()

◆ flashpage_write_page()