/*************************************************************************
 *** 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: 8 $, $JustDate:  3/24/00 $, $Author: Kalowry $
 ***
 *** 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: $
 *************************************************************************/

/*
***************************************************************
* INTEL OEM SOFTWARE LICENSE AGREEMENT
* BETWEEN INTEL CORPORATION AND OEM/Licensee ("You")
*  (Rev 10/04/99)
*
* BY USING THIS SOFTWARE, YOU ("You" or "Licensee") ARE AGREEING 
* TO BE BOUND BY THE TERMS OF THIS AGREEMENT.  DO NOT USE THE 
* SOFTWARE UNTIL YOU HAVE CAREFULLY READ AND AGREED TO THE 
* FOLLOWING TERMS AND CONDITIONS.  IF YOU DO NOT AGREE TO THE 
* TERMS OF THIS AGREEMENT, PROMPTLY RETURN THE SOFTWARE AND ANY 
* ACCOMPANYING ITEMS. LICENSEE MUST BE AN ORIGINAL EQUIPMENT 
* MANUFACTURER ("OEM") SYSTEM DEVELOPER TO ACQUIRE ANY RIGHTS 
* IN THE SOFTWARE UNDER THIS LICENSE AGREEMENT.
*
* LICENSE: Intel Corporation ("Intel") grants the Licensee the 
* non-exclusive right to use the software program ("Software") 
* in source and / or object code form on the terms set forth 
* below.  Licensee will not use, copy, modify, rent, sell or 
* transfer the Software or any portion thereof, except as 
* provided in this Agreement.  
*
* USE RESTRICTION:
* THIS ROYALTY FREE LICENSE ALLOWS LICENSEE TO USE THE SOFTWARE 
* WITH INTEL FLASH PRODUCTS ONLY. USE OF THE SOFTWARE WITH ANY 
* OTHER FLASH PRODUCTS IS EXPRESSLY PROHIBITED UNLESS AND UNTIL 
* LICENSEE APPLIES FOR, AND IS GRANTED, IN INTEL'S SOLE DISCRETION.
* A SEPARATE WRITTEN SOFTWARE LICENSE AGREEMENT BETWEEN LICENSEE 
* AND INTEL IS NECESSARY BEFORE ANY SUCH USE.
*
* LICENSEE MAY:
* 1. Copy the Software for support, backup or archival purposes;
* 2. Install or distribute the Software in object code form only;
* 3. Install, use, modify, distribute, and/or make or have made 
* Derivatives based on the Software subject to the terms and 
* conditions in this Agreement;
* 4. Modify and/or use Software source code that Intel provides to
* the Licensee, provided that Licensee does not remove or modify 
* the "Compatibility" module, if any, in the Software or in any 
* Derivatives and subject to the other restrictions contained 
* herein;
* 5. Allow authorized contractors ("Subcontractors") engaged by 
* the Licensee for the sole purpose of product development work to
* have access to the Software solely for that purpose. 
* Subcontractors do NOT acquire any of the Licensee rights to the 
* Software provided in this Agreement.
*
* RESTRICTIONS:  
* LICENSEE IS NOT ALLOWED TO: 
* 1.  Copy, disclose or distribute the Software, in whole or in 
* part, except as provided for in this Agreement;
* 2.  Remove or modify the "Compatibility" module, if any, in 
* the Software or in any Derivatives;
* 3.  Decompile or reverse engineer any Software delivered in 
* object code form.
*
* LICENSEE MUST:
* Execute the "Compatibility" module if provided with the 
* Software.
*
* TRANSFER:  Except as provided above, Licensee may not 
* transfer or disclose the Software to any other party.
*
* OWNERSHIP AND COPYRIGHT OF SOFTWARE: Title to the Software 
* and all copies thereof remain with Intel.  The Software is 
* copyrighted and is protected by United States and 
* international copyright laws.  Licensee will not remove 
* the copyright notice from the Software.  Licensee agrees 
* to prevent the unauthorized copying of the Software.
*
* DERIVATIVES: "Derivatives" are any work that is based upon the 
* Software, such as a revision, modification, translation, or 
* compilation in which the Software is recast, transformed or 
* adapted; any adaptation, subset, addition, improvement or 
* combination of or including the Software; and any new material, 
* information or data derived from the Software, including new 
* material which may be protectable by copyright, patent or other
* proprietary rights.  Licensee is not required to provide Intel 
* with a copy of the source or object code for any Derivatives 
* created by Licensee. Licensee may use, market, sell, and/or 
* distribute Derivatives in object code form only at Licensee's own
* risk and expense.  Licensee may use, but may not market, sell or 
* distribute, source code for any Derivatives, subject to the Use 
* Restriction and other restrictions contained in this Agreement. 
* Title to Derivatives, other than the portion(s) of the 
* Derivatives consisting of any portion of the Software, shall 
* remain with Licensee.
*
* CONFIDENTIALITY: Licensee will maintain the confidentiality of 
* the source code for the Software with at least the same degree 
* of care that Licensee uses to protect Licensee's own confidential 
* and proprietary information, but with no less than a reasonable 
* degree under the circumstances. Disclosure of source code will 
* only be made to Licensee's employees on a need-to-know basis. 
* Subject to the licenses granted hereunder, Licensee shall 
* maintain the Software source code and all other proprietary 
* information relating to the Software in confidence and shall 
* not disclose to others any such source code or other Intel 
* proprietary information relating to the Software. Any 
* Subcontractors to whom Licensee discloses the source code for 
* the Software must sign a written confidentiality agreement 
* which contains terms regarding the Software no less restrictive 
* than those set forth in this Agreement.
*
* WARRANTY:  The Software is provided "AS IS". Intel warrants 
* that the media on which the Software is furnished will be free 
* from defects in material and workmanship for a period of one 
* year upon receipt. 
*
* THE ABOVE WARRANTIES ARE THE ONLY WARRANTIES OF ANY KIND GIVEN 
* BY INTEL UNDER THIS AGREEMENT. INTEL SPECIFICALLY DISCLAIMS ANY 
* OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF 
* MERCHANTABILITY, NONINFRINGEMENT OR FITNESS FOR ANY PARTICULAR 
* PURPOSE.
*
* LIMITATION OF LIABILITY: NEITHER INTEL NOR ITS VENDORS OR AGENTS 
* SHALL BE LIABLE FOR ANY LOSS OF PROFITS, LOSS OF USE, LOSS OF 
* DATA, INTERRUPTION OF BUSINESS, NOR FOR INDIRECT, SPECIAL, 
* INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND WHETHER UNDER 
* THIS AGREEMENT OR OTHERWISE, EVEN IF ADVISED OF THE POSSIBILITY 
* OF SUCH DAMAGES.
*
* TERMINATION OF THIS LICENSE: Intel reserves the right to conduct 
* or have conducted audits to verify Licensee's compliance with 
* this Agreement.  Intel may terminate this Agreement at any 
* time if Licensee is in breach of any of its terms and conditions.
* Upon termination, Licensee will immediately destroy, and certify 
* in writing the destruction of, the Software and return all copies 
* of the Software and documentation to Intel.
*
* U.S. GOVERNMENT RESTRICTED RIGHTS: The Software and documentation
* were developed at private expense and are provided with 
* "RESTRICTED RIGHTS".  Use, duplication or disclosure by the 
* Government is subject to restrictions as set forth in 
* FAR52.227-14 and DFAR252.227-7013 et seq. or its successor.
*
* EXPORT LAWS: The distribution and export/re-export of the 
* Software shall be in compliance with the laws, regulations, 
* orders or other restrictions of the U.S. Export Administration 
* Regulations.
*
* APPLICABLE LAW: This Agreement is governed by the laws of the 
* State of Delaware and the United States, including patent and
* copyright laws.  Any claim arising out of this Agreement will be 
* brought in Delaware.  
*
* Intel reserves the right to use and/or include Licensee's name
* in public relations activities and marketing material after the 
* product is publicly announced.
*****************************************************************
*/
/* Page Break  */

#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 */


/* Px16 flash command definitions */
#if PX_16

   #define TMPL_PROGRAM_SETUP         0x4040
   #define TMPL_BASE_FLASH_ADDRESS    0x0000
   #define TMPL_READ_STATUS_REGISTER  0x7070
   #define TMPL_CLEAR_STATUS_REGISTER 0x5050
   #define TMPL_READ_ID_CODES         0x9090
   #define TMPL_READ_QUERY            0x9898
   #define TMPL_BLOCK_ERASE           0x2020
   #define TMPL_CONFIRM               0xD0D0
   #define TMPL_READ_ARRAY            0xffff
   #define TMPL_CONFIG_SETUP          0x6060

   /* Status Register Values */
   #define TMPL_BLOCK_LOCKED         0x0202
   #define TMPL_PROGRAM_SUSPENDED    0x0404
   #define TMPL_VPP_LOW              0x0808
   #define TMPL_PROGRAM_ERROR        0x1010
   #define TMPL_ERASE_ERROR          0x2020
   #define TMPL_ERASE_SUSPENDED      0x4040
   #define TMPL_STATUS_READY         0x8080

   typedef UINT16 TMPL_FDATA; /* flash data item */

#endif /* PX_16 */


/* 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 */


/* x32 flash command definitions */
#if X_32

   #define TMPL_PROGRAM_SETUP         0x00400040
   #define TMPL_BASE_FLASH_ADDRESS    0x00000000
   #define TMPL_READ_STATUS_REGISTER  0x00700070
   #define TMPL_CLEAR_STATUS_REGISTER 0x00500050
   #define TMPL_READ_ID_CODES         0x00900090
   #define TMPL_READ_QUERY            0x00980098
   #define TMPL_BLOCK_ERASE           0x00200020
   #define TMPL_CONFIRM               0x00D000D0
   #define TMPL_READ_ARRAY            0x00ff00ff
   #define TMPL_CONFIG_SETUP          0x00600060

   /* Status Register Values */
   #define TMPL_BLOCK_LOCKED         0x00020002
   #define TMPL_PROGRAM_SUSPENDED    0x00040004
   #define TMPL_VPP_LOW              0x00080008
   #define TMPL_PROGRAM_ERROR        0x00100010
   #define TMPL_ERASE_ERROR          0x00200020
   #define TMPL_ERASE_SUSPENDED      0x00400040
   #define TMPL_STATUS_READY         0x00800080

   typedef UINT32 TMPL_FDATA; /* flash data item */

#endif /* X_32 */