pdk_k2g_1_0_1/packages/ti/board/src/flash/include/board_flash.h

   1 /*
   2  * Copyright (c) 2016, Texas Instruments Incorporated
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * *  Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  12  * *  Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * *  Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32
  33 #ifndef BOARD_FLASH_H_
  34 #define BOARD_FLASH_H_
  35
  36 /**
  37  *  @brief      This type defines the opaque handle returned to a flash device that is opened.
  38  *              The handle must be used in all subsequent operations.
  39  *
  40  */
  41 typedef uint32_t Board_flashHandle;
  42
  43 /**
  44  * Error codes used by Board flash functions. Negative values are errors,
  45  * while positive values indicate success.
  46  */
  47 typedef int32_t Board_flash_STATUS;       /** Board Flash API return type */
  48
  49 #define BOARD_FLASH_EINVALID      -3      /**< Error code for invalid parameters */
  50 #define BOARD_FLASH_EUNSUPPORTED  -2      /**< Error code for unsupported feature */
  51 #define BOARD_FLASH_EFAIL         -1      /**< General failure code */
  52 #define BOARD_FLASH_EOK           0       /**< General success code */
  53
  54 /**
  55  * @brief       Device Identifiers. These are used in the Open call to allow access to a specific
  56  *                      memory device.
  57  *
  58  */
  59 #define BOARD_FLASH_ID_MT29F1G08ABCHC      0x2CA1 /**< 128MB NAND Flash */
  60 #define BOARD_FLASH_ID_NAND512R3A2D        0x2036 /**< 64MB NAND Flash */
  61 #define BOARD_FLASH_ID_MT29F4G08ABADA      0x2CDC /**< 512MB NAND Flash */
  62 #define BOARD_FLASH_ID_MT29F16G08ADBCAH4C  0x2CA5 /**< 16Gb,1.8v,x8 */
  63 #define BOARD_FLASH_ID_MT29F2G16ABAFA      0x2CCA /**< 2Gb, x16, 3.3V */
  64 #define BOARD_FLASH_ID_NORN25Q128          0xBB18 /**< 16MB NOR Flash */
  65 #define BOARD_FLASH_ID_NORN25Q128A13ESF40F 0xBA18 /**< 16MB, 3.3v NOR Flash */
  66 #define BOARD_FLASH_ID_NORN25Q032A             0xBB16 /**< 4MB NOR Flash */
  67 #define BOARD_FLASH_ID_EEPROM50            0x50   /**< EEPROM @ slave address 0x50  */
  68 #define BOARD_FLASH_ID_EEPROM51            0x51   /**< EEPROM @ slave address 0x51  */
  69 #define BOARD_FLASH_ID_EMMC                0xFF00 /**< eMMC device Id  */
  70 #define BOARD_FLASH_ID_SD                  0xFF01 /**< Micro SD device Id  */
  71 #define BOARD_FLASH_ID_QSPIFLASH_S25FL512S 0x0220 /**< QSPI flash device Id */
  72
  73 /**
  74  * @brief Indicates the type of device
  75  *
  76  */
  77 typedef enum {
  78     BOARD_FLASH_NAND,
  79     /**<NAND Flash*/
  80     BOARD_FLASH_NOR,
  81     /**<NOR Flash*/
  82     BOARD_FLASH_EEPROM,
  83     /**<EEPROM */
  84     BOARD_FLASH_SD,
  85     /**<SD Card*/
  86     BOARD_FLASH_EMMC,
  87     /**<eMMC Card*/
  88     BOARD_FLASH_QSPI_FLASH,
  89     /**<QSPI flash */
  90     BOARD_FLASH_MAX
  91     /**<End of devices*/
  92 } Board_flashType;
  93
  94 /**
  95  * @brief Options to set qspi flash read/write access mode
  96  */
  97 typedef enum {
  98     BOARD_FLASH_QSPI_IO_MODE_SINGLE,
  99     /**< QSPI flash read/write access on single I/O line */
 100     BOARD_FLASH_QSPI_IO_MODE_DUAL,
 101     /**< QSPI flash read/write access on two I/O lines */
 102     BOARD_FLASH_QSPI_IO_MODE_QUAD
 103     /**< QSPI flash read/write access on four I/O lines */
 104 } Board_flashQspiIoMode;
 105
 106 /**
 107  *  @brief This structure contains information about the flash device on the board
 108  *
 109  *                      The bblist points to an array of bytes where each position represents a
 110  *                      block on the device. If the block is good it is marked as 0xFF. If the block
 111  *                      is bad, it is marked as 0x00. For devices that do not support a bad block list this
 112  *                      value will be NULL. The number of blocks in the bblist is determined by the block_count field.
 113  */
 114 typedef struct
 115 {
 116     uint32_t flashHandle;
 117     /**<Handle to the flash interface as returned by flash init function */
 118     int32_t  manufacturer_id;
 119     /**<manufacturer ID*/
 120     int32_t  device_id;
 121     /**<Manufacturers device ID*/
 122     Board_flashType type;
 123     /**<Type of device */
 124     int32_t  width;
 125     /**<Width in bits*/
 126     int32_t  block_count;
 127     /**<Total blocks. First block starts at 0. */
 128     int32_t  page_count;
 129     /**<Page count per block*/
 130     int32_t  page_size;
 131     /**<Number of bytes in a page including spare area*/
 132     int32_t  spare_size;
 133     /**<Spare area size in bytes*/
 134     int32_t      bboffset;
 135     /**<Offset into spare area to check for a bad block */
 136         uint32_t column;
 137         /**<Column for a NAND device */
 138     uint8_t *bblist;
 139     /** <Bad Block list or NULL if device does not support one  */
 140 } Board_FlashInfo;
 141
 142
 143 /**************************************************************************
 144  **                      API function Prototypes
 145  **************************************************************************/
 146
 147 /**
 148  *  @brief       Opens a flash device for use
 149  *
 150  *  @param[in]   deviceId  Flash device ID to open
 151  *      @param[in]       portNum   Peripheral port number attached to the flash device
 152  *  @param[in]   params    configuration parameters for the periperal interface
 153  *
 154  *  @retval      NULL or Board_flashHandle.
 155  *
 156  *  @remark
 157  *               On success a handle is returned in which should be used in
 158  *                               all subsequent calls. As of now, the devices are not virtualized and only
 159  *                               one open may exist at a time for a particular device.
 160  *
 161  */
 162 Board_flashHandle Board_flashOpen(uint32_t  deviceId,
 163                                   uint32_t  portNum,
 164                                   void     *params);
 165
 166 /**
 167  *  @brief       Closes the device
 168  *
 169  *  @param[in]   handle  Handle to the device as returned in the open call.
 170  *
 171  *  @retval      BOARD_FLASH_EOK on Success
 172  *
 173  */
 174 Board_flash_STATUS Board_flashClose (Board_flashHandle handle);
 175
 176 /**
 177  *  @brief       Reads a page from the device
 178  *
 179  *  @param[in]   handle Flash device handle from the open
 180  *  @param[in]   offset Offset to start the read from
 181  *  @param[in]   buf    Pointer to a buffer to read the data into
 182  *  @param[in]   len    Amount of data to read
 183  *  @param[in]   params Pointer to read configuration parameters
 184  *                      for QSPI NOR, *params is used to set
 185  *                      the Board_flashQspiIoMode
 186  *
 187  *
 188  *  @retval      BOARD_FLASH_EOK on Success
 189  *
 190  *  @remark      The buffer size should be page_size + spare_size
 191  *               The application should not write into the spare area
 192  *
 193  */
 194 Board_flash_STATUS Board_flashRead(Board_flashHandle  handle,
 195                                    uint32_t           offset,
 196                                    uint8_t           *buf,
 197                                    uint32_t           len,
 198                                    void              *params);
 199
 200 /**
 201  *  @brief      Write the data to the device
 202  *
 203  *  @param[in]  offset          Offset to start writing the data at.
 204  *  @param[in]  buf         Pointer to  data to write
 205  *  @param[in]  len         Length of the data pointed to by buf
 206  *  @param[in]  params      Pointer to write configuration parameters
 207  *                          for QSPI NOR, *params is used to set
 208  *                          the Board_flashQspiIoMode
 209  *
 210  *  @retval     BOARD_FLASH_EOK on Success
 211  *
 212  */
 213 Board_flash_STATUS Board_flashWrite(Board_flashHandle  handle,
 214                                     uint32_t           offset,
 215                                     uint8_t           *buf,
 216                                     uint32_t           len,
 217                                     void              *params);
 218
 219 /**
 220  *  @brief      Convert the block and page number to offset
 221  *
 222  *  @param[in]  handle  Handle to the device as returned by open
 223  *  @param[in]  offset          Offset to start writing the data at.
 224  *  @param[in]  block       Block number
 225  *  @param[in]  page        Page number
 226  *
 227  *  @retval     BOARD_FLASH_EOK on Success
 228  *
 229  *
 230  */
 231 Board_flash_STATUS Board_flashBlkPageToOffset(Board_flashHandle  handle,
 232                                               uint32_t          *offset,
 233                                               uint32_t           block,
 234                                               uint32_t           page);
 235
 236
 237 /**
 238  *  @brief      Convert the offset to block and page number
 239  *
 240  *  @param[in]  handle  Handle to the device as returned by open
 241  *
 242  *  @param[in]  offset          Offset to start writing the data at.
 243  *
 244  *  @param[in]  block       Pointer to the block number
 245  *
 246  *  @param[in]  page        Pointer to the Page number
 247  *
 248  *  @retval     BOARD_FLASH_EOK on Success
 249  *
 250  *
 251  */
 252 Board_flash_STATUS Board_flashOffsetToBlkPage(Board_flashHandle  handle,
 253                                               uint32_t           offset,
 254                                               uint32_t          *block,
 255                                               uint32_t          *page);
 256
 257
 258 /**
 259  *  @brief       Reads spare data from the flash device
 260  *
 261  *  @param[in]   handle  Flash device handle from the open
 262  *
 263  *  @param[in]   block_number Block ID to read from
 264  *
 265  *  @param[in]   page_number  Page to read the spare area from
 266  *
 267  *  @param[in]   buf          Pointer to message data
 268  *
 269  *  @retval      BOARD_FLASH_EOK on Success
 270  *
 271  *  @remark      The buffer size should be spare_size.
 272  */
 273
 274 /**
 275  *  @brief       erase a block on the flash block
 276  *
 277  *  @param[in]   handle  Flash device handle from the open
 278  *
 279  *  @param[in]   block_number Block ID to erase
 280  *
 281  *  @retval      BOARD_FLASH_EOK on Success
 282  *
 283  */
 284 Board_flash_STATUS Board_flashEraseBlk(Board_flashHandle handle,
 285                                        uint32_t          block_number);
 286 #endif