AVR SD Safety Framework 1.0.0
Loading...
Searching...
No Matches
Power Manager

Contains API prototypes for the Power Manager. More...

Files

file  midware_power_manager.c
 Implements APIs for the Power Manager.
file  midware_power_manager.h
 Contains API prototypes for the Power Manager.
file  midware_power_manager_asm.h
 Contains assembly API for the Power Manager.
file  midware_power_manager_diag.c
 Implements APIs for the Power Manager Diagnostics.
file  midware_power_manager_diag.h
 Contains API prototypes for the Power Manager Diagnostics.

Enumerations

enum  vlmThreshold_t
 Type defines for available Voltage Level Monitor (VLM) threshold levels. More...
enum  vlmTrigger_t
 Type defines for available Voltage Level Monitor (VLM) trigger configurations. More...
enum  sleepMode_t
 Type defines for available sleep modes. More...

Functions

errFlag_t MW_GetClearVlmError (void)
 Reads and clears the flag indicating a supply voltage trigger error detected by the Voltage Level Monitor in the Brown-out Detector (BOD).
errFlag_t MW_GetClearVmonOverError (void)
 Reads and clears the flag indicating an overvoltage error detected by the Voltage Monitor.
errFlag_t MW_GetClearVmonUnderError (void)
 Reads and clears the flag indicating an undervoltage error detected by the Voltage Monitor.
errFlag_t MW_GetClearVmonDiagEntryError (void)
 Reads and clears the flag indicating a Diagnostic Mode entry error in the Voltage Monitor.
errFlag_t MW_GetClearVmonDiagExitError (void)
 Reads and clears the flag indicating a Diagnostic Mode exit error in the Voltage Monitor.
errFlag_t MW_GetClearVmonInternalError (void)
 Reads and clears the flag indicating internal error in the Voltage Monitor.
errFlag_t MW_GetClearVmonSleepEntryError (void)
 Reads and clears the flag indicating a sleep mode entry error in the Voltage Monitor.
errFlag_t MW_GetClearVmonDisabledError (void)
 Reads and clears the flag indicating a disabled Voltage Monitor error.
errFlag_t MW_GetClearSleepError (void)
 Reads and clears the flag indicating a Sleep Aborted error in the Sleep Controller.
void MW_EnablePowerInterrupts (void)
 Enables power related interrupts, including VMON, VLM and sleep error related interrupts.
errFlag_t MW_ConfigVlm (vlmThreshold_t threshold, vlmTrigger_t trigger)
 Configures the Voltage Level Monitor (VLM) with the provided voltage threshold and trigger condition.
void MW_SetVmonSleep (bool enableInSleep, bool useFullPowerMode)
 Configures Voltage Monitor (VMON) operation during Standby or Power-Down sleep.
errFlag_t MW_EnterSleepMode (sleepMode_t mode)
 Enters the selected device sleep mode.
void ASM_IssueSleepInstruction (void)
 Issues a SLEEP instruction to enter the configured device sleep mode.
errFlag_t MW_DiagVmonOverBegin (void)
 Starts error injection diagnostic to detect faults in the VMON overvoltage detector.
bool MW_IsDiagVmonOverDone (void)
 Checks if the VMON overvoltage error injection has been completed.
errFlag_t MW_DiagVmonOverEnd (void)
 Completes error injection diagnostic to detect faults in the VMON overvoltage detector.
errFlag_t MW_DiagVmonUnderBegin (void)
 Starts error injection diagnostic to detect faults in the VMON undervoltage detector.
bool MW_IsDiagVmonUnderDone (void)
 Checks if the VMON undervoltage error injection has been completed.
errFlag_t MW_DiagVmonUnderEnd (void)
 Completes error injection diagnostic to detect faults in the VMON undervoltage detector.
bool MW_IsDiagVmonOngoing (void)
 Checks whether a VMON error injection diagnostic is ongoing.

Detailed Description

Contains API prototypes for the Power Manager.

The Power Manager provides services to Tasks to ensure correct interaction with features of the SLPCTRL and BODCTRL peripherals.

UML Class Diagrams

UML Activity Diagrams

Enumeration Type Documentation

◆ sleepMode_t

Type defines for available sleep modes.

Note
Group configurations are shifted to reduce value range gaps, simplifying input validation.
Enumerator
SLP_MODE_IDLE 

Idle sleep mode

SLP_MODE_STANDBY 

Standby sleep mode

SLP_MODE_POWER_DOWN 

Power-Down sleep mode

SLP_MODE_MAX 

Reserved/invalid, used as sentinel value for sleep mode.

◆ vlmThreshold_t

Type defines for available Voltage Level Monitor (VLM) threshold levels.

Note
Group configurations are shifted to reduce value range gaps, simplifying input validation.
Enumerator
VLM_THRESHOLD_OFF 

VLM disabled

VLM_THRESHOLD_PCT_5 

VLM 5% above BOD

VLM_THRESHOLD_PCT_15 

VLM 15% above BOD

VLM_THRESHOLD_PCT_25 

VLM 25% above BOD

VLM_THRESHOLD_MAX 

Reserved/invalid, used as sentinel value for VLM threshold.

◆ vlmTrigger_t

Type defines for available Voltage Level Monitor (VLM) trigger configurations.

Note
Group configurations are shifted to reduce value range gaps, simplifying input validation.
Enumerator
VLM_TRIGGER_FALLING 

VDD falls below threshold

VLM_TRIGGER_RISING 

VDD rises above threshold

VLM_TRIGGER_BOTH 

VDD crosses threshold

VLM_TRIGGER_MAX 

Reserved/invalid, used as sentinel value for VLM trigger.

Function Documentation

◆ ASM_IssueSleepInstruction()

void ASM_IssueSleepInstruction ( void )

Issues a SLEEP instruction to enter the configured device sleep mode.

Here is the caller graph for this function:

◆ MW_ConfigVlm()

errFlag_t MW_ConfigVlm ( vlmThreshold_t threshold,
vlmTrigger_t trigger )

Configures the Voltage Level Monitor (VLM) with the provided voltage threshold and trigger condition.

Note

The VLM interrupt is enabled by MW_EnablePowerInterrupts.

Parameters
thresholdVLM threshold level value.
triggerTriggering value of VLM.
Return values
ERRORInvalid threshold or trigger value.
NO_ERRORValid threshold or trigger value.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ MW_DiagVmonOverBegin()

errFlag_t MW_DiagVmonOverBegin ( void )

Starts error injection diagnostic to detect faults in the VMON overvoltage detector.

This function starts a VMON overvoltage error injection diagnostic. The diagnostic must be completed by calling MW_DiagVmonOverEnd after MW_IsDiagVmonOverDone returns true. Because the error injection mechanism operates at a relatively slow speed (typically tens of microseconds or more), and its execution time can vary between devices and operating conditions, the diagnostic is designed to run asynchronously, independent of the CPU until completion.

Warning

It is assumed that this diagnostic is run before transitioning the device out of Safe State. It is also possible to use it outside of the Safe State, but such use requires that it is evaluated on a case by case basis whether or not it is safe for the application to inject an error into the voltage regulator while the device is not in a Safe State.

Warning

This diagnostic requires the voltage regulator to be in maximum performance mode. See the device data sheet for more information.

Warning
During diagnostic execution, the VREGFAIL and VREGWARN error channels are set to NOTIFICATION severity. These settings are restored to their original configurations when

MW_DiagVmonOverEnd is called.

Note

This function disables global interrupts during its execution to ensure atomic execution and that accidental interrupts are not triggered by initiating the error injection.

Note

This diagnostic can be used in 'polling mode' or 'interrupt mode'. If the Status Register (SREG) Global Interrupt Enable bit is set, it is assumed that the diagnostic will be finished through an interrupt. However if the Global Interrupt Enable bit is not set, it is assumed that the MW_IsDiagVmonOverDone is called repeatedly to check if the error injection is finished.

Note

The error injection will not be initiated if the Error Controller is not in NORMAL state, if the VREGWARN or VREGFAIL error channels are already set, or if another VMON diagnostic is already ongoing. The diagnostic will also verify if error injection started as expected and return ERROR if it was unsuccessful in transitioning into diagnostic mode.

Return values
ERRORDiagnostic failed to start due to illegal conditions or the diagnostic mode transition failed.
NO_ERRORDiagnostic successfully started.
Here is the caller graph for this function:

◆ MW_DiagVmonOverEnd()

errFlag_t MW_DiagVmonOverEnd ( void )

Completes error injection diagnostic to detect faults in the VMON overvoltage detector.

This function completes the diagnostic by checking the result of the error injection started by MW_DiagVmonOverBegin. It evaluates the results of the diagnostic and restores the original configurations of the VREGFAIL and VREGWARN error channels. It should be called after MW_IsDiagVmonOverDone returns true, indicating that the diagnostic has completed.

Note

This function disables global interrupts during its execution to ensure atomic execution and that accidental interrupts are not triggered by finishing the error injection.

Note

If this function is called without having called MW_DiagVmonOverBegin beforehand, it will do nothing and return ERROR in order to avoid data hazards in regards to modifying the VREGFAIL and VREGWARN error channel configurations.

Return values
ERRORFault detected in the VMON overvoltage detector or inappropriate function call.
NO_ERRORNo fault detected in the VMON overvoltage detector.
Here is the caller graph for this function:

◆ MW_DiagVmonUnderBegin()

errFlag_t MW_DiagVmonUnderBegin ( void )

Starts error injection diagnostic to detect faults in the VMON undervoltage detector.

This function starts a VMON undervoltage error injection diagnostic. The diagnostic must be completed by calling MW_DiagVmonUnderEnd after MW_IsDiagVmonUnderDone returns true. Because the error injection mechanism operates at a relatively slow speed (typically tens of microseconds or more), and its execution time can vary between devices and operating conditions, the diagnostic is designed to run asynchronously, independent of the CPU until completion.

Warning

It is assumed that this diagnostic is run before transitioning the device out of Safe State. It is also possible to use it outside of the Safe State, but such use requires that it is evaluated on a case by case basis whether or not it is safe for the application to inject an error into the voltage regulator while the device is not in a Safe State.

Warning

This diagnostic requires the voltage regulator to be in maximum performance mode. See the device data sheet for more information.

Warning
During diagnostic execution, the VREGFAIL and VREGWARN error channels are set to NOTIFICATION severity. These settings are restored to their original configurations when

MW_DiagVmonUnderEnd is called.

Note

This function disables global interrupts during its execution to ensure atomic execution and that accidental interrupts are not triggered by initiating the error injection.

Note

This diagnostic can be used in 'polling mode' or 'interrupt mode'. If the Status Register (SREG) Global Interrupt Enable bit is set, it is assumed that the diagnostic will be finished through an interrupt. However if the Global Interrupt Enable bit is not set, it is assumed that the MW_IsDiagVmonUnderDone is called repeatedly to check if the error injection is finished.

Note

The error injection will not be initiated if the Error Controller is not in NORMAL state, if the VREGWARN or VREGFAIL error channels are already set, or if another VMON diagnostic is already ongoing. The diagnostic will also verify if error injection started as expected and return ERROR if it was unsuccessful in transitioning into diagnostic mode.

Return values
ERRORDiagnostic failed to start due to illegal conditions or the diagnostic mode transition failed.
NO_ERRORDiagnostic successfully started.
Here is the caller graph for this function:

◆ MW_DiagVmonUnderEnd()

errFlag_t MW_DiagVmonUnderEnd ( void )

Completes error injection diagnostic to detect faults in the VMON undervoltage detector.

This function completes the diagnostic by checking the result of the error injection started by MW_DiagVmonUnderBegin. It evaluates the results of the diagnostic and restores the original configurations of the VREGFAIL and VREGWARN error channels. It should be called after MW_IsDiagVmonUnderDone returns true, indicating that the diagnostic has completed.

Note

This function disables global interrupts during its execution to ensure atomic execution and that accidental interrupts are not triggered by finishing the error injection.

Note

If this function is called without having called MW_DiagVmonUnderBegin beforehand, it will do nothing and return ERROR in order to avoid data hazards in regards to modifying the VREGFAIL and VREGWARN error channel configurations.

Return values
ERRORFault detected in the VMON undervoltage detector or inappropriate function call.
NO_ERRORNo fault detected in the VMON undervoltage detector.
Here is the caller graph for this function:

◆ MW_EnablePowerInterrupts()

void MW_EnablePowerInterrupts ( void )

Enables power related interrupts, including VMON, VLM and sleep error related interrupts.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ MW_EnterSleepMode()

errFlag_t MW_EnterSleepMode ( sleepMode_t mode)

Enters the selected device sleep mode.

This function configures the device to use the provided sleep mode, enables sleep, and enters the selected mode by issuing the SLEEP instruction. The device remains in sleep until an interrupt request (IRQ) from an enabled wake-up source occurs, after which execution resumes following the wake-up time associated with the selected sleep mode.

Idle Sleep Mode: The CPU clock is stopped, while all enabled peripherals continue running.

Standby Sleep Mode: The CPU and most clocks are stopped. Certain peripherals can be configured to run in Standby by enabling their RUNSTDBY setting.

Power-Down Sleep Mode: Most high-frequency clocks are stopped. Only low-power peripherals such as the Watchdog Timer (WDT) and the RTC PIT remain active.

Note

Individual peripherals may require additional configuration to operate as intended in the selected sleep mode. Refer to the device data sheet for the sleep behavior of each peripheral.

Note

For detailed information on wake-up times and wake-up sources for each sleep mode, see the device data sheet.

Warning

When enabled, the Synchronous Watchdog Timer (SWDT) is halted during all sleep modes and resumes after wake-up.

Warning

In Standby and Power-Down sleep modes, several safety mechanisms are inactive. It is recommended that the application enter a Safe State before using these modes.

Warning

Several clock sources stop when entering sleep. If the Clock Frequency Monitor (CFM) or Clock Failure Detector (CFD) monitors a clock source that stops in the selected sleep mode, a CFM or CFD event will occur. Disable monitoring before entering sleep and re-enable it after wake-up once the oscillator is stable.

Warning

Configure the Voltage Monitor (VMON) to the desired mode using MW_SetVmonSleep before entering Standby or Power-Down sleep modes.

Warning

If global interrupts are disabled, the SLEEP instruction is ignored and the Sleep Error status bit is automatically set. Check and clear this condition using MW_GetClearSleepError.

Warning

Ensure that at least one valid interrupt wake-up source is enabled before entering sleep. Without a wake-up source, the device will not resume execution except through a device reset.

Parameters
modeThe sleep mode to use when entering device sleep.
Return values
ERRORInvalid sleep mode, sleep entry aborted.
NO_ERRORValid sleep mode, sleep entry attempted.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ MW_GetClearSleepError()

errFlag_t MW_GetClearSleepError ( void )

Reads and clears the flag indicating a Sleep Aborted error in the Sleep Controller.

This function checks whether the Sleep Aborted entry error interrupt flag has been set or not, and if set, it clears the flag and returns ERROR.

Return values
ERRORSleep Aborted error flag set.
NO_ERRORSleep Aborted error flag not set.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ MW_GetClearVlmError()

errFlag_t MW_GetClearVlmError ( void )

Reads and clears the flag indicating a supply voltage trigger error detected by the Voltage Level Monitor in the Brown-out Detector (BOD).

This function checks whether the VLM trigger interrupt flag has been set or not. And if set, clears the flag and returns ERROR.

Return values
ERRORVLM trigger error flag set.
NO_ERRORVLM trigger error flag not set.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ MW_GetClearVmonDiagEntryError()

errFlag_t MW_GetClearVmonDiagEntryError ( void )

Reads and clears the flag indicating a Diagnostic Mode entry error in the Voltage Monitor.

This function checks whether the Diagnostic Mode entry error interrupt flag has been set or not, and if set, it clears the flag and returns ERROR.

Return values
ERRORDiagnostic mode entry error flag set.
NO_ERRORDiagnostic mode entry error flag not set.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ MW_GetClearVmonDiagExitError()

errFlag_t MW_GetClearVmonDiagExitError ( void )

Reads and clears the flag indicating a Diagnostic Mode exit error in the Voltage Monitor.

This function checks whether the Diagnostic Mode exit error interrupt flag has been set or not, and if set, it clears the flag and returns ERROR.

Return values
ERRORDiagnostic mode exit error flag set.
NO_ERRORDiagnostic mode exit error flag not set.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ MW_GetClearVmonDisabledError()

errFlag_t MW_GetClearVmonDisabledError ( void )

Reads and clears the flag indicating a disabled Voltage Monitor error.

This function checks whether the VMON Disabled interrupt flag has been set or not, and if set, it clears the flag and returns ERROR.

Return values
ERRORDisabled Voltage Monitor error flag set.
NO_ERRORDisabled Voltage Monitor error flag not set.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ MW_GetClearVmonInternalError()

errFlag_t MW_GetClearVmonInternalError ( void )

Reads and clears the flag indicating internal error in the Voltage Monitor.

This function checks whether the VMON internal error interrupt flag has been set or not, and if set, it clears the flag and returns ERROR.

Return values
ERRORInternal error flag set.
NO_ERRORInternal error flag not set.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ MW_GetClearVmonOverError()

errFlag_t MW_GetClearVmonOverError ( void )

Reads and clears the flag indicating an overvoltage error detected by the Voltage Monitor.

This function checks whether the overvoltage error interrupt flag has been set or not, and if set, it clears the flag and returns ERROR.

Return values
ERROROvervoltage error flag set.
NO_ERROROvervoltage error flag not set.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ MW_GetClearVmonSleepEntryError()

errFlag_t MW_GetClearVmonSleepEntryError ( void )

Reads and clears the flag indicating a sleep mode entry error in the Voltage Monitor.

This function checks whether the Sleep Mode entry error interrupt flag has been set or not, and if set, it clears the flag and returns ERROR.

Note

If OSC32K or XOSC32K are used as the main clock source, this flag will always be set.

Return values
ERROREnter Sleep Mode error flag set.
NO_ERROREnter Sleep Mode error flag not set.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ MW_GetClearVmonUnderError()

errFlag_t MW_GetClearVmonUnderError ( void )

Reads and clears the flag indicating an undervoltage error detected by the Voltage Monitor.

This function checks whether the undervoltage error interrupt flag has been set or not, and if set, it clears the flag and returns ERROR.

Return values
ERRORUndervoltage error flag set.
NO_ERRORUndervoltage error flag not set.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ MW_IsDiagVmonOngoing()

bool MW_IsDiagVmonOngoing ( void )

Checks whether a VMON error injection diagnostic is ongoing.

This function returns whether a VMON overvoltage or undervoltage error injection diagnostic has been started and not yet ended. It is intended to be used when the diagnostic completion relies on interrupts, allowing the Application to detect if the expected interrupt never occurs and the VMON remains in diagnostic mode.

Return values
trueA VMON error injection diagnostic has been started and not yet ended.
falseNo VMON error injection diagnostic is active.

◆ MW_IsDiagVmonOverDone()

bool MW_IsDiagVmonOverDone ( void )

Checks if the VMON overvoltage error injection has been completed.

This function checks the status of the VMON overvoltage error injection to determine whether the diagnostic can be completed. This is done by checking if the error injection was started in the first place, and then if the result is ready for evaluation by MW_DiagVmonOverEnd, indicating that the error injection has finished, either because the injected error was detected by the VMON or because the VMON diagnostic timer timed out.

Note

The error injection diagnostic is initiated by calling MW_DiagVmonOverBegin and is completed by calling MW_DiagVmonOverEnd.

Note

This function should be called periodically after MW_DiagVmonOverBegin to poll the status of the diagnostic or used in an interrupt to check if the diagnostic is ready to be completed.

Note

If the diagnostic was never started, this function always returns false. To determine whether a VMON error injection diagnostic is active, use MW_IsDiagVmonOngoing.

Return values
trueThe VMON overvoltage error injection is finished and ready for evaluation.
falseThe error injection is not finished or was never started.
Here is the caller graph for this function:

◆ MW_IsDiagVmonUnderDone()

bool MW_IsDiagVmonUnderDone ( void )

Checks if the VMON undervoltage error injection has been completed.

This function checks the status of the VMON undervoltage error injection to determine whether the diagnostic can be completed. This is done by checking if the error injection was started in the first place, and then if the result is ready for evaluation by MW_DiagVmonUnderEnd, indicating that the error injection has finished, either because the injected error was detected by the VMON or because the VMON diagnostic timer timed out.

Note

The error injection diagnostic is initiated by calling MW_DiagVmonUnderBegin and is completed by calling MW_DiagVmonUnderEnd.

Note

This function should be called periodically after MW_DiagVmonUnderBegin to poll the status of the diagnostic or used in an interrupt to check if the diagnostic is ready to be completed.

Note

If the diagnostic was never started, this function always returns false. To determine whether a VMON error injection diagnostic is active, use MW_IsDiagVmonOngoing.

Return values
trueThe VMON undervoltage error injection is finished and ready for evaluation.
falseThe error injection is not finished or was never started.
Here is the caller graph for this function:

◆ MW_SetVmonSleep()

void MW_SetVmonSleep ( bool enableInSleep,
bool useFullPowerMode )

Configures Voltage Monitor (VMON) operation during Standby or Power-Down sleep.

Note

If Full Power Mode is used, the VMON will always be in maximum performance regardless of main clock source and sleep modes. This will also ensure a shorter wake up time from Standby or Power-Down sleep. Otherwise, Auto Mode is used, which automatically changes performance based on device state.

Parameters
enableInSleepConfigures whether or not the VMON is enabled in Standby or Power-Down sleep.
useFullPowerModeConfigures whether the VMON uses Full Power Mode or Auto Mode.
Note
If VMON is disabled in sleep, the VDIS (VMON Disabled) flag may be set on entering sleep. If Auto Mode is used, entering Standby or Power-Down sleep may set the VSLP (VMON Sleep Entry) flag. Both flags remain set after wake-up and can be checked and cleared by

MW_GetClearVmonDisabledError and MW_GetClearVmonSleepEntryError respectively.

Here is the call graph for this function:
Here is the caller graph for this function: