SPIFI.h

00001 /*
00002  *  Copyright 2013 Embedded Artists AB
00003  *
00004  *  Licensed under the Apache License, Version 2.0 (the "License");
00005  *  you may not use this file except in compliance with the License.
00006  *  You may obtain a copy of the License at
00007  *
00008  *    http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  *  Unless required by applicable law or agreed to in writing, software
00011  *  distributed under the License is distributed on an "AS IS" BASIS,
00012  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  *  See the License for the specific language governing permissions and
00014  *  limitations under the License.
00015  */
00016 
00017 #ifndef SPIFI_H
00018 #define SPIFI_H
00019 
00020 #include "mbed.h"
00021 #include "spifi_rom_api.h"
00022 
00023 /**
00024  * SPIFI Example
00025  *
00026  * @code
00027  * #include "mbed.h"
00028  * #include "SPIFI.h"
00029  *
00030  * int main(void) {
00031  *    SPIFI::SpifiError err;
00032  *
00033  *    err = SPIFI::instance().init();
00034  *    if (err != SPIFI::Ok) {
00035  *        printf("Failed to initialize SPIFI, error %d\n", err);
00036  *    }
00037  *    
00038  *    // Write "Hello World!" into the first bytes of the SPIFI
00039  *    char buff[20] = "Hello World!";
00040  *    err = SPIFI::instance().program(0, strlen(buff)+1, buff, SPIFI::EraseAsRequired);
00041  *    if (err != SPIFI::Ok) {
00042  *        printf("Failed to write to SPIFI, error %d\n", err);
00043  *    }
00044  *
00045  *    // Now verify that it can be read
00046  *    if (memcmp((char*)SPIFI::SpifiMemBase, buff, strlen(buff)+1) == 0) {
00047  *        printf("Readback from memory OK: '%s'\n", SPIFI::SpifiMemBase);
00048  *    } else {
00049  *        printf("Spifi does not contain the correct data!\n");
00050  *    }
00051  * }
00052  * @endcode
00053  */
00054 class SPIFI {
00055 public:
00056   
00057     enum Constants {
00058         SpifiMemBase = 0x28000000
00059     };
00060 
00061     enum Options {
00062         ForceErase      = (0<<2),
00063         EraseAsRequired = (1<<2),
00064         CallerErase     = (1<<3)
00065     };
00066 
00067     enum SpifiError {
00068         Ok            =       0,
00069         Uninitialized =       1,
00070         Verification  =       2,
00071         SameAddress   =       3,
00072         UnknownError  =       4,
00073         InternalError = 0x20002,
00074         Timeout       = 0x20003,
00075         OperandError  = 0x20004,
00076         Status        = 0x20005,
00077         ExtDeviceId   = 0x20006,
00078         DeviceId      = 0x20007,
00079         DeviceType    = 0x20008,
00080         Manufacturer  = 0x20009,
00081         InvalidJDECId = 0x2000A,
00082         EraseConflict = 0x2000B,
00083     };
00084     
00085     enum Device {
00086         Spansion_S25FL032,      /* Manufacturer: 0x01, devType: 0x02, devID: 0x15 */
00087         Winbond_W25Q64FV,       /* Manufacturer: 0xEF, devType: 0x40, devID: 0x17 */
00088         Macronix_MX25L6435EM2I, /* Manufacturer: 0xC2, devType: 0x20, devID: 0x17 */
00089         UnknownDevice
00090     };
00091     
00092     static SPIFI& instance()
00093     {
00094         static SPIFI singleton;
00095         return singleton;
00096     }
00097   
00098 
00099     /** Initializes the SPIFI ROM driver making the content of the external serial flash available
00100      *
00101      *  @returns
00102      *       Ok on success
00103      *       An error code on failure
00104      */
00105     SpifiError init();
00106   
00107     /** Returns the detected external serial flash
00108      *
00109      *  @returns
00110      *       The detected device or UnknownDevice
00111      */
00112     Device device() { return _device; }
00113   
00114     /** Returns the size (in bytes) of the external serial flash
00115      *
00116      *  @returns
00117      *       The size in bytes
00118      */
00119     uint32_t memorySize() { return _memorySize; }
00120   
00121     /** Returns the size of an erase block (in bytes) on the external serial flash
00122      *
00123      *  @returns
00124      *       The erase block size in bytes
00125      */
00126     uint32_t eraseBlockSize() { return _eraseBlockSize; }
00127   
00128     /** Returns the address where the verifcation failed. Use only after a Verification error code 
00129      * has been retured from one of the other functions
00130      *
00131      *  @returns
00132      *       The address to where the program or erase operation failed
00133      */
00134     uint32_t getVerificationErrorAddr() { return _verError; }
00135     
00136     /** Used by the QSPIFileSystem class to get access to all spifi internal data.
00137      *
00138      *  @param initData  The parameter returned by spifi_init
00139      *  @param romPtr    The location of the SPIFI ROM driver in memory
00140      */
00141     void internalData(SPIFIobj** initData, const SPIFI_RTNS** romPtr) { *initData = _romData; *romPtr = _spifi; }
00142   
00143     /** Copies len data from src to dest. This function will split len > 256 into writes of 256 bytes each.
00144      *
00145      * Programming means that a bit can either be left at 0, or programmed from 1 to 0. Changing bits from 0 to 1 requires an erase operation.
00146      * While bits can be individually programmed from 1 to 0, erasing bits from 0 to 1 must be done in larger chunks (manufacturer dependant 
00147      * but typically 4Kbyte to 64KByte at a time).
00148      *
00149      * Specify how/when erasing is done with the options parameter:
00150      *
00151      *    - ForceErase causes len bytes to be erased starting at dest. If a scratch buffer (must be the size of an erase block) is
00152      *      provided then only the len bytes will be erased. If no scratch buffer is provided then the erase block surrounding
00153      *      dest will be erased. 
00154      * 
00155      *    - EraseAsRequired tests if the destination can be written to without erasing. If it can then no erasing is done. If it 
00156      *      can't then behaviour is the same as if ForceErase was specified. 
00157      * 
00158      *    - CallerErase tests if the destination can be written to without erasing. If it can then a data is written. If it 
00159      *      can't then an error code is returned and nothing is written. 
00160      *
00161      * Scratch should be NULL or the address of an area of RAM that the SPIFI driver can use 
00162      * to save data during erase operations. If provided, the scratch area should be as large 
00163      * as the smallest erase size that is available throughout the serial flash device. If scratch 
00164      * is NULL (zero) and an erase is necessary, any bytes in the first erase block before dest 
00165      * are left in erased state (all ones), as are any bytes in the last erase block after dest + len
00166      *
00167      *  @param dest      Address to write to, highest byte must be 0x00 or 0x28 as in 0x28000000
00168      *  @param len       Number of bytes to write
00169      *  @param src       Data to write
00170      *  @param options   How to handle content of destination
00171      *  @param verify    Should all writes be verified or not
00172      *  @param scratch   Used with ForceErase and EraseAsRequired option to preserve content of flash outside of
00173      *                   written area. Size of buffer must be at least the size of one erase block.
00174      *
00175      *  @returns
00176      *       Ok on success
00177      *       An error code on failure
00178      */
00179     SpifiError program(uint32_t dest, unsigned len, char* src, Options options, bool verify=false, char* scratch=NULL);
00180   
00181     /** Erases the content of the memory at the specified address
00182      *
00183      * Scratch should be NULL or the address of an area of RAM that the SPIFI driver can use 
00184      * to save data during erase operations. If provided, the scratch area should be as large 
00185      * as the smallest erase size that is available throughout the serial flash device. If scratch 
00186      * is NULL (zero) and an erase is necessary, any bytes in the first erase block before dest 
00187      * are left in erased state (all ones), as are any bytes in the last erase block after dest + len
00188      *
00189      *  @param dest      Address to start erasing at, highest byte must be 0x00 or 0x28 as in 0x28000000
00190      *  @param len       Number of bytes to erase
00191      *  @param verify    Should the erased area be verified to make sure it is all 0xff
00192      *  @param scratch   Used to preserve content of flash outside of erased area. 
00193      *                   Size of buffer must be at least the size of one erase block.
00194      *
00195      *  @returns
00196      *       Ok on success
00197      *       An error code on failure
00198      */
00199     SpifiError erase(uint32_t dest, unsigned len, char* src, bool verify=false, char* scratch=NULL);
00200   
00201 
00202 private:
00203 
00204     uint32_t _verError;
00205     
00206     bool _initialized;
00207     
00208     Device _device;
00209     uint32_t _memorySize;
00210     uint32_t _eraseBlockSize;
00211 
00212     SPIFIobj* _romData;
00213     const SPIFI_RTNS* _spifi;
00214 
00215     char _addrConflictBuff[256];
00216 
00217     explicit SPIFI();
00218     // hide copy constructor
00219     SPIFI(const SPIFI&);
00220     // hide assign operator
00221     SPIFI& operator=(const SPIFI&);
00222     ~SPIFI();
00223 
00224     SpifiError translateError(int err, bool verify = false);
00225 };
00226 
00227 #endif
00228