tool/mbed/mbed-sdk/libraries/tests/mbed/spifi1/spifi_rom_api.h

   1 /* definitions for ROM API for SPIFI in NXP MCUs
   2    copyright (c) 2010 NXP Semiconductors
   3    written by CAM  start                                     4/16/10
   4                    first testing                             5/12/10
   5                    OK with first SST & Winbond devices       6/8/10
   6                                    OK with Gigadevice, Numonyx, Atmel,
   7                                                               some Macronyx  7/13/10
   8                                    consensus with BK, performance optimized  8/24/10
   9    this file is largely platform-independent */
  10
  11 #ifndef SPIFI_ROM_API_H
  12 #define SPIFI_ROM_API_H
  13
  14
  15 #define SPIFI_MEM_BASE 0x28000000
  16 /* allocated size of the SPIFI memory area on this device */
  17 #define MEM_AREA_SIZE  0x00001000
  18 #define SPIFI_ROM_PTR  0x1FFF1FF8
  19
  20 /* define the symbol TESTING in the environment if test output desired */
  21
  22 /* maintain LONGEST_PROT >= the length (in bytes) of the largest
  23         protection block of any serial flash that this driver handles */
  24 #define LONGEST_PROT 68
  25
  26 /* protection/sector descriptors */
  27 typedef struct {
  28         unsigned base;
  29         uint8_t flags;
  30         signed char log2;
  31         uint16_t rept;
  32 } protEnt;
  33
  34 typedef union {
  35         uint16_t hw;
  36         uint8_t byte[2];
  37 }stat_t;
  38
  39 /* the object that init returns, and other routines use as an operand */
  40 typedef struct {
  41         unsigned base, regbase, devSize, memSize;
  42         uint8_t mfger, devType, devID, busy;
  43         stat_t stat;
  44         uint16_t reserved;
  45         uint16_t set_prot, write_prot;
  46         unsigned mem_cmd, prog_cmd;
  47         uint16_t sectors, protBytes;
  48         unsigned opts, errCheck;
  49         uint8_t erase_shifts[4], erase_ops[4];
  50         protEnt *protEnts;
  51         char prot[LONGEST_PROT];
  52 } SPIFIobj;
  53
  54 /* operands of program and erase */
  55 typedef struct {
  56     char *dest;                 /* starting address for programming or erasing */
  57     unsigned length;    /* number of bytes to be programmed or erased */
  58     char *scratch;              /* address of work area or NULL */
  59     int protect;                /* protection to apply after programming/erasing is done */
  60     unsigned options;   /* see the table below */
  61 } SPIFIopers;
  62
  63
  64 /* bits in options operands (MODE3, RCVCLK, and FULLCLK
  65         have the same relationship as in the Control register) */
  66 #define S_MODE3 1
  67 #define S_MODE0 0
  68 #define S_MINIMAL 2
  69 #define S_MAXIMAL 0
  70 #define S_FORCE_ERASE 4
  71 #define S_ERASE_NOT_REQD 8
  72 #define S_CALLER_ERASE 8
  73 #define S_ERASE_AS_REQD 0
  74 #define S_VERIFY_PROG 0x10
  75 #define S_VERIFY_ERASE 0x20
  76 #define S_NO_VERIFY 0
  77 #define S_RCVCLK 0x80
  78 #define S_INTCLK 0
  79 #define S_FULLCLK 0x40
  80 #define S_HALFCLK 0
  81 #define S_DUAL 0x100
  82 #define S_CALLER_PROT 0x200
  83 #define S_DRIVER_PROT 0
  84
  85 /* the length of a standard     program command is 256 on all devices */
  86 #define PROG_SIZE 256
  87
  88 /* interface to ROM API */
  89 typedef struct {
  90   int (*spifi_init)      (SPIFIobj *obj, unsigned csHigh, unsigned options,
  91                           unsigned mhz);
  92   int (*spifi_program)   (SPIFIobj *obj, char *source, SPIFIopers *opers);
  93   int (*spifi_erase)     (SPIFIobj *obj, SPIFIopers *opers);
  94   /* mode switching */
  95   void (*cancel_mem_mode)(SPIFIobj *obj);
  96   void (*set_mem_mode)   (SPIFIobj *obj);
  97
  98   /* mid level functions */
  99   int (*checkAd)         (SPIFIobj *obj, SPIFIopers *opers);
 100   int (*setProt)         (SPIFIobj *obj, SPIFIopers *opers, char *change,
 101                           char *saveProt);
 102   int (*check_block)     (SPIFIobj *obj, char *source, SPIFIopers *opers,
 103                           unsigned check_program);
 104   int (*send_erase_cmd)  (SPIFIobj *obj, unsigned char op, unsigned addr);
 105   unsigned (*ck_erase)   (SPIFIobj *obj, unsigned *addr, unsigned length);
 106   int (*prog_block)      (SPIFIobj *obj, char *source, SPIFIopers *opers,
 107                           unsigned *left_in_page);
 108   unsigned (*ck_prog)    (SPIFIobj *obj, char *source, char *dest, unsigned length);
 109
 110   /* low level functions */
 111   void(*setSize)         (SPIFIobj *obj, int value);
 112   int (*setDev)          (SPIFIobj *obj, unsigned opts, unsigned mem_cmd,
 113                           unsigned prog_cmd);
 114   unsigned (*cmd)        (uint8_t op, uint8_t addrLen, uint8_t intLen, unsigned short len);
 115   unsigned (*readAd)     (SPIFIobj *obj, unsigned cmd, unsigned addr);
 116   void (*send04)         (SPIFIobj *obj, uint8_t op, uint8_t len, unsigned value);
 117   void (*wren_sendAd)    (SPIFIobj *obj, unsigned cmd, unsigned addr, unsigned value);
 118   int (*write_stat)      (SPIFIobj *obj, uint8_t len, uint16_t value);
 119   int (*wait_busy)       (SPIFIobj *obj, uint8_t prog_or_erase);
 120 } SPIFI_RTNS;
 121
 122 //#define define_spifi_romPtr(name) const SPIFI_RTNS *name=*((SPIFI_RTNS **)SPIFI_ROM_PTR)
 123
 124 /* example of using this interface:
 125 #include "spifi_rom_api.h"
 126 #define CSHIGH 4
 127 #define SPIFI_MHZ 80
 128 #define source_data_ad (char *)1234
 129
 130         int rc;
 131         SPIFIopers opers;
 132
 133         define_spifi_romPtr(spifi);
 134         SPIFIobj *obj = malloc(sizeof(SPIFIobj));
 135         if (!obj) { can't allocate memory }
 136
 137         rc = spifi->spifi_init (obj, CSHIGH, S_FULLCLK+S_RCVCLK, SPIFI_MHZ);
 138         if (rc) { investigate init error rc }
 139         printf ("the serial flash contains %d bytes\n", obj->devSize);
 140
 141         opers.dest = where_to_program;
 142         opers.length = how_many_bytes;
 143         opers.scratch = NULL;                   // unprogrammed data is not saved/restored
 144         opers.protect = -1;                             // save & restore protection
 145         opers.options = S_VERIFY_PROG;
 146
 147         rc = spifi->spifi_program (obj, source_data_ad, &opers);
 148         if (rc) { investigate program error rc }
 149 */
 150
 151 /* these are for normal users, including boot code */
 152 int spifi_init (SPIFIobj *obj, unsigned csHigh, unsigned options, unsigned mhz);
 153 int spifi_program (SPIFIobj *obj, char *source, SPIFIopers *opers);
 154 int spifi_erase (SPIFIobj *obj, SPIFIopers *opers);
 155
 156 /* these are used by the manufacturer-specific init functions */
 157 void setSize (SPIFIobj *obj, int value);
 158 int setDev (SPIFIobj *obj, unsigned opts, unsigned mem_cmd, unsigned prog_cmd);
 159 unsigned read04(SPIFIobj *obj, uint8_t op, uint8_t len);
 160 int write_stat (SPIFIobj *obj, uint8_t len, uint16_t value);
 161 void setProtEnts(SPIFIobj *obj, const protEnt *p, unsigned protTabLen);
 162
 163 #endif
 164
 165