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