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 34 #ifndef _HAL_FLASH_H_INCLUDED 35 #define _HAL_FLASH_H_INCLUDED 36 37 #include <hpl_flash.h> 38 39 /** 40 * \addtogroup doc_driver_hal_flash 41 * 42 * @{ 43 */ 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /* Forward declaration of flash_descriptor. */ 50 struct flash_descriptor; 51 52 /** The callback types */ 53 enum flash_cb_type { 54 /** Callback type for ready to accept a new command */ 55 FLASH_CB_READY, 56 /** Callback type for error */ 57 FLASH_CB_ERROR, 58 FLASH_CB_N 59 }; 60 61 /** \brief Prototype of callback on FLASH 62 * 63 */ 64 typedef void (*flash_cb_t)(struct flash_descriptor *const descr); 65 66 /** \brief FLASH HAL callbacks 67 * 68 */ 69 struct flash_callbacks { 70 /** Callback invoked when ready to accept a new command */ 71 flash_cb_t cb_ready; 72 /** Callback invoked when error occurs */ 73 flash_cb_t cb_error; 74 }; 75 76 /** \brief FLASH HAL driver struct for asynchronous access 77 */ 78 struct flash_descriptor { 79 /** Pointer to FLASH device instance */ 80 struct _flash_device dev; 81 /** Callbacks for asynchronous transfer */ 82 struct flash_callbacks callbacks; 83 }; 84 85 /** \brief Initialize the FLASH HAL instance and hardware for callback mode 86 * 87 * Initialize FLASH HAL with interrupt mode (uses callbacks). 88 * 89 * \param[in, out] flash Pointer to the HAL FLASH instance. 90 * \param[in] hw Pointer to the hardware base. 91 * \return Initialize status. 92 */ 93 int32_t flash_init(struct flash_descriptor *flash, void *const hw); 94 95 /** \brief Deinitialize the FLASH HAL instance 96 * 97 * Abort transfer, disable and reset FLASH, and deinitialize software. 98 * 99 * \param[in, out] flash Pointer to the HAL FLASH instance. 100 * \return Deinitialze status. 101 */ 102 int32_t flash_deinit(struct flash_descriptor *flash); 103 104 /** \brief Writes a number of bytes to a page in the internal Flash 105 * 106 * \param[in, out] flash Pointer to the HAL FLASH instance. 107 * \param[in] dst_addr Destination bytes address to write into flash 108 * \param[in] buffer Pointer to a buffer where the content 109 * will be written to the flash 110 * \param[in] length Number of bytes to write 111 * \return Write status. 112 */ 113 int32_t flash_write(struct flash_descriptor *flash, uint32_t dst_addr, uint8_t *buffer, uint32_t length); 114 115 /** \brief Appends a number of bytes to a page in the internal Flash 116 * 117 * This functions never erases the flash before writing. 118 * 119 * \param[in, out] flash Pointer to the HAL FLASH instance. 120 * \param[in] dst_addr Destination bytes address to write to flash 121 * \param[in] buffer Pointer to a buffer with data to write to flash 122 * \param[in] length Number of bytes to append 123 * \return Append status. 124 */ 125 int32_t flash_append(struct flash_descriptor *flash, uint32_t dst_addr, uint8_t *buffer, uint32_t length); 126 127 /** \brief Reads a number of bytes to a page in the internal Flash 128 * 129 * \param[in, out] flash Pointer to the HAL FLASH instance. 130 * \param[in] src_addr Source bytes address to read from flash 131 * \param[out] buffer Pointer to a buffer where the content 132 * of the read pages will be stored 133 * \param[in] length Number of bytes to read 134 * \return Read status. 135 */ 136 int32_t flash_read(struct flash_descriptor *flash, uint32_t src_addr, uint8_t *buffer, uint32_t length); 137 138 /** \brief Register a function as FLASH transfer completion callback 139 * 140 * \param[in, out] flash Pointer to the HAL FLASH instance. 141 * \param[in] type Callback type (\ref flash_cb_type). 142 * \param[in] func Pointer to callback function. 143 * \retval 0 Success 144 * \retval -1 Error 145 */ 146 int32_t flash_register_callback(struct flash_descriptor *flash, const enum flash_cb_type type, flash_cb_t func); 147 148 /** \brief Execute lock in the internal flash 149 * 150 * \param[in, out] flash Pointer to the HAL FLASH instance. 151 * \param[in] dst_addr Destination bytes address aligned with page 152 * start to be locked 153 * \param[in] page_nums Number of pages to be locked 154 * 155 * \return Real locked numbers of pages. 156 */ 157 int32_t flash_lock(struct flash_descriptor *flash, const uint32_t dst_addr, const uint32_t page_nums); 158 159 /** \brief Execute unlock in the internal flash 160 * 161 * \param[in, out] flash Pointer to the HAL FLASH instance. 162 * \param[in] dst_addr Destination bytes address aligned with page 163 * start to be unlocked 164 * \param[in] page_nums Number of pages to be unlocked 165 * 166 * \return Real unlocked numbers of pages. 167 */ 168 int32_t flash_unlock(struct flash_descriptor *flash, const uint32_t dst_addr, const uint32_t page_nums); 169 170 /** \brief Execute erase in the internal flash 171 * 172 * \param[in, out] flash Pointer to the HAL FLASH instance. 173 * \param[in] dst_addr Destination bytes address aligned with page 174 * start to be erased 175 * \param[in] page_nums Number of pages to be erased 176 * \retval 0 Success 177 * \retval -1 Error 178 */ 179 int32_t flash_erase(struct flash_descriptor *flash, const uint32_t dst_addr, const uint32_t page_nums); 180 181 /** 182 * \brief Get the flash page size 183 * 184 * \param[in, out] flash Pointer to the HAL FLASH instance 185 * 186 * \return The flash page size 187 */ 188 uint32_t flash_get_page_size(struct flash_descriptor *flash); 189 190 /** 191 * \brief Get the number of flash page 192 * 193 * \param[in, out] flash Pointer to the HAL FLASH instance. 194 * 195 * \return The flash total page numbers 196 */ 197 uint32_t flash_get_total_pages(struct flash_descriptor *flash); 198 199 /** \brief Retrieve the current driver version 200 * 201 * \return Current driver version. 202 */ 203 uint32_t flash_get_version(void); 204 205 #ifdef __cplusplus 206 } 207 #endif 208 /**@}*/ 209 #endif /* ifndef _HAL_FLASH_H_INCLUDED */ 210