SAMV71 Xplained Ultra Software Package 1.5

at26.h

00001 /* ---------------------------------------------------------------------------- */
00002 /*                  Atmel Microcontroller Software Support                      */
00003 /*                       SAM Software Package License                           */
00004 /* ---------------------------------------------------------------------------- */
00005 /* Copyright (c) 2015, Atmel Corporation                                        */
00006 /*                                                                              */
00007 /* All rights reserved.                                                         */
00008 /*                                                                              */
00009 /* Redistribution and use in source and binary forms, with or without           */
00010 /* modification, are permitted provided that the following condition is met:    */
00011 /*                                                                              */
00012 /* - Redistributions of source code must retain the above copyright notice,     */
00013 /* this list of conditions and the disclaimer below.                            */
00014 /*                                                                              */
00015 /* Atmel's name may not be used to endorse or promote products derived from     */
00016 /* this software without specific prior written permission.                     */
00017 /*                                                                              */
00018 /* DISCLAIMER:  THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR   */
00019 /* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF */
00020 /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE   */
00021 /* DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,      */
00022 /* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT */
00023 /* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,  */
00024 /* OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF    */
00025 /* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING         */
00026 /* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, */
00027 /* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                           */
00028 /* ---------------------------------------------------------------------------- */
00029 
00030 //------------------------------------------------------------------------------
00031 /// \unit
00032 ///
00033 /// !Purpose
00034 ///
00035 /// The AT26 serial firmware Dataflash driver is based on top of the
00036 /// corresponding Spi driver. A Dataflash structure instance has to be
00037 /// initialized using the DF_Init function. Then basic dataflash
00038 /// operations can be launched using macros such as DF_continuous_read.
00039 /// These macros invoke the DF_Command() function which invokes the
00040 /// DPI low driver using the SPI_SendCommand() function.
00041 /// Beware to compute the dataflash internal address, the dataflash sector
00042 /// description must be known (DataflashDesc). Dataflash can be automatically
00043 /// detected using the DF_Scan() function.
00044 ///
00045 /// !Usage
00046 ///
00047 /// -# Initializes an AT26 instance and configures SPI chip select pin
00048 ///    using AT26_Configure().
00049 /// -# Detect DF and returns DF description corresponding to the device
00050 ///    connected using AT26_FindDevice().This function shall be called by
00051 ///    the application before AT26_SendCommand().
00052 /// -# Sends a command to the DF through the SPI using AT26_SendCommand().
00053 ///    The command is identified by its command code and the number of
00054 ///    bytes to transfer.
00055 ///    -# Example code for sending command to write a page to DF.
00056 /// \code
00057 ///    // Program page
00058 ///    error = AT26_SendCommand(pAt26, AT26_BYTE_PAGE_PROGRAM, 4,
00059 ///            pData, writeSize, address, 0, 0);
00060 /// \endcode
00061 ///    -# Example code for sending command to read a page from DF.
00062 ///       If data needs to be received, then a data buffer must be
00063 ///       provided.
00064 /// \code
00065 ///    // Start a read operation
00066 ///    error = AT26_SendCommand(pAt26, AT26_READ_ARRAY_LF,
00067 ///            4, pData, size, address, 0, 0);
00068 /// \endcode
00069 ///    -# This function does not block; its optional callback will
00070 ///       be invoked when the transfer completes.
00071 /// -# Check the AT26 driver is ready or not by polling AT26_IsBusy().
00072 ///
00073 //------------------------------------------------------------------------------
00074 #ifndef AT26_H
00075 #define AT26_H
00076 
00077 //------------------------------------------------------------------------------
00078 //         Headers
00079 //------------------------------------------------------------------------------
00080 
00081 //#include "chip.h"
00082 
00083 //------------------------------------------------------------------------------
00084 //         Macros
00085 //------------------------------------------------------------------------------
00086 
00087 #define AT26_Size(pAt26)            ((pAt26)->pDesc->size)
00088 #define AT26_PageSize(pAt26)        ((pAt26)->pDesc->pageSize)
00089 #define AT26_BlockSize(pAt26)       ((pAt26)->pDesc->blockSize)
00090 #define AT26_Name(pAt26)            ((pAt26)->pDesc->name)
00091 #define AT26_PageNumber(pAt26)      (AT26_Size(pAt26) / AT26_PageSize(pAt26))
00092 #define AT26_BlockNumber(pAt26)     (AT26_Size(pAt26) / AT26_BlockSize(pAt26))
00093 #define AT26_PagePerBlock(pAt26)    (AT26_BlockSize(pAt26) / AT26_PageSize(pAt26))
00094 #define AT26_BlockEraseCmd(pAt26)   ((pAt26)->pDesc->blockEraseCmd)
00095 
00096 //------------------------------------------------------------------------------
00097 //         Definitions
00098 //------------------------------------------------------------------------------
00099 
00100 /// Device is protected, operation cannot be carried out.
00101 #define AT26_ERROR_PROTECTED        1
00102 /// Device is busy executing a command.
00103 #define AT26_ERROR_BUSY             2
00104 /// There was a problem while trying to program page data.
00105 #define AT26_ERROR_PROGRAM          3
00106 /// There was an SPI communication error.
00107 #define AT26_ERROR_SPI              4
00108 
00109 /// Device ready/busy status bit.
00110 #define AT26_STATUS_RDYBSY          (1 << 0)
00111 /// Device is ready.
00112 #define AT26_STATUS_RDYBSY_READY    (0 << 0)
00113 /// Device is busy with internal operations.
00114 #define AT26_STATUS_RDYBSY_BUSY     (1 << 0)
00115 /// Write enable latch status bit.
00116 #define AT26_STATUS_WEL             (1 << 1)
00117 /// Device is not write enabled.
00118 #define AT26_STATUS_WEL_DISABLED    (0 << 1)
00119 /// Device is write enabled.
00120 #define AT26_STATUS_WEL_ENABLED     (1 << 1)
00121 /// Software protection status bitfield.
00122 #define AT26_STATUS_SWP             (3 << 2)
00123 /// All sectors are software protected.
00124 #define AT26_STATUS_SWP_PROTALL     (3 << 2)
00125 /// Some sectors are software protected.
00126 #define AT26_STATUS_SWP_PROTSOME    (1 << 2)
00127 /// No sector is software protected.
00128 #define AT26_STATUS_SWP_PROTNONE    (0 << 2)
00129 /// Write protect pin status bit.
00130 #define AT26_STATUS_WPP             (1 << 4)
00131 /// Write protect signal is not asserted.
00132 #define AT26_STATUS_WPP_NOTASSERTED (0 << 4)
00133 /// Write protect signal is asserted.
00134 #define AT26_STATUS_WPP_ASSERTED    (1 << 4)
00135 /// Erase/program error bit.
00136 #define AT26_STATUS_EPE             (1 << 5)
00137 /// Erase or program operation was successful.
00138 #define AT26_STATUS_EPE_SUCCESS     (0 << 5)
00139 /// Erase or program error detected.
00140 #define AT26_STATUS_EPE_ERROR       (1 << 5)
00141 /// Sector protection registers locked bit.
00142 #define AT26_STATUS_SPRL            (1 << 7)
00143 /// Sector protection registers are unlocked.
00144 #define AT26_STATUS_SPRL_UNLOCKED   (0 << 7)
00145 /// Sector protection registers are locked.
00146 #define AT26_STATUS_SPRL_LOCKED     (1 << 7)
00147 
00148 /// Read array command code.
00149 #define AT26_READ_ARRAY             0x0B
00150 /// Read array (low frequency) command code.
00151 #define AT26_READ_ARRAY_LF          0x03
00152 /// Block erase command code (4K block).
00153 #define AT26_BLOCK_ERASE_4K         0x20
00154 /// Block erase command code (32K block).
00155 #define AT26_BLOCK_ERASE_32K        0x52
00156 /// Block erase command code (64K block).
00157 #define AT26_BLOCK_ERASE_64K        0xD8
00158 /// Chip erase command code 1.
00159 #define AT26_CHIP_ERASE_1           0x60
00160 /// Chip erase command code 2.
00161 #define AT26_CHIP_ERASE_2           0xC7
00162 /// Byte/page program command code.
00163 #define AT26_BYTE_PAGE_PROGRAM      0x02
00164 /// Sequential program mode command code 1.
00165 #define AT26_SEQUENTIAL_PROGRAM_1   0xAD
00166 /// Sequential program mode command code 2.
00167 #define AT26_SEQUENTIAL_PROGRAM_2   0xAF
00168 /// Write enable command code.
00169 #define AT26_WRITE_ENABLE           0x06
00170 /// Write disable command code.
00171 #define AT26_WRITE_DISABLE          0x04
00172 /// Protect sector command code.
00173 #define AT26_PROTECT_SECTOR         0x36
00174 /// Unprotect sector command code.
00175 #define AT26_UNPROTECT_SECTOR       0x39
00176 /// Read sector protection registers command code.
00177 #define AT26_READ_SECTOR_PROT       0x3C
00178 /// Read status register command code.
00179 #define AT26_READ_STATUS            0x05
00180 /// Write status register command code.
00181 #define AT26_WRITE_STATUS           0x01
00182 /// Read manufacturer and device ID command code.
00183 #define AT26_READ_JEDEC_ID          0x9F
00184 /// Deep power-down command code.
00185 #define AT26_DEEP_PDOWN             0xB9
00186 /// Resume from deep power-down command code.
00187 #define AT26_RES_DEEP_PDOWN         0xAB
00188 
00189 //------------------------------------------------------------------------------
00190 //         Types
00191 //------------------------------------------------------------------------------
00192 
00193 //------------------------------------------------------------------------------
00194 /// Describes a serial firmware flash device parameters.
00195 //------------------------------------------------------------------------------
00196 typedef struct _At26Desc {
00197 
00198     /// Device string name.
00199     const char *name;
00200     /// JEDEC ID of device.
00201     unsigned int jedecId;
00202     /// Size of device in bytes.
00203     unsigned int size;
00204     /// Size of one page in bytes.
00205     unsigned int pageSize;
00206     /// Block erase size in bytes.
00207     unsigned int blockSize;
00208     /// Block erase command.
00209     unsigned int blockEraseCmd;
00210 
00211 } At26Desc;
00212 
00213 //------------------------------------------------------------------------------
00214 /// Serial flash driver structure. Holds the current state of the driver,
00215 /// including the current command and the descriptor for the underlying device.
00216 //------------------------------------------------------------------------------
00217 typedef struct _At26 {
00218 
00219     /// Pointer to the underlying SPI driver.
00220     Spid *pSpid;
00221     /// Current SPI command sent to the SPI driver.
00222     SpidCmd command;
00223     /// Pointer to a descriptor for the serial firmware flash device.
00224     const At26Desc *pDesc;
00225     /// Command buffer.
00226     unsigned int pCmdBuffer[2];
00227 
00228 } At26;
00229 
00230 //------------------------------------------------------------------------------
00231 //         Exported functions
00232 //------------------------------------------------------------------------------
00233 
00234 extern void AT26_Configure(At26 *pAt26, Spid *pSpid, unsigned char cs);
00235 
00236 extern unsigned char AT26_SendCommand(
00237     At26 *pAt26,
00238     unsigned char cmd,
00239     unsigned char cmdSize,
00240     unsigned char *pData,
00241     unsigned int dataSize,
00242     unsigned int address,
00243     SpidCallback callback,
00244     void *pArgument);
00245 
00246 extern unsigned char AT26_IsBusy(At26 *pAt26);
00247 
00248 extern const At26Desc *AT26_FindDevice(
00249     At26 *pAt26,
00250     unsigned int jedecId);
00251 
00252 #endif //#ifndef AT26_H
00253 
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines