2 * -------------------------------------------
3 * MSP432 DriverLib - v01_04_00_18
4 * -------------------------------------------
6 * --COPYRIGHT--,BSD,BSD
7 * Copyright (c) 2015, 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 pcm_api
45 //*****************************************************************************
47 //*****************************************************************************
49 // If building with a C++ compiler, make all of the definitions in this header
52 //*****************************************************************************
62 //*****************************************************************************
64 // Control specific variables
66 //*****************************************************************************
67 #define PCM_KEY 0x695A0000
70 #define PCM_AM_LDO_VCORE0 0x00
71 #define PCM_AM_LDO_VCORE1 0x01
72 #define PCM_AM_DCDC_VCORE0 0x04
73 #define PCM_AM_DCDC_VCORE1 0x05
74 #define PCM_AM_LF_VCORE0 0x08
75 #define PCM_AM_LF_VCORE1 0x09
76 #define PCM_LPM0_LDO_VCORE0 0x10
77 #define PCM_LPM0_LDO_VCORE1 0x11
78 #define PCM_LPM0_DCDC_VCORE0 0x14
79 #define PCM_LPM0_DCDC_VCORE1 0x15
80 #define PCM_LPM0_LF_VCORE0 0x18
81 #define PCM_LPM0_LF_VCORE1 0x19
83 #define PCM_LPM35_VCORE0 0xC0
84 #define PCM_LPM45 0xA0
86 #define PCM_VCORE0 0x00
87 #define PCM_VCORE1 0x01
88 #define PCM_VCORELPM3 0x02
90 #define PCM_LDO_MODE 0x00
91 #define PCM_DCDC_MODE 0x01
92 #define PCM_LF_MODE 0x02
94 #define PCM_SHUTDOWN_PARTIAL PCM_LPM35_VCORE0
95 #define PCM_SHUTDOWN_COMPLETE PCM_LPM45
97 #define PCM_DCDCERROR PCM_INTEN_EN_DCDC_ERROR
98 #define PCM_AM_INVALIDTRANSITION PCM_INTEN_EN_AM_INVALID_TR
99 #define PCM_SM_INVALIDCLOCK PCM_INTEN_EN_SM_INVALID_CLK
100 #define PCM_SM_INVALIDTRANSITION PCM_INTEN_EN_SM_INVALID_TR
102 //*****************************************************************************
104 // Prototypes for the APIs.
106 //*****************************************************************************
108 //******************************************************************************
110 //! Sets the core voltage level (Vcore). The function will take care of all
111 //! power state transitions needed to shift between core voltage levels.
112 //! Because transitions between voltage levels may require changes power modes,
113 //! the power mode might temporarily be change. The power mode will be returned
114 //! to the original state (with the new voltage level) at the end of a
115 //! successful execution of this function.
117 //! Refer to the device specific data sheet for specifics about core voltage
120 //! \param voltageLevel The voltage level to be shifted to.
124 //! \return true if voltage level set, false otherwise.
126 //******************************************************************************
127 extern bool PCM_setCoreVoltageLevel(uint_fast8_t voltageLevel);
129 //******************************************************************************
131 //! Returns the current powers state of the system see the
132 //! PCM_setCoreVoltageLevel function for specific information about the modes.
134 //! \return The current voltage of the system
136 //! Possible return values include:
139 //! - \b PCM_VCORELPM3
142 //******************************************************************************
143 extern uint8_t PCM_getCoreVoltageLevel(void);
145 //******************************************************************************
147 //! Sets the core voltage level (Vcore). This function will take care of all
148 //! power state transitions needed to shift between core voltage levels.
149 //! Because transitions between voltage levels may require changes power modes,
150 //! the power mode might temporarily be change. The power mode will be returned
151 //! to the original state (with the new voltage level) at the end of a
152 //! successful execution of this function.
154 //! This function is similar to PCMSetCoreVoltageLevel, however a timeout
155 //! mechanism is used.
157 //! Refer to the device specific data sheet for specifics about core voltage
160 //! \param voltageLevel The voltage level to be shifted to.
164 //! \param timeOut Number of loop iterations to timeout when checking for
165 //! power state transitions. This should be used for debugging initial
166 //! power/hardware configurations. After a stable hardware base is
167 //! established, the PCMSetCoreVoltageLevel function should be used
169 //! \return true if voltage level set, false otherwise.
171 //******************************************************************************
172 extern bool PCM_setCoreVoltageLevelWithTimeout(uint_fast8_t voltageLevel,
175 //******************************************************************************
177 //! Switches between power modes. This function will take care of all
178 //! power state transitions needed to shift between power modes. Note for
179 //! changing to DCDC mode, specific hardware considerations are required.
181 //! Refer to the device specific data sheet for specifics about power modes.
183 //! \param powerMode The voltage modes to be shifted to. Valid values are:
184 //! - \b PCM_LDO_MODE,
185 //! - \b PCM_DCDC_MODE,
188 //! \return true if power mode is set, false otherwise.
190 //******************************************************************************
191 extern bool PCM_setPowerMode(uint_fast8_t powerMode);
193 //******************************************************************************
195 //! Switches between power modes. This function will take care of all
196 //! power state transitions needed to shift between power modes. Note for
197 //! changing to DCDC mode, specific hardware considerations are required.
199 //! This function is similar to PCMSetPowerMode, however a timeout
200 //! mechanism is used.
202 //! Refer to the device specific data sheet for specifics about power modes.
204 //! \param powerMode The voltage modes to be shifted to. Valid values are:
205 //! - \b PCM_LDO_MODE,
206 //! - \b PCM_DCDC_MODE,
209 //! \param timeOut Number of loop iterations to timeout when checking for
210 //! power state transitions. This should be used for debugging initial
211 //! power/hardware configurations. After a stable hardware base is
212 //! established, the PCMSetPowerMode function should be used
214 //! \return true if power mode is set, false otherwise.
216 //******************************************************************************
217 extern bool PCM_setPowerModeWithTimeout(uint_fast8_t powerMode,
220 //******************************************************************************
222 //! Returns the current powers state of the system see the \b PCM_setPowerState
223 //! function for specific information about the modes.
225 //! \return The current power mode of the system
228 //******************************************************************************
229 extern uint8_t PCM_getPowerMode(void);
231 //******************************************************************************
233 //! Switches between power states. This is a convenience function that combines
234 //! the functionality of PCMSetPowerMode and PCMSetCoreVoltageLevel as well as
235 //! the sleep/LPM3/shutdown functions.
237 //! Refer to the device specific data sheet for specifics about power states.
239 //! \param powerState The voltage modes to be shifted to. Valid values are:
240 //! - \b PCM_AM_LDO_VCORE0, [Active Mode, LDO, VCORE0]
241 //! - \b PCM_AM_LDO_VCORE1, [Active Mode, LDO, VCORE1]
242 //! - \b PCM_AM_DCDC_VCORE0, [Active Mode, DCDC, VCORE0]
243 //! - \b PCM_AM_DCDC_VCORE1, [Active Mode, DCDC, VCORE1]
244 //! - \b PCM_AM_LF_VCORE0, [Active Mode, Low Frequency, VCORE0]
245 //! - \b PCM_AM_LF_VCORE1, [Active Mode, Low Frequency, VCORE1]
246 //! - \b PCM_LPM0_LDO_VCORE0, [LMP0, LDO, VCORE0]
247 //! - \b PCM_LPM0_LDO_VCORE1, [LMP0, LDO, VCORE1]
248 //! - \b PCM_LPM0_DCDC_VCORE0, [LMP0, DCDC, VCORE0]
249 //! - \b PCM_LPM0_DCDC_VCORE1, [LMP0, DCDC, VCORE1]
250 //! - \b PCM_LPM0_LF_VCORE0, [LMP0, Low Frequency, VCORE0]
251 //! - \b PCM_LPM0_LF_VCORE1, [LMP0, Low Frequency, VCORE1]
252 //! - \b PCM_LPM3, [LPM3]
253 //! - \b PCM_LPM35_VCORE0, [LPM3.5 VCORE 0]
254 //! - \b PCM_LPM45, [LPM4.5]
256 //! \return true if power state is set, false otherwise.
258 //******************************************************************************
259 extern bool PCM_setPowerState(uint_fast8_t powerState);
261 //******************************************************************************
263 //! Switches between power states. This is a convenience function that combines
264 //! the functionality of PCMSetPowerMode and PCMSetCoreVoltageLevel as well as
267 //! This function is similar to PCMChangePowerState, however a timeout
268 //! mechanism is used.
270 //! Refer to the device specific data sheet for specifics about power states.
272 //! \param powerState The voltage modes to be shifted to. Valid values are:
273 //! - \b PCM_AM_LDO_VCORE0, [Active Mode, LDO, VCORE0]
274 //! - \b PCM_AM_LDO_VCORE1, [Active Mode, LDO, VCORE1]
275 //! - \b PCM_AM_DCDC_VCORE0, [Active Mode, DCDC, VCORE0]
276 //! - \b PCM_AM_DCDC_VCORE1, [Active Mode, DCDC, VCORE1]
277 //! - \b PCM_AM_LF_VCORE0, [Active Mode, Low Frequency, VCORE0]
278 //! - \b PCM_AM_LF_VCORE1, [Active Mode, Low Frequency, VCORE1]
279 //! - \b PCM_LPM0_LDO_VCORE0, [LMP0, LDO, VCORE0]
280 //! - \b PCM_LPM0_LDO_VCORE1, [LMP0, LDO, VCORE1]
281 //! - \b PCM_LPM0_DCDC_VCORE0, [LMP0, DCDC, VCORE0]
282 //! - \b PCM_LPM0_DCDC_VCORE1, [LMP0, DCDC, VCORE1]
283 //! - \b PCM_LPM0_LF_VCORE0, [LMP0, Low Frequency, VCORE0]
284 //! - \b PCM_LPM0_LF_VCORE1, [LMP0, Low Frequency, VCORE1]
285 //! - \b PCM_LPM3, [LPM3]
286 //! - \b PCM_LPM35_VCORE0, [LPM3.5 VCORE 0]
287 //! - \b PCM_LPM45, [LPM4.5]
289 //! \param timeout Number of loop iterations to timeout when checking for
290 //! power state transitions. This should be used for debugging initial
291 //! power/hardware configurations. After a stable hardware base is
292 //! established, the PCMSetPowerMode function should be used
294 //! \return true if power state is set, false otherwise. It is important to
295 //! note that if a timeout occurs, false will be returned, however the
296 //! power state at this point is not guaranteed to be the same as the
297 //! state prior to the function call
299 //******************************************************************************
300 extern bool PCM_setPowerStateWithTimeout(uint_fast8_t powerState,
303 //******************************************************************************
305 //! Returns the current powers state of the system see the PCMChangePowerState
306 //! function for specific information about the states.
308 //! Refer to \link PCM_setPowerState \endlink for possible return values.
310 //! \return The current power state of the system
312 //******************************************************************************
313 extern uint8_t PCM_getPowerState(void);
315 //******************************************************************************
317 //! Transitions the device into LPM3.5/LPM4.5 mode.
319 //! Refer to the device specific data sheet for specifics about shutdown modes.
321 //! The following events will cause a wake up from LPM3.5 mode:
323 //! - External reset RST
324 //! - Enabled RTC, WDT, and wake-up I/O only interrupt events
326 //! The following events will cause a wake up from the LPM4.5 mode:
328 //! - External reset RST
329 //! - Wake-up I/O only interrupt events
331 //! \param shutdownMode Specific mode to go to. Valid values are:
332 //! - \b PCM_LPM35_VCORE0
336 //! \return false if shutdown state cannot be entered, true otherwise.
338 //******************************************************************************
339 extern bool PCM_shutdownDevice(uint32_t shutdownMode);
341 //******************************************************************************
343 //! Transitions the device into LPM0.
345 //! Refer to the device specific data sheet for specifics about low power modes.
347 //! \return false if sleep state cannot be entered, true otherwise.
349 //******************************************************************************
350 extern bool PCM_gotoLPM0(void);
352 //******************************************************************************
354 //! Transitions the device into LPM3
356 //! Refer to the device specific data sheet for specifics about low power modes.
357 //! Note that since LPM3 cannot be entered from a DCDC power modes, the
358 //! power mode is first switched to LDO operation (if in DCDC mode), the deep
359 //! sleep is entered, and the DCDC mode is restored on wake up.
361 //! \return false if sleep state cannot be entered, true otherwise.
363 //******************************************************************************
364 extern bool PCM_gotoLPM3(void);
366 //******************************************************************************
368 //! Transitions the device into LPM0 while maintaining a safe
369 //! interrupt handling mentality. This function is meant to be used in
370 //! situations where the user wants to go to sleep, however does not want
371 //! to go to "miss" any interrupts due to the fact that going to DSL is not
372 //! an atomic operation. This function will modify the PRIMASK and on exit of
373 //! the program the master interrupts will be disabled.
375 //! Refer to the device specific data sheet for specifics about low power modes.
377 //! \return false if sleep state cannot be entered, true otherwise.
379 //******************************************************************************
380 extern bool PCM_gotoLPM0InterruptSafe(void);
382 //******************************************************************************
384 //! Transitions the device into LPM3 while maintaining a safe
385 //! interrupt handling mentality. This function is meant to be used in
386 //! situations where the user wants to go to LPM3, however does not want
387 //! to go to "miss" any interrupts due to the fact that going to DSL is not
388 //! an atomic operation. This function will modify the PRIMASK and on exit of
389 //! the program the master interrupts will be disabled.
391 //! Refer to the device specific data sheet for specifics about low power modes.
392 //! Note that since LPM3 cannot be entered from a DCDC power modes, the
393 //! power mode is first switched to LDO operation (if in DCDC mode), the deep
394 //! sleep is entered, and the DCDC mode is restored on wake up.
396 //! \return false if sleep state cannot be entered, true otherwise.
398 //******************************************************************************
399 extern bool PCM_gotoLPM3InterruptSafe(void);
401 //******************************************************************************
403 //! Enables "rude mode" entry into LPM3 and shutdown modes. With this mode
404 //! enabled, an entry into shutdown or LPM3 will occur even if there are
405 //! clock systems active. The system will forcibly turn off all clock/systems
406 //! when going into these modes.
410 //******************************************************************************
411 extern void PCM_enableRudeMode(void);
413 //******************************************************************************
415 //! Disables "rude mode" entry into LPM3 and shutdown modes. With this
416 //! mode disabled, an entry into shutdown or LPM3 will wait for any
417 //! active clock requests to free up before going into LPM3 or shutdown.
421 //******************************************************************************
422 extern void PCM_disableRudeMode(void);
424 //*****************************************************************************
426 //! Enables individual power control interrupt sources.
428 //! \param flags is a bit mask of the interrupt sources to be enabled. Must
429 //! be a logical OR of:
430 //! - \b PCM_DCDCERROR,
431 //! - \b PCM_AM_INVALIDTRANSITION,
432 //! - \b PCM_SM_INVALIDCLOCK,
433 //! - \b PCM_SM_INVALIDTRANSITION
435 //! This function enables the indicated power control interrupt sources. Only
436 //! the sources that are enabled can be reflected to the processor interrupt;
437 //! disabled sources have no effect on the processor.
439 //! \note The interrupt sources vary based on the part in use.
440 //! Please consult the data sheet for the part you are using to determine
441 //! which interrupt sources are available.
445 //*****************************************************************************
446 extern void PCM_enableInterrupt(uint32_t flags);
448 //*****************************************************************************
450 //! Disables individual power control interrupt sources.
452 //! \param flags is a bit mask of the interrupt sources to be enabled. Must
453 //! be a logical OR of:
454 //! - \b PCM_DCDCERROR,
455 //! - \b PCM_AM_INVALIDTRANSITION,
456 //! - \b PCM_SM_INVALIDCLOCK,
457 //! - \b PCM_SM_INVALIDTRANSITION
459 //! This function disables the indicated power control interrupt sources. Only
460 //! the sources that are enabled can be reflected to the processor interrupt;
461 //! disabled sources have no effect on the processor.
463 //! \note The interrupt sources vary based on the part in use.
464 //! Please consult the data sheet for the part you are using to determine
465 //! which interrupt sources are available.
469 //*****************************************************************************
470 extern void PCM_disableInterrupt(uint32_t flags);
472 //*****************************************************************************
474 //! Gets the current interrupt status.
476 //! \return The current interrupt status, enumerated as a bit field of:
477 //! - \b PCM_DCDCERROR,
478 //! - \b PCM_AM_INVALIDTRANSITION,
479 //! - \b PCM_SM_INVALIDCLOCK,
480 //! - \b PCM_SM_INVALIDTRANSITION
482 //! \note The interrupt sources vary based on the part in use.
483 //! Please consult the data sheet for the part you are using to determine
484 //! which interrupt sources are available.
486 //*****************************************************************************
487 extern uint32_t PCM_getInterruptStatus(void);
489 //*****************************************************************************
491 //! Gets the current interrupt status masked with the enabled interrupts.
492 //! This function is useful to call in ISRs to get a list of pending
493 //! interrupts that are actually enabled and could have caused
496 //! \return The current interrupt status, enumerated as a bit field of:
497 //! - \b PCM_DCDCERROR,
498 //! - \b PCM_AM_INVALIDTRANSITION,
499 //! - \b PCM_SM_INVALIDCLOCK,
500 //! - \b PCM_SM_INVALIDTRANSITION
502 //! \note The interrupt sources vary based on the part in use.
503 //! Please consult the data sheet for the part you are using to determine
504 //! which interrupt sources are available.
506 //*****************************************************************************
507 extern uint32_t PCM_getEnabledInterruptStatus(void);
509 //*****************************************************************************
511 //! Clears power system interrupt sources.
513 //! The specified power system interrupt sources are cleared, so that they no
514 //! longer assert. This function must be called in the interrupt handler to
515 //! keep it from being called again immediately upon exit.
517 //! \note Because there is a write buffer in the Cortex-M processor, it may
518 //! take several clock cycles before the interrupt source is actually cleared.
519 //! Therefore, it is recommended that the interrupt source be cleared early in
520 //! the interrupt handler (as opposed to the very last action) to avoid
521 //! returning from the interrupt handler before the interrupt source is
522 //! actually cleared. Failure to do so may result in the interrupt handler
523 //! being immediately reentered (because the interrupt controller still sees
524 //! the interrupt source asserted).
526 //! \param flags is a bit mask of the interrupt sources to be cleared. Must
527 //! be a logical OR of
528 //! - \b PCM_DCDCERROR,
529 //! - \b PCM_AM_INVALIDTRANSITION,
530 //! - \b PCM_SM_INVALIDCLOCK,
531 //! - \b PCM_SM_INVALIDTRANSITION
533 //! \note The interrupt sources vary based on the part in use.
534 //! Please consult the data sheet for the part you are using to determine
535 //! which interrupt sources are available.
539 //*****************************************************************************
540 extern void PCM_clearInterruptFlag(uint32_t flags);
542 //*****************************************************************************
544 //! Registers an interrupt handler for the power system interrupt.
546 //! \param intHandler is a pointer to the function to be called when the power
547 //! system interrupt occurs.
549 //! This function registers the handler to be called when a clock system
550 //! interrupt occurs. This function enables the global interrupt in the
551 //! interrupt controller; specific PCM interrupts must be enabled
552 //! via PCM_enableInterrupt(). It is the interrupt handler's responsibility to
553 //! clear the interrupt source via \link PCM_clearInterruptFlag \endlink .
555 //! \sa Interrupt_registerInterrupt() for important information about
556 //! registering interrupt handlers.
560 //*****************************************************************************
561 extern void PCM_registerInterrupt(void (*intHandler)(void));
563 //*****************************************************************************
565 //! Unregisters the interrupt handler for the power system.
567 //! This function unregisters the handler to be called when a power system
568 //! interrupt occurs. This function also masks off the interrupt in the
569 //! interrupt controller so that the interrupt handler no longer is called.
571 //! \sa Interrupt_registerInterrupt() for important information about
572 //! registering interrupt handlers.
576 //*****************************************************************************
577 extern void PCM_unregisterInterrupt(void);
579 //*****************************************************************************
581 // Mark the end of the C bindings section for C++ compilers.
583 //*****************************************************************************
588 //*****************************************************************************
590 // Close the Doxygen group.
593 //*****************************************************************************