1 /** 2 * @file 3 * @brief Flash Controler driver. 4 * @details This driver can be used to operate on the embedded flash memory. 5 */ 6 7 /* **************************************************************************** 8 * Copyright (C) 2016 Maxim Integrated Products, Inc., All Rights Reserved. 9 * 10 * Permission is hereby granted, free of charge, to any person obtaining a 11 * copy of this software and associated documentation files (the "Software"), 12 * to deal in the Software without restriction, including without limitation 13 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 14 * and/or sell copies of the Software, and to permit persons to whom the 15 * Software is furnished to do so, subject to the following conditions: 16 * 17 * The above copyright notice and this permission notice shall be included 18 * in all copies or substantial portions of the Software. 19 * 20 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 21 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 22 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 23 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES 24 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 25 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 26 * OTHER DEALINGS IN THE SOFTWARE. 27 * 28 * Except as contained in this notice, the name of Maxim Integrated 29 * Products, Inc. shall not be used except as stated in the Maxim Integrated 30 * Products, Inc. Branding Policy. 31 * 32 * The mere transfer of this software does not imply any licenses 33 * of trade secrets, proprietary technology, copyrights, patents, 34 * trademarks, maskwork rights, or any other form of intellectual 35 * property whatsoever. Maxim Integrated Products, Inc. retains all 36 * ownership rights. 37 * 38 * $Date: 2019-06-05 16:53:29 -0500 (Wed, 05 Jun 2019) $ 39 * $Revision: 43696 $ 40 * 41 *************************************************************************** */ 42 43 #ifndef _FLC_H_ 44 #define _FLC_H_ 45 46 /* **** Includes **** */ 47 #include "flc_regs.h" 48 #include "mxc_sys.h" 49 50 #ifdef __cplusplus 51 extern "C" { 52 #endif 53 54 /** 55 * @defgroup flc Flash Controller 56 * @ingroup periphlibs 57 * @{ 58 */ 59 60 /***** Definitions *****/ 61 62 /// Bit mask that can be used to find the starting address of a page in flash 63 #define MXC_FLASH_PAGE_MASK ~(MXC_FLASH_PAGE_SIZE - 1) 64 65 /// Calculate the address of a page in flash from the page number 66 #define MXC_FLASH_PAGE_ADDR(page) (MXC_FLASH_MEM_BASE + ((unsigned long)page * MXC_FLASH_PAGE_SIZE)) 67 68 /***** Function Prototypes *****/ 69 70 /** 71 * @brief Initializes the flash controller for erase/write operations 72 * @param sys_cfg Reserved for future use. Use NULL as this parameter's value. 73 * @return #E_NO_ERROR if successful, @ref MXC_Error_Codes "error" if unsuccessful. 74 */ 75 int FLC_Init(const sys_cfg_flc_t *sys_cfg); 76 77 /** 78 * @brief Checks if Flash controller is busy. 79 * @details Reading or executing from flash is not possible if flash is busy 80 * with an erase or write operation. 81 * @return If non-zero, flash operation is in progress 82 */ 83 int FLC_Busy(void); 84 85 /** 86 * @brief Erases the entire flash array. 87 * @return #E_NO_ERROR if successful, @ref MXC_Error_Codes "error" if unsuccessful. 88 */ 89 int FLC_MassErase(void); 90 91 /** 92 * @brief Erases the page of flash at the specified address. 93 * @param address Any address within the page to erase. 94 * @return #E_NO_ERROR if successful, @ref MXC_Error_Codes "error" if unsuccessful. 95 */ 96 int FLC_PageErase(uint32_t address); 97 98 /** 99 * @brief Page erase from start to end address. 100 * @note All data within the selected pages will be erased. 101 * @param start Any address within the first page to erase. 102 * @param end Any address within the last page to erase. 103 * @return #E_NO_ERROR if successful, @ref MXC_Error_Codes "error" if unsuccessful. 104 */ 105 int FLC_Erase(uint32_t start, uint32_t end); 106 107 /** 108 * @brief Erase from start to end address. Restoring any flash page contents outside the given range. 109 * @param start Starting address to erase, inclusive. 110 * @param end Ending address to erase, exclusive. 111 * @param buffer Data buffer to restore data in beginning and ending pages. 112 * @param length Length of given buffer. 113 * 114 * @note Buffer should be appropriate size to store all of the data remaining in the 115 * first and last pages. length should be greater than or equal to 116 * (start % MXC_FLASH_PAGE_SIZE) and ((MXC_FLASH_PAGE_SIZE - (end % MXC_FLASH_PAGE_SIZE)) % MXC_FLASH_PAGE_SIZE). 117 * 118 * @return #E_NO_ERROR if successful, @ref MXC_Error_Codes "error" if unsuccessful. 119 */ 120 int FLC_BufferErase(uint32_t start, uint32_t end, uint8_t *buffer, unsigned length); 121 122 /** 123 * @brief Writes the specified 32-bit value to flash. 124 * @param address 32-bit aligned address in flash to write. 125 * @param data value to be written to flash. 126 * @return #E_NO_ERROR if successful, @ref MXC_Error_Codes "error" if 127 * unsuccessful. 128 */ 129 int FLC_Write32(uint32_t address, uint32_t data); 130 131 /** 132 * @brief Writes the specified 128-bits of data to flash. 133 * @param address 128-bit aligned address in flash to write. 134 * @param data pointer to data to be written to flash. 135 * @return #E_NO_ERROR if successful, @ref MXC_Error_Codes "error" if 136 * unsuccessful. 137 */ 138 int FLC_Write128(uint32_t address, uint32_t *data); 139 140 /** 141 * @brief Writes data to flash. 142 * @param address Address in flash to start writing from. 143 * @param length Number of bytes to be written. 144 * @param buffer Pointer to data to be written to flash. 145 * @return #E_NO_ERROR if successful, @ref MXC_Error_Codes "error" if 146 * unsuccessful. 147 */ 148 int FLC_Write(uint32_t address, uint32_t length, uint8_t *buffer); 149 150 /** 151 * @brief Enable flash interrupts 152 * @param mask Interrupts to enable 153 * @return #E_NO_ERROR if successful, @ref MXC_Error_Codes "error" if 154 * unsuccessful. 155 */ 156 int FLC_EnableInt(uint32_t mask); 157 158 /** 159 * @brief Disable flash interrupts 160 * @param mask Interrupts to disable 161 * @return #E_NO_ERROR if successful, @ref MXC_Error_Codes "error" if 162 * unsuccessful. 163 */ 164 int FLC_DisableInt(uint32_t mask); 165 166 /** 167 * @brief Retrieve flash interrupt flags 168 * @return Mask of active flags. 169 */ 170 int FLC_GetFlags(void); 171 172 /** 173 * @brief Clear flash interrupt flags 174 * @note Provide the bit position to clear, even if the flag is write-0-to-clear 175 * @param mask Mask of flags to clear 176 * @return #E_NO_ERROR if successful, @ref MXC_Error_Codes "error" if 177 * unsuccessful. 178 */ 179 int FLC_ClearFlags(uint32_t mask); 180 181 /** 182 * @brief Unlock info block 183 * 184 * @return #E_NO_ERROR If function is successful. 185 */ 186 int FLC_UnlockInfoBlock(void); 187 188 /** 189 * @brief Lock info block 190 * 191 * @return #E_NO_ERROR If function is successful. 192 */ 193 int FLC_LockInfoBlock(void); 194 /**@} end of group flc */ 195 196 #ifdef __cplusplus 197 } 198 #endif 199 200 #endif /* _FLC_H_ */ 201