/**************** STFL-I Flash Memory Driver ***********************************

   Filename:    c2374.c
   Description: Library routines for the M29W320E
                32Mb (4Mb x 8 or 2Mb x 16,Page,Boot Block) Flash Memory drivers
                in different configurations.

   Version:     $Id: c2374.c,v 1.0 2006/06/16 
                     
   Author:     Ze-Yu He, MSAC,STMicroelectronics, Shanghai (China)
               Wiley Xu, MSAC,STMicroelectronics, Shanghai (China)
               Echo Chen,MSAC,STMicroelectronics, Beijing  (China)
   Copyright (c) 2006 STMicroelectronics.

   THIS PROGRAM IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
   EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTY
   OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK
   AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
   PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
   REPAIR OR CORRECTION.
********************************************************************************

   Version History.

   Ver.   Date        Comments

   0.0    2006/05/29  Initial Release of the software (Alpha)
   1.0    2006/06/16  Qulified Release of the software  

********************************************************************************

   This source file provides library C code for using the M29W320E flash devices.
   The following device is supported in the code: M29W320ET and M29W320EB

   This file can be used to access the devices in 8bit and 16bit mode.

   The following functions are available in this library:

      Flash(BlockErase, ParameterType)            to erase one block
      Flash(CheckBlockProtection, ParameterType)  to check whether a given block is protected
      Flash(CheckCompatibility, ParameterType)    to check the compatibility of the flash 
      Flash(ChipErase, ParameterType)             to erase the whole chip
      Flash(ChipUnprotect, ParameterType)         to unprotect the whole chip
      Flash(GroupProtect, ParameterType)          to unprotect a blocks group
      Flash(Program, ParameterType)               to program an array of elements
      Flash(Read, ParameterType)                  to read from the flash device
      Flash(ReadCfi, ParameterType)               to read CFI information from the flash
      Flash(ReadDeviceId, ParameterType)          to get the Device ID from the device 
      Flash(ReadManufacturerCode, ParameterType)  to get the Manufacture Code from the device
      Flash(Reset, ParameterType)                 to reset the flash for normal memory access 
      Flash(Resume, ParameterType)                to resume a suspended erase
      Flash(SingleProgram, ParameterType)         to program a single element
      Flash(Suspend, ParameterType)               to suspend an erase
      Flash(Write, ParameterType)                 to write a value to the flash device

      FlashDoubleProgram()                        to program two elements in 16 bit only
      FlashEnterExtendedBlock()                   to issue the enter extended mode command
      FlashErrorStr()                             to return an error description (define VERBOSE)
      FlashExitExtendedBlock()                    to issue the exit extended mode command
      FlashMultipleBlockErase()                   to erase some blocks in same bank
      FlashPause()                                for timing short pauses (in micro seconds) 
      FlashQuadProgram()                          to program four elements in 
                                                              8 bit mode only       
      FlashReadExtendedBlockVerifyCode()    to read the lock/unlock status of the
                                                     Extended Memory Block
      FlashReadProtectionRegister()               to read a protection register location
      FlashReadStatusRegister()                   to read the Status Register
      FlashStatusPinConfig()                      to configure the Status/(Ready/Busy) pin
      FlashTimeOut()                              to return after function timeouts 
      FlashUnlockBypass()                      enter UnlockBypass mode
      FlashUnlockBypassProgram()                  to program in unlock bypass mode
      FlashUnlockBypassReset()                    to issue the unlock bypass reset command

   For further information consult the Data Sheet and the Application Note.
   The Application Note gives information about how to modify this code for
   a specific application.

   The hardware specific functions which may need to be modified by the user are:

      FlashWrite() for writing an element (uCPUBusType) to the flash
      FlashRead()  for reading an element (uCPUBusType) from the flash

   A list of the error conditions can be found at the end of the header file.

*******************************************************************************/

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include "c2374.h" /* Header file with global prototypes */

#ifdef TIME_H_EXISTS
   #include <time.h>
#endif 

/******************************************************************************
    Global variables
*******************************************************************************/ 
ErrorInfoType eiErrorInfo;


/*******************************************************************************
Function:     ReturnType Flash( CommandType cmdCommand, ParameterType *fp )
Arguments:    cmdCommand is an enum which contains all the available function
   commands of the SW driver.
              fp is a (union) parameter struct for all flash command parameters
Return Value: The function returns the following conditions: 

   Flash_AddressInvalid 
   Flash_BlockEraseFailed 
   Flash_BlockNrInvalid 
   Flash_BlockProtected 
   Flash_BlockProtectFailed 
   Flash_BlockProtectionUnclear 
   Flash_BlockUnprotected 
   Flash_CfiFailed 
   Flash_ChipEraseFailed 
   Flash_ChipUnprotectFailed 
   Flash_FunctionNotSupported
   Flash_GroupProtectFailed 
   Flash_NoInformationAvailable
   Flash_OperationOngoing 
   Flash_OperationTimeOut 
   Flash_ProgramFailed 
   Flash_ResponseUnclear 
   Flash_SpecificError
   Flash_Success 
   Flash_WrongType

Description:  This function is used to access all functions provided with the
   current flash chip.

Pseudo Code:
   Step 1: Select the right action using the cmdCommand parameter
   Step 2: Execute the Flash Function
   Step 3: Return the Error Code
*******************************************************************************/
ReturnType Flash( CommandType cmdCommand, ParameterType *fp ) { 
   ReturnType  rRetVal;
   uCPUBusType  ucDeviceId, ucManufacturerCode;

   switch (cmdCommand) {
      case BlockErase:
         rRetVal = FlashBlockErase( (*fp).BlockErase.ublBlockNr );
         break;

      case CheckBlockProtection: 
         rRetVal = FlashCheckBlockProtection( (*fp).CheckBlockProtection.ublBlockNr );  
         break; 

      case CheckCompatibility:
         rRetVal = FlashCheckCompatibility();
         break;

      case ChipErase:
         rRetVal = FlashChipErase( (*fp).ChipErase.rpResults );
         break;

      case ChipUnprotect: 
         rRetVal = FlashChipUnprotect((*fp).ChipUnprotect.rpResults ); 
         break; 

      case GroupProtect: 
         rRetVal = FlashGroupProtect( (*fp).GroupProtect.ublBlockNr ); 
         break; 

      case Program:
         rRetVal = FlashProgram( (*fp).Program.udMode,
                                 (*fp).Program.udAddrOff,
                                 (*fp).Program.udNrOfElementsInArray,
                                 (*fp).Program.pArray );                 

         break;

      case Read:
         (*fp).Read.ucValue = FlashRead( (*fp).Read.udAddrOff );
         rRetVal = Flash_Success;
         break;

      case ReadCfi:  
         rRetVal = FlashReadCfi( (*fp).ReadCfi.uwCfiFunc, &((*fp).ReadCfi.ucCfiValue) ); 
         break; 

      case ReadDeviceId:
         rRetVal = FlashReadDeviceId(&ucDeviceId);
         (*fp).ReadDeviceId.ucDeviceId = ucDeviceId;
         break;

      case ReadManufacturerCode:
         rRetVal = FlashReadManufacturerCode(&ucManufacturerCode);
         (*fp).ReadManufacturerCode.ucManufacturerCode = ucManufacturerCode;
         break;

      case Reset:
         rRetVal = FlashReset();
         break;

      case Resume:
         rRetVal = FlashResume();
         break;

      case SingleProgram:
         rRetVal = FlashSingleProgram( (*fp).SingleProgram.udAddrOff, (*fp).SingleProgram.ucValue );
         break;

      case Suspend:
         rRetVal = FlashSuspend();
         break;

      case Write:
         FlashWrite( (*fp).Write.udAddrOff, (*fp).Write.ucValue ); 
         rRetVal = Flash_Success;
         break;

      default:
         rRetVal = Flash_FunctionNotSupported;
         break;

   } /* EndSwitch */
   return rRetVal;
} /* EndFunction Flash */







/*******************************************************************************
Function:     ReturnType FlashBlockErase( uBlockType ublBlockNr )
Arguments:    ublBlockNr is the number of the Block to be erased.
Return Value: The function returns the following conditions:
   Flash_Success
   Flash_BlockEraseFailed
   Flash_BlockNrInvalid
   Flash_BlockProtected
   Flash_OperationTimeOut

Description:  This function can be used to erase the Block specified in ublBlockNr.
   The function checks that the block nr is within the valid range and not protected
   before issuing the erase command, otherwise the block will not be erased and an
   error code will be returned.
   The function returns only when the block is erased. During the Erase Cycle the
   Data Toggle Flow Chart of the Datasheet is followed. The polling bit, DQ7, is not
   used.
   
Pseudo Code:
   Step 1:  Check that the block number exists
   Step 2:  Check if the block is protected
   Step 3:  Write Block Erase command
   Step 4:  Wait for the timer bit to be set
   Step 5:  Follow Data Toggle Flow Chart until the Program/Erase Controller is
            finished
   Step 6:  Return to Read mode (if an error occurred)
*******************************************************************************/
ReturnType FlashBlockErase( uBlockType ublBlockNr) {

   ReturnType rRetVal = Flash_Success; /* Holds return value: optimistic initially! */

   /* Step 1: Check for invalid block. */
   if( ublBlockNr >= NUM_BLOCKS ) /* Check specified blocks <= NUM_BLOCKS */
      return Flash_BlockNrInvalid;

   /* Step 2: Check if the block is protected */
   if ( FlashCheckBlockProtection(ublBlockNr) == Flash_BlockProtected)
      return Flash_BlockProtected;

   /* Step 3: Write Block Erase command */
   FlashWrite( ConvAddr(0x00555), (uCPUBusType)CMD(0x00AA) );
   FlashWrite( ConvAddr(0x002AA), (uCPUBusType)CMD(0x0055) );
   FlashWrite( ConvAddr(0x00555), (uCPUBusType)CMD(0x0080) );
   FlashWrite( ConvAddr(0x00555), (uCPUBusType)CMD(0x00AA) );
   FlashWrite( ConvAddr(0x002AA), (uCPUBusType)CMD(0x0055) );
   FlashWrite( BlockOffset[ublBlockNr], (uCPUBusType)CMD(0x0030) );

   /* Step 4: Wait for the Erase Timer Bit (DQ3) to be set */
   FlashTimeOut(0); /* Initialize TimeOut Counter */
   while( !(FlashRead( BlockOffset[ublBlockNr] ) & CMD(0x0008) ) ){
      if (FlashTimeOut(5) == Flash_OperationTimeOut) {
         FlashWrite( ANY_ADDR, (uCPUBusType)CMD(0x00F0) ); /* Use single instruction cycle method */
         return Flash_OperationTimeOut;
      } /* EndIf */
   } /* EndWhile */

   /* Step 5: Follow Data Toggle Flow Chart until Program/Erase Controller completes */
   if( FlashDataToggle(BlockOffset[ublBlockNr]) !=  Flash_Success ) {
      /* Step 6: Return to Read mode (if an error occurred) */
      FlashWrite( ANY_ADDR, (uCPUBusType)CMD(0x00F0) ); /* Use single instruction cycle method */
      rRetVal=Flash_BlockEraseFailed;
   } /* EndIf */
   return rRetVal;
} /* EndFunction FlashBlockErase */





/*******************************************************************************
Function:      ReturnType FlashCheckBlockProtection( uBlockType ublBlockNr )
Arguments:     ublBlockNr = block number to be checked
Note: the first block is Block 0

Return Values: The function returns the following conditions: 
   Flash_BlockNrInvalid
   Flash_BlockUnprotected
   Flash_BlockProtected
   Flash_BlockProtectionUnclear

Description:   This function reads the protection status of a block.
Pseudo Code:
   Step 1:  Check that the block number exists
   Step 2:  Send the AutoSelect command
   Step 3:  Read Protection Status
   Step 4:  Return the device to Read Array mode