c2312.h

flash programer driver

/***************** Header File for STFL-I Flash Memory Driver ******************

   Filename:    c2312.h
   Description: Header file for c2312.c
                Consult also the C file for more details.

   Version:     $Id: c2312.h,v 1.0 2006/05/10 
   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/02/20  Initial Release of the software (Alpha)
   1.0    2006/05/10  Qualified Release of the software   

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


/*************** User Change Area *******************************************

   This section is meant to give all the opportunities to customize the
   SW Drivers according to the requirements of hardware and flash configuration.
   It is possible to choose flash start address, CPU Bitdepth, number of flash
   chips, hardware configuration and performance data (TimeOut Info).

   The options are listed and explained below:

   ********* Data Types *********
   The source code defines hardware independent datatypes assuming the
   compiler implements the numerical types as

   unsigned char    8 bits (defined as ubyte)
   char             8 bits (defined as byte)  
   unsigned short  16 bits (defined as uword)
   short           16 bits (defined as word)
   unsigned int    32 bits (defined as udword)
   int             32 bits (defined as dword)
 
   In case the compiler does not support the currently used numerical types,
   they can be easily changed just once here in the user area of the headerfile.
   The data types are consequently referenced in the source code as (u)byte,
   (u)word and (u)dword. No other data types like 'CHAR','SHORT','INT','LONG'
   directly used in the code.


   ********* Flash Type *********
   This driver supports the following Flash Types

   M29DW640F     8bit, 64Mbit Dual Bank Flash  #define USE_M29DW640F_8
   M29DW640F    16bit, 64Mbit Dual Bank Flash #define USE_M29DW640F_16

   ********* Base Address *********
   The start address where the flash memory chips are "visible" within
   the memory of the CPU is called the BASE_ADDR. This address must be
   set according to the current system. This value is used by FlashRead()
   FlashWrite(). Some applications which require a more complicated
   FlashRead() or FlashWrite() may not use BASE_ADDR.


   ********* Flash and Board Configuration *********
   The driver supports also different configurations of the flash chips
   on the board. In each configuration a new data Type called
   'uCPUBusType' is defined to match the current CPU data bus width.
   This data type is then used for all accesses to the memory.

   The different options (defines) are explained below:
   
   - USE_16BIT_CPU_ACCESSING_2_8BIT_FLASH
   Using this define enables a configuration consisting of an environment
   containing a CPU with 16bit databus and 2 8bit flash chips connected
   to it.

   - USE_16BIT_CPU_ACCESSING_1_16BIT_FLASH
   Using this define enables a configuration consisting of an environment
   containing a CPU with 16bit databus and 1 16bit flash chip connected
   to it. Standard Configuration

   - USE_32BIT_CPU_ACCESSING_4_8BIT_FLASH
   Using this define enables a configuration consisting of an environment
   containing a CPU with 32bit databus and 4 8bit flash chips connected
   to it.

   - USE_32BIT_CPU_ACCESSING_2_16BIT_FLASH
   Using this define enables a configuration consisting of an environment
   containing a CPU with 32bit databus and 2 16bit flash chips connected
   to it.

   - USE_8BIT_CPU_ACCESSING_1_8BIT_FLASH
   Using this define enables a configuration consisting of an environment
   containing a CPU with 8bit databus and 1 8bit flash chips connected
   to it.
   
   ********* TimeOut *********
   There are timeouts implemented in the loops of the code, in order
   to enable a timeout for operations that would otherwise never terminate.
   There are two possibilities:

   1) The ANSI Library functions declared in 'time.h' exist
  
      If the current compiler supports 'time.h' the define statement
      TIME_H_EXISTS should be activated. This makes sure that
      the performance of the current evaluation HW does not change
      the timeout settings. 

   2) or they are not available (COUNT_FOR_A_SECOND)

      If the current compiler does not support 'time.h', the define
      statement can not be used. To overcome this constraint the value
      COUNT_FOR_A_SECOND has to be defined in order to create a one
      second delay. For example, if 100000 repetitions of a loop are
      needed, to give a time delay of one second, then
      COUNT_FOR_A_SECOND should have the value 100000.

   ********* Pause Constant *********
   The function Flashpause() is used in several areas of the code to
   generate a delay required for correct operation of the flash device.
   There are two options provided:


   1) The Option ANSI Library functions declared in 'time.h' exists
      If the current compiler supports 'time.h' the define statement TIME_H_EXISTS should be
	  activated. This makes sure that the performance of the current evaluation HW does not
	  change the timeout settings.

      #define TIME_H_EXISTS

    2)	The Option COUNT_FOR_A_MICROSECOND
      If the current compiler does not support 'time.h', the define statement TIME_H_EXISTS can
	  not be used. To overcome this constraint the value COUNT_FOR_A_MICROSECOND has to be defined
	  in order to create a one micro second delay.
      Depending on a 'While(count-- != 0);' loop a value has to be found which creates the
	  necessary delay.
      - An approximate approach can be given by using the clock frequency of the test plattform.
	  That means if an evaluation board with 200 Mhz is used, the value for COUNT_FOR_A_MICROSECOND 
	  would be: 200.
      - The real exact value can only be found using a logic state analyser.

      #define COUNT_FOR_A_MICROSECOND (chosen value).

      Note: This delay is HW (Performance) dependent and needs,
      therefore, to be updated with every new HW.

      This driver has been tested with a certain configuration and other
      target platforms may have other performance data, therefore, the
      value may have to be changed.
      
      It is up to the user to implement this value to avoid the code
      timing out too early instead of completing correctly.


   ********* Additional Routines *********
   The drivers provides also a subroutine which displays the full
   error message instead of just an error number.

   The define statement VERBOSE activates additional Routines.
   Currently it activates the function FlashErrorStr()

   No further changes should be necessary. 

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

#ifndef __C2312__H__
#define __C2312__H__

typedef unsigned char  ubyte; /* All HW dependent Basic Data Types */      
typedef          char   byte;  
typedef unsigned short uword;      
typedef          short  word;      
typedef unsigned int  udword;      
typedef          int   dword;      

#define USE_M29DW640F_16
/* Possible Values: USE_M29DW640F_8
                      USE_M29DW640F_16
*/
#define BASE_ADDR ((volatile uCPUBusType*)0x00000000)
/* BASE_ADDR is the base or start address of the flash, see the functions
   FlashRead and FlashWrite(). Some applications which require a more
   complicated FlashRead() or FlashWrite() may not use BASE_ADDR */

#define USE_16BIT_CPU_ACCESSING_1_16BIT_FLASH /* Current PCB Info */
/* Possible Values: USE_16BIT_CPU_ACCESSING_2_8BIT_FLASH
                    USE_16BIT_CPU_ACCESSING_1_16BIT_FLASH
                    USE_32BIT_CPU_ACCESSING_4_8BIT_FLASH
                    USE_32BIT_CPU_ACCESSING_2_16BIT_FLASH */ 


#define TIME_H_EXISTS  /* set this macro if C-library "time.h" is supported */
/* Possible Values: TIME_H_EXISTS 
                    - no define - TIME_H_EXISTS */


#ifndef TIME_H_EXISTS
   #define COUNT_FOR_A_SECOND 100000    /* Timer Usage */
   #define COUNT_FOR_MICROSECOND 20  /* Used in FlashPause function */
#endif

#define VERBOSE /* Activates additional Routines */
/* Currently the Error String Definition */

/********************** End of User Change Area *****************************/


/*****************************************************************************
HW Structure Info, Usage of the Flash Memory (Circuitry)
*****************************************************************************/

#ifdef USE_16BIT_CPU_ACCESSING_2_8BIT_FLASH
   typedef uword uCPUBusType;
   typedef  word  CPUBusType;
   #define FLASH_BIT_DEPTH 8
   #define HEX "04Xh"
   #define CMD(A)  ((A<<8)+A) 
   #define CONFIGURATION_DEFINED
#endif

#ifdef USE_16BIT_CPU_ACCESSING_1_16BIT_FLASH
   typedef uword uCPUBusType;
   typedef  word  CPUBusType;
   #define FLASH_BIT_DEPTH 16
   #define HEX "04Xh"
   #define CMD(A) (A)
   #define CONFIGURATION_DEFINED
#endif                                       

#ifdef USE_32BIT_CPU_ACCESSING_4_8BIT_FLASH
   typedef udword uCPUBusType;
   typedef  dword  CPUBusType;
   #define FLASH_BIT_DEPTH 8
   #define HEX "08Xh"
   #define CMD(A) (A+(A<<24)+(A<<16)+(A<<8))
   #define CONFIGURATION_DEFINED
#endif

#ifdef USE_32BIT_CPU_ACCESSING_2_16BIT_FLASH
   typedef udword uCPUBusType;
   typedef  dword  CPUBusType;
   #define FLASH_BIT_DEPTH 16
   #define HEX "08Xh"
   #define CMD(A) (A+(A<<16))
   #define CONFIGURATION_DEFINED
#endif



/*******************************************************************************
Device Specific Return Codes
*******************************************************************************/

typedef enum {
   FlashSpec_TooManyBlocks,
   FlashSpec_MpuTooSlow,
   FlashSpec_ToggleFailed
} SpecificReturnType;

/******************************************************************************* 
     CONFIGURATION CHECK
*******************************************************************************/ 
 
#ifndef CONFIGURATION_DEFINED 
#error  User Change Area Error: PCB Info uncorrect Check the USE_xxBIT_CPU_ACCESSING_n_yyBIT_FLASH Value
#endif

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