spi_flash.h

00001 /**
00002  *
00003  * \file
00004  *
00005  * \brief WINC1500 SPI Flash.
00006  *
00007  * Copyright (c) 2016-2017 Atmel Corporation. All rights reserved.
00008  *
00009  * \asf_license_start
00010  *
00011  * \page License
00012  *
00013  * Redistribution and use in source and binary forms, with or without
00014  * modification, are permitted provided that the following conditions are met:
00015  *
00016  * 1. Redistributions of source code must retain the above copyright notice,
00017  *    this list of conditions and the following disclaimer.
00018  *
00019  * 2. Redistributions in binary form must reproduce the above copyright notice,
00020  *    this list of conditions and the following disclaimer in the documentation
00021  *    and/or other materials provided with the distribution.
00022  *
00023  * 3. The name of Atmel may not be used to endorse or promote products derived
00024  *    from this software without specific prior written permission.
00025  *
00026  * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
00027  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00028  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
00029  * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
00030  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00031  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00032  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00033  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
00034  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00035  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00036  * POSSIBILITY OF SUCH DAMAGE.
00037  *
00038  * \asf_license_stop
00039  *
00040  */
00041 
00042 /** \defgroup SPIFLASH Spi Flash
00043  * @file           spi_flash.h
00044  * @brief          This file describe SPI flash APIs, how to use it and limitations with each one. 
00045  * @section      Example
00046  *                 This example illustrates a complete guide of how to use these APIs.
00047  * @code{.c}
00048                     #include "spi_flash.h"
00049 
00050                     #define DATA_TO_REPLACE "THIS IS A NEW SECTOR IN FLASH"
00051 
00052                     int main()
00053                     {
00054                         uint8   au8FlashContent[FLASH_SECTOR_SZ] = {0};
00055                         uint32  u32FlashTotalSize = 0;
00056                         uint32  u32FlashOffset = 0;
00057     
00058                         ret = m2m_wifi_download_mode();
00059                         if(M2M_SUCCESS != ret)
00060                         {
00061                             printf("Unable to enter download mode\r\n");
00062                         }
00063                         else
00064                         {
00065                             u32FlashTotalSize = spi_flash_get_size();
00066                         }
00067 
00068                         while((u32FlashTotalSize > u32FlashOffset) && (M2M_SUCCESS == ret))
00069                         {
00070                             ret = spi_flash_read(au8FlashContent, u32FlashOffset, FLASH_SECTOR_SZ);
00071                             if(M2M_SUCCESS != ret)
00072                             {
00073                                 printf("Unable to read SPI sector\r\n");
00074                                 break;
00075                             }
00076                             memcpy(au8FlashContent, DATA_TO_REPLACE, strlen(DATA_TO_REPLACE));
00077         
00078                             ret = spi_flash_erase(u32FlashOffset, FLASH_SECTOR_SZ);
00079                             if(M2M_SUCCESS != ret)
00080                             {
00081                                 printf("Unable to erase SPI sector\r\n");
00082                                 break;
00083                             }
00084         
00085                             ret = spi_flash_write(au8FlashContent, u32FlashOffset, FLASH_SECTOR_SZ);
00086                             if(M2M_SUCCESS != ret)
00087                             {
00088                                 printf("Unable to write SPI sector\r\n");
00089                                 break;
00090                             }
00091                             u32FlashOffset += FLASH_SECTOR_SZ;
00092                         }
00093     
00094                         if(M2M_SUCCESS == ret)
00095                         {
00096                             printf("Successful operations\r\n");
00097                         }
00098                         else
00099                         {
00100                             printf("Failed operations\r\n");
00101                         }
00102     
00103                         while(1);
00104                         return M2M_SUCCESS;
00105                     }
00106  * @endcode  
00107  */
00108 
00109 #ifndef __SPI_FLASH_H__
00110 #define __SPI_FLASH_H__
00111 #include "common/include/nm_common.h"
00112 #include "bus_wrapper/include/nm_bus_wrapper.h"
00113 #include "driver/source/nmbus.h"
00114 #include "driver/source/nmasic.h"
00115 
00116 /**
00117  *  @fn     spi_flash_enable
00118  *  @brief  Enable spi flash operations
00119  *  @version    1.0
00120  */
00121 sint8 spi_flash_enable(uint8 enable);
00122 /** \defgroup SPIFLASHAPI Function
00123  *   @ingroup SPIFLASH
00124  */
00125 
00126  /** @defgroup SPiFlashGetFn spi_flash_get_size
00127  *  @ingroup SPIFLASHAPI
00128  */
00129   /**@{*/
00130 /*!
00131  * @fn             uint32 spi_flash_get_size(void);
00132  * @brief         Returns with \ref uint32 value which is total flash size\n
00133  * @note         Returned value in Mb (Mega Bit).
00134  * @return      SPI flash size in case of success and a ZERO value in case of failure.
00135  */
00136 uint32 spi_flash_get_size(void);
00137  /**@}*/
00138 
00139   /** @defgroup SPiFlashRead spi_flash_read
00140  *  @ingroup SPIFLASHAPI
00141  */
00142   /**@{*/
00143 /*!
00144  * @fn             sint8 spi_flash_read(uint8 *, uint32, uint32);
00145  * @brief          Read a specified portion of data from SPI Flash.\n
00146  * @param [out]    pu8Buf
00147  *                 Pointer to data buffer which will fill in with data in case of successful operation.
00148  * @param [in]     u32Addr
00149  *                 Address (Offset) to read from at the SPI flash.
00150  * @param [in]     u32Sz
00151  *                 Total size of data to be read in bytes
00152  * @warning        
00153  *                 - Address (offset) plus size of data must not exceed flash size.\n
00154  *                 - No firmware is required for reading from SPI flash.\n
00155  *                 - In case of there is a running firmware, it is required to pause your firmware first 
00156  *                   before any trial to access SPI flash to avoid any racing between host and running firmware on bus using 
00157  *                   @ref m2m_wifi_download_mode
00158  * @note           
00159  *                 - It is blocking function\n
00160  * @sa             m2m_wifi_download_mode, spi_flash_get_size
00161  * @return        The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
00162  */
00163 sint8 spi_flash_read(uint8 *pu8Buf, uint32 u32Addr, uint32 u32Sz);
00164  /**@}*/
00165 
00166   /** @defgroup SPiFlashWrite spi_flash_write
00167  *  @ingroup SPIFLASHAPI
00168  */
00169   /**@{*/
00170 /*!
00171  * @fn             sint8 spi_flash_write(uint8 *, uint32, uint32);
00172  * @brief          Write a specified portion of data to SPI Flash.\n
00173  * @param [in]     pu8Buf
00174  *                 Pointer to data buffer which contains the required to be written.
00175  * @param [in]     u32Offset
00176  *                 Address (Offset) to write at the SPI flash.
00177  * @param [in]     u32Sz
00178  *                 Total number of size of data bytes
00179  * @note           
00180  *                 - It is blocking function\n
00181  *                 - It is user's responsibility to verify that data has been written successfully 
00182  *                   by reading data again and compare it with the original.
00183  * @warning        
00184  *                 - Address (offset) plus size of data must not exceed flash size.\n
00185  *                 - No firmware is required for writing to SPI flash.\n
00186  *                 - In case of there is a running firmware, it is required to pause your firmware first 
00187  *                   before any trial to access SPI flash to avoid any racing between host and running firmware on bus using 
00188  *                   @ref m2m_wifi_download_mode.
00189  *                 - Before writing to any section, it is required to erase it first.
00190  * @sa             m2m_wifi_download_mode, spi_flash_get_size, spi_flash_erase
00191  * @return       The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
00192  
00193  */
00194 sint8 spi_flash_write(uint8* pu8Buf, uint32 u32Offset, uint32 u32Sz);
00195  /**@}*/
00196 
00197   /** @defgroup SPiFlashErase spi_flash_erase
00198  *  @ingroup SPIFLASHAPI
00199  */
00200   /**@{*/
00201 /*!
00202  * @fn             sint8 spi_flash_erase(uint32, uint32);
00203  * @brief          Erase a specified portion of SPI Flash.\n
00204  * @param [in]     u32Offset
00205  *                 Address (Offset) to erase from the SPI flash.
00206  * @param [in]     u32Sz
00207  *                 Size of SPI flash required to be erased.
00208  * @note         It is blocking function \n  
00209 * @warning         
00210 *                 - Address (offset) plus size of data must not exceed flash size.\n
00211 *                 - No firmware is required for writing to SPI flash.\n
00212  *                 - In case of there is a running firmware, it is required to pause your firmware first 
00213  *                   before any trial to access SPI flash to avoid any racing between host and running firmware on bus using 
00214  *                   @ref m2m_wifi_download_mode
00215  *                 - It is blocking function\n
00216  * @sa             m2m_wifi_download_mode, spi_flash_get_size
00217  * @return       The function returns @ref M2M_SUCCESS for successful operations  and a negative value otherwise.
00218 
00219  */
00220 sint8 spi_flash_erase(uint32 u32Offset, uint32 u32Sz);
00221  /**@}*/
00222 #endif  //__SPI_FLASH_H__
00223