1 //***************************************************************************** 2 // 3 //! @file am_hal_mram.h 4 //! 5 //! @brief BootROM Helper Function Table 6 //! 7 //! @addtogroup mram4_4p MRAM Functionality 8 //! @ingroup apollo4p_hal 9 //! @{ 10 // 11 //***************************************************************************** 12 13 //***************************************************************************** 14 // 15 // Copyright (c) 2023, Ambiq Micro, Inc. 16 // All rights reserved. 17 // 18 // Redistribution and use in source and binary forms, with or without 19 // modification, are permitted provided that the following conditions are met: 20 // 21 // 1. Redistributions of source code must retain the above copyright notice, 22 // this list of conditions and the following disclaimer. 23 // 24 // 2. Redistributions in binary form must reproduce the above copyright 25 // notice, this list of conditions and the following disclaimer in the 26 // documentation and/or other materials provided with the distribution. 27 // 28 // 3. Neither the name of the copyright holder nor the names of its 29 // contributors may be used to endorse or promote products derived from this 30 // software without specific prior written permission. 31 // 32 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 33 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 34 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 35 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 36 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 37 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 38 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 39 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 40 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 41 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 42 // POSSIBILITY OF SUCH DAMAGE. 43 // 44 // This is part of revision release_sdk_4_4_0-3c5977e664 of the AmbiqSuite Development Package. 45 // 46 //***************************************************************************** 47 #ifndef AM_HAL_MRAM_H 48 #define AM_HAL_MRAM_H 49 50 #ifdef __cplusplus 51 extern "C" 52 { 53 #endif 54 55 #include <stdint.h> 56 #include <stdbool.h> 57 58 //***************************************************************************** 59 // 60 //! @name MRAM Program keys. 61 //! @{ 62 // 63 //***************************************************************************** 64 #define AM_HAL_MRAM_PROGRAM_KEY 0x12344321 65 #define AM_HAL_MRAM_INFO_KEY 0xD894E09E 66 //! @} 67 68 //***************************************************************************** 69 // 70 //! @name Some helpful SRAM values and macros. 71 //! @{ 72 // 73 //***************************************************************************** 74 #define AM_HAL_MRAM_SRAM_ADDR SRAM_BASEADDR 75 #define AM_HAL_MRAM_SRAM_SIZE (1024 * 1024) 76 #define AM_HAL_MRAM_SRAM_LARGEST_VALID_ADDR (AM_HAL_MRAM_SRAM_ADDR + AM_HAL_MRAM_SRAM_SIZE - 1) 77 #define AM_HAL_MRAM_DTCM_START AM_HAL_MRAM_SRAM_ADDR 78 #define AM_HAL_MRAM_DTCM_END (AM_HAL_MRAM_SRAM_ADDR + (384 * 1024) - 1) 79 //! @} 80 81 //***************************************************************************** 82 // 83 //! @name Some helpful MRAM values and macros. 84 //! @{ 85 // 86 //***************************************************************************** 87 #define AM_HAL_MRAM_ADDR MRAM_BASEADDR 88 #define AM_HAL_MRAM_INSTANCE_SIZE ( 1 * 1024 * 1024 ) 89 #define AM_HAL_MRAM_NUM_INSTANCES 2 90 #define AM_HAL_MRAM_TOTAL_SIZE ( AM_HAL_MRAM_INSTANCE_SIZE * AM_HAL_MRAM_NUM_INSTANCES ) 91 #define AM_HAL_MRAM_LARGEST_VALID_ADDR ( AM_HAL_MRAM_ADDR + AM_HAL_MRAM_TOTAL_SIZE - 1 ) 92 //! @} 93 94 #define AM_HAL_INFO0_SIZE_BYTES (2 * 1024) 95 #define AM_HAL_INFO1_SIZE_BYTES (6 * 1024) 96 #define AM_HAL_INFO1_VISIBLE_OFFSET (0x1200) 97 98 //***************************************************************************** 99 // 100 //! @brief This programs up to N words of the Main MRAM 101 //! 102 //! @param ui32ProgramKey - The programming key, AM_HAL_MRAM_PROGRAM_KEY. 103 //! @param pui32Src - Pointer to word aligned array of data to program into 104 //! the MRAM. 105 //! @param pui32Dst - Pointer to the 4 words (16 byte) aligned MRAM location where 106 //! programming of the MRAM is to begin. 107 //! @param ui32NumWords - The number of words to be programmed. This MUST be 108 //! a multiple of 4 (16 byte multiple) 109 //! 110 //! This function will program multiple 4 words (16 byte) tuples in main MRAM. 111 //! 112 //! @note THIS FUNCTION ONLY OPERATES ON 16 BYTE BLOCKS OF MAIN MRAM. The pDst 113 //! MUST be 4 words (16 byte) aligned, and ui32NumWords MUST be multiple of 4. 114 //! 115 //! @return 0 for success, non-zero for failure. 116 //! Failing return code indicates: 117 //! -1 invalid alignment for pui32Dst or ui32NumWords not 16 byte multiple 118 //! 1 ui32ProgramKey is invalid. 119 //! 2 pui32Dst is invalid. 120 //! 3 Flash addressing range would be exceeded. That is, (pui32Dst + 121 //! (ui32NumWords * 4)) is greater than the last valid address. 122 //! 4 pui32Src is invalid. 123 //! 5 pui32Src is invalid. 124 //! 6 Flash controller hardware timeout. 125 // 126 //***************************************************************************** 127 extern int am_hal_mram_main_program(uint32_t ui32ProgramKey, uint32_t *pui32Src, 128 uint32_t *pui32Dst, uint32_t ui32NumWords); 129 130 //***************************************************************************** 131 // 132 //! @brief This Fills up to N words of the Main MRAM 133 //! 134 //! @param ui32ProgramKey - The programming key, AM_HAL_MRAM_PROGRAM_KEY. 135 //! @param ui32Value - 32-bit data value to fill into the MRAM 136 //! @param pui32Dst - Pointer to the 4 words (16 byte) aligned MRAM location where 137 //! programming of the MRAM is to begin. 138 //! @param ui32NumWords - The number of words to be programmed. This MUST be 139 //! a multiple of 4 (16 byte multiple) 140 //! 141 //! This function will fill multiple 16 byte tuples in main MRAM with specified pattern. 142 //! 143 //! @note THIS FUNCTION ONLY OPERATES ON 16 BYTE BLOCKS OF MAIN MRAM. The pDst 144 //! MUST be 4 words (16 byte) aligned, and ui32NumWords MUST be multiple of 4. 145 //! 146 //! @return 0 for success, non-zero for failure. 147 //! -1 invalid alignment for pui32Dst or ui32NumWords not 16 byte multiple 148 //! 1 ui32InfoKey is invalid. 149 //! 2 ui32Offset is invalid. 150 //! 3 addressing range would be exceeded. That is, (ui32Offset + 151 //! (ui32NumWords * 4)) is greater than the last valid address. 152 //! 4 pui32Src is invalid. 153 //! 5 pui32Src is invalid. 154 //! 6 Flash controller hardware timeout. 155 // 156 //***************************************************************************** 157 extern int am_hal_mram_main_fill(uint32_t ui32ProgramKey, uint32_t ui32Value, 158 uint32_t *pui32Dst, uint32_t ui32NumWords); 159 160 //***************************************************************************** 161 // 162 //! @brief This programs up to N words of the Main array on one MRAM. 163 //! 164 //! @param ui32InfoKey - The programming key, AM_HAL_MRAM_INFO_KEY. 165 //! @param pui32Src - Pointer to word aligned array of data to program into 166 //! INFO0 167 //! @param ui32Offset - Pointer to the word aligned INFO0 offset where 168 //! programming of the INFO0 is to begin. 169 //! @param ui32NumWords - The number of words to be programmed. 170 //! 171 //! This function will program multiple words in INFO0 172 //! 173 //! @return 0 for success, non-zero for failure. 174 //! 1 ui32InfoKey is invalid. 175 //! 2 ui32Offset is invalid. 176 //! 3 addressing range would be exceeded. That is, (ui32Offset + 177 //! (ui32NumWords * 4)) is greater than the last valid address. 178 //! 4 pui32Src is invalid. 179 //! 5 pui32Src is invalid. 180 //! 6 Flash controller hardware timeout. 181 // 182 //***************************************************************************** 183 extern int am_hal_mram_info_program(uint32_t ui32InfoKey, uint32_t *pui32Src, 184 uint32_t ui32Offset, uint32_t ui32NumWords); 185 186 //***************************************************************************** 187 // 188 //! @brief This function erases main MRAM + customer INFO space 189 //! 190 //! @param ui32BrickKey - The Brick key. 191 //! 192 //! This function erases main MRAM and customer INFOinstance 193 //! even if the customer INFO space is programmed to not be erasable. This 194 //! function completely erases the MRAM main and info instance and wipes the 195 //! SRAM. Upon completion of the erasure operations, it does a POI (power on 196 //! initialization) reset. 197 //! 198 //! @note This function enforces 128 bit customer key lock. The caller needs to assert 199 //! the Recovery Lock using am_hal_security_set_key() providing appropriate key. 200 //! Otherwise, the function will fail. Therefore, always check for a return code. 201 //! If the function returns, a failure has occured. 202 //! 203 //! @return Does not return if successful. Returns failure code otherwise. 204 //! Failing return code indicates: 205 //! 0x00000001 ui32BrickKey is invalid. 206 //! 0x00000002 Recovery key lock not set. 207 //! Other values indicate Internal error. 208 // 209 //***************************************************************************** 210 extern int am_hal_mram_recovery(uint32_t ui32BrickKey); 211 212 //***************************************************************************** 213 // 214 //! @brief This programs up to N words of the Main MRAM 215 //! 216 //! @param ui32ProgramKey - The programming key, AM_HAL_MRAM_PROGRAM_KEY. 217 //! @param pui32Src - Pointer to word aligned array of data to program into 218 //! the MRAM. 219 //! @param pui32Dst - Pointer to the words (4 byte) aligned MRAM location where 220 //! programming of the MRAM is to begin. 221 //! @param ui32NumWords - The number of words to be programmed. 222 //! 223 //! This function will program multiple words (4 byte) tuples in main MRAM. 224 //! 225 //! @note This function is provided only for convenience. It is most efficient 226 //! to operate on MRAM in be 4 words (16 byte) aligned multiples. Doing word 227 //! access will be very inefficient and should be avoided. 228 //! 229 //! @return 0 for success, non-zero for failure. 230 //! Failing return code indicates: 231 //! -1 invalid alignment for pui32Dst or ui32NumWords not 16 bye multiple 232 //! 1 ui32ProgramKey is invalid. 233 //! 2 pui32Dst is invalid. 234 //! 3 Flash addressing range would be exceeded. That is, (pui32Dst + 235 //! (ui32NumWords * 4)) is greater than the last valid address. 236 //! 4 pui32Src is invalid. 237 //! 5 pui32Src is invalid. 238 //! 6 Flash controller hardware timeout. 239 // 240 //***************************************************************************** 241 extern int am_hal_mram_main_words_program(uint32_t ui32ProgramKey, uint32_t *pui32Src, 242 uint32_t *pui32Dst, uint32_t ui32NumWords); 243 244 //***************************************************************************** 245 // 246 //! @brief Read INFO data. 247 //! 248 //! This function implements a workaround required for Apollo4 B0 parts in 249 //! order to accurately read INFO space. 250 //! 251 //! @param ui32InfoSpace - 0 = Read INFO0. 252 //! 1 = Only valid to read the customer visible area 253 //! of INFO1. If INFO1, the ui32WordOffset argument 254 //! must be 0x480 or greater (byte offset 0x1200). 255 //! @param ui32WordOffset - Desired word offset into INFO space. 256 //! @param ui32NumWords - The number of words to be retrieved. 257 //! @param pui32Dst - Pointer to the location where the INFO data 258 //! is to be copied to. 259 //! 260 //! @return 0 for success, non-zero for failure. 261 // 262 //***************************************************************************** 263 extern int am_hal_mram_info_read(uint32_t ui32InfoSpace, uint32_t ui32WordOffset, 264 uint32_t ui32NumWords, uint32_t *pui32Dst); 265 266 //***************************************************************************** 267 // 268 //! @brief Initialize MRAM for DeepSleep. 269 //! 270 //! This function is currently hollow for the apollo4p 271 //! 272 //! @return 0 for success, non-zero for failure. 273 // 274 //***************************************************************************** 275 extern int am_hal_mram_ds_init(void); 276 277 #ifdef __cplusplus 278 } 279 #endif 280 281 #endif // AM_HAL_MRAM_H 282 283 //***************************************************************************** 284 // 285 // End Doxygen group. 286 //! @} 287 // 288 //***************************************************************************** 289 290
