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_LAST
  57 }
  58 spiflashError_e;
  59
  60 /**************************************************************************/
  61 /*!
  62     @brief  Describes the storage capacity of the SPI flash, including the
  63             size of the minimum HW write (page) and erase (sector) units.
  64 */
  65 /**************************************************************************/
  66 typedef struct
  67 {
  68   uint32_t pageSize;                    // Page size to write data (in bytes)
  69   uint32_t pageCount;                   // Number of pages
  70   uint32_t sectorSize;                  // Sector size to erase data (in bytes)
  71   uint32_t sectorCount;                 // Number of sectors
  72 }
  73 spiflashSizeInfo_t;
  74
  75 /**************************************************************************/
  76 /*!
  77     @brief Tries to initialise the flash device, and setups any HW
  78            required by the SPI flash
  79 */
  80 /**************************************************************************/
  81 void spiflashInit (void);
  82
  83 /**************************************************************************/
  84 /*!
  85     @brief Gets an instance of spiflashSizeInfo_t that describes the
  86            storage limits of the SPI flash like page size (minimum write
  87            size) and sector size (minimum erase size).
  88 */
  89 /**************************************************************************/
  90 spiflashSizeInfo_t spiflashGetSizeInfo(void);
  91
  92 /**************************************************************************/
  93 /*!
  94     @brief Gets the 8-bit manufacturer ID and device ID for the flash
  95
  96     @param[out] *manufID
  97                 Pointer to the uint8_t that will store the manufacturer ID
  98     @param[out] *deviceID
  99                 Pointer to the uint8_t that will store the device ID
 100 */
 101 /**************************************************************************/
 102 void spiflashGetManufacturerInfo (uint8_t *manufID, uint8_t *deviceID);
 103
 104 /**************************************************************************/
 105 /*!
 106     @brief Sets the write flag on the SPI flash, and if required puts the
 107            WP pin in an appropriate state
 108
 109     @param[in]  enable
 110                 True (1) to enable writing, false (0) to disable it
 111 */
 112 /**************************************************************************/
 113 void spiflashWriteEnable (bool enable);
 114
 115 /**************************************************************************/
 116 /*!
 117     @brief Reads the specified number of bytes from the supplied address.
 118
 119     This function will read one or more bytes starting at the supplied
 120     address. Please note that bufferLength is zero-based, meaning you
 121     should  supply '0' to read a single byte, '3' to read 4 bytes of data,
 122     etc.
 123
 124     @param[in]  address
 125                 The 24-bit address where the read will start.
 126     @param[out] *buffer
 127                 Pointer to the buffer that will store the read results
 128     @param[in]  len
 129                 Length of the buffer (zero-based).
 130
 131     @section EXAMPLE
 132
 133     @code
 134     uint8_t buffer[64];
 135     spiflashError_e error;
 136     error = spiflashReadBuffer (0, buffer, 64);
 137     if (error)
 138     {
 139       // Check what went wrong
 140       switch (error)
 141       {
 142         case SPIFLASH_ERROR_ADDROUTOFRANGE:
 143           // Specified starting address is out of range
 144           break;
 145         case SPIFLASH_ERROR_TIMEOUT_READY:
 146           // Timed out waiting for flash to return ready state
 147           break;
 148         case SPIFLASH_ERROR_ADDROVERFLOW:
 149           // Ran over the upper address during read
 150           break;
 151       }
 152     }
 153     @endcode
 154 */
 155 /**************************************************************************/
 156 spiflashError_e spiflashReadBuffer (uint32_t address, uint8_t *buffer, uint32_t len);
 157
 158 /**************************************************************************/
 159 /*!
 160     @brief Writes a single byte to the SPI flash
 161
 162     @param[in]  address
 163                 The 24-bit address where the read will start.
 164     @param[out] *buffer
 165                 Pointer to the buffer that will store the read results
 166     @param[in]  len
 167                 Length of the buffer (zero-based).
 168 */
 169 /**************************************************************************/
 170 spiflashError_e spiflashWriteBuffer (uint32_t address, uint8_t *buffer, uint32_t len);
 171
 172 /**************************************************************************/
 173 /*!
 174     @brief Erases the contents of a single sector
 175
 176     @param[in]  sectorNumber
 177                 The sector number to erase (zero-based).
 178
 179     @section  EXAMPLE
 180
 181     @code
 182     spiflashError_e error;
 183     error = spiflashEraseSector(0);
 184     if (error)
 185     {
 186       // Check what went wrong
 187       switch (error)
 188       {
 189         case SPIFLASH_ERROR_ADDROUTOFRANGE:
 190           // Specified starting address is out of range
 191           break;
 192         case SPIFLASH_ERROR_PROTECTIONERR:
 193           // Couldn't set the write enable bit
 194           break;
 195         case SPIFLASH_ERROR_TIMEOUT_READY:
 196           // Timed out waiting for flash to return ready state
 197           break;
 198       }
 199     }
 200     @endcode
 201 */
 202 /**************************************************************************/
 203 spiflashError_e spiflashEraseSector (uint32_t sectorNumber);
 204
 205 /**************************************************************************/
 206 /*!
 207     @brief Erases the entire flash chip
 208
 209     @section  EXAMPLE
 210
 211     @code
 212     spiflashError_e error;
 213     error = spiflashEraseChip();
 214     if (error)
 215     {
 216       // Check what went wrong
 217       switch (error)
 218       {
 219         case SPIFLASH_ERROR_PROTECTIONERR:
 220           // Couldn't set the write enable bit
 221           break;
 222         case SPIFLASH_ERROR_TIMEOUT_READY:
 223           // Timed out waiting for flash to return ready state
 224           break;
 225       }
 226     }
 227     @endcode
 228 */
 229 /**************************************************************************/
 230 spiflashError_e spiflashEraseChip (void);
 231
 232 #endif