tool/mbed/mbed-sdk/libraries/mbed/targets/cmsis/TARGET_STM/TARGET_STM32L1/stm32l1xx_hal_flash.c

   1 /**
   2   ******************************************************************************
   3   * @file    stm32l1xx_hal_flash.c
   4   * @author  MCD Application Team
   5   * @version V1.0.0
   6   * @date    5-September-2014
   7   * @brief   FLASH HAL module driver.
   8   *          This file provides firmware functions to manage the following
   9   *          functionalities of the internal FLASH memory:
  10   *            + FLASH Interface configuration
  11   *            + FLASH Memory Programming
  12   *            + Interrupts and flags management
  13   *
  14   *  @verbatim
  15
  16   ==============================================================================
  17                       ##### FLASH peripheral features #####
  18   ==============================================================================
  19
  20   [..] The Flash memory interface manages CPU AHB I-Code and D-Code accesses
  21        to the Flash memory. It implements the erase and program Flash memory operations
  22        and the read and write protection mechanisms.
  23
  24   [..] The Flash memory interface accelerates code execution with a system of instruction prefetch.
  25
  26   [..] The FLASH main features are:
  27       (+) Flash memory read operations
  28       (+) Flash memory program/erase operations
  29       (+) Read / write protections
  30       (+) Prefetch on I-Code
  31       (+) Option Bytes programming
  32
  33             ##### How to use this driver #####
  34   ==============================================================================
  35   [..] This driver provides functions to configure and program the Flash
  36      memory of all STM32L1xx devices.
  37
  38      (#) FLASH Memory Programming functions: this group includes all
  39        needed functions to erase and program the main memory:
  40        (++) Lock and Unlock the Flash interface.
  41        (++) Erase function: Erase Page.
  42        (++) Program functions: Fast Word and Half Page(should be
  43         executed from internal SRAM).
  44
  45      (#) DATA EEPROM Programming functions: this group includes all
  46        needed functions to erase and program the DATA EEPROM memory:
  47        (++) Lock and Unlock the DATA EEPROM interface.
  48        (++) Erase function: Erase Byte, erase HalfWord, erase Word, erase
  49        Double Word (should be executed from internal SRAM).
  50        (++) Program functions: Fast Program Byte, Fast Program Half-Word,
  51         FastProgramWord, Program Byte, Program Half-Word,
  52         Program Word and Program Double-Word (should be executed
  53         from internal SRAM).
  54
  55      (#) FLASH Option Bytes Programming functions: this group includes
  56        all needed functions to:
  57        (++) Lock and Unlock the Flash Option bytes.
  58        (++) Set/Reset the write protection.
  59        (++) Set the Read protection Level.
  60        (++) Set the BOR level.
  61        (++) Program the user option Bytes.
  62        (++) Launch the Option Bytes loader.
  63        (++) Get the Write protection.
  64        (++) Get the read protection status.
  65        (++) Get the BOR level.
  66        (++) Get the user option bytes.
  67
  68      (#) Interrupts and flags management functions :
  69        (++) Handle FLASH interrupts by calling HAL_FLASH_IRQHandler()
  70        (++) Wait for last FLASH operation according to its status
  71        (++) Get error flag status by calling HAL_GetErrorCode()
  72
  73     (#) FLASH Interface configuration functions: this group includes
  74       the management of following features:
  75       (++) Enable/Disable the RUN PowerDown mode.
  76       (++) Enable/Disable the SLEEP PowerDown mode.
  77
  78     (#) FLASH Peripheral State methods: this group includes
  79       the management of following features:
  80       (++) Wait for the FLASH operation
  81       (++)  Get the specific FLASH error flag
  82
  83   [..] In addition to these function, this driver includes a set of macros allowing
  84        to handle the following operations:
  85
  86     (+) Set/Get the latency
  87     (+) Enable/Disable the prefetch buffer
  88     (+) Enable/Disable the 64 bit Read Access.
  89        (+) Enable/Disable the Flash power-down
  90        (+) Enable/Disable the FLASH interrupts
  91        (+) Monitor the FLASH flags status
  92
  93   ===============================================================================
  94                  ##### Programming operation functions #####
  95   ===============================================================================
  96      [..]
  97      This subsection provides a set of functions allowing to manage the FLASH
  98      program operations.
  99
 100     [..] The FLASH Memory Programming functions, includes the following functions:
 101      (+) HAL_FLASH_Unlock(void);
 102      (+) HAL_FLASH_Lock(void);
 103      (+) HAL_FLASH_Program(uint32_t TypeProgram, uint32_t Address, uint32_t Data)
 104      (+) HAL_FLASH_Program_IT(uint32_t TypeProgram, uint32_t Address, uint32_t Data)
 105
 106      [..] Any operation of erase or program should follow these steps:
 107      (#) Call the HAL_FLASH_Unlock() function to enable the flash control register and
 108          program memory access.
 109      (#) Call the desired function to erase page or program data.
 110      (#) Call the HAL_FLASH_Lock() to disable the flash program memory access
 111         (recommended to protect the FLASH memory against possible unwanted operation).
 112
 113    ==============================================================================
 114                ##### Option Bytes Programming functions #####
 115    ==============================================================================
 116
 117      [..] The FLASH_Option Bytes Programming_functions, includes the following functions:
 118      (+) HAL_FLASH_OB_Unlock(void);
 119      (+) HAL_FLASH_OB_Lock(void);
 120      (+) HAL_FLASH_OB_Launch(void);
 121      (+) HAL_FLASHEx_OBProgram(FLASH_OBProgramInitTypeDef *pOBInit);
 122      (+) HAL_FLASHEx_OBGetConfig(FLASH_OBProgramInitTypeDef *pOBInit);
 123
 124      [..] Any operation of erase or program should follow these steps:
 125      (#) Call the HAL_FLASH_OB_Unlock() function to enable the Flash option control
 126          register access.
 127      (#) Call the following functions to program the desired option bytes.
 128          (++) HAL_FLASHEx_OBProgram(FLASH_OBProgramInitTypeDef *pOBInit);
 129      (#) Once all needed option bytes to be programmed are correctly written, call the
 130          HAL_FLASH_OB_Launch(void) function to launch the Option Bytes programming process.
 131      (#) Call the HAL_FLASH_OB_Lock() to disable the Flash option control register access (recommended
 132          to protect the option Bytes against possible unwanted operations).
 133
 134   *  @endverbatim
 135   *
 136   ******************************************************************************
 137   * @attention
 138   *
 139   * <h2><center>&copy; COPYRIGHT(c) 2014 STMicroelectronics</center></h2>
 140   *
 141   * Redistribution and use in source and binary forms, with or without modification,
 142   * are permitted provided that the following conditions are met:
 143   *   1. Redistributions of source code must retain the above copyright notice,
 144   *      this list of conditions and the following disclaimer.
 145   *   2. Redistributions in binary form must reproduce the above copyright notice,
 146   *      this list of conditions and the following disclaimer in the documentation
 147   *      and/or other materials provided with the distribution.
 148   *   3. Neither the name of STMicroelectronics nor the names of its contributors
 149   *      may be used to endorse or promote products derived from this software
 150   *      without specific prior written permission.
 151   *
 152   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 153   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 154   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 155   * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
 156   * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 157   * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 158   * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 159   * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 160   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 161   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 162   *
 163   ******************************************************************************
 164   */
 165
 166 /* Includes ------------------------------------------------------------------*/
 167 #include "stm32l1xx_hal.h"
 168
 169 /** @addtogroup STM32L1xx_HAL_Driver
 170   * @{
 171   */
 172
 173 #ifdef HAL_FLASH_MODULE_ENABLED
 174
 175 /** @defgroup FLASH FLASH
 176   * @brief FLASH driver modules
 177   * @{
 178   */
 179
 180 /* Private typedef -----------------------------------------------------------*/
 181 /* Private define ------------------------------------------------------------*/
 182 /* Private macro -------------------------------------------------------------*/
 183 /* Private variables ---------------------------------------------------------*/
 184 /** @defgroup FLASH_Internal_Variables FLASH Internal Variables
 185   * @{
 186   */
 187
 188 /**
 189   * @brief  Variable used for Program/Erase sectors under interruption
 190   */
 191 FLASH_ProcessTypeDef      ProcFlash;
 192
 193
 194 /**
 195   * @}
 196   */
 197 /* Private function prototypes -----------------------------------------------*/
 198 /* Private functions ---------------------------------------------------------*/
 199
 200 /** @defgroup FLASH_Exported_Functions FLASH Exported functions
 201   * @{
 202   */
 203
 204 /** @defgroup FLASH_Exported_Functions_Group1 Programming operation functions
 205  *  @brief   Programming operation functions
 206  *
 207 @verbatim
 208 @endverbatim
 209   * @{
 210   */
 211 /**
 212   * @brief  Program word at a specified address
 213   * @note   To correctly run this function, the HAL_FLASH_Unlock() function
 214   *         must be called before.
 215   *         Call the HAL_FLASH_Lock() to disable the flash memory access
 216   *         (recommended to protect the FLASH memory against possible unwanted operation).
 217   * @param  TypeProgram:  Indicate the way to program at a specified address.
 218   *                           This parameter can be a value of @ref FLASH_Type_Program
 219   * @param  Address:  specifies the address to be programmed.
 220   * @param  Data: specifies the data to be programmed
 221   *
 222   * @retval HAL_StatusTypeDef HAL Status
 223   */
 224 HAL_StatusTypeDef HAL_FLASH_Program(uint32_t TypeProgram, uint32_t Address, uint64_t Data)
 225 {
 226   HAL_StatusTypeDef status = HAL_ERROR;
 227
 228   /* Process Locked */
 229   __HAL_LOCK(&ProcFlash);
 230
 231   /* Check the parameters */
 232   assert_param(IS_TYPEPROGRAMFLASH(TypeProgram));
 233   assert_param(IS_FLASH_PROGRAM_ADDRESS(Address));
 234
 235   /* Wait for last operation to be completed */
 236   status = FLASH_WaitForLastOperation((uint32_t)HAL_FLASH_TIMEOUT_VALUE);
 237
 238   if(status == HAL_OK)
 239   {
 240     /*Program word (32-bit) at a specified address.*/
 241     *(__IO uint32_t *)Address = Data;
 242
 243     /* Wait for last operation to be completed */
 244     status = FLASH_WaitForLastOperation((uint32_t)HAL_FLASH_TIMEOUT_VALUE);
 245   }
 246
 247   /* Process Unlocked */
 248   __HAL_UNLOCK(&ProcFlash);
 249
 250   return status;
 251 }
 252
 253 /**
 254   * @brief   Program word at a specified address  with interrupt enabled.
 255   * @param  TypeProgram:  Indicate the way to program at a specified address.
 256   *                           This parameter can be a value of @ref FLASH_Type_Program
 257   * @param  Address:  specifies the address to be programmed.
 258   * @param  Data: specifies the data to be programmed
 259   *
 260   * @retval HAL_StatusTypeDef HAL Status
 261   */
 262 HAL_StatusTypeDef HAL_FLASH_Program_IT(uint32_t TypeProgram, uint32_t Address, uint64_t Data)
 263 {
 264   HAL_StatusTypeDef status = HAL_OK;
 265
 266   /* Process Locked */
 267   __HAL_LOCK(&ProcFlash);
 268
 269   /* Check the parameters */
 270   assert_param(IS_TYPEPROGRAMFLASH(TypeProgram));
 271   assert_param(IS_FLASH_PROGRAM_ADDRESS(Address));
 272
 273   /* Enable End of FLASH Operation interrupt */
 274   __HAL_FLASH_ENABLE_IT(FLASH_IT_EOP);
 275
 276   /* Enable Error source interrupt */
 277   __HAL_FLASH_ENABLE_IT(FLASH_IT_ERR);
 278
 279   /* Clear pending flags (if any) */
 280   __HAL_FLASH_CLEAR_FLAG(FLASH_FLAG_MASK);
 281
 282   ProcFlash.ProcedureOnGoing = FLASH_PROC_PROGRAM;
 283   ProcFlash.Address = Address;
 284
 285   if(TypeProgram == TYPEPROGRAM_WORD)
 286   {
 287     /*Program word (32-bit) at a specified address.*/
 288     *(__IO uint32_t *)Address = Data;
 289   }
 290
 291   /* Process Unlocked */
 292   __HAL_UNLOCK(&ProcFlash);
 293
 294   return status;
 295 }
 296
 297 /**
 298   * @brief  FLASH end of operation interrupt callback
 299   * @param  ReturnValue: The value saved in this parameter depends on the ongoing procedure
 300   *                 - Pages Erase: Sector which has been erased
 301   *                    (if 0xFFFFFFFF, it means that all the selected sectors have been erased)
 302   *                 - Program: Address which was selected for data program
 303   * @retval none
 304   */
 305 __weak void HAL_FLASH_EndOfOperationCallback(uint32_t ReturnValue)
 306 {
 307   /* NOTE : This function Should not be modified, when the callback is needed,
 308             the HAL_FLASH_EndOfOperationCallback could be implemented in the user file
 309    */
 310 }
 311
 312 /**
 313   * @brief  FLASH operation error interrupt callback
 314   * @param  ReturnValue: The value saved in this parameter depends on the ongoing procedure
 315   *                 - Pagess Erase: Sector number which returned an error
 316   *                 - Program: Address which was selected for data program
 317   * @retval none
 318   */
 319 __weak void HAL_FLASH_OperationErrorCallback(uint32_t ReturnValue)
 320 {
 321   /* NOTE : This function Should not be modified, when the callback is needed,
 322             the HAL_FLASH_OperationErrorCallback could be implemented in the user file
 323    */
 324 }
 325
 326 /**
 327   * @}
 328   */
 329
 330 /** @defgroup FLASH_Exported_Functions_Group2 Peripheral Control functions
 331  *  @brief   management functions
 332  *
 333 @verbatim
 334  ===============================================================================
 335                       ##### Peripheral Control functions #####
 336  ===============================================================================
 337     [..]
 338     This subsection provides a set of functions allowing to control the FLASH
 339     memory operations.
 340
 341 @endverbatim
 342   * @{
 343   */
 344
 345 /**
 346   * @brief  Unlock the FLASH control register access
 347   * @retval HAL_StatusTypeDef HAL Status
 348   */
 349 HAL_StatusTypeDef HAL_FLASH_Unlock(void)
 350 {
 351   if((FLASH->PECR & FLASH_PECR_PRGLOCK) != RESET)
 352   {
 353     /* Unlocking FLASH_PECR register access*/
 354     if((FLASH->PECR & FLASH_PECR_PELOCK) != RESET)
 355     {
 356       FLASH->PEKEYR = FLASH_PEKEY1;
 357       FLASH->PEKEYR = FLASH_PEKEY2;
 358     }
 359
 360     /* Unlocking the program memory access */
 361     FLASH->PRGKEYR = FLASH_PRGKEY1;
 362     FLASH->PRGKEYR = FLASH_PRGKEY2;
 363   }
 364   else
 365   {
 366     return HAL_ERROR;
 367   }
 368
 369   return HAL_OK;
 370 }
 371
 372 /**
 373   * @brief  Locks the FLASH control register access
 374   * @retval HAL_StatusTypeDef HAL Status
 375   */
 376 HAL_StatusTypeDef HAL_FLASH_Lock(void)
 377 {
 378   /* Set the PRGLOCK Bit to lock the program memory access */
 379   SET_BIT(FLASH->PECR, FLASH_PECR_PRGLOCK);
 380
 381   return HAL_OK;
 382 }
 383
 384 /**
 385   * @brief  Unlock the FLASH Option Control Registers access.
 386   * @retval HAL_StatusTypeDef HAL Status
 387   */
 388 HAL_StatusTypeDef HAL_FLASH_OB_Unlock(void)
 389 {
 390   if((FLASH->PECR & FLASH_PECR_OPTLOCK) != RESET)
 391   {
 392     /* Unlocking FLASH_PECR register access*/
 393     if((FLASH->PECR & FLASH_PECR_PELOCK) != RESET)
 394     {
 395       /* Unlocking FLASH_PECR register access*/
 396       FLASH->PEKEYR = FLASH_PEKEY1;
 397       FLASH->PEKEYR = FLASH_PEKEY2;
 398     }
 399
 400     /* Unlocking the option bytes block access */
 401     FLASH->OPTKEYR = FLASH_OPTKEY1;
 402     FLASH->OPTKEYR = FLASH_OPTKEY2;
 403   }
 404   else
 405   {
 406     return HAL_ERROR;
 407   }
 408
 409   return HAL_OK;
 410 }
 411
 412 /**
 413   * @brief  Lock the FLASH Option Control Registers access.
 414   * @retval HAL_StatusTypeDef HAL Status
 415   */
 416 HAL_StatusTypeDef HAL_FLASH_OB_Lock(void)
 417 {
 418   /* Set the OPTLOCK Bit to lock the option bytes block access */
 419   SET_BIT(FLASH->PECR, FLASH_PECR_OPTLOCK);
 420
 421   return HAL_OK;
 422 }
 423
 424 /**
 425   * @brief  Launch the option byte loading.
 426   * @retval HAL_StatusTypeDef HAL Status
 427   */
 428 HAL_StatusTypeDef HAL_FLASH_OB_Launch(void)
 429 {
 430   /* Set the OBL_Launch bit to lauch the option byte loading */
 431   SET_BIT(FLASH->PECR, FLASH_PECR_OBL_LAUNCH);
 432
 433   /* Wait for last operation to be completed */
 434   return(FLASH_WaitForLastOperation((uint32_t)HAL_FLASH_TIMEOUT_VALUE));
 435 }
 436
 437 /**
 438   * @}
 439   */
 440
 441 /** @defgroup FLASH_Exported_Functions_Group3 Peripheral State and Errors functions
 442  *  @brief   Peripheral Errors functions
 443  *
 444 @verbatim
 445  ===============================================================================
 446                 ##### Peripheral Errors functions #####
 447  ===============================================================================
 448     [..]
 449     This subsection permit to get in run-time Errors of the FLASH peripheral.
 450
 451 @endverbatim
 452   * @{
 453   */
 454
 455 /**
 456   * @brief  Get the specific FLASH error flag.
 457   * @retval FLASH_ErrorCode: The returned value can be:
 458   *            @arg FLASH_ERROR_WRP: FLASH Write protected error flag
 459   *            @arg FLASH_ERROR_PGA: FLASH Programming Alignment error flag
 460   *            @arg FLASH_ERROR_SIZE: FLASH Size error flag
 461   *            @arg FLASH_ERROR_OPTV: Option validity error flag
 462   *            @arg FLASH_ERROR_OPTVUSR: Option UserValidity Error flag (available only Cat.3, Cat.4 and Cat.5 devices)
 463   *            @arg FLASH_ERROR_RD:   FLASH Read Protection error flag (PCROP) (available only Cat.2 and Cat.3 devices)
 464   */
 465 FLASH_ErrorTypeDef HAL_FLASH_GetError(void)
 466 {
 467    return ProcFlash.ErrorCode;
 468 }
 469
 470 /**
 471   * @}
 472   */
 473
 474 /**
 475   * @}
 476   */
 477
 478 #endif /* HAL_FLASH_MODULE_ENABLED */
 479
 480 /**
 481   * @}
 482   */
 483
 484 /**
 485   * @}
 486   */
 487
 488
 489
 490 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/