|
| 1 | +/** |
| 2 | + * |
| 3 | + * @file nvm.h |
| 4 | + * |
| 5 | + * @defgroup nvm_driver Non-Volatile Memory |
| 6 | + * |
| 7 | + * @brief This file contains API prototypes and other data types for the Non-Volatile Memory (NVM) driver. |
| 8 | + * |
| 9 | + * @version NVM Driver Version 3.2.0 |
| 10 | + */ |
| 11 | +/* |
| 12 | +© [2025] Microchip Technology Inc. and its subsidiaries. |
| 13 | +
|
| 14 | + Subject to your compliance with these terms, you may use Microchip |
| 15 | + software and any derivatives exclusively with Microchip products. |
| 16 | + You are responsible for complying with 3rd party license terms |
| 17 | + applicable to your use of 3rd party software (including open source |
| 18 | + software) that may accompany Microchip software. SOFTWARE IS ?AS IS.? |
| 19 | + NO WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS |
| 20 | + SOFTWARE, INCLUDING ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, |
| 21 | + MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT |
| 22 | + WILL MICROCHIP BE LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, |
| 23 | + INCIDENTAL OR CONSEQUENTIAL LOSS, DAMAGE, COST OR EXPENSE OF ANY |
| 24 | + KIND WHATSOEVER RELATED TO THE SOFTWARE, HOWEVER CAUSED, EVEN IF |
| 25 | + MICROCHIP HAS BEEN ADVISED OF THE POSSIBILITY OR THE DAMAGES ARE |
| 26 | + FORESEEABLE. TO THE FULLEST EXTENT ALLOWED BY LAW, MICROCHIP?S |
| 27 | + TOTAL LIABILITY ON ALL CLAIMS RELATED TO THE SOFTWARE WILL NOT |
| 28 | + EXCEED AMOUNT OF FEES, IF ANY, YOU PAID DIRECTLY TO MICROCHIP FOR |
| 29 | + THIS SOFTWARE. |
| 30 | +*/ |
| 31 | + |
| 32 | +#ifndef NVM_H |
| 33 | +#define NVM_H |
| 34 | + |
| 35 | +#include "../system/utils/compiler.h" |
| 36 | + |
| 37 | +/** |
| 38 | + * @ingroup nvm_driver |
| 39 | + * @def PROGMEM_BLOCK_SIZE |
| 40 | + * Contains the program memory block size in bytes. |
| 41 | + * The BOOTSIZE and CODESIZE fuses select the Flash section sizes in blocks of PROGMEM_BLOCK_SIZE bytes. |
| 42 | + */ |
| 43 | +#define PROGMEM_BLOCK_SIZE (512U) |
| 44 | + |
| 45 | + |
| 46 | +/** |
| 47 | + * @ingroup nvm_driver |
| 48 | + * @brief Data type for the Flash data. |
| 49 | + */ |
| 50 | +typedef uint8_t flash_data_t; |
| 51 | +/** |
| 52 | + * @ingroup nvm_driver |
| 53 | + * @brief Data type for the Flash address. |
| 54 | + */ |
| 55 | +typedef uint32_t flash_address_t; |
| 56 | + |
| 57 | +/** |
| 58 | + * @ingroup nvm_driver |
| 59 | + * @brief Data type for the EEPROM data. |
| 60 | + */ |
| 61 | +typedef uint8_t eeprom_data_t; |
| 62 | +/** |
| 63 | + * @ingroup nvm_driver |
| 64 | + * @brief Data type for the EEPROM address. |
| 65 | + */ |
| 66 | +typedef uint16_t eeprom_address_t; |
| 67 | + |
| 68 | +/** |
| 69 | + * @ingroup nvm_driver |
| 70 | + * @enum nvm_status_t |
| 71 | + * @brief Contains the return codes for the NVM driver APIs. |
| 72 | + */ |
| 73 | +typedef enum |
| 74 | +{ |
| 75 | + NVM_OK, /**<0 - The NVM operation succeeded*/ |
| 76 | + NVM_ERROR /**<1 - The NVM operation failed*/ |
| 77 | +} nvm_status_t; |
| 78 | + |
| 79 | +/** |
| 80 | + * @ingroup nvm_driver |
| 81 | + * @brief Initializes the NVM driver. |
| 82 | + * @param None. |
| 83 | + * @return None. |
| 84 | + */ |
| 85 | +void NVM_Initialize(void); |
| 86 | + |
| 87 | +/** |
| 88 | + * @ingroup nvm_driver |
| 89 | + * @brief Returns the status of the last NVM operation. |
| 90 | + * @param None. |
| 91 | + * @retval NVM_OK - The NVM operation succeeded |
| 92 | + * @retval NVM_ERROR - The NVM operation failed |
| 93 | + */ |
| 94 | +nvm_status_t NVM_StatusGet(void); |
| 95 | + |
| 96 | +/** |
| 97 | + * @ingroup nvm_driver |
| 98 | + * @brief Clears the NVM error status. |
| 99 | + * @param None. |
| 100 | + * @return None. |
| 101 | + */ |
| 102 | +void NVM_StatusClear(void); |
| 103 | + |
| 104 | +/** |
| 105 | + * @ingroup nvm_driver |
| 106 | + * @brief Reads a byte from the given Flash address. |
| 107 | + * @pre NVM must be initialized with @ref NVM_Initialize() before calling this API. |
| 108 | + * @param [in] address - Address of the Flash location from which data is to be read |
| 109 | + * @return Byte read from the given Flash address. |
| 110 | + */ |
| 111 | +flash_data_t FLASH_Read(flash_address_t address); |
| 112 | + |
| 113 | +/** |
| 114 | + * @ingroup nvm_driver |
| 115 | + * @brief Writes a word at the given Flash address. |
| 116 | + * As this is a non-portable API, it may not be supported by all 8-bit PIC® and AVR® devices. |
| 117 | + * @pre NVM must be initialized with @ref NVM_Initialize() before calling this API. |
| 118 | + * Erase the Flash location before writing. |
| 119 | + * @param [in] address - Address of the Flash location at which data is to be written |
| 120 | + * @param [in] data - Word to be written |
| 121 | + * @return Status of the Flash write operation as described in @ref nvm_status_t. |
| 122 | + */ |
| 123 | +nvm_status_t FLASH_Write(flash_address_t address, uint16_t data); |
| 124 | + |
| 125 | +/** |
| 126 | + * @ingroup nvm_driver |
| 127 | + * @brief Writes one entire Flash row/page from the given starting address of the row (the first byte location). |
| 128 | + * The size of the input buffer must be one Flash row and the address must be aligned with the row boundary. |
| 129 | + * Use @ref FLASH_PageAddressGet() to obtain the starting address of the row. |
| 130 | + * @pre Erase Flash row before calling this function. |
| 131 | + * @param [in] address - Starting address of the Flash row to be written |
| 132 | + * @param [in] *dataBuffer - Pointer to a buffer which holds the data to be written |
| 133 | + * @return Status of the Flash row write operation as described in @ref nvm_status_t. |
| 134 | + */ |
| 135 | +nvm_status_t FLASH_RowWrite(flash_address_t address, flash_data_t *dataBuffer); |
| 136 | + |
| 137 | +/** |
| 138 | + * @ingroup nvm_driver |
| 139 | + * @brief Erases one Flash page containing the given address. |
| 140 | + * @pre NVM must be initialized with @ref NVM_Initialize() before calling this API. |
| 141 | + * @param [in] address - Starting address of the Flash page to be erased. |
| 142 | + * @return Status of the Flash page erase operation as described in @ref nvm_status_t. |
| 143 | + */ |
| 144 | +nvm_status_t FLASH_PageErase(flash_address_t address); |
| 145 | + |
| 146 | +/** |
| 147 | + * @ingroup nvm_driver |
| 148 | + * @brief Checks if the Flash is busy. |
| 149 | + * @pre NVM must be initialized with @ref NVM_Initialize() before calling this API. |
| 150 | + * @param None. |
| 151 | + * @retval True - The Flash operation is being performed |
| 152 | + * @retval False - The Flash operation is not being performed |
| 153 | + */ |
| 154 | +bool FLASH_IsBusy(void); |
| 155 | + |
| 156 | +/** |
| 157 | + * @ingroup nvm_driver |
| 158 | + * @brief Returns the starting address of the page (the first byte location) containing the given Flash address. |
| 159 | + * @param [in] address - Flash address for which the page starting address will be obtained |
| 160 | + * @return Starting address of the page containing the given Flash address. |
| 161 | + */ |
| 162 | +flash_address_t FLASH_PageAddressGet(flash_address_t address); |
| 163 | + |
| 164 | +/** |
| 165 | + * @ingroup nvm_driver |
| 166 | + * @brief Returns the offset from the starting address of the page (the first byte location). |
| 167 | + * @param [in] address - Flash address for which the offset from the starting address of the page will be obtained |
| 168 | + * @return Offset of the given address from the starting address of the page. |
| 169 | + */ |
| 170 | +uint16_t FLASH_PageOffsetGet(flash_address_t address); |
| 171 | + |
| 172 | +//Below macros are added to provide backward compatibility. These will be deprecated in the future versions. |
| 173 | +#define FLASH_ErasePageAddressGet FLASH_PageAddressGet |
| 174 | +#define FLASH_ErasePageOffsetGet FLASH_PageOffsetGet |
| 175 | + |
| 176 | +/** |
| 177 | + * @ingroup nvm_driver |
| 178 | + * @brief Reads one byte from the given EEPROM address. |
| 179 | + * @pre NVM must be initialized with @ref NVM_Initialize() before calling this API. |
| 180 | + * @param [in] address - Address of the EEPROM location to be read |
| 181 | + * @return Byte read from the given EEPROM address. |
| 182 | + */ |
| 183 | +eeprom_data_t EEPROM_Read(eeprom_address_t address); |
| 184 | + |
| 185 | +/** |
| 186 | + * @ingroup nvm_driver |
| 187 | + * @brief Writes one byte to the given EEPROM address. |
| 188 | + * The EEPROM Busy status must be checked using the @ref EEPROM_IsBusy() API to know if the write operation is completed. |
| 189 | + * Use the @ref NVM_StatusGet() API to see the result of the write operation. |
| 190 | + * @param [in] address - Address of the EEPROM location to be written |
| 191 | + * @param [in] data - Byte to be written to the given EEPROM location |
| 192 | + * @return None. |
| 193 | + */ |
| 194 | +void EEPROM_Write(eeprom_address_t address, eeprom_data_t data); |
| 195 | + |
| 196 | +/** |
| 197 | + * @ingroup nvm_driver |
| 198 | + * @brief Checks if the EEPROM is busy. |
| 199 | + * @pre NVM must be initialized with @ref NVM_Initialize() before calling this API. |
| 200 | + * @param None. |
| 201 | + * @retval True - The EEPROM operation is being performed |
| 202 | + * @retval False - The EEPROM operation is not being performed |
| 203 | + */ |
| 204 | +bool EEPROM_IsBusy(void); |
| 205 | + |
| 206 | +#endif //NVM_H |
0 commit comments