flash.h File Reference

Detailed Description

HAL flash functions.

Author

zane

Standard disclaimer whenever using flash memory:

Note that regardless of platform that this code rests on (ie. RP2350) flash memory is flash memory. It has a finite amount of uses, and while this is typically measured in the tens of thousands of write cycles it is still finite. This means that writing to flash should be done as sparingly as the program permits, with anything requiring frequent saving or writing to be done on a different medium. This also means it's best to write data in batches (ie. saving data only when you've filled up a page or sectors worth) instead of saving small chunks together. However, reading does not share this same fate, so have at it.

Also note that the indexing for these functions start from zero and essentially go reverse from the max flash size up to the min flash size. Therefore the max allowable index can be no greater than WHISKERS_FLASH_SIZE/FLASH_(PAGE or SECTOR)_SIZE.

Platform Specific Information

Typically this is all abstracted by the HAL but I believe this to be relatively useful to understand the internal quirks here.

RP2350

Note that for the flash operations to work both cores need to be suspended (this is done internally by the HAL) as instructions are stored on the on chip memory and reading and writing while executing is a bad idea. This shouldn't matter typically but for critical operations that require both cores (ie. a communication protocol is going on core1 that needs real-time response times) this is something that needs to be designed around.

Also note that if any of the flash functions fail it is a hard assert (meaning that the chip will "crash" and reboot itself). This ONLY occurs when writing or erasing flash, as reading from flash is essentially just reading from a pointer in our address space. This really shouldn't be a problem for any reason, but be prepared for a worst case scenario when writing or erasing to flash and preferably only do these operations if the chip can safely shutdown anyways.

#include "shared.h"

Go to the source code of this file.

Macros
#define	WHISKERS_FLASH_SIZE   0
	This is 2Mb (2097152b) for board version(s) 1.0.
#define	FLASH_PAGE_SIZE   0
	This is 256 bytes for board versions(s) 1.0.
#define	FLASH_SECTOR_SIZE   0
	This is 4Kb (4096b) for board version(s) 1.0.

Functions
HAL_ERROR	read_page (uint32_t page, char buf[FLASH_PAGE_SIZE])
	Reads a page from memory.
HAL_ERROR	read_sector (uint32_t sector, char buf[FLASH_SECTOR_SIZE])
	Reads a sector from memory.
HAL_ERROR	check_memory_integrity_sector (uint32_t sector, char checkagainst[FLASH_SECTOR_SIZE])
	Checks a sector against a known correct value to see if that sector is still good to use.
HAL_ERROR	check_memory_integrity_page (uint32_t page, char checkagainst[FLASH_PAGE_SIZE])
	Checks a page against a known correct value to see if that page is still good to use.
HAL_ERROR	write_page (uint32_t page, char buf[FLASH_PAGE_SIZE])
	Writes a page-sized amount of data.
HAL_ERROR	write_sector (uint32_t sector, char buf[FLASH_SECTOR_SIZE])
	Writes a sector-sized amount of data.
HAL_ERROR	erase_page (uint32_t page)
	Erases a page.
HAL_ERROR	erase_sector (uint32_t sector)
	Erases a sector.

Function Documentation

check_memory_integrity_page()

HAL_ERROR check_memory_integrity_page	(	uint32_t	page,
		char	checkagainst[FLASH_PAGE_SIZE] )

Checks a page against a known correct value to see if that page is still good to use.

Parameters

page	Page index.
checkagainst	Known correct buf to check against.

Returns

HAL_OKAY or either HAL_FLASH_OUT_OF_BOUNDS or HAL_FLASH_BAD_INTEGRITY

check_memory_integrity_sector()

HAL_ERROR check_memory_integrity_sector	(	uint32_t	sector,
		char	checkagainst[FLASH_SECTOR_SIZE] )

Checks a sector against a known correct value to see if that sector is still good to use.

Parameters

sector	Sector index.
checkagainst	Known correct buf to check against.

Returns

HAL_OKAY or either HAL_FLASH_OUT_OF_BOUNDS or HAL_FLASH_BAD_INTEGRITY

erase_page()

HAL_ERROR erase_page

(

uint32_t

page

)

Erases a page.

Parameters

page	Page index.

Returns

HAL_OKAY or HAL_FLASH_OUT_OF_BOUNDS

erase_sector()

HAL_ERROR erase_sector

(

uint32_t

sector

)

Erases a sector.

Parameters

sector

Sector index.

Returns

HAL_OKAY or HAL_FLASH_OUT_OF_BOUNDS

read_page()

HAL_ERROR read_page	(	uint32_t	page,
		char	buf[FLASH_PAGE_SIZE] )

Reads a page from memory.

Parameters

page	Page index.
buf	Buffer to store resulting page.

Returns

HAL_OKAY or HAL_FLASH_OUT_OF_BOUNDS

read_sector()

HAL_ERROR read_sector	(	uint32_t	sector,
		char	buf[FLASH_SECTOR_SIZE] )

Reads a sector from memory.

Parameters

sector	Sector index.
buf	Buffer to store resulting sector.

Returns

HAL_OKAY or HAL_FLASH_OUT_OF_BOUNDS

write_page()

HAL_ERROR write_page	(	uint32_t	page,
		char	buf[FLASH_PAGE_SIZE] )

Writes a page-sized amount of data.

Parameters

page	Page index.
buf	Page-sized buffer to write.

Note that this function internally checks itself with check_memory_integrity_page().

Returns

HAL_OKAY or either HAL_FLASH_OUT_OF_BOUNDS or HAL_FLASH_BAD_INTEGRITY

write_sector()

HAL_ERROR write_sector	(	uint32_t	sector,
		char	buf[FLASH_SECTOR_SIZE] )

Writes a sector-sized amount of data.

Parameters

page	Sector index.
buf	Sector-sized buffer to write.

Note that this function internally checks itself with check_memory_integrity_sector().

Returns

HAL_OKAY or either HAL_FLASH_OUT_OF_BOUNDS or HAL_FLASH_BAD_INTEGRITY