The tcDspFlash class may be used to write to and read from a Flash memory device. More...

#include <core/DspFlash.h>

Inheritance diagram for MityDSP::tcDspFlash:

Public Types
enum	teFlashType { eeFlashNone, eeFlashC1649, eeFlashS29GL128N, eeFlashUnknown }
typedef tsSectorMap	tsMapType
Public Types inherited from MityDSP::tcDspStorageBase
typedef void(*	tfIsrCallback )(bool, void *)
	prototype for the ISR callback

Public Member Functions
	tcDspFlash (void apBaseAddr, tcDspBankSelect apBankSel)
	This constructor is used to save parameters and initialize protected member variables to safe defaults.
virtual	~tcDspFlash ()
	Default destructor.
virtual int	write (void apAddr, void apData, int anBytes)
	Address-based write method without error return integer.
virtual int	write (void apAddr, void apData, int anBytes, int *apErr)
	This routine copies the specified number of bytes starting at the given buffer address to the provided offset into flash.
virtual int	write (unsigned int anSector, unsigned int anOffset, void *apData, int anBytes)
	Sector-based write method without error return integer and block spanning always available.
virtual int	write (unsigned int anSector, unsigned int anOffset, void apData, int anBytes, bool abSpanBlocks, int apErr=NULL)
	This routine provides an alternate API to the write method.
virtual int	rawWrite (void apAddr, void apData, int anBytes, int *apErr=NULL)
	This routine copies the specified number of bytes starting at the given buffer address to the provided offset into flash.
virtual int	rawWrite (int anSector, int anOffset, void apData, int anBytes, bool abSpanBlocks=false, int apErr=NULL)
	This routine provides an alternate API to the rawWrite method.
virtual int	read (void apStartAddr, void apBuffer, int anBytes)
	Address-based read method without error return integer.
virtual int	read (void apStartAddr, void apBuffer, int anBytes, int *apErr)
	This routine copies the specified number of bytes starting at the given flash address to the provided buffer.
virtual int	read (unsigned int anSector, unsigned int anOffset, void *apBuffer, int anBytes)
	Sector-based read method without error return integer.
virtual int	read (unsigned int anSector, unsigned int anOffset, void apBuffer, int anBytes, int apErr)
	This routine copies the specified number of bytes starting at the given flash sector and offset to the provided buffer.
virtual bool	erase (unsigned int anSector)
	Erase method without error return integer.
virtual bool	erase (unsigned int anSector, int *apErr)
	This routine attempts to erase a sector of flash.
teFlashType	identify (void)
	This routine returns the type of Flash associated with this object.
Public Member Functions inherited from MityDSP::tcDspStorageBase
	tcDspStorageBase ()
	This constructor is used to initialize storage base class.
virtual	~tcDspStorageBase ()
	Default Destructor.
virtual void	registerISRCallback (tfIsrCallback afCallback, void *apUserArg)
	This method is used to register a callback that is activated whenever the device changes state.
virtual void *	getAddress (unsigned int anSector, unsigned int anOffset)
	This routine uses the device's sector map to compute an offset address from a supplied sector and offset.
virtual unsigned int	getSize (unsigned int anSector)
	This routine uses the device's sector map to determine the size of the specified sector.
virtual unsigned int	getSector (void *apAddr)
	This routine uses the device's sector map to compute a sector from a from a supplied offset address.
virtual double	getDeviceSizeKB (void)
	This routine returns the size of the device in kilobytes.
const tsSectorMap *	getMap (int &anNumSectors)
	This routine returns a pointer to access the device's sector map.
virtual bool	getMediaPresent ()

Protected Member Functions
virtual bool	flashDataToggle (void)
	The function is used to monitor the Program/Erase Controller during erase or program operations.
virtual bool	flashSectorProtect (unsigned int anSector)
	This function protects the specified sector in the flash chip using the In-System Protection procedure.
virtual bool	flashSectorErase (unsigned int anSector)
	This function erases one block in the flash.
virtual bool	flashChipUnprotect (void)
	This function unprotects the whole chip by implementing the In-System Unprotection procedure.
virtual int	flashProgram (void apAddr, void apData, int anLength)
	This function is used to program an array into the flash.
virtual bool	eraseAsNeeded (unsigned int anSector, unsigned int anOffset, void *apData, int anBytes)
	This routine checks a sector of flash to see if erasure is required to write the provided new data.
unsigned char	readCFI (volatile unsigned char *apBaseAddr, unsigned int anOffset)
	This routine does a CFI query and returns the value read.
int	getEraseBlocks (tsSectorMap *apMap, bool abOldStyle=false)
	This routine fills in the flash map.

Static Protected Member Functions
static teFlashType	identifyFlash (void *apBaseAddr)
	This routine probes the Flash device using the standard JEDEC method and returns the type of Flash found.

Protected Attributes
SEM_Handle	mhMyMutex
	Semaphore to serialize access.
unsigned int	mnTicksPerMsec
	Low resolution clock tics per msec.
volatile unsigned char *	mpBaseAddr
tcDspBankSelect *	mpBankSelect
teFlashType	meFlashType
	Flash type identifier.
bool	mbAllowBank0Writes
	Only bootloader may write bank 0.
bool	mbUseBufferedWrites
	Used buffered writes if supported.
unsigned int	mnWriteBufferSize
	if allowed, write buffer size
unsigned char *	mpSectorBuffer
	Pointer to scratch buffer for read-modify-write operations.
Protected Attributes inherited from MityDSP::tcDspStorageBase
unsigned int	mnNumSectors
	Number of sectors in this device.
double	mnDeviceSize
	Overall device size (in bytes)
tsSectorMap *	mpSectorInfo
	Map of sectors and sizes.
bool	mbMediaPresent
	True if device is loaded.
tfIsrCallback	mfIsrCallback
void *	mpUserArg
	User-supplied argument for ISR callback.

Static Protected Attributes
static const int	gnMaxFlashSectors = 256

Additional Inherited Members
Static Public Member Functions inherited from MityDSP::tcDspStorageBase
static int	readDispatch (unsigned int anSector, unsigned int anOffset, char apBuffer, unsigned int anLength, void apInstance)
	Static dispatch routine to allow the read method to be registered as a callback.
static int	writeDispatch (unsigned int anSector, unsigned int anOffset, char apData, unsigned int anBytes, void apInstance)
	Static dispatch routine to allow the write method to be registered as a callback.
Public Attributes inherited from MityDSP::tcDspStorageBase
unsigned int	mnTxBytes
	Count of bytes written (debug)
unsigned int	mnRxBytes
	Count of bytes read (debug)

Detailed Description

The tcDspFlash class may be used to write to and read from a Flash memory device.

Any flash device that supports CFI is theoretically supported by this class.

See also:: tcDspFlash Page

Member Typedef Documentation

typedef tsSectorMap MityDSP::tcDspFlash::tsMapType

Member Enumeration Documentation

enum MityDSP::tcDspFlash::teFlashType

Enumerator:

eeFlashNone
eeFlashC1649
eeFlashS29GL128N
eeFlashUnknown

Constructor & Destructor Documentation

tcDspFlash::tcDspFlash	(	void *	apBaseAddr,
		tcDspBankSelect *	apBankSel
	)

This constructor is used to save parameters and initialize protected member variables to safe defaults.

It also uses the CFI interface to determine the flash type and geometry.

Parameters:

[in]	apBaseAddr	The base address of the flash device.
[in]	apBankSel	Pointer to the bank selector for this device.

tcDspFlash::~tcDspFlash ( )

virtual

Default destructor.

Member Function Documentation

int tcDspFlash::write	(	void *	apAddr,
		void *	apData,
		int	anBytes
	)

virtual

Address-based write method without error return integer.

Parameters:

[in]	apAddr	Address (relative to start of FLASH) to copy to.
[in]	apData	A pointer to the source buffer.
[in]	anBytes	The number of bytes to copy.

Returns:: Number of bytes actually written.

Implements MityDSP::tcDspStorageBase.

int tcDspFlash::write	(	void *	apAddr,
		void *	apData,
		int	anBytes,
		int *	apErr
	)

virtual

This routine copies the specified number of bytes starting at the given buffer address to the provided offset into flash.

All required bank selection is handled, and copies may span banks. This routine checks to see if any sectors specified need to be erased. If so, any existing data is preserved in a scratch buffer.

Parameters:

[in]	apAddr	Address (relative to start of FLASH) to copy to.
[in]	apData	A pointer to the source buffer.
[in]	anBytes	The number of bytes to copy.
[out]	apErr	Pointer to storage for additional error information.

Returns:: Number of bytes actually written.

int tcDspFlash::write	(	unsigned int	anSector,
		unsigned int	anOffset,
		void *	apData,
		int	anBytes
	)

virtual

Sector-based write method without error return integer and block spanning always available.

Parameters:

[in]	anSector	The flash sector to copy to.
[in]	anOffset	The byte offset within the specified sector.
[in]	apData	A pointer to the source buffer.
[in]	anBytes	The number of bytes to copy.

Returns:: Number of bytes actually written.

Implements MityDSP::tcDspStorageBase.

int tcDspFlash::write	(	unsigned int	anSector,
		unsigned int	anOffset,
		void *	apData,
		int	anBytes,
		bool	abSpanBlocks,
		int *	apErr = `NULL`
	)

virtual

This routine provides an alternate API to the write method.

Instead of an offset address in flash to write to, a sector and offset are provided.

Parameters:

[in]	anSector	The flash sector to copy to.
[in]	anOffset	The byte offset within the specified sector.
[in]	apData	A pointer to the source buffer.
[in]	anBytes	The number of bytes to copy.
[in]	abSpanBlocks	Boolean indicating if writes may span sectors.
[out]	apErr	Pointer to storage for additional error information.

Returns:: Number of bytes actually written.

int tcDspFlash::rawWrite	(	void *	apAddr,
		void *	apData,
		int	anBytes,
		int *	apErr = `NULL`
	)

virtual

This routine copies the specified number of bytes starting at the given buffer address to the provided offset into flash.

All required bank selection is handled, and copies may span banks.

Note:: It is assumed that any required erasures have already been performed.

Parameters:

[in]	apAddr	Address (relative to start of FLASH) to write to.
[in]	apData	A pointer to the source buffer.
[in]	anBytes	The number of bytes to copy.
[out]	apErr	Pointer to storage for additional error information.

Returns:: Number of bytes actually written.

int tcDspFlash::rawWrite	(	int	anSector,
		int	anOffset,
		void *	apData,
		int	anBytes,
		bool	abSpanBlocks = `false`,
		int *	apErr = `NULL`
	)

virtual

This routine provides an alternate API to the rawWrite method.

Instead of an offset address in flash to write to, a sector and offset are provided.

Parameters:

[in]	anSector	The flash sector to copy to.
[in]	anOffset	The byte offset within the specified sector.
[in]	apData	A pointer to the source buffer.
[in]	anBytes	The number of bytes to copy.
[in]	abSpanBlocks	Boolean indicating if writes may span sectors.
[out]	apErr	Pointer to storage for additional error information.

Returns:: Number of bytes actually written.

int tcDspFlash::read	(	void *	apStartAddr,
		void *	apBuffer,
		int	anBytes
	)

virtual

Address-based read method without error return integer.

Parameters:

[in]	apStartAddr	Address (from start of FLASH) to copy from.
[in]	apBuffer	A pointer to the destination buffer.
[in]	anBytes	The number of bytes to copy.

Returns:: Number of bytes actually copied.

Implements MityDSP::tcDspStorageBase.

int tcDspFlash::read	(	void *	apStartAddr,
		void *	apBuffer,
		int	anBytes,
		int *	apErr
	)

virtual

This routine copies the specified number of bytes starting at the given flash address to the provided buffer.

All required bank selection is handled, and copies may span banks.

Parameters:

[in]	apStartAddr	Address (from start of FLASH) to copy from.
[in]	apBuffer	A pointer to the destination buffer.
[in]	anBytes	The number of bytes to copy.
[out]	apErr	Pointer to storage for additional error information.

Returns:: Number of bytes actually copied.

int tcDspFlash::read	(	unsigned int	anSector,
		unsigned int	anOffset,
		void *	apBuffer,
		int	anBytes
	)

virtual

Sector-based read method without error return integer.

Parameters:

[in]	anSector	The flash sector to copy from.
[in]	anOffset	The offset from the start of the flash sector.
[in]	apBuffer	A pointer to the destination buffer.
[in]	anBytes	The number of bytes to copy.

Returns:: Number of bytes actually copied.

Implements MityDSP::tcDspStorageBase.

int tcDspFlash::read	(	unsigned int	anSector,
		unsigned int	anOffset,
		void *	apBuffer,
		int	anBytes,
		int *	apErr
	)

virtual

This routine copies the specified number of bytes starting at the given flash sector and offset to the provided buffer.

All required bank selection is handled, and copies may span banks.

Parameters:

[in]	anSector	The flash sector to copy from.
[in]	anOffset	The offset from the start of the flash sector.
[in]	apBuffer	A pointer to the destination buffer.
[in]	anBytes	The number of bytes to copy.
[out]	apErr	Pointer to storage for additional error information.

Returns:: Number of bytes actually copied.

bool tcDspFlash::erase ( unsigned int anSector )

virtual

Erase method without error return integer.

Parameters:

[in] anSector The flash sector to erase.

Returns:: true if erase successful, false otherwise.

Reimplemented from MityDSP::tcDspStorageBase.

bool tcDspFlash::erase	(	unsigned int	anSector,
		int *	apErr
	)

virtual

This routine attempts to erase a sector of flash.

Bank selection is handled within this routine.

Parameters:

[in]	anSector	The flash sector to erase.
[out]	apErr	Pointer to storage for additional error information.

Returns:: true if erase successful, false otherwise.

tcDspFlash::teFlashType tcDspFlash::identify ( void )

This routine returns the type of Flash associated with this object.

Returns:: Enumeration representing the type of Flash device.

bool tcDspFlash::flashDataToggle ( void )

protectedvirtual

The function is used to monitor the Program/Erase Controller during erase or program operations.

It returns when the Program/Erase Controller

Returns:: true if successful, false otherwise.

bool tcDspFlash::flashSectorProtect ( unsigned int anSector )

protectedvirtual

This function protects the specified sector in the flash chip using the In-System Protection procedure.

Parameters:

[in] anSector The number of the sector to protect.

Returns:: true if successful, false otherwise

bool tcDspFlash::flashSectorErase ( unsigned int anSector )

protectedvirtual

This function erases one block in the flash.

The function does not return until the block is erased. If the block is protected or invalid the block is will not erase.

Parameters:

[in] anSector The sector number to erase.

Returns:: true if successful, false otherwise

bool tcDspFlash::flashChipUnprotect ( void )

protectedvirtual

This function unprotects the whole chip by implementing the In-System Unprotection procedure.

Returns:: true if successful, false otherwise

int tcDspFlash::flashProgram	(	void *	apAddr,
		void *	apData,
		int	anLength
	)

protectedvirtual

This function is used to program an array into the flash.

It does not erase the flash first and will not produce proper results, if the block(s) is (are) not erased first. Any errors are returned without any further attempts to program other addresses of the device.

Parameters:

[in]	apAddr	Address (relative to start of FLASH) to be programmed.
[in]	anLength	The size of the array, in bytes.
[in]	apData	A void pointer to the array with the contents to be programmed.

Returns:: Number of bytes successfully written.

bool tcDspFlash::eraseAsNeeded	(	unsigned int	anSector,
		unsigned int	anOffset,
		void *	apData,
		int	anBytes
	)

protectedvirtual

This routine checks a sector of flash to see if erasure is required to write the provided new data.

If so, all data within the sector but outside the new data is preserved in the scratch buffer. The sector is then erased. Finally, any previously-preserved data is written back to its original location.

Note:: This routine is a private member function which assumes the data falls entirely within one sector and the bank selection has already been performed.

Parameters:

[in]	anSector	The flash sector to check for erasure.
[in]	anOffset	The byte offset within the specified sector.
[in]	apData	A pointer to the source buffer.
[in]	anBytes	The number of bytes to test.

Returns:: True if sector is ready to be written, false otherwise.

unsigned char tcDspFlash::readCFI	(	volatile unsigned char *	apBaseAddr,
		unsigned int	anOffset
	)

protected

This routine does a CFI query and returns the value read.

Parameters:

[in]	apBaseAddr	The base address of the flash device.
[in]	anOffset	Address offset to CFI item requested.

Returns:: value

int tcDspFlash::getEraseBlocks	(	tsSectorMap *	apMap,
		bool	abOldStyle = `false`
	)

protected

This routine fills in the flash map.

Parameters:

[in]	apMap	Pointer to a map structure to fill.
[in]	abOldStyle	If true, creates an "old-style" secor map, with the repeat count always set to 1 (default: false).

Returns:: Number of sector map entries required

tcDspFlash::teFlashType tcDspFlash::identifyFlash ( void * apBaseAddr )

staticprotected

This routine probes the Flash device using the standard JEDEC method and returns the type of Flash found.

Parameters:

[in] apBaseAddr The base address of the flash device.

Returns:: Enumeration representing the type of Flash device (eeFlashNone if the probe is unsuccessful).

Member Data Documentation

const int MityDSP::tcDspFlash::gnMaxFlashSectors = 256

staticprotected

SEM_Handle MityDSP::tcDspFlash::mhMyMutex

protected

Semaphore to serialize access.

unsigned int MityDSP::tcDspFlash::mnTicksPerMsec

protected

Low resolution clock tics per msec.

volatile unsigned char* MityDSP::tcDspFlash::mpBaseAddr

protected

tcDspBankSelect* MityDSP::tcDspFlash::mpBankSelect

protected

teFlashType MityDSP::tcDspFlash::meFlashType

protected

Flash type identifier.

bool MityDSP::tcDspFlash::mbAllowBank0Writes

protected

Only bootloader may write bank 0.

bool MityDSP::tcDspFlash::mbUseBufferedWrites

protected

Used buffered writes if supported.

unsigned int MityDSP::tcDspFlash::mnWriteBufferSize

protected

if allowed, write buffer size

unsigned char* MityDSP::tcDspFlash::mpSectorBuffer

protected

Pointer to scratch buffer for read-modify-write operations.

Public Types

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation