drivers/spiflash/spiflash.h

   1 /**************************************************************************/
   2 /*!
   3     @file     spiflash.h
   4     @author   K. Townsend (microBuilder.eu)
   5
   6     @section LICENSE
   7
   8     Software License Agreement (BSD License)
   9
  10     Copyright (c) 2010, microBuilder SARL
  11     All rights reserved.
  12
  13     Redistribution and use in source and binary forms, with or without
  14     modification, are permitted provided that the following conditions are met:
  15     1. Redistributions of source code must retain the above copyright
  16     notice, this list of conditions and the following disclaimer.
  17     2. Redistributions in binary form must reproduce the above copyright
  18     notice, this list of conditions and the following disclaimer in the
  19     documentation and/or other materials provided with the distribution.
  20     3. Neither the name of the copyright holders nor the
  21     names of its contributors may be used to endorse or promote products
  22     derived from this software without specific prior written permission.
  23
  24     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS'' AND ANY
  25     EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  26     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  27     DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY
  28     DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  29     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  30     LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  31     ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  32     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  33     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34 */
  35 /**************************************************************************/
  36
  37 #ifndef _SPIFLASH_H_
  38 #define _SPIFLASH_H_
  39
  40 #include "projectconfig.h"
  41
  42 /**************************************************************************/
  43 /*!
  44     @brief  Error messages
  45 */
  46 /**************************************************************************/
  47 typedef enum
  48 {
  49   SPIFLASH_ERROR_OK = 0,                    // Everything executed normally
  50   SPIFLASH_ERROR_ADDROUTOFRANGE = 1,        // Address out of range
  51   SPIFLASH_ERROR_TIMEOUT_READY = 2,         // Timeout waiting for ready status
  52   SPIFLASH_ERROR_WRITEERR = 3,              // Write Error
  53   SPIFLASH_ERROR_PROTECTIONERR = 4,         // Write Protection Error
  54   SPIFLASH_ERROR_ADDROVERFLOW = 5,          // Address overflow during read/write
  55   SPIFLASH_ERROR_UNEXPECTEDID = 6,          // The manufacturer and/or device ID are different than expected
  56   SPIFLASH_ERROR_NOTSTARTOFPAGE = 7,        // The supplied address is not the start of a new page
  57   SPIFLASH_ERROR_DATAEXCEEDSPAGESIZE = 9,   // When writing page data, you can't exceed page size
  58   SPIFLASH_ERROR_PAGEWRITEOVERFLOW = 10,    // Page data will overflow beause (start address + len) > page size
  59   SPIFLASH_ERROR_LAST
  60 }
  61 spiflashError_e;
  62
  63 /**************************************************************************/
  64 /*!
  65     @brief  Describes the storage capacity of the SPI flash, including the
  66             size of the minimum HW write (page) and erase (sector) units.
  67 */
  68 /**************************************************************************/
  69 typedef struct
  70 {
  71   uint32_t pageSize;                    // Page size to write data (in bytes)
  72   uint32_t pageCount;                   // Number of pages
  73   uint32_t sectorSize;                  // Sector size to erase data (in bytes)
  74   uint32_t sectorCount;                 // Number of sectors
  75 }
  76 spiflashSizeInfo_t;
  77
  78 /**************************************************************************/
  79 /*!
  80     @brief Tries to initialise the flash device, and sets up any HW
  81            required by the SPI flash
  82 */
  83 /**************************************************************************/
  84 void spiflashInit (void);
  85
  86 /**************************************************************************/
  87 /*!
  88     @brief Gets an instance of spiflashSizeInfo_t that describes the
  89            storage limits of the SPI flash like page size (minimum write
  90            size) and sector size (minimum erase size).
  91 */
  92 /**************************************************************************/
  93 spiflashSizeInfo_t spiflashGetSizeInfo(void);
  94
  95 /**************************************************************************/
  96 /*!
  97     @brief Gets the 8-bit manufacturer ID and device ID for the flash
  98
  99     @param[out] *manufID
 100                 Pointer to the uint8_t that will store the manufacturer ID
 101     @param[out] *deviceID
 102                 Pointer to the uint8_t that will store the device ID
 103 */
 104 /**************************************************************************/
 105 void spiflashGetManufacturerInfo (uint8_t *manufID, uint8_t *deviceID);
 106
 107 /**************************************************************************/
 108 /*!
 109     @brief Sets the write flag on the SPI flash, and if required puts the
 110            WP pin in an appropriate state
 111
 112     @param[in]  enable
 113                 True (1) to enable writing, false (0) to disable it
 114 */
 115 /**************************************************************************/
 116 void spiflashWriteEnable (bool enable);
 117
 118 /**************************************************************************/
 119 /*!
 120     @brief Reads the specified number of bytes from the supplied address.
 121
 122     This function will read one or more bytes starting at the supplied
 123     address. Please note that bufferLength is zero-based, meaning you
 124     should  supply '0' to read a single byte, '3' to read 4 bytes of data,
 125     etc.
 126
 127     @param[in]  address
 128                 The 24-bit address where the read will start.
 129     @param[out] *buffer
 130                 Pointer to the buffer that will store the read results
 131     @param[in]  len
 132                 Length of the buffer.
 133
 134     @section EXAMPLE
 135
 136     @code
 137     uint8_t buffer[64];
 138     spiflashError_e error;
 139     error = spiflashReadBuffer (0, buffer, 64);
 140     if (error)
 141     {
 142       // Check what went wrong
 143       switch (error)
 144       {
 145         case SPIFLASH_ERROR_ADDROUTOFRANGE:
 146           // Specified starting address is out of range
 147           break;
 148         case SPIFLASH_ERROR_TIMEOUT_READY:
 149           // Timed out waiting for flash to return ready state
 150           break;
 151         case SPIFLASH_ERROR_ADDROVERFLOW:
 152           // Ran over the upper address during read
 153           break;
 154       }
 155     }
 156     @endcode
 157 */
 158 /**************************************************************************/
 159 spiflashError_e spiflashReadBuffer (uint32_t address, uint8_t *buffer, uint32_t len);
 160
 161 /**************************************************************************/
 162 /*!
 163     @brief Erases the contents of a single sector
 164
 165     @param[in]  sectorNumber
 166                 The sector number to erase (zero-based).
 167
 168     @section  EXAMPLE
 169
 170     @code
 171     spiflashError_e error;
 172     error = spiflashEraseSector(0);
 173     if (error)
 174     {
 175       // Check what went wrong
 176       switch (error)
 177       {
 178         case SPIFLASH_ERROR_ADDROUTOFRANGE:
 179           // Specified starting address is out of range
 180           break;
 181         case SPIFLASH_ERROR_PROTECTIONERR:
 182           // Couldn't set the write enable bit
 183           break;
 184         case SPIFLASH_ERROR_TIMEOUT_READY:
 185           // Timed out waiting for flash to return ready state
 186           break;
 187       }
 188     }
 189     @endcode
 190 */
 191 /**************************************************************************/
 192 spiflashError_e spiflashEraseSector (uint32_t sectorNumber);
 193
 194 /**************************************************************************/
 195 /*!
 196     @brief Erases the entire flash chip
 197
 198     @section  EXAMPLE
 199
 200     @code
 201     spiflashError_e error;
 202     error = spiflashEraseChip();
 203     if (error)
 204     {
 205       // Check what went wrong
 206       switch (error)
 207       {
 208         case SPIFLASH_ERROR_PROTECTIONERR:
 209           // Couldn't set the write enable bit
 210           break;
 211         case SPIFLASH_ERROR_TIMEOUT_READY:
 212           // Timed out waiting for flash to return ready state
 213           break;
 214       }
 215     }
 216     @endcode
 217 */
 218 /**************************************************************************/
 219 spiflashError_e spiflashEraseChip (void);
 220
 221 /**************************************************************************/
 222 /*!
 223     @brief      Writes up to 256 bytes of data to the specified page.
 224
 225     @note       Before writing data to a page, make sure that the 4K sector
 226                 containing the specific page has been erased, otherwise the
 227                 data will be meaningless.
 228
 229     @param[in]  address
 230                 The 24-bit address where the write will start.
 231     @param[out] *buffer
 232                 Pointer to the buffer that will store the read results
 233     @param[in]  len
 234                 Length of the buffer.  Valid values are from 1 to 256,
 235                 within the limits of the starting address and page length.
 236
 237     @section  EXAMPLE
 238
 239     @code
 240     spiflashError_e error;
 241     uint8_t buffer[256];
 242
 243     buffer[0] = 0x12;
 244     buffer[1] = 0x34;
 245     buffer[2] = 0x56;
 246     buffer[3] = 0x78;
 247     buffer[4] = 0xDE;
 248     buffer[5] = 0xAD;
 249     buffer[6] = 0xC0;
 250     buffer[7] = 0xDE;
 251
 252     error = spiflashWritePage (0, buffer, 8);
 253     if (error)
 254     {
 255       // Check what went wrong
 256       switch (error)
 257       {
 258         case SPIFLASH_ERROR_ADDROUTOFRANGE:
 259           // Specified starting address is out of range
 260           break;
 261         case SPIFLASH_ERROR_DATAEXCEEDSPAGESIZE:
 262           // Supplied data exceeds max page size
 263           break;
 264         case SPIFLASH_ERROR_PAGEWRITEOVERFLOW:
 265           // The data length plus the start address offset exceeeds page limits
 266           break;
 267         case SPIFLASH_ERROR_TIMEOUT_READY:
 268           // Timeout waiting for ready status (can be pre or post write)
 269           break;
 270         case SPIFLASH_ERROR_PROTECTIONERR:
 271           // Unable to set write latch
 272           break;
 273       }
 274     }
 275     @endcode
 276 */
 277 /**************************************************************************/
 278 spiflashError_e spiflashWritePage (uint32_t address, uint8_t *buffer, uint32_t len);
 279
 280 /**************************************************************************/
 281 /*!
 282     @brief      Writes a continuous stream of data that will automatically
 283                 cross page boundaries.
 284
 285     @note       Before writing data, make sure that the appropriate sectors
 286                 have been erased, otherwise the data will be meaningless.
 287
 288     @param[in]  address
 289                 The 24-bit address where the write will start.
 290     @param[out] *buffer
 291                 Pointer to the buffer that will store the read results
 292     @param[in]  len
 293                 Length of the buffer, within the limits of the starting
 294                 address and size of the flash device.
 295
 296     @section  EXAMPLE
 297
 298     @code
 299     spiflashError_e error;
 300     uint8_t buffer[256];
 301
 302     buffer[0] = 0x12;
 303     buffer[1] = 0x34;
 304     buffer[2] = 0x56;
 305     buffer[3] = 0x78;
 306     buffer[4] = 0xDE;
 307     buffer[5] = 0xAD;
 308     buffer[6] = 0xC0;
 309     buffer[7] = 0xDE;
 310
 311     error = spiflashWrite (0, buffer, 8);
 312     if (error)
 313     {
 314       // Check what went wrong
 315       switch (error)
 316       {
 317         case SPIFLASH_ERROR_ADDROUTOFRANGE:
 318           // Specified starting address is out of range
 319           break;
 320         case SPIFLASH_ERROR_DATAEXCEEDSPAGESIZE:
 321           // Supplied data exceeds max page size
 322           break;
 323         case SPIFLASH_ERROR_PAGEWRITEOVERFLOW:
 324           // The data length plus the start address offset exceeeds page limits
 325           break;
 326         case SPIFLASH_ERROR_TIMEOUT_READY:
 327           // Timeout waiting for ready status (can be pre or post write)
 328           break;
 329         case SPIFLASH_ERROR_PROTECTIONERR:
 330           // Unable to set write latch
 331           break;
 332       }
 333     }
 334     @endcode
 335 */
 336 /**************************************************************************/
 337 spiflashError_e spiflashWrite (uint32_t address, uint8_t *buffer, uint32_t len);
 338
 339 #endif