/*************************************************************************************************
 *** Copyright (C) Intel Corporation 2006
 *** All Rights Reserved.
 *** ---------------------------------------------------------------------------------------------
 *** PROJECT NAME: Intel StrataFlash(R) Cellular Memory (M18) Template Reference Code
 ***
 *** FILE:         template.h
 ***
 *** TARGET:  	   Motorola Coldfire* 5272 with custom M18 Add-on sockets
 ***
 *** VERSION:      1.0
 ***
 *** DATE:         03/24/06
 ***
 *** AUTHOR:       Ronald Richardson
 ***
 *** PURPOSE:      Driver function signatures, declarations, and documentation. The first
 ***			   section of definitions are user-customizable. Please review these options
 ***			   and make any appropritate changes or additions.
 ***
 *** ---------------------------------------------------------------------------------------------
 *** General Note(s): (function headers make reference these notes)
 ***
 *** 1.	If this code is being run from the partition addressed by this
 ***	command, the system is at risk of stalling due to inaccessible
 ***	code. This method will/may change the 'Array State' of this
 ***	partition from Read Array mode to anther, thus making the code
 ***	being executed inaccessable to the processor. To avoid this issue,
 ***	this code should be linked onto a different memory device or
 ***	to a different partition before execution.
 ***
 *** 2.	This template driver has been written to support X16 devices only, and must be
 ***	heavily modified to support X32 devices.
 ***
 *** 4.	The constant address TMPL_DEF_PARTITION_ADDR will be used to read or write data to
 ***	the device in these functions. In these cases, the address written/read is not important
 ***	and will not alter the state of the device. Other functions accept a 'partitionAddr' as
 ***	a parameter if the issued command address is important.
 ***
 *** 5. The template algorithm package is designed for single threaded environments only.
 ***	Testing has only occured in single threaded environments. No testing has occured in
 ***	multi-threaded environments and the design does not directly provide multi-threaded
 ***	support.
 ***
 *************************************************************************************************
 *** NOTICE OF LICENSE AGREEMENT
 ***
 *** This code is provided by Intel Corp., and the use is governed
 *** under the terms of a license agreement. See license agreement
 *** for complete terms of license.
 ***
 *** YOU MAY ONLY USE THE SOFTWARE WITH INTEL FLASH PRODUCTS. YOUR
 *** USE OF THE SOFTWARE WITH ANY OTHER FLASH PRODUCTS IS EXPRESSLY
 *** PROHIBITED UNLESS AND UNTIL YOU APPLY FOR, AND ARE GRANTED IN
 *** INTEL'S SOLE DISCRETION, A SEPARATE WRITTEN SOFTWARE LICENSE
 *** FROM INTEL LICENSING ANY SUCH USE.
 *************************************************************************************************/


#ifndef TEMPLATE_H_
#define TEMPLATE_H_

/*******************************************************************************************
 ***     User-customizable Features:
 *******************************************************************************************/

/*-----------------------------------------------------------------------------------------*
 | ADDRESS_PIN_LEFT_OFFSET
 |
 | 	In the case of TMPL_ProgramReadConfigReg() and TMPL_ProgramEnhancedConfigReg(),
 |	register data is passed on the address lines. Some target systems will disconnect
 |	the lowest address pins to account for differences in memory granularity.
 |	Use this to shift left the bits of any data being written to the address lines
 |	in the case that the address lines are not connected 1:1. See Section 9.3 Note
 |	of the datasheet for more information.
 |
 |		#define USE_ADDRESS_PIN_OFFSET
 |
 *-----------------------------------------------------------------------------------------*/

#ifdef USE_ADDRESS_PIN_OFFSET
	#define ADDRESS_PIN_LEFT_OFFSET		1
#endif


/*-----------------------------------------------------------------------------------------*
 | RUNTIME_SAFETY_CHECKS
 |
 |	Many template method implementations contain optional code to PARTIALLY validate
 |	parameters at run-time. Runtime safety checks should be used in development to
 |	avoid or detect CERTAIN run-time errors, but should not be inculded if efficiency
 |	is paramount.
 |
 *-----------------------------------------------------------------------------------------*/

#define RUNTIME_SAFETY_CHECKS


/*-----------------------------------------------------------------------------------------*
 | Primitive Data Types:
 |
 |	Option to instead #include a local file that contains these definitions. These are
 |	included here for completeness, but are used throughout the driver.
 |
 *-----------------------------------------------------------------------------------------*/

typedef unsigned char				uint8;  	/*  8 bits */
typedef unsigned short int			uint16; 	/* 16 bits */
typedef unsigned long int			uint32; 	/* 32 bits */


/*-----------------------------------------------------------------------------------------*
 | ErrorTypes
 |
 |	Each runtime safety check will report a unique 'ErrorType' code in the flash_info->error
 |	value before the TMPL_HandleError() method is called. These should be used for identification
 |	purposes only and are not extensive.
 |
 |	Please Note: These values are not from the datasheet. They are instead an enumeration
 |	of various parameter errors that are detected during run-time checks.
 *-----------------------------------------------------------------------------------------*/

enum ErrorTypes {
	/* General Case: No errors or SR errors: */
	TMPL_etNone						= 0x00,		/* No Errors */
	TMPL_etSRError					= 0x01,		/* SR Error bits, see 'lastSR' in flash_info */

	/* Errors from RunTimeChecks: */
	TMPL_etControlModeError			= 0x11,		/* Runtime-check reported write to invalid half of memory for SingleWordProgram opp */
	TMPL_etInvalidBPWordCount		= 0x12,		/* Invalid Buffered Program word count */
	TMPL_etBuffProgStartObjectMode	= 0x13,		/* The starting address of a Buffered Program command in object mode was not buffer-aligned */
	TMPL_etBuffProgAddrControlMode	= 0x14,		/* A Control-mode buffered program's starting address had addr3=1, which is illegal */
	TMPL_etEFAAddrError				= 0x15,		/* An EFA Address was out of range */
	TMPL_etBEFProgStartAddress		= 0x16,		/* Starting address in BEFP was not buffer-size aligned */
	TMPL_etBEFProgCtrlStartAddress	= 0x17,		/* Control Mode address must be block-aligned, not only buffer size-aligned */
	TMPL_etBEFProgVerifyError		= 0x18,		/* BEFP operation failed to validate written contents */
	TMPL_etBlankCheckFailure		= 0x19,		/* An error occured during a blank check operation */
	TMPL_etReadArrayControlMode		= 0x1A,		/* Starting address for read array had addr3=1 for a control-mode read */
	TMPL_etOTPAddrOutOfRange		= 0x1B,		/* On program OTP, the address specified is out of the OTP address range. */
	TMPL_etInitPartitionAddrAlign	= 0x1C,		/* The Default Partition Address supplied in InitFlashInfo was not alligned with PartitionSize */
	TMPL_etInitPartitionAddrMax		= 0x1D		/* The Default Partition Address exceeds the device size */
};
typedef uint8 ErrorType;						/* Used in flash_info struct */


/*-----------------------------------------------------------------------------------------*
 | flash_info
 |
 |	This structure is passed to all driver routines. It identifies the desired
 |	flash device through the 'baseAddr,' and contains other information about
 |	the particular flash device in use. This approach allows for multiple device
 |	support without conflicting global data.
 |
 |	The lastSR and error values are set by various methods during execution.
 |
 *-----------------------------------------------------------------------------------------*/

typedef struct {

	/* Fixed device info, set by TMPL_InitFlashInfo() */
    uint16 * 		baseAddr;					/* Physical base address of device from the OS's perspective */
    uint32 			deviceSize;					/* Device Size in words (= Max addressable address + 1) */
    uint32 			partitionSize;				/* deviceSize / 8 = Size of one partition */

    /* Runtime info (updated according to method called) */
    ErrorType		error;						/* Error flag. See ErrorTypes above */
    uint16 			lastSR;						/* Most recent read Status register value, see function header */

} flash_info;


/*-----------------------------------------------------------------------------------------*
 | TMPL_DEF_PARTITION_ADDR
 |
 |	Several commands that issue 'generic' reads/writes to the device can be issued at any
 |	address. This address is the default address for those reads/writes. If an operation will
 |	behave differently depending on the address issued, that address is included as a
 |	parameter to that method.
 |
 |	The partition at this address will/may be taken out of Read Array mode momentarily during
 |	executing of the following commands. Care should be taken to ensure this address does
 |	not refer to an active code partition.
 |
 |	The commands that use this location for reads/writes are:
 |		TMPL_ClearStatReg(.) 		TMPL_Suspend(.)		TMPL_DeepPowerDown(.)
 |		TMPL_isProgramComplete(.)	TMPL_Resume(.)		TMPL_ReleaseFromDeepPowerDown(.)
 |
 |	See note 4 of this header file for other information.
 |
 *-----------------------------------------------------------------------------------------*/

#define TMPL_DEF_PARTITION_ADDR		0x00000000


/*-----------------------------------------------------------------------------------------*
 | TMPL_HandleError
 |
 |	The TMPL_HandleError routine will be called when any error is detected during a
 |	Runtime-Safety-Check or in the isProgrammingComplete() method.
 |
 | Please Note:
 |
 |	This method's implementation is purposely left as a skeleton and should be completed
 |	appropriately.
 |
 *-----------------------------------------------------------------------------------------*/

#ifdef RUNTIME_SAFETY_CHECKS
	void TMPL_HandleError(flash_info * info);
#endif

/*******************************************************************************************
 ***     Definitions: Device-Specific size boundaries
 *******************************************************************************************/

#define TMPL_PARTITION_COUNT			0x08

#define TMPL_EFA_SIZE					0x4000
#define TMPL_BLOCK_SIZE					0x20000

#define TMPL_PARTITION_SIZE_256			0x200000
#define TMPL_PARTITION_SIZE_512			0x400000

#define TMPL_DEVICE_SIZE_256			0x1000000
#define TMPL_DEVICE_SIZE_512			0x2000000

#define TMPL_OTP_START_ADDR				0x00000080
#define TMPL_OTP_END_ADDR				0x00000109

/* The device's Buffered Write buffer size is specified here in words:
 * (default to 512 words, constant used in BEFP program routine)
 */
#define BUFFER_SIZE_WORDS				0x200


/*******************************************************************************************
 ***     Definitions: Device ID Codes
 *******************************************************************************************/

#define DEVID_512_NON_MUX				0x887E
#define DEVID_512_AD_MUX				0x8881
#define DEVID_256_NON_MUX				0x8901
#define DEVID_256_AD_MUX				0x8904


/*******************************************************************************************
 ***     Definitions: M18 Device Operation & Confirmation Codes
 *******************************************************************************************/

/* Registers */
#define OPCODE_PROG_READ_CFG_REG		0x0060
#define OPCODE_PROG_READ_CFG_REG_CONF	0x0003
#define OPCODE_PROG_ENHC_CFG_REG		0x0060
#define OPCODE_PROG_ENHC_CFG_REG_CONF	0x0004
#define OPCODE_PROG_OTP_REG				0x00C0

#define OPCODE_CLEAR_STATUS_REG			0x0050

/* Read Modes */
#define OPCODE_READ_ARRAY				0x00FF
#define OPCODE_READ_STATUS_REG			0x0070
#define OPCODE_READ_DEVICE_INFO			0x0090
#define OPCODE_READ_EFA					0x0094
#define OPCODE_CFI_QUERY				0x0098

/* Program/Erase Operations */
#define OPCODE_SINGLE_WORD_PROGRAM		0x0041
#define OPCODE_BFRD_PROG				0x00E9
#define OPCODE_BFRD_PROG_CONF			0x00D0
#define OPCODE_BFRD_ENHC_FACT_PROG		0x0080
#define OPCODE_BFRD_ENHC_FACT_PROG_CONF	0x00D0
#define OPCODE_EFA_PROG					0x0044

/* Suspend/Resume */
#define OPCODE_SUSPEND					0x00B0
#define OPCODE_RESUME					0x00D0

/* Blank Check Operation */
#define OPCODE_BLANK_CHECK				0x00BC
#define OPCODE_BLANK_CHECK_CONF			0x00D0

/* Security - both Standard & EFA Locking Commands */
#define OPCODE_STD_LOCKING_SETUP_CMD	0x0060
#define OPCODE_EFA_LOCKING_SETUP_CMD	0x0064

#define OPCODE_LOCK_BLOCK_CONF			0x0001
#define OPCODE_UNLOCK_BLOCK_CONF		0x00D0
#define OPCODE_LOCK_DOWN_BLOCK_CONF		0x002F

/* Block Erase Operations */
#define OPCODE_STD_BLOCK_ERASE			0x0020
#define OPCODE_EFA_BLOCK_ERASE			0x0024

#define OPCODE_BLOCK_ERASE_CONF			0x00D0


/*******************************************************************************************
 ***     Definitions: Simple Status Register Masks
 *******************************************************************************************/

/* Isolate all 'error flags' */
#define SR_MASK_ERROR_FLAGS				0x003A

/* General bit masks */
#define SR_MASK_RESERVED				0xFC00
#define SR_MASK_REGION_PROGRAM_STATUS	0x0300
#define SR_MASK_READY_STATUS			0x0080
#define SR_MASK_ERASE_SUSPEND_STATUS	0x0040
#define SR_MASK_ERASE_ERR				0x0020
#define SR_MASK_PROG_ERR				0x0010
#define SR_MASK_PROG_ERASE_VOLTAGE_ERR	0x0008
#define SR_MASK_PROG_SUSPEND_STATUS		0x0004
#define SR_MASK_BLOCK_LOCKED_ERR		0x0002
#define SR_MASK_PARTITION_STATUS		0x0001


/*******************************************************************************************
 ***     Definitions: Read Configuration Register Masks & Values
 *******************************************************************************************/

#define RCR_MASK_READ_MODE				0x8000
#define RCR_MASK_LATENCY_COUNT			0x7800
#define RCR_MASK_WAIT_POLARITY			0x0400
#define RCR_MASK_WAIT_DELAY				0x0100
#define RCR_MASK_BURST_LENGTH			0x0007

#define RCR_LATENCY_COUNT_CODE_3		0x1800
#define RCR_LATENCY_COUNT_CODE_4		0x2000
#define RCR_LATENCY_COUNT_CODE_5		0x2800
#define RCR_LATENCY_COUNT_CODE_6		0x3000
#define RCR_LATENCY_COUNT_CODE_7		0x3800
#define RCR_LATENCY_COUNT_CODE_8		0x4000
#define RCR_LATENCY_COUNT_CODE_9		0x4800
#define RCR_LATENCY_COUNT_CODE_10		0x5000
#define RCR_LATENCY_COUNT_CODE_11		0x5800
#define RCR_LATENCY_COUNT_CODE_12		0x6000

#define RCR_BURST_LENGTH_8_WORD			0x0002
#define RCR_BURST_LENGTH_16_WORD		0x0003
#define RCR_BURST_LENGTH_CTS_WORD		0x0007


/*******************************************************************************************
 ***     Definitions: Enchanced Configuration Register Masks & Values
 *******************************************************************************************/

#define ECR_MASK_DEEP_POWER_DOWN_MODE	0x8000
#define ECR_MASK_DPD_POLARITY			0x6000
#define ECR_MASK_OUTPUT_DRVR_CTRL		0x0007

#define ECR_OUTPUT_DRVR_CTRL_CODE_1		0x0001
#define ECR_OUTPUT_DRVR_CTRL_CODE_2		0x0002
#define ECR_OUTPUT_DRVR_CTRL_CODE_3		0x0003
#define ECR_OUTPUT_DRVR_CTRL_CODE_4		0x0004
#define ECR_OUTPUT_DRVR_CTRL_CODE_5		0x0005
#define ECR_OUTPUT_DRVR_CTRL_CODE_6		0x0006


/*******************************************************************************************
 ***     Definition: Control Mode Address Rules
 *******************************************************************************************/

#define INVALID_CTRL_MODE_ADDR(addr)	((addr & 0x08) != 0x00)


/*******************************************************************************************
 ***     Definitions: ReadDeviceInfo codes & data type
 *******************************************************************************************/

/* Used with the TMPL_ReadDeviceInfo() routine, and represent fixed memory addresses only: */
enum DeviceInfoOffsets {
	TMPL_dioDeviceManufacturerCode 		= 0x0000,
	TMPL_dioDeviceIDCode				= 0x0001,
	TMPL_dioMainBlockLockStatus			= 0x0002,
	TMPL_dioEFABlockLockStatus			= 0x0002,
	TMPL_dioReadCfgReg					= 0x0005,
	TMPL_dioEnhancedCfgReg				= 0x0006,
	TMPL_dioOTPLockReg0					= 0x0080,
	TMPL_dioOTPReg_FactorySegment		= 0x0081,
	TMPL_dioOTPReg_UserProgSegment		= 0x0085,
	TMPL_dioOTPLockReg1					= 0x0089,
	TMPL_dioOTPRegisters				= 0x008A
};
/* Type 'DeviceInfoOffset' does nothing more than associate parameters to this enum */
typedef uint16 DeviceInfoOffset;


/*******************************************************************************************
 ***     Definitions: ReadModes
 *******************************************************************************************/

/* The five partition array states available, for use with TMPL_ChangeArrayState(): */
enum ArrayStates {
	TMPL_asReadArray					= OPCODE_READ_ARRAY,
	TMPL_asReadStatReg					= OPCODE_READ_STATUS_REG,
	TMPL_asReadDeviceInfo				= OPCODE_READ_DEVICE_INFO,
	TMPL_asCFIQuery						= OPCODE_CFI_QUERY,
	TMPL_asReadEFABlock					= OPCODE_READ_EFA
};
/* Type 'ArrayState' does nothing more than associate parameters to this enum */
typedef uint16 ArrayState;


/*******************************************************************************************
 ***     Definitions: Lock Commands
 *******************************************************************************************/

/* Opcodes used to differentiate between locking operations, used with TMPL_IssueLockCommand(): */
enum LockCommands {
	TMPL_lcLockBlock 					= OPCODE_LOCK_BLOCK_CONF,
	TMPL_lcUnlockBlock					= OPCODE_UNLOCK_BLOCK_CONF,
	TMPL_lcLockDownBlock				= OPCODE_LOCK_DOWN_BLOCK_CONF
};
/* Type 'LockCommand' does nothing more than associate parameters to this enum */
typedef uint16 LockCommand;





/*******************************************************************************************
 ***     Definitions: Driver Functions
 *******************************************************************************************/

/*-----------------------------------------------------------------------------------------*
 | TMPL_InitFlashInfo
 |
 | Description:
 |
 | 	Initializes the flash_info structure to be used with all driver methods. flash_info must
 |	be initialized before use, and is used for the 'baseAddr' * in all commands.
 |
 |	When initializing info->deviceSize, this method assumes that partition size was entered
 |	correctly, and that TMPL_PARTITION_COUNT partitions exist on the device.
 |
 | Parameters:
 |
 | 	OUT info			Instance of flash_info structure to be populated, returns
 |						populated struct.
 | 	IN	baseAddr		The base address of the flash within the target device's
 |						address space. Writing to 'baseAddress' should effectively be
 |						writing to flash address 0x0.
 | 	IN	partitionSize	Size of device's partitions in number of words. This value is used
 |						with TMPL_PARTITION_COUNT to calculate the size of the device.
 |
 | Returns:
 |
 |	Nothing
 |
 | Precondition:
 |
 |	ArrayState: 		N/A
 |
 | Postcondition:
 |
 |	ArrayState: 		N/A
 |	info:				Populated with parameters & size, error data cleared.
 |	info->baseAddr:		Should refer to the devices local address 0x0.
 |
 | Notes:
 |
 |	DeviceSize and partitionSize are used in runtime safety checks and BEFP Logic, but are
 |	optional if not for these uses.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_InitFlashInfo (
	flash_info * 	info,
	uint32 			baseAddr,
	uint32			partitionSize
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_ChangeArrayState
 |
 | Description:
 |
 | 	Changes the state of the addressed partition to that specified.
 |
 | Parameters:
 |
 | 	IN	info			Flash device base address.
 |	IN	partitionAddr	Any address within the device partition of request.
 |	IN	arrayState		Array State identifier. Values are enumerated from Table 29
 |						as 'ArrayStates' in this header file.
 |
 | Returns:
 |
 |	Nothing
 |
 | Precondition:
 |
 |	ArrayState: 		Any (partition at 'partitionAddr')
 |
 | Postcondition:
 |
 |	ArrayState: 		As specified by 'arrayState' or SR will show error.
 |						(partition at 'partitionAddr')
 |
 | Notes:
 |
 |	See Note 1 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_ChangeArrayState (
	const flash_info * 	info,
	uint32				partitionAddr,
	ArrayState 			arrayState
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_ReadStatReg
 |
 | Description:
 |
 | 	Reads the Status Register (SR), may clear the SR of errors, restores the device to
 |	Read Array mode, and returns the read SR value.
 |
 | Parameters:
 |
 | 	IN	info			Flash device base address.
 |	IN	partitionAddr	An address within the desired partition: this address will be
 |						used to issue the RSR command. The SR has bits that are partition-
 |						dependant; this allows partition-specific RSR requests.
 |	IN	clearErrors		Flag indicates that the Clear Status Register command will be issued
 |						before returning the SR value.
 |						FALSE (0):	The command to clear SR error flags will not be sent.
 |						TRUE (!0):	'ClearSRErrors' will be sent to the device after
 |									the SR has been read for return.
 |
 | Returns:
 |
 |	The 16-bit device Status register value before errors are optionally cleared.
 |
 | Precondition:
 |
 |	ArrayState: 		Any
 |						(partition at 'partitionAddr')
 |
 | Postcondition:
 |
 |	ArrayState: 		Read Array
 |						(partition at 'partitionAddr')
 |	SR:					Cleared of error flags if 'clearErrors' is set, else unchanged.
 |
 | Notes:
 |
 |	In the case that the device is in Read Status Register mode and SR information is
 |	required continuously, use TMPL_ReadWord() from target.h to retrieve SR information
 |	and leave ArrayState Unchanged.
 |
 |	See Notes 1 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
uint16 TMPL_ReadStatReg (
	const flash_info * 	info,
	uint32				partitionAddr,
	uint8 				clearErrors
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_ClearStatReg
 |
 | Description:
 |
 | 	Clears the Status register of any error flags. The SR must be cleared of errors before
 |	issuing any new program/erase/blank-check operations. See Data Sheet for more information.
 |
 | Parameters:
 |
 | 	IN		info	Flash device base address.
 |
 | Returns:
 |
 |	Nothing
 |
 | Precondition:
 |
 |	ArrayState: 	Any
 |					(partition at 'TMPL_DEF_PARTITION_ADDR')
 |
 | Postcondition:
 |
 |	ArrayState: 	Read Array
 |					(partition at 'TMPL_DEF_PARTITION_ADDR')
 |	SR:				Cleared of error flags (SR & SR_MASK_ERROR_FLAGS == 0)
 |
 | Notes:
 |
 |	Resetting the device has the same effect.
 |
 |	See Notes 1,4 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_ClearStatReg (
	const flash_info * 	info
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_ReadDeviceInfo
 |
 | Description:
 |
 |	Used to access ECR, RCR, OTP, EFA Lock Status, Main Block Lock status, and ID codes
 |	according to Section 9.5.3 Table 30 of the datasheet. The routine will switch the device
 |	to Read Device Information mode, read the data at the provided offset from the default
 |	partition address as set in the flash_info structure used, return the device partition
 |	to Read Array mode, and return the requested word.
 |
 |	This function is equivalent to the datasheet's definition of Device Info.
 |
 | Parameters:
 |
 | 	IN	info			Flash device base address.
 |	IN	commandBaseAddr	The base device address to issue the command. The 'infoOffset' will be
 |						added to this base when reading the device info data. To read from a
 |						particular partition, pass that partitions base address. To read from
 |						a particular block, pass that blocks base address (always relative to
 |						device address 0).
 |	IN	infoOffset		The effective 'address' of the requested information within the 'Device
 |						Information' address space. The effective read would appear as in this
 |						c statement: "return *(commandBaseAddr + infoOffset);"
 |						See Table 30 of the datasheet for specifics.
 |
 | Returns:
 |
 |	16-bit data value at 'infoOffset' from within the 'Device Info' address space.
 |
 | Precondition:
 |
 |	ArrayState: 		Any
 |						(partition at 'commandBaseAddr')
 |
 | Postcondition:
 |
 |	ArrayState: 		Read Array
 |						(partition at 'commandBaseAddr')
 |
 | Notes:
 |
 |	To perform consecutive reads without the overhead of changing array state on each,
 |	first issue the ChangeArrayState() command with asReadDeviceInfo as the ArrayState.
 |	Use ReadWord() or ReadWords() with the correct address offset to access DeviceInfo
 |	data, and return the device to ReadArray state when finished.
 |
 |	See Note 1 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
uint16 TMPL_ReadDeviceInfo (
	const flash_info * 	info,
	uint32				commandBaseAddr,
	DeviceInfoOffset 	infoOffset
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_CFIQuery
 |
 | Description:
 |
 | 	Accesses words of the 'Command Flash Interface' information. Please see datasheet for
 |	the CFI offsets of specific data. Also, see 'Notes' below for efficiency notes if
 |  doing consecutive CFI reads.
 |
 | Parameters:
 |
 | 	IN	info			Fash device base address.
 |	IN	cfiQueryAddr	The effective 'address' of the requested information within the
 |						device address space. Since CFI data can be read from any partition,
 |						reading CFI data at offset 0x15 (for example) can be read from 0x15
 |						if accessing from partition 0, or 0x400015 to read from partition
 |						2 (on a 256Mb device) or partition 1 (on a 512Mb Device).
 |						See Appendix D of the datasheet for specifics.
 |
 | Returns:
 |
 |	16-bit Word of data associated with the 'offset' address returned from the CFI
 |	information on the device.
 |
 | Precondition:
 |
 |	ArrayState: 		Any
 |						(partition at 'cfiQueryAddr')
 |
 | Postcondition:
 |
 |	ArrayState: 		Read Array
 |						(partition at 'cfiQueryAddr')
 |
 | Notes:
 |
 |	Similar to ReadDeviceInfo, to perform consecutive reads without the overhead of
 |	changing array state on each, first issue the ChangeArrayState() command with
 |	TMPL_asCFIQuery as the ArrayState. Use ReadWord() or ReadWords() with the correct
 |	address offset to access DeviceInfo data, and return the device to TMPL_asReadArray
 |	state when finished.
 |
 |	See Notes 1 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
uint16 TMPL_CFIQuery (
	const flash_info * 	info,
	uint32				cfiQueryAddr
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_ProgramReadConfigReg
 |
 | Description:
 |
 | 	Issuing this command programs the device's 'Read Configuration Register' with the
 |	provided data. Please see the datasheet for the RCR's responsibility.
 |
 |	Use TMPL_ReadDeviceInfo() with TMPL_dioReadCfgReg as an offest to access the RCR
 |	initially if masking is desired.
 |
 | Parameters:
 |
 | 	IN		info	Flash device to access, and potential status information returned.
 |	IN		rcr		The value of the RCR to be written. Use ReadDeviceInfo() with
 |					TMPL_dioReadCfgReg as an offset to read the RCR first. Bit masks
 |					are defined as RCR_* in this file.
 |
 | Returns:
 |
 |	Nothing
 |
 | Precondition:
 |
 |	ArrayState: 	Any
 |					(partition 0)
 |	RCR:			Any
 |
 | Postcondition:
 |
 |	ArrayState: 	Read Array
 |					(partition 0)
 |	RCR:			Takes the value of the parameter 'rcr'
 |
 | Warning:
 |
 |	Datasheet sectoin 9.3 indicates that switching device mode from Synchronous to
 |	Asynchronous or vice versa requires a delay. Please take care to see that this criteria
 |	is met if switching modes.
 |
 | Notes:
 |
 |	Section 9.3 of the datasheet mentions that some hardware configurations will leave one
 |	or more of the lowest-order address pins disconnected. Since the RCR value is passed in
 |	on the address lines, this word must be offset to be interpreted correctly. Use the
 |	ADDRESS_PIN_LEFT_OFFSET definition section at the beginning of this file to correct this
 |	problem.
 |
 |	See Note 1 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_ProgramReadConfigReg (
	const flash_info * 	info,
	uint16 				rcr
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_ProgramEnhancedConfigReg
 |
 | Description:
 |
 | 	Issuing this command programs the device's 'Enhanced Configuration Register' with the
 |	provided data. Please see the datasheet for the ECR's responsibility.
 |
 |	Use TMPL_ReadDeviceInfo() with TMPL_dioEnhancedCfgReg as an offest to access the ECR
 |	initially if masking is desired.
 |
 | Parameters:
 |
 | 	IN	info		Flash device to access, and potential status information returned.
 |	IN	ecr			The value of the ECR to be written. Use ReadDeviceInfo() with
 |					TMPL_dioEnhancedCfgReg as an offset to read the ECR first. Bit masks
 |					are defined as ECR_* in this file.
 |
 | Returns:
 |
 |	Nothing
 |
 | Precondition:
 |
 |	ArrayState: 	Any
 |					(partition 0)
 |	ECR:			Any
 |
 | Postcondition:
 |
 |	ArrayState: 	Read Array
 |					(partition 0)
 |	ECR:			Takes the value of the parameter 'ecr'
 |
 | Notes:
 |
 |	Section 9.3 of the datasheet mentions that some hardware configurations will leave one
 |	or more of the lowest-order address pins disconnected. Since the ECR value is passed in
 |	on the address lines, this word must be offset to be interpreted correctly. Use the
 |	ADDRESS_PIN_LEFT_OFFSET definition section at the beginning of this file to correct this
 |	problem.
 |
 |	See Note 1 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_ProgramEnhancedConfigReg (
	const flash_info * 	info,
	uint16	 			ecr
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_ReadWords
 |
 | Description:
 |
 | 	Reads 'wordCount' sequential words from the device starting at address 'addr.' Flash
 |	data is recorded in the output buffer given as 'outBuff.' The array state of the
 |	addressed partition(s) should be set before calling this method.
 |
 |	This method also supports reading data programmed in Control mode when
 |	'inControlMode' != 0.
 |
 | Parameters:
 |
 | 	IN	info			Flash device base address.
 |	IN	addr			Main array address to begin sequential read.
 |	IN	wordCount		Number of data words to read (wordCount > 0).
 |	IN	inControlMode	Will skip all addresses with addr3=1:
 |						FALSE (0):	'wordCount' sequential data words will be read starting
 |									with word at 'addr'
 |						TRUE (!0):	'wordCount' data words will be read starting with word
 |									at 'addr' but skipping all addresses with addr3=1. Should
 |									only be used in Read Array mode when desired block is
 |									programmed in Control mode.
 |	OUT	outBuff			Available buffer space to record flash device output.
 |						(outBuff.length >= wordCount)
 |
 | Returns:
 |
 |	None
 |
 | Precondition:
 |
 |	ArrayState: 		(As Desired)
 |						(partition at 'addr')
 |
 | Postcondition:
 |
 |	ArrayState: 		Unchanged
 |						(partition at 'addr')
 |	outBuff:			outBuff[0] to outBuff[wordCount-1] will contain data read from
 |						the device.
 |
 | Notes:
 |
 |	To read a single word, use the low-level 'TMPL_ReadWord()' function from target.h.
 |
 |	See Note 1 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_ReadWords (
	flash_info * 	info,
	uint32			addr,
	uint32			wordCount,
	uint8			inControlMode,
	uint16 * 		outBuff
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_SingleWordProgram
 |
 | Description:
 |
 | 	Initiates programming of a single word to the flash array at the address specified.
 |
 | Parameters:
 |
 | 	IN	info		Flash device base address
 |	IN	addr		Address within main array, bit 3 of address must be zero (addr3=0)
 |	IN	data		Word to be written to address (upon prog. complete; array[addr] = data)
 |
 | Returns:
 |
 |	Nothing
 |
 | Precondition:
 |
 |	ArrayState: 	Any
 |					(partition at 'addr')
 |	Array[addr]: 	Block unlocked and either erased or in Control mode.
 |	Device:			No active operations, no suspended programs.
 |	SR:				Cleared of all errors.
 |
 | Postcondition:
 |
 |	ArrayState: 	Read Status Register
 |					(partition at 'addr')
 |	Array:			'data' is being programmed to 'addr' but not necessarily complete.
 |
 | Notes:
 |
 |	Use isProgramComplete() to monitor programming operation after issuing this command.
 |
 |	See Note 1 in header of template.h.
 |
 | Warning
 |
 |	This operation is only available to blocks operating in Control Mode. See datasheet for
 |	details.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_SingleWordProgram (
	flash_info *	info,
	uint32			addr,
	uint16			data
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_BufferedProgram
 |
 | Description:
 |
 | 	Issues the Buffered Program command which programs a group of words to the flash
 |	array. While in object mode, Buffered programming operations can only be performed
 |	once between erases. While in control mode, programmed address are sequential but
 |	skip all addresses with addr3=1.
 |
 |	The micro-code latches only the lower bits of the address long word. Beginning with
 |  a non-aligned buffer address may cause writing beyond the buffer size. This will
 |  not break the code, instead, the writes will effectively 'wrap' within the writable
 |  block.
 |
 | Parameters:
 |
 | 	IN	info			Flash device base address.
 |	IN	addr			Starting address of program...
 |						- Object Mode: Must* be aligned to 512-word buffer boundary
 |						  (addr[0:8]=0) (NOTE: alignement is optional, but warned against.)
 |						- Control Mode: Must be within A-half of region (addr[3]=0)
 |	IN	wordBuffer		Array of words to be programmed (length >= wordCount)
 |	IN	wordCount		The number of words, from wordBuffer, to be programmed
 |						(1 <= wordCount <= BUFFER_SIZE_WORDS)
 |	IN	inControlMode 	Signifies how the addresses should be incremented when writing
 |						to the Buffer:
 |						FALSE(0):	Object Mode, written addresses should increment
 |									linearly from addr.
 |						TRUE(!0):	Control Mode, written addresses should skip addr3=1
 |						  			(addr = (0000 0000 0000 x000)b where 'x'==0 always)
 |
 | Returns:
 |
 |	Nothing
 |
 | Precondition:
 |
 |	ArrayState: 		Any
 |						(partition at 'addr')
 |	Array[addr]: 		Block unlocked, see addr parameter description.
 |	Device:				No active operations, no suspended programs.
 |	SR:					Cleared of all errors.
 |
 | Postcondition:
 |
 |	ArrayState: 		Read Status Register
 |						(partition at 'addr')
 |	Array:				'wordBuffer[0:wordCount-1]' is being programmed to 'wordBuffer'
 |						or the SR has errors.
 |
 | Warning:
 |
 |	If in control mode, this function does not provide 'bit twiddling' ability. Instead of
 |	a buffer write having the effect of (*addr) = wordBuffer[i], this function performs as in
 |	the c-statement (*addr) &= wordBuffer[i]. Any pre-programmed data will be 'and-ed' with
 |	the new word.
 |
 | Notes:
 |
 |	Use isProgramComplete() to monitor programming operation after issuing this command.
 |	Also, this command cannot program more than BUFFER_SIZE_WORDS per execution.
 |
 |	See Note 1 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_BufferedProgram (
	flash_info * 	info,
	uint32			addr,
	const uint16 * 	wordBuffer,
	uint16			wordCount,
	uint8 			inControlMode
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_isProgramComplete
 |
 | Description:
 |
 | 	Returns Yes/No (1/0) to indicate that programming operation is complete by polling the
 |	device status register. SR is saved to info->lastSR, and the function will call
 |	TMPL_HandleError() if the SR shows errors. If the SR shows errors, the SR will be cleared
 |	of those errors before calling TMPL_HandleError(). See datasheet 9.7.2 for more information.
 |
 | Parameters:
 |
 | 	IN/OUT	info	IN: Flash device base address.
 |					OUT: lastSR and 'error' flag if necessary
 |
 | Returns:
 |
 |	0x00			If SR7=0 => Device busy
 |	0x01			If SR7=1 => Operation complete (possibly also operation had errors)
 |
 | Precondition:
 |
 |	ArrayState: 	Read Status Register
 |					(partition at 'TMPL_DEF_PARTITION_ADDR')
 |
 | Postcondition:
 |
 |	ArrayState: 	No Change
 |					(partition at 'TMPL_DEF_PARTITION_ADDR')
 |	info->lastSR:	Most recent device SR value
 |	Errors:			Will set info->error and call TMPL_HandleError() if SR has errors when SR7=1
 |	SR:				Left as-is after operation. 'TMPL_HandleError()' may alter SR state.
 |
 | Notes:
 |
 |	See Note 1,4 in header of template.h.
 |
 | Warning:
 |
 |	This function returns IMMEDIATELY. If the intention is to block until Programming
 |	or Erase is complete, then place this function in a while loop.
 |
 *-----------------------------------------------------------------------------------------*/
uint8 TMPL_isProgramComplete (
	flash_info * 	info
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_BEFProgram
 |
 | Description:
 |
 |	Buffered Enhanced Factory Program can be used for fast sequential data programming over
 |	an entire block. Special environmental conditions are required to run a BEFP, please
 |	see datasheet for those parameters. The methods TMPL_PreBEFP() and TMPL_PostBEFP()
 |	are called internally & respectively before & after the BEFP algorithm. These are
 |	available hooks to add any state setup / teardown code.
 |
 |	BEFP can be used for both Object and Control mode date regions. While in Control mode,
 |	data is written to sequential addresses starting from 'addr' but skips addresses with
 |	addr3=1.
 |
 |	This method blocks until operation is complete, and gives the option of a
 |	final verification stage in which input data is cross-referenced with programmed data.
 |
 | Parameters:
 |
 | 	IN/OUT	info		Flash device to access, and potential status information returned
 |	IN		addr		Starting address of program, must be buffer-size aligned
 |	IN		wordBuffer	Array of words to be programmed (length >= wordCount)
 |	IN		wordCount	The number of words, from wordBuffer, to be programmed starting
 |						at address 'addr,' (1 <= wordCount <= 512)
 |	IN	inControlMode 	Signifies how the addresses should be incremented when writing
 |						to the Buffer:
 |						FALSE(0):	Object Mode, written addresses should increment
 |									linearly from addr.
 |						TRUE(!0):	Control Mode, written addresses should skip addr3=1
 |						  			(addr = (0000 0000 0000 x000)b where 'x'==0 always)
 |	IN	verifyWrite 	Requests that this method perform an extra verfication step in
 |						which all data is read back and compared against original input
 |						buffer.
 |						FALSE(0):	No extra verification step is performed.
 |						TRUE(!0):	Perform verification.
 |
 | Returns:
 |
 |	0x00				No errors, operation successful
 |	0xAA				Operation Failed: Runtime Safety Checks
 |	0xBB 				Operation Failed: TMPL_PreBEFP() returned in error
 |	0xCC				Operation Failed: SR showed errors mid-way through programming
 |	0xDD				Operation Failed: SR showed errors after Exit Phase
 |	0xEE				Operation Failed: Data verification failed (optional)
 |
 | Precondition:
 |
 |	ArrayState: 		Any
 |						(partition at 'addr')
 |	Environment: 		'BEFP Requirements and Considerations' as specified in datasheet
 |						table 33 are met. See 'TMPL_PreBEFP()' as well.
 |
 | Postcondition:
 |
 |	ArrayState: 		Read Array Mode
 |						(partition at 'addr')
 |	info->lastSR: 		Most recent device SR value
 |	Errors:				Will set info->error and call TMPL_HandleError() if SR has errors when SR7=1
 |	SR:					Left as-is after operation. 'TMPL_HandleError()' may alter SR state.
 |	addr[]				Programmed with data on no Errors, indeterminant on failure.
 |
 | Warning:
 |
 |  The implementation of this method has not been rigerously tested, and should be used
 |  as a starting point for development of a BEFP algorithm.
 |
 | Notes:
 |
 |	See Note 1 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
uint8 TMPL_BEFProgram (
	flash_info * 	info,
	uint32			addr,
	const uint16 * 	wordBuffer,
	uint16			wordCount,
	uint8 			inControlMode,
	uint8			verifyWrite
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_PreBEFP
 |
 | Description:
 |
 | 	Empty method allows hardware-specific setup/init for BEFP operation.
 |
 | Parameters:
 |
 | 	None
 |
 | Returns:
 |
 |	0x00			If Pre-BEFP	setup operation completed successfully and the BEFP
 |					operation should be initiated.
 |	Other			Indicates an error in Pre-BEFP setup and prevents BEFP operation
 |					from running.
 |
 | Precondition:
 |
 |	ArrayState: 	(Same as TMPL_BEFProgram())
 |
 | Postcondition:
 |
 |	Environment:	On 0x0 return, 'BEFP Requirements and Considerations' for target
 |					hardware from datasheet must be met.
 |
 *-----------------------------------------------------------------------------------------*/
uint8 TMPL_PreBEFP (
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_PostBEFP
 |
 | Description:
 |
 | 	Empty method allows hardware-specific teardown after BEFP operation.
 |
 | Parameters:
 |
 | 	None
 |
 | Returns:
 |
 |	None
 |
 | Precondition:
 |
 |	ArrayState: 	Read Array Mode
 |
 | Postcondition:
 |
 |	ArrayState:		Read Array Mode
 |	Environment:	Any 'BEFP Requirements and Considerations' that are set from
 |					TMPL_PreBEFP() are reversed and Flash is in a normal state.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_PostBEFP (
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_EFAWordProgram
 |
 | Description:
 |
 | 	Initiates programming of a single word of data to the specified address within EFA space.
 |
 | Parameters:
 |
 | 	IN	info		Flash device base address.
 |	IN	addr		EFA address to be programmed, as referenced from device baseAddress.
 |					EFA space within a particular partition can be accessed by setting
 |					addr = 'partition base address' + 'EFA relative address'.
 |	IN 	data		Word to be programmed at addr.
 |
 | Returns:
 |
 |	Nothing
 |
 | Precondition:
 |
 |	ArrayState: 	Any
 |					(partition at 'addr')
 |
 | Postcondition:
 |
 |	ArrayState: 	Read Status Register, EFA plane in foreground
 |					(partition at 'addr')
 |	EFA Array:		'EFA Array[addr]' is being programmed to 'data' or the SR has errors.
 |
 | Notes:
 |
 |	See Note 1 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_EFAWordProgram (
	flash_info * 	info,
	uint32			addr,
	uint16			data
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_BlockErase
 |
 | Description:
 |
 | 	Initiates a block erase (0s to 1s) operation on the block specified by 'blockAddr.'
 |	May be used to erase EFA blocks or main array blocks. A block must be unlocked to be
 |	erased.
 |
 | Parameters:
 |
 | 	IN	info		Flash device to access
 |	IN	blockAddr	Address within block to be erased
 |	IN	onEFABlock	Specifies which plane (main array or EFA) to erase
 |					FALSE (0): Address refers to an EFA block.
 |					TRUE (!0): Address refers to a block in the main array.
 | Returns:
 |
 |	Nothing
 |
 | Precondition:
 |
 |	ArrayState: 	Any
 |					(partition at 'blockAddr')
 |	Device:			No active operations, no suspended Erase operations.
 |
 | Postcondition:
 |
 |	ArrayState: 	Read Status Register
 |					EFA or Main Array plane in foreground depending on 'onEFABlock'
 |					(partition at 'blockAddr')
 |	Device: 		Block erase operation is underway or SR has errors.
 |
 | Notes:
 |
 |	See Note 1 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_BlockErase (
	const flash_info * 	info,
	uint32				blockAddr,
	uint8				onEFABlock
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_BlankCheck
 |
 | Description:
 |
 | 	A blocking method which validates that an entire block is erased (all 1s). This
 |	operation is not necessary to confirm a blockErase() command. May not be used on EFA
 |	blocks, and may not be suspended nor resumed.
 |
 |	Use TMPL_isProgrammingComplete() to monitor operation.
 |
 | Parameters:
 |
 | 	IN/OUT	info		Flash device to access, and status register returned.
 |	IN		blockAddr	Address withing block on which Blank check will be performed.
 |
 | Returns:
 |
 |	0x00				Operation Successful; Block is blank (all 1s)
 |	!0x0				Operation Failed; Block is not completely erased.
 |
 | Precondition:
 |
 |	ArrayState: 		Any
 |						(partition at 'blockAddr')
 |	Device:				No active or suspended program or erase operations.
 |	SR:					Clear of error flags & device ready.
 |
 | Postcondition:
 |
 |	ArrayState: 		Read Array Mode
 |						(partition at 'blockAddr')
 |	info->lastSR:		Status Register Value upon completion of the operation (incl. errors)
 |	SR:					Cleared of errors
 |	Errors:				TMPL_HandleError() called upon detection of error with
 |						info->error = TMPL_etBlankCheckFailure.
 |
 | Notes:
 |
 |	Should be used to speed manufacturing operations, and not to determine erase
 |	operation success/failure.
 |
 | Notes:
 |
 |	See Note 1 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
uint8 TMPL_BlankCheck (
	flash_info * 	info,
	uint32			blockAddr
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_IssueLockCommand
 |
 | Description:
 |
 | 	Issues a lock/unlock/lock-down command to the designated block, either EFA or main array.
 |	All security (besides WP# for lock-down) commands are issued via this method.
 |
 | Parameters:
 |
 | 	IN	info	 	Flash device base address.
 |	IN	blockAddr	Address within the requested block to be locked/unlocked/locked-down.
 |	IN	cmd			The specific security command to be issued from the LockCommand enum:
 |					TMPL_lcLockBlock:	 	Lock the specified block.
 |					TMPL_lcUnlockBlock:		Unlock the specified block.
 |					TMPL_lcLockDownBlock:	Lock-Down the specified block.
 |	IN	onEFABlock	Whether to issue this command to the EFA or main array plane:
 |					FALSE (0):	Issue to Main Array block
 |					TRUE (!0):	Issue to EFA block
 |
 | Returns:
 |
 |	Nothing
 |
 | Precondition:
 |
 |	ArrayState: 	Any
 |					(partition at 'blockAddr')
 |	Device:			No suspended programming operations (suspended erase operations allowed)
 |
 | Postcondition:
 |
 |	ArrayState: 	Read Status Register
 |					(partition at 'blockAddr')
 |	Device:			Lock command operation in progress, check SR for errors
 |
 | Notes:
 |
 |	Block lock-down protection is dependant on WP#. See datasheet for more information.
 |
 | Notes:
 |
 |	See Note 1 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_IssueLockCommand (
	const flash_info * 	info,
	uint32				blockAddr,
	LockCommand			cmd,
	uint8				onEFABlock
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_ProgramOTPRegister
 |
 | Description:
 |
 | 	Initiates programming 'data' to 'OTPAddr' within OTP address space.
 |
 |	OTP blocks can be locked, and this operation is performed by writing to the OTP Lock
 |	registers using this method as well. Please see datasheet for the 'OTPAddr' of the
 |	available OTP lock registers. The command will place the partition referenced by
 |	'OPTAddr' into RSR mode.
 |
 | Parameters:
 |
 | 	IN	info		Flash device information.
 |	IN	OTPAddr		OTP address to be programmed. OTP can be programmed from any partition;
 |					this requires that the OTP offset (address in the OTP space) be added
 |					to the desired partition's base address when passed.
 |	IN 	data		Word to be programmed at OTPAddr.
 |
 | Returns:
 |
 |	Nothing
 |
 | Precondition:
 |
 |	ArrayState: 	Any
 |					(partition at 'OTPAddr')
 |
 | Postcondition:
 |
 |	ArrayState: 	Read Status Register
 |					(partition at 'OTPAddr')
 |	Device:			OTP Word program in operation or SR has errors
 |
 | Notes:
 |
 |	See Notes 1 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_ProgramOTPRegister (
	flash_info * 	info,
	uint32			OTPAddr,
	uint16			data
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_Suspend
 |
 | Description:
 |
 | 	Issues the suspend command to the device which will potentially suspend the active
 |	program or erase operation. Please see datasheet for tSUSP delay and its effect on
 |	whether or not an active operation is actually suspended.
 |
 |	Also, many device states exist in which suspending operations is not allowed. Please
 |	again see datasheet for Suspend/Resume behaviour, and valid commands during suspend.
 |
 | Parameters:
 |
 | 	IN	info		Flash device base address.
 |
 | Returns:
 |
 |	Nothing
 |
 | Precondition:
 |
 |	ArrayState:		Any
 |					(partition at 'TMPL_DEF_PARTITION_ADDR')
 |	Device:			An active operation to be suspended is in progress.
 |
 | Postcondition:
 |
 |	ArrayState:		Unchanged
 |					(partition at 'TMPL_DEF_PARTITION_ADDR')
 |	Device:			Either operation will be suspended or completed. Monitor SR to determine.
 |	SR:				Error bits raised, SR[7,6]=1 or SR[7,2]=1 (success), or operation
 |					completed and SR[7]=1.
 |
 | Warning:
 |
 |	Please see datasheet for allowed device states, valid commands during suspend
 |	datasheet (Table 37), and information on simultaneous operations (Table 38).
 |
 | Notes:
 |
 |	The M18 device supports suspending an erase to do a program, but not vice versa. And
 |	can only suspend a program to perform a read.
 |
 |	See Note 4 from this header file.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_Suspend (
	const flash_info * 	info
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_isEraseSuspended
 |
 | Description:
 |
 | 	Macro will return Yes (!0) if an erase is suspended or Unknown (0) if either an erase is
 |	not suspended or status isn't ready.
 |
 | Parameters:
 |
 | 	IN	info		Flash device base address.
 |
 | Returns:
 |
 |	0x00			Device busy or No: SR7=0 or SR6=0
 |	!0x0			Yes: SR[7,6]=1
 |
 | Warning:
 |
 |	Since 0x00 can be returned when SR7=0, this should be used in conjunction with other SR
 |	checks.
 |
 *-----------------------------------------------------------------------------------------*/
#define TMPL_isEraseSuspended(info)		((TMPL_ReadStatReg(info) & 0x00C0) == 0x00C0)


/*-----------------------------------------------------------------------------------------*
 | TMPL_isProgramSuspended
 |
 | Description:
 |
 | 	Macro will return Yes (!0) if a program is suspended or Unknown (0) if either a program
 |	is not suspended or status isn't ready.
 |
 | Parameters:
 |
 | 	IN	info		Flash device base address.
 |
 | Returns:
 |
 |	0x00			Device busy or No: SR7=0 or SR2=0
 |	!0x0			Yes: SR[7,2]=1
 |
 | Warning:
 |
 |	Since 0x00 can be returned when SR7=0, this should be used in conjunction with other SR
 |	checks.
 |
 *-----------------------------------------------------------------------------------------*/
#define TMPL_isProgramSuspended(info)	((TMPL_ReadStatReg(info) & 0x0084) == 0x0084)


/*-----------------------------------------------------------------------------------------*
 | TMPL_areBothSuspended
 |
 | Description:
 |
 | 	Macro will return Yes (!0) if both an erase and program operation are both suspended
 |	simultaneously or Unknown (0) if either SR7=0 (not ready) or suspend flags aren't raised.
 |
 | Parameters:
 |
 | 	IN	info		Flash device base address.
 |
 | Returns:
 |
 |	0x00			Device busy or No: SR7=0 or SR6=0 or SR2=0
 |	!0x0			Yes: SR[7,6,2]=1
 |
 | Warning:
 |
 |	Since 0x00 can be returned when SR7=0, this should be used in conjunction with other SR
 |	checks.
 |
 *-----------------------------------------------------------------------------------------*/
#define TMPL_areBothSuspended(info)		((TMPL_ReadStatReg(info) & 0x00C4) == 0x00C4)


/*-----------------------------------------------------------------------------------------*
 | TMPL_Resume
 |
 | Description:
 |
 | 	Issues the resume command which will restart a suspended program or erase operation.
 |
 | Parameters:
 |
 | 	IN	info		Flash device base address.
 |
 | Returns:
 |
 |	Nothing
 |
 | Precondition:
 |
 |	ArrayState:		Any
 |					(partition at 'TMPL_DEF_PARTITION_ADDR')
 |	Device:			Either one or both of a Program or Erase operations are suspended.
 |	SR:				SR[7,6]=1 or SR[7,2]=1 or SR[7,6,2]=1
 |
 | Postcondition:
 |
 |	ArrayState:		Unchanged
 |					(partition at 'TMPL_DEF_PARTITION_ADDR')
 |	Effect:			When the Resume command is issued during a simultaneous erase-
 |					suspend/program-suspend condition, the programming operation is
 |					resumed first.
 |	SR:				Respective 'Operation Suspended' bit of SR is cleared.
 |
 | Warning:
 |
 |	To avoid masking errors in previous operations, should clear SR before
 |	resuming - See 'Note' following Table 22 on datasheet.
 |
 |	See Note 4 from this header file.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_Resume (
	const flash_info * 	info
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_DeepPowerDown
 |
 | Description:
 |
 | 	Writes ECR15=1 to place the device in DPD mode. See datasheet for details.
 |
 | Parameters:
 |
 | 	IN info			Flash device information.
 |
 | Returns:
 |
 |	Nothing
 |
 | Precondition:
 |
 |	ArrayState: 	Any
 |					(partition at 'TMPL_DEF_PARTITION_ADDR')
 |	Device: 		No operations in progress and the device is ready to enter DPD mode
 |					(see datasheet for more information).
 |
 | Postcondition:
 |
 |	ArrayState: 	Read Array Mode
 |					(partition at 'TMPL_DEF_PARTITION_ADDR')
 |	ECR:			ECR15=1, other bits unchanged.
 |
 | Notes:
 |
 |	See Note 1,4 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_DeepPowerDown (
	const flash_info * 	info
);


/*-----------------------------------------------------------------------------------------*
 | TMPL_ReleaseFromDeepPowerDown
 |
 | Description:
 |
 | 	Writes ECR15=0 to return the device to DPD Disabled mode (normal). See datasheet for
 |	details.
 |
 | Parameters:
 |
 | 	IN info			Flash device information.
 |
 | Returns:
 |
 |	Nothing
 |
 | Precondition:
 |
 |	ArrayState: 	Any
 |					(partition at 'TMPL_DEF_PARTITION_ADDR')
 |
 | Postcondition:
 |
 |	ArrayState: 	Read Array Mode
 |					(partition at 'TMPL_DEF_PARTITION_ADDR')
 |	ECR:			ECR15=0, other bits unchanged.
 |
 | Notes:
 |
 |	See Note 1,4 in header of template.h.
 |
 *-----------------------------------------------------------------------------------------*/
void TMPL_ReleaseFromDeepPowerDown (
	const flash_info * 	info
);


#endif /*TEMPLATE_H_*/