/*************************************************************************
 *** Intel Confidential                                      
 *** Copyright (C) Intel Corporation 2000                 
 *** All Rights Reserved.                                    
 *** --------------------------------------------------------------------
 ***
 *** Project Name: Flash Templates
 ***
 *** Module Name: Template
 ***
 *** File: Template.C - Common template C source file
 ***
 *** File Revision: $Revision: 6 $, $JustDate:  3/24/00 $, $Author: Kalowry $
 ***
 *** Purpose:
 ***
 ***    The purpose of this file is to implement the common application 
 ***    programmers interface for flash template software.  This module
 ***    implements all flash template subroutines that do not have
 ***    a device specific implementation in the device.c module for
 ***    the supported device.  Macros are used to determine if
 ***    the template.c common implementation or the device.c specific
 ***    implementation is used by the template for each subroutine.
 ***
 ***    Note that some common template functions implemented in this
 ***    module will return STATUS_UNSUPPORTED since no common
 ***    implementation is possible due to the differences between 
 ***    supported devices for those functions.  The device.c module
 ***    must contain implementations for these particular functions
 ***    when the function is in fact supported for that device.
 ***
 *** $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  */


/* Include Files */
#include "template.h"

/*
 * Global Functions
 */ 

#if !DEVICE_CLEAR_STATUS /* if there is no device.c implementation */
/****************************************************************************
 *
 * 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_WriteF( TMPL_BASE_FLASH_ADDRESS,  TMPL_CLEAR_STATUS_REGISTER );

}
#endif /* !DEVICE_CLEAR_STATUS */


#if !DEVICE_ERASE_BLOCK /* if there is no device.c implementation */
/****************************************************************************
 *
 * 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_Status   stat;
   UINT32 blockadd;
  
   stat = TMPL_GetBlockAddress( blocknum, &blockadd );

   if ( stat.Result != StatCompleted )
   {
	  return( stat );
   }

   if ( returnSR )
   {
      TMPL_ClearStatus();
   }

   TMPL_WriteF(blockadd, TMPL_BLOCK_ERASE);

   TMPL_WriteF(blockadd, TMPL_CONFIRM );

   if ( !TMPL_WaitUntilReady( TMPL_ERASE_TIMEOUT ) )
   {
      stat.Result = StatTimeout;
   }
   else
   {
      stat.Result = StatCompleted;
   }

   if ( returnSR )
   {
      stat.SR = TMPL_ReadStatus();
   }

   /* return device to read array mode */
   TMPL_WriteF(TMPL_BASE_FLASH_ADDRESS, TMPL_READ_ARRAY );

   return( stat );

}
#endif /* !DEVICE_ERASE_BLOCK */


#if !DEVICE_ERASE_ALL_BLOCKS /* if there is no device.c implementation */
/****************************************************************************
 *
 * 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_Status stat;

   stat.Result = StatUnsupported;

   return( stat );
}
#endif /* !DEVICE_ERASE_ALL_BLOCKS */


#if !DEVICE_ERASE_SUSPEND /* if there is no device.c implementation */
/****************************************************************************
 *
 * 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_Status stat;

   stat.Result = StatUnsupported;

   return( stat );
}
#endif /* !DEVICE_ERASE_SUSPEND */


#if !DEVICE_EXTENDED_QUERY
/****************************************************************************
 *
 * 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:
 *
 *    NONE
 ***************************************************************************/
TMPL_Status TMPL_ExtendedQuery( struct TMPL_ExtQueryData *extquery )
{

   TMPL_Status stat;

   stat.Result = StatUnsupported;

   return( stat );

}
#endif /* !DEVICE_EXTENDED_QUERY */


#if !DEVICE_GET_BLOCK_ADDRESS /* if there is no device.c implementation */
/****************************************************************************
 *
 * TMPL_GetBlockAddress
 *
 * Description:   
 *
 *    This procedure is called to get the flash starting address for the
 *    specified block number.
 *
 * Parameters:
 *
 *    IN      blocknum - the block number on the device.
 *
 *    OUT     address  - the starting flash address for the specified
 *                       block.
 *
 * Returns:   
 *
 *    TMPL_Status - includes function return status defined by enum
 *                  TMPL_CommandStat.
 *
 * Assumptions:
 *
 *    NONE
 *
 ***************************************************************************/
TMPL_Status TMPL_GetBlockAddress ( UINT16     blocknum, 
                                   UINT32_PTR address )
{

   TMPL_Status stat;

   stat.Result = StatUnsupported;

   return( stat );
}
#endif /* !DEVICE_GET_BLOCK_ADDRESS */


#if !CLIENT_GET_FPTR /* if there is no client provided implementation */
/****************************************************************************
 *
 * TMPL_GetFptr
 *
 * Description:   
 *
 *    This procedure is called to return a flash ptr given a 
 *    specified device address.  This routine will likely need to be
 *    provided externally by the template client in order to properly
 *    deal with addressing details that are specific to the HW platform.
 *
 * Parameters:
 *
 *    IN      address  - the flash address 
 *
 * Returns:   
 *
 *    TMPL_FDATA_PTR  - address returned in ptr form
 *
 * Assumptions:
 *
 *    NONE
 *
 ***************************************************************************/
TMPL_FDATA_PTR  GetFptr( UINT32 address )
{
   return( (TMPL_FDATA_PTR)address );
}
#endif /* !CLIENT_GET_FPTR */


#if !DEVICE_GET_QUERY_ADDRESS /* if there is no device.c implementation */
/****************************************************************************
 *
 * TMPL_GetQueryAddress
 *
 * Description:   
 *
 *    This procedure is called to get the flash address for a given
 *    query offset.
 *
 *   Parameters:
 *
 *    IN      offset   - query offset location
 *
 *    OUT     address  - the flash address for the specified query
 *                       offset.
 *
 * Returns:   
 *
 *    TMPL_Status - includes function return status defined by enum
 *                  TMPL_CommandStat.
 *
 * Assumptions:
 *
 *    NONE
 *
 ***************************************************************************/
TMPL_Status TMPL_GetQueryAddress ( UINT32 offset, UINT32_PTR address )
{
   TMPL_Status stat;