spifi_rom_api.h

00001 /* definitions for ROM API for SPIFI in NXP MCUs
00002    copyright (c) 2010 NXP Semiconductors
00003    written by CAM  start                                     4/16/10
00004                    first testing                             5/12/10
00005                    OK with first SST & Winbond devices       6/8/10
00006                    OK with Gigadevice, Numonyx, Atmel, 
00007                                               some Macronyx  7/13/10
00008                    consensus with BK, performance optimized  8/24/10              
00009    this file is largely platform-independent */
00010 
00011 #ifndef SPIFI_ROM_API_H
00012 #define SPIFI_ROM_API_H
00013 
00014 
00015 #define SPIFI_MEM_BASE 0x28000000
00016 /* allocated size of the SPIFI memory area on this device */
00017 #define MEM_AREA_SIZE  0x00001000 
00018 #define SPIFI_ROM_PTR  0x1FFF1FF8
00019 
00020 /* define the symbol TESTING in the environment if test output desired */
00021 
00022 /* maintain LONGEST_PROT >= the length (in bytes) of the largest
00023     protection block of any serial flash that this driver handles */
00024 #define LONGEST_PROT 68
00025 
00026 /* protection/sector descriptors */
00027 typedef struct {
00028     unsigned base;
00029     uint8_t flags;
00030     signed char log2;
00031     uint16_t rept;
00032 } protEnt;
00033 
00034 typedef union {
00035     uint16_t hw;
00036     uint8_t byte[2];
00037 }stat_t;
00038 
00039 /* the object that init returns, and other routines use as an operand */
00040 typedef struct {
00041     unsigned base, regbase, devSize, memSize;
00042     uint8_t mfger, devType, devID, busy;
00043     stat_t stat;
00044     uint16_t reserved;
00045     uint16_t set_prot, write_prot;
00046     unsigned mem_cmd, prog_cmd;
00047     uint16_t sectors, protBytes;
00048     unsigned opts, errCheck;
00049     uint8_t erase_shifts[4], erase_ops[4];
00050     protEnt *protEnts;
00051     char prot[LONGEST_PROT];
00052 } SPIFIobj;
00053 
00054 /* operands of program and erase */
00055 typedef struct {
00056     char *dest;         /* starting address for programming or erasing */
00057     unsigned length;    /* number of bytes to be programmed or erased */
00058     char *scratch;      /* address of work area or NULL */
00059     int protect;        /* protection to apply after programming/erasing is done */
00060     unsigned options;   /* see the table below */
00061 } SPIFIopers;
00062 
00063 
00064 /* bits in options operands (MODE3, RCVCLK, and FULLCLK 
00065     have the same relationship as in the Control register) */
00066 #define S_MODE3 1
00067 #define S_MODE0 0
00068 #define S_MINIMAL 2
00069 #define S_MAXIMAL 0
00070 #define S_FORCE_ERASE 4
00071 #define S_ERASE_NOT_REQD 8
00072 #define S_CALLER_ERASE 8
00073 #define S_ERASE_AS_REQD 0
00074 #define S_VERIFY_PROG 0x10
00075 #define S_VERIFY_ERASE 0x20
00076 #define S_NO_VERIFY 0
00077 #define S_RCVCLK 0x80
00078 #define S_INTCLK 0
00079 #define S_FULLCLK 0x40
00080 #define S_HALFCLK 0
00081 #define S_DUAL 0x100
00082 #define S_CALLER_PROT 0x200
00083 #define S_DRIVER_PROT 0
00084 
00085 /* the length of a standard program command is 256 on all devices */
00086 #define PROG_SIZE 256
00087 
00088 /* interface to ROM API */
00089 typedef struct {
00090   int (*spifi_init)      (SPIFIobj *obj, unsigned csHigh, unsigned options, 
00091                           unsigned mhz);
00092   int (*spifi_program)   (SPIFIobj *obj, char *source, SPIFIopers *opers);
00093   int (*spifi_erase)     (SPIFIobj *obj, SPIFIopers *opers);
00094   /* mode switching */
00095   void (*cancel_mem_mode)(SPIFIobj *obj);
00096   void (*set_mem_mode)   (SPIFIobj *obj);
00097 
00098   /* mid level functions */
00099   int (*checkAd)         (SPIFIobj *obj, SPIFIopers *opers);
00100   int (*setProt)         (SPIFIobj *obj, SPIFIopers *opers, char *change, 
00101                           char *saveProt);
00102   int (*check_block)     (SPIFIobj *obj, char *source, SPIFIopers *opers, 
00103                           unsigned check_program);
00104   int (*send_erase_cmd)  (SPIFIobj *obj, unsigned char op, unsigned addr);
00105   unsigned (*ck_erase)   (SPIFIobj *obj, unsigned *addr, unsigned length);
00106   int (*prog_block)      (SPIFIobj *obj, char *source, SPIFIopers *opers, 
00107                           unsigned *left_in_page);
00108   unsigned (*ck_prog)    (SPIFIobj *obj, char *source, char *dest, unsigned length);
00109 
00110   /* low level functions */
00111   void(*setSize)         (SPIFIobj *obj, int value);
00112   int (*setDev)          (SPIFIobj *obj, unsigned opts, unsigned mem_cmd, 
00113                           unsigned prog_cmd);
00114   unsigned (*cmd)        (uint8_t op, uint8_t addrLen, uint8_t intLen, unsigned short len);
00115   unsigned (*readAd)     (SPIFIobj *obj, unsigned cmd, unsigned addr);
00116   void (*send04)         (SPIFIobj *obj, uint8_t op, uint8_t len, unsigned value);
00117   void (*wren_sendAd)    (SPIFIobj *obj, unsigned cmd, unsigned addr, unsigned value);
00118   int (*write_stat)      (SPIFIobj *obj, uint8_t len, uint16_t value);
00119   int (*wait_busy)       (SPIFIobj *obj, uint8_t prog_or_erase);
00120 } SPIFI_RTNS;
00121 
00122 //#define define_spifi_romPtr(name) const SPIFI_RTNS *name=*((SPIFI_RTNS **)SPIFI_ROM_PTR)
00123 
00124 /* example of using this interface:
00125 #include "spifi_rom_api.h"
00126 #define CSHIGH 4
00127 #define SPIFI_MHZ 80
00128 #define source_data_ad (char *)1234
00129 
00130     int rc;
00131     SPIFIopers opers;
00132 
00133     define_spifi_romPtr(spifi);
00134     SPIFIobj *obj = malloc(sizeof(SPIFIobj));
00135     if (!obj) { can't allocate memory }
00136 
00137     rc = spifi->spifi_init (obj, CSHIGH, S_FULLCLK+S_RCVCLK, SPIFI_MHZ);
00138     if (rc) { investigate init error rc }
00139     printf ("the serial flash contains %d bytes\n", obj->devSize);
00140 
00141     opers.dest = where_to_program;
00142     opers.length = how_many_bytes;
00143     opers.scratch = NULL;           // unprogrammed data is not saved/restored
00144     opers.protect = -1;             // save & restore protection
00145     opers.options = S_VERIFY_PROG;
00146 
00147     rc = spifi->spifi_program (obj, source_data_ad, &opers);
00148     if (rc) { investigate program error rc }
00149 */
00150 
00151 /* these are for normal users, including boot code */
00152 int spifi_init (SPIFIobj *obj, unsigned csHigh, unsigned options, unsigned mhz);
00153 int spifi_program (SPIFIobj *obj, char *source, SPIFIopers *opers);
00154 int spifi_erase (SPIFIobj *obj, SPIFIopers *opers);
00155 
00156 /* these are used by the manufacturer-specific init functions */
00157 void setSize (SPIFIobj *obj, int value);
00158 int setDev (SPIFIobj *obj, unsigned opts, unsigned mem_cmd, unsigned prog_cmd);
00159 unsigned read04(SPIFIobj *obj, uint8_t op, uint8_t len);
00160 int write_stat (SPIFIobj *obj, uint8_t len, uint16_t value);
00161 void setProtEnts(SPIFIobj *obj, const protEnt *p, unsigned protTabLen);
00162 
00163 #endif
00164 
00165