c2082.c

Description: Library routines for the M25P05A, M25P10A, M25P20, M25P40, M25P80, M25P16, M25P32, M25P

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

   Filename:    c2082.c
   Description: Library routines for the M25P05A, M25P10A, M25P20, M25P40, M25P80
                M25P16, M25P32, M25P64 Serial Flash Memories

   Version:     V2.0
   Date:        20/07/2005
   Authors:     Tan Zhi, STMicroelectronics, Shanghai (China)
   Copyright (c) 2004 STMicroelectronics.

   THE PRESENT SOFTWARE WHICH IS FOR GUIDANCE ONLY AIMS AT PROVIDING CUSTOMERS WITH
   CODING INFORMATION REGARDING THEIR PRODUCTS IN ORDER FOR THEM TO SAVE TIME. AS A
   RESULT, STMICROELECTRONICS SHALL NOT BE HELD LIABLE FOR ANY DIRECT, INDIRECT OR 
   CONSEQUENTIAL DAMAGES WITH RESPECT TO ANY CLAIMS ARISING FROM THE CONTENT OF SUCH
   SOFTWARE AND/OR THE USE MADE BY CUSTOMERS OF THE CODING INFORMATION CONTAINED HEREIN
   IN CONNECTION WITH THEIR PRODUCTS.
********************************************************************************

   Version History.
   Ver.   Date      Comments
   
   1.0   16/11/2004   Initial release
   2.0   20/07/2005   Add support for M25P32, M25P64
                      Add JEDEC ID support for M25P05A, M25P10A
      
********************************************************************************

   This source file provides library C code for M25P05A, M25P10A, M25P20,
   M25P40, M25P80, M25P16, M25P32, M25P64 serial flash devices.

   The following functions are available in this library(some memories may only support
   a subset of the list, refer to the specific product datasheet for details):

      Flash(WriteEnable, 0)                         to disable Write Protect in the Flash memory
      Flash(WriteDisable, 0)                        to enable Write Protect in the Flash memory
      Flash(ReadDeviceIdentification, ParameterType)  to get the Device Identification from the device 
      Flash(ReadManufacturerIdentification, ParameterType)(if available in the memory)    to get the manufacturer Identification from the device 
      Flash(ReadStatusRegister, ParameterType)      to get the value in the Status Register from the device 
      Flash(WriteStatusRegister, ParameterType)      to set the value in the Status Register from the device 
      Flash(Read, ParameterType)                    to read from the Flash device
      Flash(FastRead, ParameterType)                to read from the Flash device in a faster way
      Flash(PageProgram, ParameterType)             to write an array of elements within one page
      Flash(SectorErase, ParameterType)             to erase a whole sector
      Flash(BulkErase, ParameterType)               to erase the whole memory
      Flash(DeepPowerDown, 0)                       to set the memory into the low power consumption mode
      Flash(ReleaseFromDeepPowerDown, 0)            to wake up the memory from the low power consumption mode
      Flash(Program, ParameterType)                 to program an array of elements
      FlashErrorStr()                               to return an error description (define VERBOSE)
      
   Note that data Bytes will be referred to as elements throughout the document unless otherwise specified.

   For further information consult the related Datasheets and 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() used to write an element (uCPUBusType) to the Flash memory
      FlashRead()  used to read an element (uCPUBusType) from the Flash memory
      FlashTimeOut() to return after the function has timed out 

   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 "c2082.h" /* Header file with global prototypes */
#include "Serialize.h" /* Header file with SPI master abstract prototypes */

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

#ifdef SYNCHRONOUS_IO    
#define WAIT_TILL_Instruction_EXECUTION_COMPLETE(x) FlashTimeOut(0); while(IsFlashBusy()) \
    { \
        if(Flash_OperationTimeOut == FlashTimeOut(x)) return  Flash_OperationTimeOut; \
    };
 
#else  
    // do nothing
#endif


/******************************************************************************
    Global variables: none
*******************************************************************************/ 

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

   Flash_AddressInvalid, 
   Flash_MemoryOverflow, 
   Flash_PageEraseFailed, 
   Flash_PageNrInvalid, 
   Flash_SectorNrInvalid, 
   Flash_FunctionNotSupported,
   Flash_NoInformationAvailable,
   Flash_OperationOngoing, 
   Flash_OperationTimeOut, 
   Flash_ProgramFailed, 
   Flash_SpecificError,
   Flash_Success, 
   Flash_WrongType

Description:  This function is used to access all functions provided with the
   current Flash device.

Pseudo Code:
   Step 1: Select the right action using the insInstruction parameter
   Step 2: Execute the Flash memory Function
   Step 3: Return the Error Code
*******************************************************************************/
ReturnType Flash( InstructionType insInstruction, ParameterType *fp ) { 
    ReturnType  rRetVal;
	ST_uint8  ucStatusRegister;
    ST_uint16 ucDeviceIdentification;
#ifdef USE_JEDEC_STANDARD_TWO_BYTE_SIGNATURE
    ST_uint8  ucManufacturerIdentification;
#endif 
   switch (insInstruction) {
      case WriteEnable: 
           rRetVal = FlashWriteEnable( ); 
           break; 

      case WriteDisable: 
           rRetVal = FlashWriteDisable( );
           break; 
            
      case ReadDeviceIdentification: 
           rRetVal = FlashReadDeviceIdentification(&ucDeviceIdentification);
           (*fp).ReadDeviceIdentification.ucDeviceIdentification = ucDeviceIdentification;
           break; 

#ifdef USE_JEDEC_STANDARD_TWO_BYTE_SIGNATURE
      case ReadManufacturerIdentification: 
           rRetVal = FlashReadManufacturerIdentification(&ucManufacturerIdentification);
           (*fp).ReadManufacturerIdentification.ucManufacturerIdentification = ucManufacturerIdentification;
           break; 
#endif

      case ReadStatusRegister:
            rRetVal = FlashReadStatusRegister(&ucStatusRegister);
           (*fp).ReadStatusRegister.ucStatusRegister = ucStatusRegister;
           break;

      case WriteStatusRegister:
           ucStatusRegister = (*fp).WriteStatusRegister.ucStatusRegister;
            rRetVal = FlashWriteStatusRegister(ucStatusRegister);
           break;

      case Read: 
           rRetVal = FlashRead( (*fp).Read.udAddr,
                                (*fp).Read.pArray,
                                (*fp).Read.udNrOfElementsToRead
                              ); 
           break; 

      case FastRead:
           rRetVal = FlashFastRead( (*fp).Read.udAddr,
                                    (*fp).Read.pArray,
                                    (*fp).Read.udNrOfElementsToRead
                                  ); 
           break;
 
      case PageProgram:
           rRetVal = FlashProgram( (*fp).PageProgram.udAddr,
                                 (*fp).PageProgram.pArray,
                                 (*fp).PageProgram.udNrOfElementsInArray
                               );  
           break;
           
      case SectorErase: 
           rRetVal = FlashSectorErase((*fp).SectorErase.ustSectorNr ); 
           break; 
           
      case BulkErase: 
           rRetVal = FlashBulkErase( ); 
           break; 


 #ifndef NO_DEEP_POWER_DOWN_SUPPORT
      case DeepPowerDown:
           rRetVal = FlashDeepPowerDown( );                 
           break;
	  
      case ReleaseFromDeepPowerDown:
           rRetVal = FlashReleaseFromDeepPowerDown( );                 
           break;
#endif

      case Program:
           rRetVal = FlashProgram( (*fp).Program.udAddr,
                                   (*fp).Program.pArray,
                                   (*fp).Program.udNrOfElementsInArray);                 
           break;
           
       default:
           rRetVal = Flash_FunctionNotSupported;
           break;

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

/*******************************************************************************
Function:     FlashWriteEnable( void )
Arguments:    void

Return Value: 
   Flash_Success 

Description:  This function sets the Write Enable Latch(WEL)
              by sending a WREN Instruction.

Pseudo Code:
   Step 1: Initialize the data (i.e. Instruction) packet to be sent serially
   Step 2: Send the packet serially
*******************************************************************************/
ReturnType  FlashWriteEnable( void )
{
    CharStream char_stream_send;
    ST_uint8  cWREN = SPI_FLASH_INS_WREN; 

    // Step 1: Initialize the data (i.e. Instruction) packet to be sent serially
    char_stream_send.length = 1;
    char_stream_send.pChar  = &cWREN;

    // Step 2: Send the packet serially
    Serialize(&char_stream_send, 
              ptrNull,
              enumEnableTransOnly_SelectSlave,
              enumDisableTransOnly_DeSelectSlave
              );
    return Flash_Success;
}

/*******************************************************************************
Function:     FlashWriteDisable( void )
Arguments:    void

Return Value: 
   Flash_Success 

Description:  This function resets the Write Enable Latch(WEL)
              by sending a WRDI Instruction.

Pseudo Code:
   Step 1: Initialize the data (i.e. Instruction) packet to be sent serially
   Step 2: Send the packet serially
*******************************************************************************/
ReturnType  FlashWriteDisable( void )
{
    CharStream char_stream_send;
    ST_uint8  cWRDI = SPI_FLASH_INS_WRDI; 

    // Step 1: Initialize the data (i.e. Instruction) packet to be sent serially
    char_stream_send.length = 1;
    char_stream_send.pChar  = &cWRDI;

    // Step 2: Send the packet serially
    Serialize(&char_stream_send, 
              ptrNull,
              enumEnableTransOnly_SelectSlave,
              enumDisableTransOnly_DeSelectSlave
              );
    return Flash_Success;
}

/*******************************************************************************
Function:     FlashReadDeviceIdentification( ST_uint16 *uwpDeviceIdentification)
Arguments:    uwpDeviceIdentificaiton, 16-bit buffer to hold the DeviceIdentification read from the 
              memory, with memory type residing in the higher 8 bits, and
              memory capacity in the lower ones.

Return Value: 
   Flash_Success
   Flash_WrongType(if USE_JEDEC_STANDARD_TWO_BYTE_SIGNATURE defined)

Description:  This function returns the Device Identification (memory type + memory capacity)
              by sending an SPI_FLASH_INS_RDID Instruction.
              After retrieving the Device Identificaiton, the routine checks if the device is
              an expected device(defined by EXPECTED_DEVICE). If not, 
              Flash_WrongType is returned.

              If USE_JEDEC_STANDARD_TWO_BYTE_SIGNATURE is defined, the returned 16-bit
              word comprises memory type(higher 8 bits) and memory capacity
              (lower 8 bits).
              If USE_JEDEC_STANDARD_TWO_BYTE_SIGNATURE is NOT defined, only the lower
              8-bit byte of the returned 16-bit word is valid information,i.e. the 
              Device Identification.
              For memories that have a capacity of more than 16Mb(inclusive), 
              USE_JEDEC_STANDARD_TWO_BYTE_SIGNATURE is defined by default.

Pseudo Code:
   Step 1: Initialize the data (i.e. Instruction) packet to be sent serially
   Step 2: Send the packet serially
   Step 3: Device Identification is returned
*******************************************************************************/
ReturnType  FlashReadDeviceIdentification( ST_uint16 *uwpDeviceIdentification)
{
#ifdef USE_JEDEC_STANDARD_TWO_BYTE_SIGNATURE
    CharStream char_stream_send;
    CharStream char_stream_recv;
    ST_uint8  cRDID = SPI_FLASH_INS_RDID; 
    ST_uint8  pIdentification[3]; 

    // Step 1: Initialize the data (i.e. Instruction) packet to be sent serially
    char_stream_send.length  = 1;
    char_stream_send.pChar   = &cRDID;

    char_stream_recv.length  = 3;
    char_stream_recv.pChar   = &pIdentification[0];

    // Step 2: Send the packet serially
    Serialize(&char_stream_send, 
              &char_stream_recv,
              enumEnableTansRecv_SelectSlave,
              enumDisableTansRecv_DeSelectSlave
              );

    // Step 3: Device Identification is returned ( memory type + memory capacity )
    *uwpDeviceIdentification = char_stream_recv.pChar[1];
    *uwpDeviceIdentification <<= 8;
    *uwpDeviceIdentification |= char_stream_recv.pChar[2];

    if(EXPECTED_DEVICE == *uwpDeviceIdentification)
        return Flash_Success;
    else
        return Flash_WrongType;

#else   // USE_JEDEC_STANDARD_TWO_BYTE_SIGNATURE not defined
    CharStream char_stream_send;
    CharStream char_stream_recv;
    ST_uint8  pIns[4]; 
    ST_uint8  cRDID = SPI_FLASH_INS_RES; 
    ST_uint8  pIdentification; 

    // Step 1: Initialize the data (i.e. Instruction) packet to be sent serially
    char_stream_send.length  = 4;
    char_stream_send.pChar   = &pIns[0];
    pIns[0] = SPI_FLASH_INS_RES;
    pIns[1] = SPI_FLASH_INS_DUMMY;
    pIns[2] = SPI_FLASH_INS_DUMMY;
    pIns[3] = SPI_FLASH_INS_DUMMY;

    char_stream_recv.length  = 1;
    char_stream_recv.pChar   = &pIdentification;

    // Step 2: Send the packet serially
    Serialize(&char_stream_send, 
              &char_stream_recv,
              enumEnableTansRecv_SelectSlave,
              enumDisableTansRecv_DeSelectSlave
              );

    // Step 3: Get the returned device Identification
    *uwpDeviceIdentification = *char_stream_recv.pChar;

    if(EXPECTED_DEVICE == *uwpDeviceIdentification)
        return Flash_Success;
    else
        return Flash_WrongType;
#endif
}