1 /* --COPYRIGHT--,BSD 2 * Copyright (c) 2017, Texas Instruments Incorporated 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of Texas Instruments Incorporated nor the names of 17 * its contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 * --/COPYRIGHT--*/ 32 #ifndef __FLASH_H__ 33 #define __FLASH_H__ 34 35 #include <stdbool.h> 36 #include <ti/devices/msp432p4xx/inc/msp.h> 37 38 /* Define to ensure that our current MSP432 has the FLCTL module. This 39 definition is included in the device specific header file */ 40 #ifdef __MCU_HAS_FLCTL__ 41 42 //***************************************************************************** 43 // 44 //! \addtogroup flash_api 45 //! @{ 46 // 47 //***************************************************************************** 48 49 //***************************************************************************** 50 // 51 // If building with a C++ compiler, make all of the definitions in this header 52 // have a C binding. 53 // 54 //***************************************************************************** 55 #ifdef __cplusplus 56 extern "C" 57 { 58 #endif 59 60 //***************************************************************************** 61 // 62 // Control specific variables 63 // 64 //***************************************************************************** 65 #define FLASH_BURST_PRG_BIT 0x03 66 67 /* Interrupts */ 68 #define FLASH_PROGRAM_ERROR FLCTL_IFG_PRG_ERR 69 #define FLASH_BENCHMARK_INT FLCTL_IFG_BMRK 70 #define FLASH_ERASE_COMPLETE FLCTL_IFG_ERASE 71 #define FLASH_BRSTPRGM_COMPLETE FLCTL_IFG_PRGB 72 #define FLASH_WRDPRGM_COMPLETE FLCTL_IFG_PRG 73 #define FLASH_POSTVERIFY_FAILED FLCTL_IFG_AVPST 74 #define FLASH_PREVERIFY_FAILED FLCTL_IFG_AVPRE 75 #define FLASH_BRSTRDCMP_COMPLETE FLCTL_IFG_RDBRST 76 77 #define FLASH_NORMAL_READ_MODE FLCTL_BANK0_RDCTL_RD_MODE_0 78 #define FLASH_MARGIN0_READ_MODE FLCTL_BANK0_RDCTL_RD_MODE_1 79 #define FLASH_MARGIN1_READ_MODE FLCTL_BANK0_RDCTL_RD_MODE_2 80 #define FLASH_PROGRAM_VERIFY_READ_MODE FLCTL_BANK0_RDCTL_RD_MODE_3 81 #define FLASH_ERASE_VERIFY_READ_MODE FLCTL_BANK0_RDCTL_RD_MODE_4 82 #define FLASH_LEAKAGE_VERIFY_READ_MODE FLCTL_BANK0_RDCTL_RD_MODE_5 83 #define FLASH_MARGIN0B_READ_MODE FLCTL_BANK0_RDCTL_RD_MODE_9 84 #define FLASH_MARGIN1B_READ_MODE FLCTL_BANK0_RDCTL_RD_MODE_10 85 86 #define FLASH_PRGBRSTCTLSTAT_BURSTSTATUS_COMPLETE FLCTL_PRGBRST_CTLSTAT_BURST_STATUS_7 87 88 #define FLASH_BANK0 0x00 89 #define FLASH_BANK1 0x01 90 #define FLASH_DATA_READ 0x00 91 #define FLASH_INSTRUCTION_FETCH 0x01 92 93 #define FLASH_MAIN_MEMORY_SPACE_BANK0 0x01 94 #define FLASH_MAIN_MEMORY_SPACE_BANK1 0x02 95 #define FLASH_INFO_MEMORY_SPACE_BANK0 0x03 96 #define FLASH_INFO_MEMORY_SPACE_BANK1 0x04 97 98 #define FLASH_MAIN_SPACE FLCTL_RDBRST_CTLSTAT_MEM_TYPE_0 99 #define FLASH_INFO_SPACE FLCTL_RDBRST_CTLSTAT_MEM_TYPE_1 100 #define FLASH_1_PATTERN FLCTL_RDBRST_CTLSTAT_DATA_CMP 101 #define FLASH_0_PATTERN 0x00 102 103 #define FLASH_SECTOR0 FLCTL_BANK0_MAIN_WEPROT_PROT0 104 #define FLASH_SECTOR1 FLCTL_BANK0_MAIN_WEPROT_PROT1 105 #define FLASH_SECTOR2 FLCTL_BANK0_MAIN_WEPROT_PROT2 106 #define FLASH_SECTOR3 FLCTL_BANK0_MAIN_WEPROT_PROT3 107 #define FLASH_SECTOR4 FLCTL_BANK0_MAIN_WEPROT_PROT4 108 #define FLASH_SECTOR5 FLCTL_BANK0_MAIN_WEPROT_PROT5 109 #define FLASH_SECTOR6 FLCTL_BANK0_MAIN_WEPROT_PROT6 110 #define FLASH_SECTOR7 FLCTL_BANK0_MAIN_WEPROT_PROT7 111 #define FLASH_SECTOR8 FLCTL_BANK0_MAIN_WEPROT_PROT8 112 #define FLASH_SECTOR9 FLCTL_BANK0_MAIN_WEPROT_PROT9 113 #define FLASH_SECTOR10 FLCTL_BANK0_MAIN_WEPROT_PROT10 114 #define FLASH_SECTOR11 FLCTL_BANK0_MAIN_WEPROT_PROT11 115 #define FLASH_SECTOR12 FLCTL_BANK0_MAIN_WEPROT_PROT12 116 #define FLASH_SECTOR13 FLCTL_BANK0_MAIN_WEPROT_PROT13 117 #define FLASH_SECTOR14 FLCTL_BANK0_MAIN_WEPROT_PROT14 118 #define FLASH_SECTOR15 FLCTL_BANK0_MAIN_WEPROT_PROT15 119 #define FLASH_SECTOR16 FLCTL_BANK0_MAIN_WEPROT_PROT16 120 #define FLASH_SECTOR17 FLCTL_BANK0_MAIN_WEPROT_PROT17 121 #define FLASH_SECTOR18 FLCTL_BANK0_MAIN_WEPROT_PROT18 122 #define FLASH_SECTOR19 FLCTL_BANK0_MAIN_WEPROT_PROT19 123 #define FLASH_SECTOR20 FLCTL_BANK0_MAIN_WEPROT_PROT20 124 #define FLASH_SECTOR21 FLCTL_BANK0_MAIN_WEPROT_PROT21 125 #define FLASH_SECTOR22 FLCTL_BANK0_MAIN_WEPROT_PROT22 126 #define FLASH_SECTOR23 FLCTL_BANK0_MAIN_WEPROT_PROT23 127 #define FLASH_SECTOR24 FLCTL_BANK0_MAIN_WEPROT_PROT24 128 #define FLASH_SECTOR25 FLCTL_BANK0_MAIN_WEPROT_PROT25 129 #define FLASH_SECTOR26 FLCTL_BANK0_MAIN_WEPROT_PROT26 130 #define FLASH_SECTOR27 FLCTL_BANK0_MAIN_WEPROT_PROT27 131 #define FLASH_SECTOR28 FLCTL_BANK0_MAIN_WEPROT_PROT28 132 #define FLASH_SECTOR29 FLCTL_BANK0_MAIN_WEPROT_PROT29 133 #define FLASH_SECTOR30 FLCTL_BANK0_MAIN_WEPROT_PROT30 134 #define FLASH_SECTOR31 FLCTL_BANK0_MAIN_WEPROT_PROT31 135 136 #define FLASH_NOVER 0 137 #define FLASH_BURSTPOST FLCTL_PRGBRST_CTLSTAT_AUTO_PST 138 #define FLASH_BURSTPRE FLCTL_PRGBRST_CTLSTAT_AUTO_PRE 139 #define FLASH_REGPRE FLCTL_PRG_CTLSTAT_VER_PRE 140 #define FLASH_REGPOST FLCTL_PRG_CTLSTAT_VER_PST 141 #define FLASH_FULLVER (FLCTL_PRGBRST_CTLSTAT_AUTO_PST | \ 142 FLCTL_PRGBRST_CTLSTAT_AUTO_PRE | FLCTL_PRG_CTLSTAT_VER_PRE \ 143 | FLCTL_PRG_CTLSTAT_VER_PST) 144 145 #define FLASH_COLLATED_WRITE_MODE 0x01 146 #define FLASH_IMMEDIATE_WRITE_MODE 0x02 147 148 #define __INFO_FLASH_TECH_START__ 0x00200000 149 #define __INFO_FLASH_TECH_MIDDLE__ 0x00202000 150 151 152 //***************************************************************************** 153 // 154 // Prototypes for the APIs. 155 // 156 //***************************************************************************** 157 158 //***************************************************************************** 159 // 160 //! Calculates the flash bank and sector number given an address. Stores the 161 //! results into the two pointers given as parameters. The user must provide 162 //! a valid memory address (an address in SRAM for example will give an invalid 163 //! result). 164 //! 165 //! \param addr Address to calculate the bank/sector information for 166 //! 167 //! \param bankNum The bank number will be stored in here after the function 168 //! completes. 169 //! 170 //! \param sectorNum The sector number will be stored in here after the function 171 //! completes. 172 //! 173 //! \note For simplicity, this API only works with address in MAIN flash memory. 174 //! For calculating the sector/bank number of an address in info memory, 175 //! please refer to your device datasheet/ 176 //! 177 //! \return None. 178 // 179 //***************************************************************************** 180 extern void FlashCtl_getMemoryInfo(uint32_t addr, uint32_t *bankNum, 181 uint32_t *sectorNum); 182 183 //***************************************************************************** 184 // 185 //! Enables read buffering on accesses to a specified bank of flash memory 186 //! 187 //! \param memoryBank is the value of the memory bank to enable read 188 //! buffering. Must be only one of the following values: 189 //! - \b FLASH_BANK0, 190 //! - \b FLASH_BANK1 191 //! 192 //! \param accessMethod is the value of the access type to enable read 193 //! buffering. Must be only one of the following values: 194 //! - \b FLASH_DATA_READ, 195 //! - \b FLASH_INSTRUCTION_FETCH 196 //! 197 //! \return None. 198 // 199 //***************************************************************************** 200 extern void FlashCtl_enableReadBuffering(uint_fast8_t memoryBank, 201 uint_fast8_t accessMethod); 202 203 //***************************************************************************** 204 // 205 //! Disables read buffering on accesses to a specified bank of flash memory 206 //! 207 //! \param memoryBank is the value of the memory bank to disable read 208 //! buffering. Must be only one of the following values: 209 //! - \b FLASH_BANK0, 210 //! - \b FLASH_BANK1 211 //! 212 //! \param accessMethod is the value of the access type to disable read 213 //! buffering. Must ne only one of the following values: 214 //! - \b FLASH_DATA_READ, 215 //! - \b FLASH_INSTRUCTION_FETCH 216 //! 217 //! \return None. 218 // 219 //***************************************************************************** 220 extern void FlashCtl_disableReadBuffering(uint_fast8_t memoryBank, 221 uint_fast8_t accessMethod); 222 223 //***************************************************************************** 224 // 225 //! Disables program protection on the given sector mask. This setting can be 226 //! applied on a sector-wise bases on a given memory space (INFO or MAIN). 227 //! 228 //! \param memorySpace is the value of the memory bank to disable program 229 //! protection. Must be only one of the following values: 230 //! - \b FLASH_MAIN_MEMORY_SPACE_BANK0, 231 //! - \b FLASH_MAIN_MEMORY_SPACE_BANK1, 232 //! - \b FLASH_INFO_MEMORY_SPACE_BANK0, 233 //! - \b FLASH_INFO_MEMORY_SPACE_BANK1 234 //! 235 //! \param sectorMask is a bit mask of the sectors to disable program 236 //! protection. Must be a bitfield of the following values: 237 //! - \b FLASH_SECTOR0, 238 //! - \b FLASH_SECTOR1, 239 //! - \b FLASH_SECTOR2, 240 //! - \b FLASH_SECTOR3, 241 //! - \b FLASH_SECTOR4, 242 //! - \b FLASH_SECTOR5, 243 //! - \b FLASH_SECTOR6, 244 //! - \b FLASH_SECTOR7, 245 //! - \b FLASH_SECTOR8, 246 //! - \b FLASH_SECTOR9, 247 //! - \b FLASH_SECTOR10, 248 //! - \b FLASH_SECTOR11, 249 //! - \b FLASH_SECTOR12, 250 //! - \b FLASH_SECTOR13, 251 //! - \b FLASH_SECTOR14, 252 //! - \b FLASH_SECTOR15, 253 //! - \b FLASH_SECTOR16, 254 //! - \b FLASH_SECTOR17, 255 //! - \b FLASH_SECTOR18, 256 //! - \b FLASH_SECTOR19, 257 //! - \b FLASH_SECTOR20, 258 //! - \b FLASH_SECTOR21, 259 //! - \b FLASH_SECTOR22, 260 //! - \b FLASH_SECTOR23, 261 //! - \b FLASH_SECTOR24, 262 //! - \b FLASH_SECTOR25, 263 //! - \b FLASH_SECTOR26, 264 //! - \b FLASH_SECTOR27, 265 //! - \b FLASH_SECTOR28, 266 //! - \b FLASH_SECTOR29, 267 //! - \b FLASH_SECTOR30, 268 //! - \b FLASH_SECTOR31 269 //! 270 //! \note Flash sector sizes are 4KB and the number of sectors may vary 271 //! depending on the specific device. Also, for INFO memory space, only sectors 272 //! \b FLASH_SECTOR0 and \b FLASH_SECTOR1 will exist. 273 //! 274 //! \note Not all devices will contain a dedicated INFO memory. Please check the 275 //! device datasheet to see if your device has INFO memory available for use. 276 //! For devices without INFO memory, any operation related to the INFO memory 277 //! will be ignored by the hardware. 278 //! 279 //! \return true if sector protection disabled false otherwise. 280 // 281 //***************************************************************************** 282 extern bool FlashCtl_unprotectSector(uint_fast8_t memorySpace, 283 uint32_t sectorMask); 284 285 //***************************************************************************** 286 // 287 //! Enables program protection on the given sector mask. This setting can be 288 //! applied on a sector-wise bases on a given memory space (INFO or MAIN). 289 //! 290 //! \param memorySpace is the value of the memory bank to enable program 291 //! protection. Must be only one of the following values: 292 //! - \b FLASH_MAIN_MEMORY_SPACE_BANK0, 293 //! - \b FLASH_MAIN_MEMORY_SPACE_BANK1, 294 //! - \b FLASH_INFO_MEMORY_SPACE_BANK0, 295 //! - \b FLASH_INFO_MEMORY_SPACE_BANK1 296 //! 297 //! \param sectorMask is a bit mask of the sectors to enable program 298 //! protection. Must be a bitfield of the following values: 299 //! - \b FLASH_SECTOR0, 300 //! - \b FLASH_SECTOR1, 301 //! - \b FLASH_SECTOR2, 302 //! - \b FLASH_SECTOR3, 303 //! - \b FLASH_SECTOR4, 304 //! - \b FLASH_SECTOR5, 305 //! - \b FLASH_SECTOR6, 306 //! - \b FLASH_SECTOR7, 307 //! - \b FLASH_SECTOR8, 308 //! - \b FLASH_SECTOR9, 309 //! - \b FLASH_SECTOR10, 310 //! - \b FLASH_SECTOR11, 311 //! - \b FLASH_SECTOR12, 312 //! - \b FLASH_SECTOR13, 313 //! - \b FLASH_SECTOR14, 314 //! - \b FLASH_SECTOR15, 315 //! - \b FLASH_SECTOR16, 316 //! - \b FLASH_SECTOR17, 317 //! - \b FLASH_SECTOR18, 318 //! - \b FLASH_SECTOR19, 319 //! - \b FLASH_SECTOR20, 320 //! - \b FLASH_SECTOR21, 321 //! - \b FLASH_SECTOR22, 322 //! - \b FLASH_SECTOR23, 323 //! - \b FLASH_SECTOR24, 324 //! - \b FLASH_SECTOR25, 325 //! - \b FLASH_SECTOR26, 326 //! - \b FLASH_SECTOR27, 327 //! - \b FLASH_SECTOR28, 328 //! - \b FLASH_SECTOR29, 329 //! - \b FLASH_SECTOR30, 330 //! - \b FLASH_SECTOR31 331 //! 332 //! \note Flash sector sizes are 4KB and the number of sectors may vary 333 //! depending on the specific device. Also, for INFO memory space, only sectors 334 //! \b FLASH_SECTOR0 and \b FLASH_SECTOR1 will exist. 335 //! 336 //! \note Not all devices will contain a dedicated INFO memory. Please check the 337 //! device datasheet to see if your device has INFO memory available for use. 338 //! For devices without INFO memory, any operation related to the INFO memory 339 //! will be ignored by the hardware. 340 //! 341 //! \return true if sector protection enabled false otherwise. 342 // 343 //***************************************************************************** 344 extern bool FlashCtl_protectSector(uint_fast8_t memorySpace, 345 uint32_t sectorMask); 346 347 //***************************************************************************** 348 // 349 //! Returns the sector protection for given sector mask and memory space 350 //! 351 //! \param memorySpace is the value of the memory bank to check for program 352 //! protection. Must be only one of the following values: 353 //! - \b FLASH_MAIN_MEMORY_SPACE_BANK0, 354 //! - \b FLASH_MAIN_MEMORY_SPACE_BANK1, 355 //! - \b FLASH_INFO_MEMORY_SPACE_BANK0, 356 //! - \b FLASH_INFO_MEMORY_SPACE_BANK1 357 //! 358 //! \param sector is the sector to check for program protection. 359 //! Must be one of the following values: 360 //! - \b FLASH_SECTOR0, 361 //! - \b FLASH_SECTOR1, 362 //! - \b FLASH_SECTOR2, 363 //! - \b FLASH_SECTOR3, 364 //! - \b FLASH_SECTOR4, 365 //! - \b FLASH_SECTOR5, 366 //! - \b FLASH_SECTOR6, 367 //! - \b FLASH_SECTOR7, 368 //! - \b FLASH_SECTOR8, 369 //! - \b FLASH_SECTOR9, 370 //! - \b FLASH_SECTOR10, 371 //! - \b FLASH_SECTOR11, 372 //! - \b FLASH_SECTOR12, 373 //! - \b FLASH_SECTOR13, 374 //! - \b FLASH_SECTOR14, 375 //! - \b FLASH_SECTOR15, 376 //! - \b FLASH_SECTOR16, 377 //! - \b FLASH_SECTOR17, 378 //! - \b FLASH_SECTOR18, 379 //! - \b FLASH_SECTOR19, 380 //! - \b FLASH_SECTOR20, 381 //! - \b FLASH_SECTOR21, 382 //! - \b FLASH_SECTOR22, 383 //! - \b FLASH_SECTOR23, 384 //! - \b FLASH_SECTOR24, 385 //! - \b FLASH_SECTOR25, 386 //! - \b FLASH_SECTOR26, 387 //! - \b FLASH_SECTOR27, 388 //! - \b FLASH_SECTOR28, 389 //! - \b FLASH_SECTOR29, 390 //! - \b FLASH_SECTOR30, 391 //! - \b FLASH_SECTOR31 392 //! 393 //! Note that flash sector sizes are 4KB and the number of sectors may vary 394 //! depending on the specific device. Also, for INFO memory space, only sectors 395 //! FLASH_SECTOR0 and FLASH_SECTOR1 will exist. 396 //! 397 //! \note Not all devices will contain a dedicated INFO memory. Please check the 398 //! device datasheet to see if your device has INFO memory available for use. 399 //! For devices without INFO memory, any operation related to the INFO memory 400 //! will be ignored by the hardware. 401 //! 402 //! \return true if sector protection enabled false otherwise. 403 // 404 //***************************************************************************** 405 extern bool FlashCtl_isSectorProtected(uint_fast8_t memorySpace, 406 uint32_t sector); 407 408 //***************************************************************************** 409 // 410 //! Verifies a given segment of memory based off either a high (1) or low (0) 411 //! state. 412 //! 413 //! \param verifyAddr Start address where verification will begin 414 //! 415 //! \param length Length in bytes to verify based off the pattern 416 //! 417 //! \param pattern The pattern which verification will check versus. This can 418 //! either be a low pattern (each register will be checked versus a pattern 419 //! of 32 zeros, or a high pattern (each register will be checked versus a 420 //! pattern of 32 ones). Valid values are: FLASH_0_PATTERN, FLASH_1_PATTERN 421 //! 422 //! \note There are no sector/boundary restrictions for this function, 423 //! however it is encouraged to proved a start address aligned on 32-bit 424 //! boundaries. Providing an unaligned address will result in unaligned data 425 //! accesses and detriment efficiency. 426 //! 427 //! \note This function is blocking and will not exit until operation has 428 //! either completed or failed due to an error. Furthermore, given the 429 //! complex verification requirements of the flash controller, master 430 //! interrupts are disabled throughout execution of this function. The original 431 //! interrupt context is saved at the start of execution and restored prior 432 //! to exit of the API. 433 //! 434 //! \note Due to the hardware limitations of the flash controller, this 435 //! function cannot verify a memory address in the same flash bank that it 436 //! is executing from. If using the ROM version of this API (by using the 437 //! (ROM_ or MAP_ prefixes) this is a don't care, however if this API resides 438 //! in flash then special care needs to be taken to ensure no code execution 439 //! or reads happen in the flash bank being programmed while this API is 440 //! being executed. 441 //! 442 //! \return true if memory verification is successful, false otherwise. 443 // 444 //***************************************************************************** 445 extern bool FlashCtl_verifyMemory(void* verifyAddr, uint32_t length, 446 uint_fast8_t pattern); 447 448 //***************************************************************************** 449 // 450 //! Performs a mass erase on all unprotected flash sectors. Protected sectors 451 //! are ignored. 452 //! 453 //! \note This function is blocking and will not exit until operation has 454 //! either completed or failed due to an error. Furthermore, given the 455 //! complex verification requirements of the flash controller, master 456 //! interrupts are disabled throughout execution of this function. The original 457 //! interrupt context is saved at the start of execution and restored prior 458 //! to exit of the API. 459 //! 460 //! \note Due to the hardware limitations of the flash controller, this 461 //! function cannot erase a memory address in the same flash bank that it 462 //! is executing from. If using the ROM version of this API (by using the 463 //! (ROM_ or MAP_ prefixes) this is a don't care, however if this API resides 464 //! in flash then special care needs to be taken to ensure no code execution 465 //! or reads happen in the flash bank being programmed while this API is 466 //! being executed. 467 //! 468 //! \return true if mass erase completes successfully, false otherwise 469 // 470 //***************************************************************************** 471 extern bool FlashCtl_performMassErase(void); 472 473 //***************************************************************************** 474 // 475 //! Initiates a mass erase and returns control back to the program. This is a 476 //! non-blocking function, however it is the user's responsibility to perform 477 //! the necessary verification requirements after the interrupt is set to 478 //! signify completion. 479 //! 480 //! \return None 481 // 482 //***************************************************************************** 483 extern void FlashCtl_initiateMassErase(void); 484 485 //***************************************************************************** 486 // 487 //! Erases a sector of MAIN or INFO flash memory. 488 //! 489 //! \param addr The start of the sector to erase. Note that with flash, 490 //! the minimum allowed size that can be erased is a flash sector 491 //! (which is 4KB on the MSP432 family). If an address is provided to 492 //! this function which is not on a 4KB boundary, the entire sector 493 //! will still be erased. 494 //! 495 //! \note This function is blocking and will not exit until operation has 496 //! either completed or failed due to an error. Furthermore, given the 497 //! complex verification requirements of the flash controller, master 498 //! interrupts are disabled throughout execution of this function. The original 499 //! interrupt context is saved at the start of execution and restored prior 500 //! to exit of the API. 501 //! 502 //! \note Due to the hardware limitations of the flash controller, this 503 //! function cannot erase a memory addressin the same flash bank that it 504 //! is executing from. If using the ROM version of this API (by using the 505 //! (ROM_ or MAP_ prefixes) this is a don't care, however if this API resides 506 //! in flash then special care needs to be taken to ensure no code execution 507 //! or reads happen in the flash bank being programmed while this API is 508 //! being executed. 509 //! 510 //! \return true if sector erase is successful, false otherwise. 511 // 512 //***************************************************************************** 513 extern bool FlashCtl_eraseSector(uint32_t addr); 514 515 //***************************************************************************** 516 // 517 //! Program a portion of flash memory with the provided data 518 //! 519 //! \param src Pointer to the data source to program into flash 520 //! 521 //! \param dest Pointer to the destination in flash to program 522 //! 523 //! \param length Length in bytes to program 524 //! 525 //! \note There are no sector/boundary restrictions for this function, 526 //! however it is encouraged to proved a start address aligned on 32-bit 527 //! boundaries. Providing an unaligned address will result in unaligned data 528 //! accesses and detriment efficiency. 529 //! 530 //! \note This function is blocking and will not exit until operation has 531 //! either completed or failed due to an error. Furthermore, given the 532 //! complex verification requirements of the flash controller, master 533 //! interrupts are disabled throughout execution of this function. The original 534 //! interrupt context is saved at the start of execution and restored prior 535 //! to exit of the API. 536 //! 537 //! \note Due to the hardware limitations of the flash controller, this 538 //! function cannot program a memory addressin the same flash bank that it 539 //! is executing from. If using the ROM version of this API (by using the 540 //! (ROM_ or MAP_ prefixes) this is a don't care, however if this API resides 541 //! in flash then special care needs to be taken to ensure no code execution 542 //! or reads happen in the flash bank being programmed while this API is 543 //! being executed. 544 //! 545 //! \return Whether or not the program succeeded 546 // 547 //***************************************************************************** 548 extern bool FlashCtl_programMemory(void* src, void* dest, uint32_t length); 549 550 //***************************************************************************** 551 // 552 //! Setups pre/post verification of burst and regular flash programming 553 //! instructions. Note that this API is for advanced users that are programming 554 //! their own flash drivers. The program/erase APIs are not affected by this 555 //! setting and take care of the verification requirements. 556 //! 557 //! \param verificationSetting Verification setting to set. This value can 558 //! be a bitwise OR of the following values: 559 //! - \b FLASH_BURSTPOST, 560 //! - \b FLASH_BURSTPRE, 561 //! - \b FLASH_REGPRE, 562 //! - \b FLASH_REGPOST 563 //! - \b FLASH_NOVER No verification enabled 564 //! - \b FLASH_FULLVER Full verification enabled 565 //! 566 //! \return none 567 // 568 //***************************************************************************** 569 extern void FlashCtl_setProgramVerification(uint32_t verificationSetting); 570 571 //***************************************************************************** 572 // 573 //! Clears pre/post verification of burst and regular flash programming 574 //! instructions. Note that this API is for advanced users that are programming 575 //! their own flash drivers. The program/erase APIs are not affected by this 576 //! setting and take care of the verification requirements. 577 //! 578 //! \param verificationSetting Verification setting to clear. This value can 579 //! be a bitwise OR of the following values: 580 //! - \b FLASH_BURSTPOST, 581 //! - \b FLASH_BURSTPRE, 582 //! - \b FLASH_REGPRE, 583 //! - \b FLASH_REGPOST 584 //! - \b FLASH_NOVER No verification enabled 585 //! - \b FLASH_FULLVER Full verification enabled 586 //! 587 //! \return none 588 // 589 //***************************************************************************** 590 extern void FlashCtl_clearProgramVerification(uint32_t verificationSetting); 591 592 //***************************************************************************** 593 // 594 //! Enables word programming of flash memory. 595 //! 596 //! This function will enable word programming of the flash memory and set the 597 //! mode of behavior when the flash write occurs. 598 //! 599 //! \param mode The mode specifies the behavior of the flash controller when 600 //! programming words to flash. In \b FLASH_IMMEDIATE_WRITE_MODE, the 601 //! program operation happens immediately on the write to flash while 602 //! in \b FLASH_COLLATED_WRITE_MODE the write will be delayed until a full 603 //! 128-bits have been collated. Possible values include: 604 //! - \b FLASH_IMMEDIATE_WRITE_MODE 605 //! - \b FLASH_COLLATED_WRITE_MODE 606 //! 607 //! 608 //! Refer to the user's guide for further documentation. 609 //! 610 //! \return none 611 // 612 //***************************************************************************** 613 extern void FlashCtl_enableWordProgramming(uint32_t mode); 614 615 //***************************************************************************** 616 // 617 //! Disables word programming of flash memory. 618 //! 619 //! Refer to FlashCtl_enableWordProgramming and the user's guide for description 620 //! on the difference between full word and immediate programming 621 //! 622 //! \return None. 623 // 624 //***************************************************************************** 625 extern void FlashCtl_disableWordProgramming(void); 626 627 //***************************************************************************** 628 // 629 //! Returns if word programming mode is enabled (and if it is, the specific mode) 630 //! 631 //! Refer to FlashCtl_enableWordProgramming and the user's guide for description 632 //! on the difference between full word and immediate programming 633 //! 634 //! \return a zero value if word programming is disabled, 635 //! - \b FLASH_IMMEDIATE_WRITE_MODE 636 //! - \b FLASH_COLLATED_WRITE_MODE 637 //! 638 // 639 //***************************************************************************** 640 extern uint32_t FlashCtl_isWordProgrammingEnabled(void); 641 642 //***************************************************************************** 643 // 644 //! Sets the flash read mode to be used by default flash read operations. 645 //! Note that the proper wait states must be set prior to entering this 646 //! function. 647 //! 648 //! \param flashBank Flash bank to set read mode for. Valid values are: 649 //! - \b FLASH_BANK0 650 //! - \b FLASH_BANK1 651 //! 652 //! \param readMode The read mode to set. Valid values are: 653 //! - \b FLASH_NORMAL_READ_MODE, 654 //! - \b FLASH_MARGIN0_READ_MODE, 655 //! - \b FLASH_MARGIN1_READ_MODE, 656 //! - \b FLASH_PROGRAM_VERIFY_READ_MODE, 657 //! - \b FLASH_ERASE_VERIFY_READ_MODE, 658 //! - \b FLASH_LEAKAGE_VERIFY_READ_MODE, 659 //! - \b FLASH_MARGIN0B_READ_MODE, 660 //! - \b FLASH_MARGIN1B_READ_MODE 661 //! 662 //! \return None. 663 // 664 //***************************************************************************** 665 extern bool FlashCtl_setReadMode(uint32_t flashBank, uint32_t readMode); 666 667 //***************************************************************************** 668 // 669 //! Gets the flash read mode to be used by default flash read operations. 670 //! 671 //! \param flashBank Flash bank to set read mode for. Valid values are: 672 //! - \b FLASH_BANK0 673 //! - \b FLASH_BANK1 674 //! 675 //! \return Returns the read mode to set. Valid values are: 676 //! - \b FLASH_NORMAL_READ_MODE, 677 //! - \b FLASH_MARGIN0_READ_MODE, 678 //! - \b FLASH_MARGIN1_READ_MODE, 679 //! - \b FLASH_PROGRAM_VERIFY_READ_MODE, 680 //! - \b FLASH_ERASE_VERIFY_READ_MODE, 681 //! - \b FLASH_LEAKAGE_VERIFY_READ_MODE, 682 //! - \b FLASH_MARGIN0B_READ_MODE, 683 //! - \b FLASH_MARGIN1B_READ_MODE 684 //! 685 // 686 //***************************************************************************** 687 extern uint32_t FlashCtl_getReadMode(uint32_t flashBank); 688 689 //***************************************************************************** 690 // 691 //! Changes the number of wait states that are used by the flash controller 692 //! for read operations. When changing frequency ranges of the clock, this 693 //! functions must be used in order to allow for readable flash memory. 694 //! 695 //! \param waitState The number of wait states to set. Note that only 696 //! bits 0-3 are used. 697 //! 698 //! \param flashBank Flash bank to set wait state for. Valid values are: 699 //! - \b FLASH_BANK0 700 //! - \b FLASH_BANK1 701 //! 702 // 703 //***************************************************************************** 704 extern void FlashCtl_setWaitState(uint32_t bank, uint32_t waitState); 705 706 //***************************************************************************** 707 // 708 //! Returns the set number of flash wait states for the given flash bank. 709 //! 710 //! \param flashBank Flash bank to set wait state for. Valid values are: 711 //! - \b FLASH_BANK0 712 //! - \b FLASH_BANK1 713 //! 714 //! \return The wait state setting for the specified flash bank 715 // 716 //***************************************************************************** 717 extern uint32_t FlashCtl_getWaitState(uint32_t bank); 718 719 //***************************************************************************** 720 // 721 //! Enables individual flash control interrupt sources. 722 //! 723 //! \param flags is a bit mask of the interrupt sources to be enabled. Must 724 //! be a logical OR of: 725 //! - \b FLASH_PROGRAM_ERROR, 726 //! - \b FLASH_BENCHMARK_INT, 727 //! - \b FLASH_ERASE_COMPLETE, 728 //! - \b FLASH_BRSTPRGM_COMPLETE, 729 //! - \b FLASH_WRDPRGM_COMPLETE, 730 //! - \b FLASH_POSTVERIFY_FAILED, 731 //! - \b FLASH_PREVERIFY_FAILED, 732 //! - \b FLASH_BRSTRDCMP_COMPLETE 733 //! 734 //! This function enables the indicated flash system interrupt sources. Only 735 //! the sources that are enabled can be reflected to the processor interrupt; 736 //! disabled sources have no effect on the processor. 737 //! 738 //! \note The interrupt sources vary based on the part in use. 739 //! Please consult the data sheet for the part you are using to determine 740 //! which interrupt sources are available. 741 //! 742 //! \return None. 743 // 744 //***************************************************************************** 745 extern void FlashCtl_enableInterrupt(uint32_t flags); 746 747 //***************************************************************************** 748 // 749 //! Disables individual flash system interrupt sources. 750 //! 751 //! \param flags is a bit mask of the interrupt sources to be disabled. Must 752 //! be a logical OR of: 753 //! - \b FLASH_PROGRAM_ERROR, 754 //! - \b FLASH_BENCHMARK_INT, 755 //! - \b FLASH_ERASE_COMPLETE, 756 //! - \b FLASH_BRSTPRGM_COMPLETE, 757 //! - \b FLASH_WRDPRGM_COMPLETE, 758 //! - \b FLASH_POSTVERIFY_FAILED, 759 //! - \b FLASH_PREVERIFY_FAILED, 760 //! - \b FLASH_BRSTRDCMP_COMPLETE 761 //! 762 //! This function disables the indicated flash system interrupt sources. 763 //! Only the sources that are enabled can be reflected to the processor 764 //! interrupt; disabled sources have no effect on the processor. 765 //! 766 //! 767 //! \return None. 768 // 769 //***************************************************************************** 770 extern void FlashCtl_disableInterrupt(uint32_t flags); 771 772 //***************************************************************************** 773 // 774 //! Gets the current interrupt status masked with the enabled interrupts. 775 //! This function is useful to call in ISRs to get a list 776 //! of pending interrupts that are actually enabled and could have caused the 777 //! ISR. 778 //! 779 //! \return The current interrupt status, enumerated as a bit field of 780 //! - \b FLASH_PROGRAM_ERROR, 781 //! - \b FLASH_BENCHMARK_INT, 782 //! - \b FLASH_ERASE_COMPLETE, 783 //! - \b FLASH_BRSTPRGM_COMPLETE, 784 //! - \b FLASH_WRDPRGM_COMPLETE, 785 //! - \b FLASH_POSTVERIFY_FAILED, 786 //! - \b FLASH_PREVERIFY_FAILED, 787 //! - \b FLASH_BRSTRDCMP_COMPLETE 788 //! 789 //! \note The interrupt sources vary based on the part in use. 790 //! Please consult the data sheet for the part you are using to determine 791 //! which interrupt sources are available. 792 // 793 //***************************************************************************** 794 extern uint32_t FlashCtl_getEnabledInterruptStatus(void); 795 796 //***************************************************************************** 797 // 798 //! Gets the current interrupt status. 799 //! 800 //! \return The current interrupt status, enumerated as a bit field of: 801 //! - \b FLASH_PROGRAM_ERROR, 802 //! - \b FLASH_BENCHMARK_INT, 803 //! - \b FLASH_ERASE_COMPLETE, 804 //! - \b FLASH_BRSTPRGM_COMPLETE, 805 //! - \b FLASH_WRDPRGM_COMPLETE, 806 //! - \b FLASH_POSTVERIFY_FAILED, 807 //! - \b FLASH_PREVERIFY_FAILED, 808 //! - \b FLASH_BRSTRDCMP_COMPLETE 809 //! 810 //! \note The interrupt sources vary based on the part in use. 811 //! Please consult the data sheet for the part you are using to determine 812 //! which interrupt sources are available. 813 // 814 //***************************************************************************** 815 extern uint32_t FlashCtl_getInterruptStatus(void); 816 817 //***************************************************************************** 818 // 819 //! Clears flash system interrupt sources. 820 //! 821 //! \param flags is a bit mask of the interrupt sources to be cleared. Must 822 //! be a logical OR of: 823 //! - \b FLASH_PROGRAM_ERROR, 824 //! - \b FLASH_BENCHMARK_INT, 825 //! - \b FLASH_ERASE_COMPLETE, 826 //! - \b FLASH_BRSTPRGM_COMPLETE, 827 //! - \b FLASH_WRDPRGM_COMPLETE, 828 //! - \b FLASH_POSTVERIFY_FAILED, 829 //! - \b FLASH_PREVERIFY_FAILED, 830 //! - \b FLASH_BRSTRDCMP_COMPLETE 831 //! 832 //! The specified flash system interrupt sources are cleared, so that they no 833 //! longer assert. This function must be called in the interrupt handler to 834 //! keep it from being called again immediately upon exit. 835 //! 836 //! \note Because there is a write buffer in the Cortex-M processor, it may 837 //! take several clock cycles before the interrupt source is actually cleared. 838 //! Therefore, it is recommended that the interrupt source be cleared early in 839 //! the interrupt handler (as opposed to the very last action) to avoid 840 //! returning from the interrupt handler before the interrupt source is 841 //! actually cleared. Failure to do so may result in the interrupt handler 842 //! being immediately reentered (because the interrupt controller still sees 843 //! the interrupt source asserted). 844 //! 845 //! \note The interrupt sources vary based on the part in use. 846 //! Please consult the data sheet for the part you are using to determine 847 //! which interrupt sources are available. 848 //! 849 //! \return None. 850 // 851 //***************************************************************************** 852 extern void FlashCtl_clearInterruptFlag(uint32_t flags); 853 854 //***************************************************************************** 855 // 856 //! Registers an interrupt handler for flash clock system interrupt. 857 //! 858 //! \param intHandler is a pointer to the function to be called when the clock 859 //! system interrupt occurs. 860 //! 861 //! This function registers the handler to be called when a clock system 862 //! interrupt occurs. This function enables the global interrupt in the 863 //! interrupt controller; specific flash controller interrupts must be enabled 864 //! via FlashCtl_enableInterrupt(). It is the interrupt handler's 865 //! responsibility to clear the interrupt source via 866 //! FlashCtl_clearInterruptFlag(). 867 //! 868 //! \sa Interrupt_registerInterrupt() for important information about 869 //! registering interrupt handlers. 870 //! 871 //! \return None. 872 // 873 //***************************************************************************** 874 extern void FlashCtl_registerInterrupt(void (*intHandler)(void)); 875 876 //***************************************************************************** 877 // 878 //! Unregisters the interrupt handler for the flash system. 879 //! 880 //! This function unregisters the handler to be called when a clock system 881 //! interrupt occurs. This function also masks off the interrupt in the 882 //! interrupt controller so that the interrupt handler no longer is called. 883 //! 884 //! \sa Interrupt_registerInterrupt() for important information about 885 //! registering interrupt handlers. 886 //! 887 //! \return None. 888 // 889 //***************************************************************************** 890 extern void FlashCtl_unregisterInterrupt(void); 891 892 893 //***************************************************************************** 894 // 895 //! Initiates a sector erase of MAIN or INFO flash memory. Note that this 896 //! function simply initaites the sector erase, but does no verification 897 //! which is required by the flash controller. The user must manually set 898 //! and enable interrupts on the flash controller to fire on erase completion 899 //! and then use the FlashCtl_verifyMemory function to verify that the sector 900 //! was actually erased 901 //! 902 //! \param addr The start of the sector to erase. Note that with flash, 903 //! the minimum allowed size that can be erased is a flash sector 904 //! (which is 4KB on the MSP432 family). If an address is provided to 905 //! this function which is not on a 4KB boundary, the entire sector 906 //! will still be erased. 907 //! 908 //! \return None 909 // 910 //***************************************************************************** 911 extern void FlashCtl_initiateSectorErase(uint32_t addr); 912 913 914 /* The following functions are advanced functions that are used by the flash 915 * driver to remask a failed bit in the event of a post or pre verification 916 * failure. They are meant to be advanced functions and should not be used 917 * by the majority of users (unless you are writing your own flash driver). 918 */ 919 extern uint8_t __FlashCtl_remaskData8Post(uint8_t data, uint32_t addr); 920 extern uint8_t __FlashCtl_remaskData8Pre(uint8_t data, uint32_t addr); 921 extern uint32_t __FlashCtl_remaskData32Post(uint32_t data, uint32_t addr); 922 extern uint32_t __FlashCtl_remaskData32Pre(uint32_t data, uint32_t addr); 923 extern void __FlashCtl_remaskBurstDataPost(uint32_t addr, uint32_t size); 924 extern void __FlashCtl_remaskBurstDataPre(uint32_t addr, uint32_t size); 925 926 //***************************************************************************** 927 // 928 // Mark the end of the C bindings section for C++ compilers. 929 // 930 //***************************************************************************** 931 #ifdef __cplusplus 932 } 933 #endif 934 935 //***************************************************************************** 936 // 937 // Close the Doxygen group. 938 //! @} 939 // 940 //***************************************************************************** 941 942 #endif /* __MCU_HAS_FLCTL__ */ 943 944 #endif // __FLASH_H__ 945
