Low level NOR flash read/erase/write interface. More...

#include "types.h"

Classes
struct	flash_region
	Metadata of a flash region, consisting of several sectors. /. More...
struct	flash_chip
	Metadata of a flash chip, describing memory layout. More...
Defines
#define	FLASH_REGION_MAX 4
Functions
int16_t	flash_init (void)
	Initialise flash chip. Call this function only once, before any other function in the module.
void	flash_deinit (void)
	Deinitialise flash chip.
struct flash_chip *	flash_metadata_get (void)
	Get chip metadata.
uint32_t	flash_sector_erase (uint32_t addr)
	Erases a flash sector. Erased sectors will be read as 0xFF.
uint16_t	flash_program (uint32_t addr, const uint8_t *data, uint16_t len)
	Programs (writes) a data buffer to the specified flash address.
int16_t	flash_read (uint32_t addr, uint8_t *data, uint16_t len)
	Reads data from the specified flash address.
int16_t	flash_copy (uint32_t dst, uint32_t src, uint16_t len)
	Copy data from a flash region to other region also in flash.
int16_t	flash_sector_limits (uint32_t addr, uint32_t start, uint32_t next)
	Obtains the sector limits (start of sector, start of next sector) corresponding to the specified address.

Detailed Description

Low level NOR flash read/erase/write interface.

Author:: Jesus Alonso (doragasu)

Date:: 08/2022

This module allows reading, erasing and writing data from/to the cartridge flash chip. It should work with any flash chip compatible with the AMD format, and implementing a CFI interface. It has been tested successfully with S29GL032 and W29GL032C chips. Also it is required that the cart has the WE line connected to the flash chip (that should be the case on most flash carts, but is not guaranteed).

Note:: The module has some limitations: addresses must be even, data pointers must be word aligned, and some functions (flash_init(), flash_sector_erase() and flash_program()) must be run with interrupts disabled and Z80 stopped. Please also take into account that flash suffers from wear, so if you use this e.g. for saving data, avoid saving very frequently and/or implement a wear leveling algorithm to avoid damaging the chip.; Although it is not a requirement for this module to work, it is strongly recommended that the cart you use also has the RESET pin connected to the console RESET signal. Otherwise, if the user pushes the RESET button while the flash chip is being erased/programmed, the machine will most likely freeze, requiring another press of the RESET button or a power cycle.

Function Documentation

int16_t flash_copy	(	uint32_t	dst,
		uint32_t	src,
		uint16_t	len
	)

Copy data from a flash region to other region also in flash.

Parameters:

[in]	dst	Destination address to copy data to.
[in]	src	Source address to copy data from
[in]	len	Length of the data block to copy.

Returns:: The number of copied bytes.

Warning:: dst and src must be even.; If len is odd, the last byte will not be copied.; Before using this function, make sure the dst region is erased. Otherwise this function can lock the machine.; This function must be called with interrupts disabled and Z80 stopped.

int16_t flash_init ( void )

Initialise flash chip. Call this function only once, before any other function in the module.

Warning:: This function must be called with interrupts disabled and Z80 stopped.

struct flash_chip* flash_metadata_get ( void ) [read]

Get chip metadata.

Returns:: An immutable reference to the chip metadata.

uint16_t flash_program	(	uint32_t	addr,
		const uint8_t *	data,
		uint16_t	len
	)

Programs (writes) a data buffer to the specified flash address.

Parameters:

[in]	addr	Address to which data will be programmed.
[in]	data	Buffer containing the data to program.
[in]	len	Length of the data buffer to write.

Returns:: The number of written bytes on success, 0 on error.

Warning:: Before using this function, make sure the address range to program is erased. Otherwise this function can lock the machine.; If addr is not even, this function can lock the machine.; If data is not word aligned, this function can lock the machine.; If data is not in work RAM, this function can lock the machine.; If len is odd, the last byte will not be written.; This function must be called with interrupts disabled and Z80 stopped.

int16_t flash_read	(	uint32_t	addr,
		uint8_t *	data,
		uint16_t	len
	)

Reads data from the specified flash address.

Parameters:

[in]	addr	Address to read data from.
[out]	data	Buffer used to copy readed data.
[in]	len	Length of the data block to read.

Returns:: The number of read bytes.

Warning:: addr must be even.; data must be word aligned.; If len is odd, the last byte will not be read.

uint32_t flash_sector_erase ( uint32_t addr )

Erases a flash sector. Erased sectors will be read as 0xFF.

Parameters:

[in] addr Any even address contained in the sector to erase.

Note:: This function erases a complete sector. Use flash_sector_limits() function to obtain the sector limits that will be erased.

Warning:: If addr is not even, this function can lock the machine.; This function must be called with interrupts disabled and Z80 stopped.

Returns:: The address of the next sector to the one erased on success, 0 on error.

int16_t flash_sector_limits	(	uint32_t	addr,
		uint32_t *	start,
		uint32_t *	next
	)

Obtains the sector limits (start of sector, start of next sector) corresponding to the specified address.

Returns:: 0 on success, -1 if input address does not fit in the chip.

Parameters:

[in]	addr	Address corresponding to the sector to get info from.
[out]	start	Start address of the sector. Can be NULL if this parameter is not needed.
[out]	next	Start address of the sector next to the current one. Can be NULL if this parameter is not needed.

Classes

Defines

Functions

Detailed Description

Function Documentation