1 /** 2 * \file 3 * 4 * \brief FLASH related functionality declaration. 5 * 6 * Copyright (c) 2015-2018 Microchip Technology Inc. and its subsidiaries. 7 * 8 * \asf_license_start 9 * 10 * \page License 11 * 12 * Subject to your compliance with these terms, you may use Microchip 13 * software and any derivatives exclusively with Microchip products. 14 * It is your responsibility to comply with third party license terms applicable 15 * to your use of third party software (including open source software) that 16 * may accompany Microchip software. 17 * 18 * THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES, 19 * WHETHER EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE, 20 * INCLUDING ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, 21 * AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL MICROCHIP BE 22 * LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, INCIDENTAL OR CONSEQUENTIAL 23 * LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND WHATSOEVER RELATED TO THE 24 * SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS BEEN ADVISED OF THE 25 * POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE FULLEST EXTENT 26 * ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN ANY WAY 27 * RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY, 28 * THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE. 29 * 30 * \asf_license_stop 31 * 32 */ 33 #ifndef _HPL_FLASH_H_INCLUDED 34 #define _HPL_FLASH_H_INCLUDED 35 36 /** 37 * \addtogroup hpl__flash__group FLASH HPL APIs 38 * 39 */ 40 41 /**@{*/ 42 43 #include <compiler.h> 44 #include "hpl_irq.h" 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /** 51 * \brief FLASH device structure 52 * 53 * The FLASH device structure forward declaration. 54 */ 55 struct _flash_device; 56 57 /** The callback types */ 58 enum _flash_cb_type { FLASH_DEVICE_CB_READY, FLASH_DEVICE_CB_ERROR, FLASH_DEVICE_CB_N }; 59 60 /** 61 * \brief FLASH interrupt handlers structure 62 */ 63 struct _flash_callback { 64 /** Ready to accept new command handler */ 65 void (*ready_cb)(struct _flash_device *device); 66 /** Error handler */ 67 void (*error_cb)(struct _flash_device *device); 68 }; 69 70 /** 71 * \brief FLASH descriptor device structure. 72 */ 73 struct _flash_device { 74 struct _flash_callback flash_cb; /*!< Interrupt handers */ 75 struct _irq_descriptor irq; /*!< Interrupt descriptor */ 76 void * hw; /*!< Hardware module instance handler */ 77 }; 78 79 /** 80 * \brief Initialize FLASH. 81 * 82 * This function does low level FLASH configuration. 83 * 84 * \param[in] device The pointer to FLASH device instance 85 * \param[in] hw The pointer to hardware instance 86 * 87 * \return Initialize status. 88 */ 89 int32_t _flash_init(struct _flash_device *const device, void *const hw); 90 91 /** 92 * \brief Deinitialize FLASH. 93 * 94 * \param[in] device The pointer to FLASH device instance 95 */ 96 void _flash_deinit(struct _flash_device *const device); 97 98 /** 99 * \brief Reads a number of bytes in the internal Flash. 100 * 101 * \param[in] device The pointer to FLASH device instance 102 * \param[in] src_addr Source bytes address to read from flash 103 * \param[out] buffer Pointer to a buffer where the content 104 * of the read page will be stored 105 * \param[in] length Number of bytes to read 106 */ 107 void _flash_read(struct _flash_device *const device, const uint32_t src_addr, uint8_t *buffer, uint32_t length); 108 109 /** 110 * \brief Writes a number of bytes in the internal Flash. 111 * 112 * \param[in] device The pointer to FLASH device instance 113 * \param[in] dst_addr Destination bytes address to write into flash 114 * \param[in] buffer Pointer to buffer where the data to 115 * write is stored 116 * \param[in] length Number of bytes to write 117 */ 118 void _flash_write(struct _flash_device *const device, const uint32_t dst_addr, uint8_t *buffer, uint32_t length); 119 120 /** 121 * \brief Appends a number of bytes in the internal Flash. 122 * 123 * \param[in] device The pointer to FLASH device instance 124 * \param[in] dst_addr Destination bytes address to write into flash 125 * \param[in] buffer Pointer to buffer with data to write to flash 126 * \param[in] length Number of bytes to write 127 */ 128 void _flash_append(struct _flash_device *const device, const uint32_t dst_addr, uint8_t *buffer, uint32_t length); 129 130 /** \brief Execute lock in the internal flash 131 * \param[in] device The pointer to FLASH device instance 132 * \param[in] dst_addr Destination bytes address aligned with page 133 * start to be locked 134 * \param[in] page_nums Number of pages to be locked 135 * 136 * \return Real locked numbers of pages. 137 */ 138 int32_t _flash_lock(struct _flash_device *const device, const uint32_t dst_addr, uint32_t page_nums); 139 140 /** \brief Execute unlock in the internal flash 141 * \param[in] device The pointer to FLASH device instance 142 * \param[in] dst_addr Destination bytes address aligned with page 143 * start to be unlocked 144 * \param[in] page_nums Number of pages to be unlocked 145 * 146 * \return Real unlocked numbers of pages. 147 */ 148 int32_t _flash_unlock(struct _flash_device *const device, const uint32_t dst_addr, uint32_t page_nums); 149 150 /** \brief check whether the region which is pointed by address 151 * is locked 152 * \param[in] device The pointer to FLASH device instance 153 * \param[in] dst_addr Destination bytes address to check 154 * 155 * \return The lock status of assigned address. 156 */ 157 bool _flash_is_locked(struct _flash_device *const device, const uint32_t dst_addr); 158 159 /** \brief Execute erase in the internal flash 160 * \param[in] device The pointer to FLASH device instance 161 * \param[in] dst_addr Destination bytes address aligned with page 162 * start to be erased 163 * \param[in] page_nums Number of pages to be erased 164 */ 165 void _flash_erase(struct _flash_device *const device, const uint32_t dst_addr, uint32_t page_nums); 166 167 /** 168 * \brief Get the flash page size. 169 * 170 * \param[in] device The pointer to FLASH device instance 171 * 172 * \return The flash page size 173 */ 174 uint32_t _flash_get_page_size(struct _flash_device *const device); 175 176 /** 177 * \brief Get the numbers of flash page. 178 * 179 * \param[in] device The pointer to FLASH device instance 180 * 181 * \return The flash total page numbers 182 */ 183 uint32_t _flash_get_total_pages(struct _flash_device *const device); 184 185 /** 186 * \brief Get the number of wait states for read and write operations. 187 * 188 * \param[in] device The pointer to FLASH device instance 189 * 190 * \return The number of wait states for read and write operations 191 */ 192 uint8_t _flash_get_wait_state(struct _flash_device *const device); 193 194 /** 195 * \brief Set the number of wait states for read and write operations. 196 * 197 * \param[in] device The pointer to FLASH device instance 198 * \param[in] state The number of wait states 199 * 200 */ 201 void _flash_set_wait_state(struct _flash_device *const device, uint8_t state); 202 203 /** 204 * \brief Enable/disable Flash interrupt 205 * 206 * param[in] device The pointer to Flash device instance 207 * param[in] type The type of interrupt to disable/enable if applicable 208 * param[in] state Enable or disable 209 */ 210 void _flash_set_irq_state(struct _flash_device *const device, const enum _flash_cb_type type, const bool state); 211 212 /* 213 * Below RWW flash APIs are only available for device which has RWWEE 214 * flash array, such as SAM C20/C21/D21/L21/L22/R30/DA1/HA1 etc. 215 */ 216 /** 217 * \brief Get the RWWEE flash page size. 218 * 219 * \param[in] device The pointer to FLASH device instance 220 * 221 * \return The flash page size 222 */ 223 uint32_t _rww_flash_get_page_size(struct _flash_device *const device); 224 225 /** 226 * \brief Get the total page numbers of RWWEE flash. 227 * 228 * \param[in] device The pointer to FLASH device instance 229 * 230 * \return The flash total page numbers 231 */ 232 uint32_t _rww_flash_get_total_pages(struct _flash_device *const device); 233 234 /** 235 * \brief Reads a number of bytes in the internal RWWEE Flash. 236 * 237 * \param[in] device The pointer to FLASH device instance 238 * \param[in] src_addr Source bytes address to read from flash 239 * \param[out] buffer Pointer to a buffer where the content 240 * of the read page will be stored 241 * \param[in] length Number of bytes to read 242 * 243 * \return Read status, ERR_NONE for successful read. 244 */ 245 int32_t _rww_flash_read(struct _flash_device *const device, const uint32_t src_addr, uint8_t *buffer, uint32_t length); 246 247 /** 248 * \brief Writes a number of bytes in the internal RWWEE Flash. 249 * 250 * \param[in] device The pointer to FLASH device instance 251 * \param[in] dst_addr Destination bytes address to write into flash 252 * \param[in] buffer Pointer to buffer where the data to 253 * write is stored 254 * \param[in] length Number of bytes to write 255 * 256 * \return Write status, ERR_NONE for successful write. 257 */ 258 int32_t _rww_flash_write(struct _flash_device *const device, const uint32_t dst_addr, uint8_t *buffer, uint32_t length); 259 #ifdef __cplusplus 260 } 261 #endif 262 263 /**@}*/ 264 265 #endif /* _HPL_FLASH_H_INCLUDED */ 266