MityDSP::tcDspFlash Class Reference

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 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.
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.
Static Protected Attributes
static const int	gnMaxFlashSectors = 256

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 ) [protected, virtual]

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 ) [protected, virtual]

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 ) [protected, virtual]

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 ) [protected, virtual]

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
	)			`[protected, virtual]`

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
	)			`[protected, virtual]`

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).