SAMV71 Xplained Ultra Software Package 1.3

at26.h

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