/*************************************************************************
 *** Intel Confidential                                      
 *** Copyright (C) Intel Corporation 2000                 
 *** All Rights Reserved.                                    
 *** --------------------------------------------------------------------
 ***
 *** Project Name: Flash Templates
 ***
 *** Module Name: Template
 ***
 *** File: Template.H - Common template C header
 ***
 *** File Revision: $Revision: 10 $, $JustDate:  4/21/00 $, $Author: Tchuynh $
 ***
 *** Purpose:
 ***
 ***    The purpose of this file is to define the common application 
 ***    programmers interface for Flash template software.  This module
 ***    defines all flash template subroutines and common definitions.
 ***
 *** $NoKeywords: $
 *************************************************************************/

#ifndef __TEMPLATE_H  /* ensure this file only gets included once */
#define __TEMPLATE_H

#ifndef TRUE
#define TRUE (1 == 1)
#endif /* TRUE */

#ifndef FALSE
#define FALSE (1 == 0)
#endif /* FALSE */

/****************************************************************************
*
* Standard Data Types:
*
* Be certain to modify the root data types (e.g. char, short, long, etc.)
* in the TYPEDEFs below to produce a new data type on the target system of
* of the size and sign indicated by the comments that follow each TYPEDEF.
*
* Note that if support for 64-bit integer data types has been disabled
* (by setting the TYPEDEFS_64BIT_ENABLED compile option above to FALSE),
* the root types for the SINT64 and UINT64 types do not need to be
* modified, as they will not be included during compilation.
*
****************************************************************************/

/*
 * If any of the integral types below : UINT8, UINT16, UINT32
 * UINT8_PTR, UINT16_PTR, UINT32_PTR have already
 * been defined elsewhere, the conflicts must be manually
 * resolved to ensure the existing definitions produce
 * data types of the proper size and sign.  Note that
 * this check may not work under all compilers.
 */

/* integral data types */
#if ( !defined(UINT8) ) 
   typedef unsigned char  UINT8; /* 8-bit  unsigned integer */
#endif

#if ( !defined(UINT16) )
   typedef unsigned short UINT16; /* 16-bit unsigned integer */
#endif

#if ( !defined(UINT32) )
   typedef unsigned long  UINT32; /* 32-bit unsigned integer */
#endif

/* integral pointer types */
#if ( !defined(UINT8_PTR) )
   typedef UINT8 * UINT8_PTR;   /* pointer to 8-bit unsigned integer */
#endif

#if ( !defined(UINT16_PTR) )
   typedef UINT16 * UINT16_PTR; /* pointer to 16-bit unsigned integer */
#endif

#if ( !defined(UINT32_PTR) )
   typedef UINT32 * UINT32_PTR; /* pointer to 32-bit unsigned integer */
#endif

/* Include Files */

#include "device.h" /* include device specific header */

/* Status Macros */

#define mIsBlockLocked(A) ( ( A & TMPL_BLOCK_LOCKED ) == TMPL_BLOCK_LOCKED )
#define mIsProgramSuspended(A) ( ( A & TMPL_PROGRAM_SUSPENDED ) == TMPL_PROGRAM_SUSPENDED )
#define mIsVppLow(A) ( ( A & TMPL_VPP_LOW ) == TMPL_VPP_LOW )
#define mIsProgramError(A) ( ( A & TMPL_PROGRAM_ERROR ) == TMPL_PROGRAM_ERROR )
#define mIsEraseError(A) ( ( A & TMPL_ERASE_ERROR ) == TMPL_ERASE_ERROR )
#define mIsEraseSuspended(A) ( ( A & TMPL_ERASE_SUSPENDED ) == TMPL_ERASE_SUSPENDED )
#define mIsStatusReady(A) ( ( A & TMPL_STATUS_READY ) == TMPL_STATUS_READY )

#define mIsBlockstatLocked(A) ( ( A & TMPL_BLOCKSTAT_LOCKED ) == TMPL_BLOCKSTAT_LOCKED )
#define mIsBlockstatUnlocked(A) ( A == TMPL_BLOCKSTAT_UNLOCKED )
#define mIsBlockstatLockedDown(A) ( ( A & TMPL_BLOCKSTAT_LOCKEDDOWN ) == TMPL_BLOCKSTAT_LOCKEDDOWN )


/* mask macros used for programming/reading single bytes */
#if X_16

   #if BIG_ENDIAN_ARCHITECTURE

      #define mGetHighMemoryByte(a) (UINT8)(a & 0x00ff)
      #define mGetLowMemoryByte(a)  (UINT8)((a & 0xff00) >> 8)

   #else /* little endian */

      #define mGetLowMemoryByte(a)  (UINT8)(a & 0x00ff)
      #define mGetHighMemoryByte(a) (UINT8)((a & 0xff00) >> 8)

   #endif /* BIG_ENDIAN_ARCHITECTURE */

#endif /* X_16 */

/* type definitions */

/* status return values */
enum TMPL_CommandStat { StatCompleted,  /* the function completed */
                        StatTimeout,    /* access to the device timed out */
                        StatBadBlock,   /* block # not valid for this device */
                        StatBadAddress, /* address not valid for this device */
                        StatBadOtp,     /* otp loc not valid for this device */
                        StatUnsupported /* this function is not supported */
                  };


typedef struct TMPL_QueryData {
   char   QueryStr[4];           /* 3 bytes + null */
   UINT16 VendorId;              /* 2 bytes */
   UINT16 ExtTablePtr;           /* 2 bytes */
   UINT16 AltVendorId;           /* 2 bytes */
   UINT16 SecExtTablePtr;        /* 2 bytes */
   UINT8  VccMin;	    	     /* 1 byte */
   UINT8  VccMax;	    	     /* 1 byte */
   UINT8  VppMin;                /* 1 byte */
   UINT8  VppMax;                /* 1 byte */
   UINT8  TypicalProgTimeout;    /* 1 byte */
   UINT8  TypicalBufferTimeout;  /* 1 byte */
   UINT8  BlockEraseTimeout;     /* 1 byte */
   UINT8  ChipEraseTimeout;      /* 1 byte */
   UINT8  MaxSingleTimeout;      /* 1 byte */
   UINT8  MaxBufferTimeout;      /* 1 byte */
   UINT8  MaxBlockEraseTimeout;  /* 1 byte */
   UINT8  MaxChipEraseTimeout;   /* 1 byte */
   UINT8  DeviceSize;            /* 1 byte */
   UINT16 DeviceInterface;       /* 2 bytes */
   UINT16 MaxWriteBufferBytes;   /* 2 bytes */
   UINT8  NumEraseBlocks;        /* 1 byte */
   UINT32 EraseBlockInformation; /* 4 bytes */
}TMPL_query;

#if !DEVICE_EXTENDED_QUERY
/* flash query structure */
typedef struct TMPL_ExtQueryData {
   char           Blank;
}TMPL_extquery;
#endif


#if !DEVICE_SEC_EXTENDED_QUERY
/* flash query structure */
typedef struct TMPL_SecExtQueryData {
   char           Blank;
}TMPL_secextquery;
#endif

#define TMPL_QUERY_START_OFFSET 0x10

/* x8 flash command definitions */
#if X_8

   #define TMPL_PROGRAM_SETUP         0x40
   #define TMPL_BASE_FLASH_ADDRESS    0x00
   #define TMPL_READ_STATUS_REGISTER  0x70
   #define TMPL_CLEAR_STATUS_REGISTER 0x50
   #define TMPL_READ_ID_CODES         0x90
   #define TMPL_READ_QUERY            0x98
   #define TMPL_BLOCK_ERASE           0x20
   #define TMPL_CONFIRM               0xD0
   #define TMPL_READ_ARRAY            0xff
   #define TMPL_CONFIG_SETUP          0x60  

   /* Status Register Values */
   #define TMPL_BLOCK_LOCKED         0x02
   #define TMPL_PROGRAM_SUSPENDED    0x04
   #define TMPL_VPP_LOW              0x08
   #define TMPL_PROGRAM_ERROR        0x10
   #define TMPL_ERASE_ERROR          0x20
   #define TMPL_ERASE_SUSPENDED      0x40
   #define TMPL_STATUS_READY         0x80

   typedef UINT8 TMPL_FDATA; /* flash data item */

#endif /* X_8 */


/* x16 flash command definitions */
#if X_16

   #define TMPL_PROGRAM_SETUP         0x0040
   #define TMPL_BASE_FLASH_ADDRESS    0x0000
   #define TMPL_READ_STATUS_REGISTER  0x0070
   #define TMPL_CLEAR_STATUS_REGISTER 0x0050
   #define TMPL_READ_ID_CODES         0x0090
   #define TMPL_READ_QUERY            0x0098
   #define TMPL_BLOCK_ERASE           0x0020
   #define TMPL_CONFIRM               0x00D0
   #define TMPL_READ_ARRAY            0x00ff
   #define TMPL_CONFIG_SETUP          0x0060

   /* Status Register Values */
   #define TMPL_BLOCK_LOCKED         0x0002
   #define TMPL_PROGRAM_SUSPENDED    0x0004
   #define TMPL_VPP_LOW              0x0008
   #define TMPL_PROGRAM_ERROR        0x0010
   #define TMPL_ERASE_ERROR          0x0020
   #define TMPL_ERASE_SUSPENDED      0x0040
   #define TMPL_STATUS_READY         0x0080

   typedef UINT16 TMPL_FDATA; /* flash data item */

#endif /* X_16 */


typedef TMPL_FDATA * volatile TMPL_FDATA_PTR; 

/* status structure */
typedef struct TMPL_stat {
   enum TMPL_CommandStat Result;  /* subroutine status */
   volatile TMPL_FDATA   SR;      /* Flash status register value */
}TMPL_Status;


/*
 *  Flash template function declarations
 */

/****************************************************************************
 *
 * TMPL_ClearStatus
 *
 * Description:   
 *    This procedure is called to clear the status register on the flash
 *    device.  See the flash device datasheet for specific details on 
 *    this command.
 *
 * Parameters:
 *    NONE
 *
 * Returns:   
 *    NONE
 *
 * Assumptions:
 *    NONE
 *
 ***************************************************************************/
void TMPL_ClearStatus ( void );


/****************************************************************************
 *
 * TMPL_EraseBlock
 *
 * Description:   
 *
 *    This procedure is called to erase a data block on the flash 
 *    device.  See the flash device datasheet for specific details on
 *    this command.
 *
 * Parameters:
 *
 *    IN      blocknum - the block number on the device.
 *
 *    IN      returnSR - flag to indicate whether the device status register
 *                       value should be returned by this function.
 *
 * Returns:   
 *
 *    TMPL_Status - includes function return status defined by enum 
 *                  TMPL_CommandStat and optionally the flash device
 *                  status register value.
 *
 * Assumptions:
 *
 *    NONE
 *
 ***************************************************************************/
TMPL_Status TMPL_EraseBlock ( UINT16 blocknum, 
                              UINT8  returnSR );


/****************************************************************************
 *
 * TMPL_EraseAllBlocks
 *
 * Description:   
 *
 *    This procedure is called to erase all data blocks on the flash 
 *    device.  See the flash device datasheet for specific details on
 *    the block erase command.
 *
 * Parameters:
 *
 *    IN      returnSR - flag to indicate whether the device status register
 *                       value should be returned by this function.
 *
 * Returns:   
 *
 *    TMPL_Status - includes function return status defined by enum 
 *                  TMPL_CommandStat and optionally the flash device status
 *                  register value.
 *
 * Assumptions:
 *
 *    NONE
 *
 ***************************************************************************/
TMPL_Status TMPL_EraseAllBlocks ( UINT8 returnSR );


/****************************************************************************
 *
 * TMPL_EraseSuspend
 *
 * Description:   
 *
 *    This procedure is called to issue the erase suspend command to
 *    the flash device.  See the flash device datasheet for specific details 
 *    on this command.
 *
 * Parameters:
 *
 *    IN      blocknum - the block number on the device.
 *
 *    IN      returnSR - flag to indicate whether the device status register
 *                       value should be returned by this function.
 *
 * Returns:   
 *
 *    TMPL_Status - includes function return status defined by enum
 *                  TMPL_CommandStat and optionally the flash device
 *                  status register value.
 *
 * Assumptions:
 *
 *    When this function is called the device is currently in the erase 
 *    mode for the block identified.
 *
 ***************************************************************************/
TMPL_Status TMPL_EraseSuspend ( UINT16 blocknum,
                                UINT8  returnSR );


/****************************************************************************
 *
 * TMPL_ExtendedQuery
 *
 * Description:   
 *
 *    This procedure is called to retrieve the extended query
 *    data from the flash device.  See the flash device datasheet for
 *    specific details on this command.
 *
 * Parameters:
 *
 *    OUT      *extquery - pointer to extended query structure
 *
 * Returns:   
 *
 *    TMPL_Status - includes function return status defined by enum 
 *                  TMPL_CommandStat.
 *
 * Assumptions:
 *