SPIFI.h

00001 /*
00002  *  Copyright 2014 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_MX25L6435E,  /* Manufacturer: 0xC2, devType: 0x20, devID: 0x17 */
00089         Macronix_MX25L12835F, /* Manufacturer: 0xC2, devType: 0x20, devID: 0x18 */
00090         SpecifiedInBios,      /* The device is known by the BIOS */
00091         UnknownDevice
00092     };
00093     
00094     static SPIFI& instance()
00095     {
00096         static SPIFI singleton;
00097         return singleton;
00098     }
00099   
00100 
00101     /** Initializes the SPIFI ROM driver making the content of the external serial flash available
00102      *
00103      *  @returns
00104      *       Ok on success
00105      *       An error code on failure
00106      */
00107     SpifiError init();
00108   
00109     /** Returns the detected external serial flash
00110      *
00111      *  @returns
00112      *       The detected device or UnknownDevice
00113      */
00114     Device device() { return _device; }
00115   
00116     /** Returns the size (in bytes) of the external serial flash
00117      *
00118      *  @returns
00119      *       The size in bytes
00120      */
00121     uint32_t memorySize() { return _memorySize; }
00122   
00123     /** Returns the size of an erase block (in bytes) on the external serial flash
00124      *
00125      *  @returns
00126      *       The erase block size in bytes
00127      */
00128     uint32_t eraseBlockSize() { return _eraseBlockSize; }
00129   
00130     /** Returns the address where the verifcation failed. Use only after a Verification error code 
00131      * has been retured from one of the other functions
00132      *
00133      *  @returns
00134      *       The address to where the program or erase operation failed
00135      */
00136     uint32_t getVerificationErrorAddr() { return _verError; }
00137     
00138     /** Used by the QSPIFileSystem class to get access to all spifi internal data.
00139      *
00140      *  @param initData  The parameter returned by spifi_init
00141      *  @param romPtr    The location of the SPIFI ROM driver in memory
00142      */
00143     void internalData(SPIFIobj** initData, const SPIFI_RTNS** romPtr) { *initData = _romData; *romPtr = _spifi; }
00144   
00145     /** Copies len data from src to dest. This function will split len > 256 into writes of 256 bytes each.
00146      *
00147      * 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.
00148      * While bits can be individually programmed from 1 to 0, erasing bits from 0 to 1 must be done in larger chunks (manufacturer dependant 
00149      * but typically 4Kbyte to 64KByte at a time).
00150      *
00151      * Specify how/when erasing is done with the options parameter:
00152      *
00153      *    - ForceErase causes len bytes to be erased starting at dest. If a scratch buffer (must be the size of an erase block) is
00154      *      provided then only the len bytes will be erased. If no scratch buffer is provided then the erase block surrounding
00155      *      dest will be erased. 
00156      * 
00157      *    - EraseAsRequired tests if the destination can be written to without erasing. If it can then no erasing is done. If it 
00158      *      can't then behaviour is the same as if ForceErase was specified. 
00159      * 
00160      *    - CallerErase tests if the destination can be written to without erasing. If it can then a data is written. If it 
00161      *      can't then an error code is returned and nothing is written. 
00162      *
00163      * Scratch should be NULL or the address of an area of RAM that the SPIFI driver can use 
00164      * to save data during erase operations. If provided, the scratch area should be as large 
00165      * as the smallest erase size that is available throughout the serial flash device. If scratch 
00166      * is NULL (zero) and an erase is necessary, any bytes in the first erase block before dest 
00167      * are left in erased state (all ones), as are any bytes in the last erase block after dest + len
00168      *
00169      *  @param dest      Address to write to, highest byte must be 0x00 or 0x28 as in 0x28000000
00170      *  @param len       Number of bytes to write
00171      *  @param src       Data to write
00172      *  @param options   How to handle content of destination
00173      *  @param verify    Should all writes be verified or not
00174      *  @param scratch   Used with ForceErase and EraseAsRequired option to preserve content of flash outside of
00175      *                   written area. Size of buffer must be at least the size of one erase block.
00176      *
00177      *  @returns
00178      *       Ok on success
00179      *       An error code on failure
00180      */
00181     SpifiError program(uint32_t dest, unsigned len, char* src, Options options, bool verify=false, char* scratch=NULL);
00182   
00183     /** Erases the content of the memory at the specified address
00184      *
00185      * Scratch should be NULL or the address of an area of RAM that the SPIFI driver can use 
00186      * to save data during erase operations. If provided, the scratch area should be as large 
00187      * as the smallest erase size that is available throughout the serial flash device. If scratch 
00188      * is NULL (zero) and an erase is necessary, any bytes in the first erase block before dest 
00189      * are left in erased state (all ones), as are any bytes in the last erase block after dest + len
00190      *
00191      *  @param dest      Address to start erasing at, highest byte must be 0x00 or 0x28 as in 0x28000000
00192      *  @param len       Number of bytes to erase
00193      *  @param verify    Should the erased area be verified to make sure it is all 0xff
00194      *  @param scratch   Used to preserve content of flash outside of erased area. 
00195      *                   Size of buffer must be at least the size of one erase block.
00196      *
00197      *  @returns
00198      *       Ok on success
00199      *       An error code on failure
00200      */
00201     SpifiError erase(uint32_t dest, unsigned len, bool verify=false, char* scratch=NULL);
00202   
00203 
00204 private:
00205 
00206     uint32_t _verError;
00207     
00208     bool _initialized;
00209     
00210     Device _device;
00211     uint32_t _memorySize;
00212     uint32_t _eraseBlockSize;
00213 
00214     SPIFIobj* _romData;
00215     const SPIFI_RTNS* _spifi;
00216 
00217     char _addrConflictBuff[256];
00218 
00219     explicit SPIFI();
00220     // hide copy constructor
00221     SPIFI(const SPIFI&);
00222     // hide assign operator
00223     SPIFI& operator=(const SPIFI&);
00224     ~SPIFI();
00225 
00226     SpifiError translateError(int err, bool verify = false);
00227 };
00228 
00229 #endif