pdk_k2g_1_0_1/packages/ti/board/src/idkAM571x/device/qspi_flash.h

   1 /**
   2  *  \file   S25FL.h
   3  *
   4  *  \brief  Header file for S25FL QSPI Nor Flash driver.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2014 Texas Instruments Incorporated - http://www.ti.com/
  10  *
  11  * Redistribution and use in source and binary forms, with or without
  12  * modification, are permitted provided that the following conditions
  13  * are met:
  14  *
  15  * Redistributions of source code must retain the above copyright
  16  * notice, this list of conditions and the following disclaimer.
  17  *
  18  * Redistributions in binary form must reproduce the above copyright
  19  * notice, this list of conditions and the following disclaimer in the
  20  * documentation and/or other materials provided with the
  21  * distribution.
  22  *
  23  * Neither the name of Texas Instruments Incorporated nor the names of
  24  * its contributors may be used to endorse or promote products derived
  25  * from this software without specific prior written permission.
  26  *
  27  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  28  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  29  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  30  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  31  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  32  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  33  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  34  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  35  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  36  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  37  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  38  *
  39  */
  40
  41 #ifndef __S25FL_H
  42 #define __S25FL_H
  43
  44 #ifdef __cplusplus
  45 extern "C" {
  46 #endif
  47
  48 #include <stdint.h>
  49 #include <stddef.h>
  50 #include <stdbool.h>
  51
  52 /* TI-RTOS Header files */
  53 #include <ti/drv/spi/SPI.h>
  54
  55 /*!
  56  *  @brief Flash device size in bytes.
  57  */
  58 #define S25FL_FLASH_DEVICE_SIZE        (32 * 1024 *1024)
  59
  60 /*!
  61  *  @brief Flash block size in bytes.
  62  */
  63 #define S25FL_FLASH_BLOCK_SIZE         (64 * 1024)
  64
  65 /*!
  66  *  @brief Flash sector size in bytes.
  67  */
  68 #define S25FL_FLASH_SECTOR_SIZE        (4 * 1024)
  69
  70 /*!
  71  *  @brief Flash device ID.
  72  */
  73 #define S25FL_FLASH_DEVICE_ID          (0x18)
  74
  75 /*!
  76  *  @brief Macro to enable quad mode.
  77  */
  78 #define QSPI_FLASH_QUAD_ENABLE_VALUE (0x1)
  79
  80 /*!
  81  *  @brief Macro indicating the bit position of quad enable bit.
  82  */
  83 #define QSPI_FLASH_QUAD_ENABLE_BIT   (0x01U)
  84
  85
  86 /**
  87  * \brief  This enumerates the commands of qspi flash
  88  *         for communication with the flash device.
  89  */
  90 typedef enum qspiLibCmd
  91 {
  92     QSPI_LIB_CMD_READ_SINGLE = 0x3U,
  93     /**< Single read from qspi flash device */
  94     QSPI_LIB_CMD_READ_DUAL = 0x3BU,
  95     /**< Dual Read from QSPI flash device */
  96     QSPI_LIB_CMD_READ_QUAD = 0x6B,
  97     /**< Quad read commnad from QSPI flash */
  98     QSPI_LIB_CMD_WRITE_ENABLE = 0x6U,
  99     /**< QSPI flash write enable command */
 100     QSPI_LIB_CMD_READ_STATUS_REG = 0x5U,
 101     /**< Read status register */
 102     QSPI_LIB_CMD_READ_STATUS_REG2 = 0x7U,
 103     /**< Read status register 2 */
 104     QSPI_LIB_CMD_READ_CONF_REG = 0x35U,
 105     /**< Read configuration register */
 106     QSPI_LIB_CMD_WRITE_STATUS_REG = 0x1U,
 107     /**< Write status register */
 108     QSPI_LIB_CMD_READ_SFDP = 0x5AU,
 109     /**< Command to read SFDP header and parameter table */
 110     QSPI_LIB_CMD_PAGE_PRG = 0x2U,
 111     /**< Command to write to serial nor flash */
 112     QSPI_LIB_CMD_FAST_READ = 0x0BU,
 113     /**< Fast single read command */
 114     QSPI_LIB_CMD_READ_MFG_ID = 0x90U,
 115     /**< Read manufacturer and device ID */
 116     QSPI_LIB_CMD_BLOCK_ERASE = 0xD8U,
 117     /**< QSPI flash block erase command */
 118     QSPI_LIB_CMD_FULL_ERASE = 0x60U,
 119     /**< Completely erase flash data */
 120     QSPI_LIB_CMD_ENTER_4_BYTE_ADDR = 0xB7U,
 121     /**< Command to enter 4 byte addressing mode */
 122     QSPI_LIB_CMD_EXIT_4_BYTE_ADDR = 0xE9U,
 123     /**< Command to exit 4 byte addressing mode */
 124     QSPI_LIB_CMD_QUAD_RD_CMD_REG   = 0x35U,
 125     /**< command to read the register where the quad enable bit has to be set */
 126     QSPI_LIB_CMD_QUAD_WR_CMD_REG   = 0x01U
 127     /**< command to read the register where the quad enable bit has to be set */
 128 }qspiLibCmd_t;
 129
 130
 131 /*!
 132  *  @brief Flash object containing flash attributes.
 133  */
 134 typedef struct S25FL_Object {
 135     SPI_Handle       spiHandle;     /* Handle for SPI object */
 136     unsigned int     boardSPI;      /* Board SPI in Board.h */
 137     unsigned int     sectorSize;    /* Indicates sector size of the flash */
 138     unsigned int     blockSize;     /* block size of the flash in bytes */
 139     unsigned int     deviceSize;    /* Size of the flash device */
 140     unsigned int     flashDeviceId; /* Flash device id */
 141 }S25FL_Object;
 142
 143
 144 /*!
 145  *  @brief Flash transaction data structure.
 146  */
 147 typedef struct S25FL_Transaction {
 148     uint8_t  *data;      /* Transaction data buffer  */
 149     uint32_t address;    /* Flash address object for transaction */
 150     uint32_t  dataSize;   /* size of transaction data in bytes */
 151 }S25FL_Transaction;
 152
 153
 154 /*!
 155  *  @brief A handle that is returned from a S25FL_open() call.
 156  */
 157 typedef S25FL_Object *S25FL_Handle;
 158
 159
 160 /*!
 161  *  @brief  Opens the S25FL object. This will internally opens the corresponding
 162  *          QSPI instance and gets the QSPI instance handle.
 163  *
 164  *  @param  index    Flash index.
 165  *  @param  params   Pointer to the SPI parameters structure.
 166  */
 167 extern S25FL_Handle SF25FL_open(unsigned int index, SPI_Params *params);
 168
 169
 170 /*!
 171  *  @brief  Closes the S25FL object.
 172  *
 173  *  @param  flashHandle   A S25FL_Handle
 174  */
 175 extern void SF25FL_close(S25FL_Handle flashHandle);
 176
 177
 178 /*!
 179  *  @brief  This function writes data to the flash using QSPI interface.
 180  *
 181  *  @param  flashHandle       A S25FL_Handle
 182  *  @param  transaction       A S25FL_Transaction
 183  *  @return Status            true if successful; else false
 184  *
 185  */
 186 extern bool SF25FL_bufferWrite(S25FL_Handle flashHandle,
 187                                S25FL_Transaction* flashTransaction);
 188
 189 /*!
 190  *  @brief  This function reads specific number of bytes from the flash using
 191  *          QSPI interface.
 192  *
 193  *  @param  flashHandle       A S25FL_Handle
 194  *  @param  transaction       A S25FL_Transaction
 195  *  @return Status            true if successful; else false
 196  *
 197  */
 198 extern bool SF25FL_bufferRead(S25FL_Handle flashHandle,
 199                               S25FL_Transaction* flashTransaction);
 200
 201 /*!
 202  *  @brief  This function reads the value of flash status register. This status
 203  *          is required to know whether flash transaction is completed or still
 204  *          going on.
 205  *
 206  *  @param  flashHandle       A S25FL_Handle
 207  *  @return status            value of the flash status register.
 208  *
 209  */
 210 extern uint32_t FlashStatus(S25FL_Handle flashHandle);
 211
 212
 213 /*!
 214  *  @brief  This function controls the enable/disable of the 4 byte addressing
 215  *          mode. If the destination flash offset address is greater than
 216  *          0xFFFFFFU then this mode should be enabled else not required.
 217  *
 218  *  @param  flashHandle  A S25FL_Handle
 219  *  @param  enableFlag   Flag controlling enable/disable of 4 byte address mode.
 220  *                       TRUE- enable 4 Byte mode; FALSE- disable 4 Byte mode.
 221  *
 222  */
 223 extern bool S25FLFlash_Enable4ByteAddrMode(S25FL_Handle flashHandle,
 224                                            bool enable4ByteMode);
 225
 226
 227 /*!
 228  *  @brief  This function sends write enable command to the flash device. This
 229  *          function has to be called first before performing any write to
 230  *          flash.
 231  *
 232  *  @param  flashHandle  A S25FL_Handle
 233  *  @return status       status of the operation
 234  *
 235  */
 236 extern bool S25FLFlash_WriteEnable(S25FL_Handle flashHandle);
 237
 238
 239 /*!
 240  *  @brief  This API enables the quad enable bit in the flash device. This will
 241  *          called only if 4-Line(QUAD) transfers through QSPI interface.
 242  *
 243  *  @param  flashHandle  A S25FL_Handle
 244  *  @return status       status of the operation
 245  *
 246  */
 247 extern bool S25FLFlash_QuadModeEnable(S25FL_Handle flashHandle);
 248
 249
 250 /*!
 251  *  @brief  This API erases a block of QSPI flash device by sending the command
 252  *          through QSPI controller.
 253
 254  *  @param  flashHandle  A S25FL_Handle
 255  *  @return none
 256  *
 257  */
 258 extern bool S25FLFlash_BlockErase(S25FL_Handle flashHandle,
 259                                   unsigned int blockNumber);
 260
 261
 262 /*!
 263  *  @brief  This API prints the flash id.
 264
 265  *  @param  flashHandle  A S25FL_Handle
 266  *  @return none
 267  *
 268  */
 269 extern void FlashPrintId(S25FL_Handle flashHandle);
 270
 271 #endif /* __S25FL_H */