git.sur5r.net Git - freertos/blob

   1 /*******************************************************************************\r
   2  * (c) Copyright 2011-2013 Microsemi SoC Products Group.  All rights reserved.\r
   3  * \r
   4  * This file contains public APIs for SmartFusion2 eNVM software driver.\r
   5  * \r
   6  * SVN $Revision: 5362 $\r
   7  * SVN $Date: 2013-03-26 21:37:53 +0000 (Tue, 26 Mar 2013) $\r
   8  */\r
   9 /*=========================================================================*//**\r
  10   @mainpage SmartFusion2 MSS eNVM Bare Metal Driver.\r
  11   \r
  12   @section intro_sec Introduction\r
  13   The SmartFusion2 microcontroller subsystem (MSS) includes up to two embedded\r
  14   non-volatile memory (eNVM) blocks. Each of these eNVM blocks can be a maximum\r
  15   size of 256kB. This software driver provides a set of functions for accessing\r
  16   and controlling the MSS eNVM as part of a bare metal system where no operating\r
  17   system is available. The driver can be adapted for use as part of an operating\r
  18   system, but the implementation of the adaptation layer between the driver and\r
  19   the operating system's driver model is outside the scope of the driver.\r
  20   \r
  21   The MSS eNVM driver provides support for the following features:\r
  22     - eNVM write (program) operations.\r
  23     - eNVM page unlocking\r
  24   The MSS eNVM driver is provided as C source code.\r
  25 \r
  26   \r
  27   @section configuration Driver Configuration\r
  28   The size of the MSS eNVM varies with different SmartFusion2 device types. You\r
  29   must only use this driver to access memory locations within the valid MSS eNVM\r
  30   address space for the targeted device. The size of the valid MSS eNVM address\r
  31   space corresponds to the size of the MSS eNVM in the device. Some pages of the\r
  32   MSS eNVM may be write protected by the SmartFusion2 MSS configurator as part\r
  33   of the hardware design flow. The driver cannot unlock or write to these\r
  34   protected pages.\r
  35   The base address, register addresses and interrupt number assignment for the\r
  36   MSS eNVM blocks are defined as constants in the SmartFusion2 CMSIS HAL. You\r
  37   must ensure that the latest SmartFusion2 CMSIS HAL is included in the project\r
  38   settings of the software tool chain used to build your project and that it is\r
  39   generated into your project.\r
  40 \r
  41   @section theory_op Theory of Operation\r
  42   The total amount of eNVM available in a SmartFusion device ranges from 128kB\r
  43   to 512kB, provided in one or two physical eNVM blocks. The eNVM blocks are\r
  44   divided into pages, with each page holding 128 bytes of data. The MSS eNVM\r
  45   driver treats the entire eNVM as a contiguous memory space. It provides write\r
  46   access to all pages that are in the valid eNVM address range for the\r
  47   SmartFusion device and that are not write-protected. The driver imposes no\r
  48   restrictions on writing data across eNVM block or page boundaries. The driver\r
  49   supports random access writes to the eNVM memory. \r
  50 \r
  51  *//*=========================================================================*/\r
  52 #ifndef __MSS_NVM_H\r
  53 #define __MSS_NVM_H\r
  54 \r
  55 #include <stdint.h>\r
  56 \r
  57 #ifdef __cplusplus\r
  58 extern "C" {\r
  59 #endif\r
  60 \r
  61 /******************************************************************************/\r
  62 /* Public definitions                                                         */\r
  63 /******************************************************************************/\r
  64 /*******************************************************************************\r
  65  * Page Locking constants:\r
  66  */\r
  67 /*\r
  68  * Indicates that the NVM_write() function should not lock the addressed pages\r
  69  * after programming the data.\r
  70  */\r
  71 #define NVM_DO_NOT_LOCK_PAGE    0u\r
  72 \r
  73 /*\r
  74  * Indicates that the NVM_write() function should lock the addressed pages after\r
  75  * programming the data.\r
  76  */\r
  77 #define NVM_LOCK_PAGE           1u\r
  78 \r
  79 /*******************************************************************************\r
  80   The nvm_status_t enumeration specifies the possible return values from the\r
  81   NVM_write() and NVM_unlock() functions.\r
  82   \r
  83     NVM_SUCCESS:\r
  84       Indicates that the programming was successful.\r
  85         \r
  86     NVM_PROTECTION_ERROR:\r
  87       Indicates that the operation could not be completed because of a\r
  88       protection error. This happens when attempting to program a page that was\r
  89       set as protected in the hardware flow.\r
  90       \r
  91     NVM_VERIFY_FAILURE:\r
  92       Indicates that one of the verify operations failed.\r
  93       \r
  94     NVM_PAGE_LOCK_ERROR:\r
  95       Indicates that the operation could not complete because one of the pages\r
  96       is locked. This may happen if the page was locked during a previous call\r
  97       to NVM_write() or if the page was locked in the hardware design flow.\r
  98       \r
  99     NVM_WRITE_THRESHOLD_ERROR:\r
 100       Indicates that the NVM maximum number of programming cycles has been\r
 101       reached.\r
 102       \r
 103     NVM_IN_USE_BY_OTHER_MASTER:\r
 104       Indicates that some other MSS AHB Bus Matrix master is accessing the NVM.\r
 105       This could be due to the FPGA logic or the system controller programming\r
 106       the NVM.\r
 107       \r
 108     NVM_INVALID_PARAMETER:\r
 109       Indicates that one of more of the function parameters has an invalid\r
 110       value. This is typically  returned when attempting to write or unlock more\r
 111       eNVM than is available on  the device.\r
 112  */\r
 113 typedef enum nvm_status\r
 114 {\r
 115     NVM_SUCCESS = 0,\r
 116     NVM_PROTECTION_ERROR,\r
 117     NVM_VERIFY_FAILURE,\r
 118     NVM_PAGE_LOCK_ERROR,\r
 119     NVM_WRITE_THRESHOLD_ERROR,\r
 120     NVM_IN_USE_BY_OTHER_MASTER,\r
 121     NVM_INVALID_PARAMETER\r
 122 } nvm_status_t;\r
 123 \r
 124 /******************************************************************************/\r
 125 /* Public variables                                                           */\r
 126 /******************************************************************************/\r
 127 \r
 128 \r
 129 /******************************************************************************/\r
 130 /* Public function declarations                                               */\r
 131 /******************************************************************************/\r
 132 \r
 133 /***************************************************************************//**\r
 134   The NVM_write() function is used to program (or write) data into the eNVM.\r
 135   This function treats the two eNVM blocks contiguously, so a total of 512kB of\r
 136   memory can be accessed linearly. The start address and end address of the\r
 137   memory range to be programmed do not need to be page aligned. This function\r
 138   supports programming of data that spans multiple pages. This function is a\r
 139   blocking function.\r
 140   Note: The NVM_write() function performs a verify operation on each page \r
 141         programmed to ensure the eNVM is programmed with the expected data.\r
 142 \r
 143   @param start_addr\r
 144     The start_addr parameter is the byte aligned start address in the eNVM\r
 145     address space, to which the data is to be programmed.\r
 146 \r
 147   @param pidata\r
 148     The pidata parameter is the byte aligned start address of the input data.\r
 149 \r
 150   @param length\r
 151     The length parameter is the number of bytes of data to be programmed.\r
 152 \r
 153   @param lock_page\r
 154     The lock_page parameter specifies whether the pages that are programmed\r
 155     must be locked or not once programmed. Locking the programmed pages prevents\r
 156     them from being overwritten by mistake. Subsequent programming of these\r
 157     pages will require the pages to be unlocked prior to calling NVM_write().\r
 158     Allowed values for lock_page are:\r
 159         - NVM_DO_NOT_LOCK_PAGE\r
 160         - NVM_LOCK_PAGE\r
 161         \r
 162   @return\r
 163     This function returns NVM_SUCCESS on successful execution. \r
 164     It returns one of the following error codes if the programming of the eNVM\r
 165     fails:\r
 166         - NVM_PROTECTION_ERROR\r
 167         - NVM_VERIFY_FAILURE\r
 168         - NVM_PAGE_LOCK_ERROR\r
 169         - NVM_WRITE_THRESHOLD_ERROR\r
 170         - NVM_IN_USE_BY_OTHER_MASTER\r
 171         - NVM_INVALID_PARAMETER\r
 172         \r
 173   Example:\r
 174   @code\r
 175     uint8_t idata[815] = {"Z"};\r
 176     status = NVM_write(0x0, idata, sizeof(idata), NVM_DO_NOT_LOCK_PAGE);\r
 177   @endcode\r
 178  */\r
 179 nvm_status_t \r
 180 NVM_write\r
 181 (\r
 182     uint32_t start_addr,\r
 183     const uint8_t * pidata,\r
 184     uint32_t  length,\r
 185     uint32_t  lock_page\r
 186 );\r
 187 \r
 188 /***************************************************************************//**\r
 189   The NVM_unlock() function is used to unlock the eNVM pages for a specified\r
 190   range of eNVM addresses in preparation for writing data into the unlocked\r
 191   locations. This function treats the two eNVM blocks contiguously, so a total\r
 192   of 512kB of memory can be accessed linearly. The start address and end address\r
 193   of the memory range to be unlocked do not need to be page aligned. This\r
 194   function supports unlocking of an eNVM address range that spans multiple\r
 195   pages. This function is a blocking function.\r
 196 \r
 197   @param start_addr\r
 198     The start_addr parameter is the byte aligned start address, in the eNVM\r
 199     address space, of the memory range to be unlocked.\r
 200     \r
 201   @param length\r
 202     The length parameter is the size in bytes of the memory range to be\r
 203     unlocked.\r
 204 \r
 205   @return\r
 206     This function returns NVM_SUCCESS on successful execution. \r
 207     It returns one of the following error codes if the unlocking of the eNVM fails:\r
 208         - NVM_PROTECTION_ERROR\r
 209         - NVM_VERIFY_FAILURE\r
 210         - NVM_PAGE_LOCK_ERROR\r
 211         - NVM_WRITE_THRESHOLD_ERROR\r
 212         - NVM_IN_USE_BY_OTHER_MASTER\r
 213         - NVM_INVALID_PARAMETER\r
 214         \r
 215   The example code below demonstrates the intended use of the NVM_unlock()\r
 216   function:\r
 217   @code\r
 218     int program_locked_nvm(uint32_t target_addr, uint32_t length)\r
 219     {\r
 220         nvm_status_t status;\r
 221         int success = 0;\r
 222         \r
 223         status = NVM_unlock(target_addr, length);\r
 224         if(NVM_SUCCESS == status)\r
 225         {\r
 226             status = NVM_write(target_addr, buffer, length, NVM_LOCK_PAGE);\r
 227             if(NVM_SUCCESS == status)\r
 228             {\r
 229                 success = 1; \r
 230             }\r
 231         }\r
 232         return success;\r
 233     }\r
 234   @endcode\r
 235  */\r
 236 nvm_status_t\r
 237 NVM_unlock\r
 238 (\r
 239     uint32_t start_addr,\r
 240     uint32_t length\r
 241 );\r
 242 \r
 243 #ifdef __cplusplus\r
 244 }\r
 245 #endif\r
 246 \r
 247 #endif /* __MSS_NVM_H */\r
 248 \r
 249 \r