![]() |
AVR SD Safety Framework 1.0.0
|
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. | |
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.
| enum sleepMode_t |
Type defines for available sleep modes.
| 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. |
| enum vlmThreshold_t |
Type defines for available Voltage Level Monitor (VLM) threshold levels.
| enum vlmTrigger_t |
Type defines for available Voltage Level Monitor (VLM) trigger configurations.
| void ASM_IssueSleepInstruction | ( | void | ) |
Issues a SLEEP instruction to enter the configured device sleep mode.
| errFlag_t MW_ConfigVlm | ( | vlmThreshold_t | threshold, |
| vlmTrigger_t | trigger ) |
Configures the Voltage Level Monitor (VLM) with the provided voltage threshold and trigger condition.
The VLM interrupt is enabled by MW_EnablePowerInterrupts.
| threshold | VLM threshold level value. |
| trigger | Triggering value of VLM. |
| ERROR | Invalid threshold or trigger value. |
| NO_ERROR | Valid threshold or trigger value. |
| 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.
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.
This diagnostic requires the voltage regulator to be in maximum performance mode. See the device data sheet for more information.
MW_DiagVmonOverEnd is called.
This function disables global interrupts during its execution to ensure atomic execution and that accidental interrupts are not triggered by initiating the error injection.
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.
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.
| ERROR | Diagnostic failed to start due to illegal conditions or the diagnostic mode transition failed. |
| NO_ERROR | Diagnostic successfully started. |
| 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.
This function disables global interrupts during its execution to ensure atomic execution and that accidental interrupts are not triggered by finishing the error injection.
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.
| ERROR | Fault detected in the VMON overvoltage detector or inappropriate function call. |
| NO_ERROR | No fault detected in the VMON overvoltage detector. |
| 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.
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.
This diagnostic requires the voltage regulator to be in maximum performance mode. See the device data sheet for more information.
MW_DiagVmonUnderEnd is called.
This function disables global interrupts during its execution to ensure atomic execution and that accidental interrupts are not triggered by initiating the error injection.
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.
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.
| ERROR | Diagnostic failed to start due to illegal conditions or the diagnostic mode transition failed. |
| NO_ERROR | Diagnostic successfully started. |
| 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.
This function disables global interrupts during its execution to ensure atomic execution and that accidental interrupts are not triggered by finishing the error injection.
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.
| ERROR | Fault detected in the VMON undervoltage detector or inappropriate function call. |
| NO_ERROR | No fault detected in the VMON undervoltage detector. |
| void MW_EnablePowerInterrupts | ( | void | ) |
Enables power related interrupts, including VMON, VLM and sleep error related interrupts.
| 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.
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.
For detailed information on wake-up times and wake-up sources for each sleep mode, see the device data sheet.
When enabled, the Synchronous Watchdog Timer (SWDT) is halted during all sleep modes and resumes after wake-up.
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.
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.
Configure the Voltage Monitor (VMON) to the desired mode using MW_SetVmonSleep before entering Standby or Power-Down sleep modes.
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.
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.
| mode | The sleep mode to use when entering device sleep. |
| ERROR | Invalid sleep mode, sleep entry aborted. |
| NO_ERROR | Valid sleep mode, sleep entry attempted. |
| 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.
| ERROR | Sleep Aborted error flag set. |
| NO_ERROR | Sleep Aborted error flag not set. |
| 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.
| ERROR | VLM trigger error flag set. |
| NO_ERROR | VLM trigger error flag not set. |
| 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.
| ERROR | Diagnostic mode entry error flag set. |
| NO_ERROR | Diagnostic mode entry error flag not set. |
| 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.
| ERROR | Diagnostic mode exit error flag set. |
| NO_ERROR | Diagnostic mode exit error flag not set. |
| 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.
| ERROR | Disabled Voltage Monitor error flag set. |
| NO_ERROR | Disabled Voltage Monitor error flag not set. |
| 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.
| ERROR | Internal error flag set. |
| NO_ERROR | Internal error flag not set. |
| 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.
| ERROR | Overvoltage error flag set. |
| NO_ERROR | Overvoltage error flag not set. |
| 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.
If OSC32K or XOSC32K are used as the main clock source, this flag will always be set.
| ERROR | Enter Sleep Mode error flag set. |
| NO_ERROR | Enter Sleep Mode error flag not set. |
| 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.
| ERROR | Undervoltage error flag set. |
| NO_ERROR | Undervoltage error flag not set. |
| 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.
| true | A VMON error injection diagnostic has been started and not yet ended. |
| false | No VMON error injection diagnostic is active. |
| 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.
The error injection diagnostic is initiated by calling MW_DiagVmonOverBegin and is completed by calling MW_DiagVmonOverEnd.
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.
If the diagnostic was never started, this function always returns false. To determine whether a VMON error injection diagnostic is active, use MW_IsDiagVmonOngoing.
| true | The VMON overvoltage error injection is finished and ready for evaluation. |
| false | The error injection is not finished or was never started. |
| 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.
The error injection diagnostic is initiated by calling MW_DiagVmonUnderBegin and is completed by calling MW_DiagVmonUnderEnd.
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.
If the diagnostic was never started, this function always returns false. To determine whether a VMON error injection diagnostic is active, use MW_IsDiagVmonOngoing.
| true | The VMON undervoltage error injection is finished and ready for evaluation. |
| false | The error injection is not finished or was never started. |
| void MW_SetVmonSleep | ( | bool | enableInSleep, |
| bool | useFullPowerMode ) |
Configures Voltage Monitor (VMON) operation during Standby or Power-Down sleep.
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.
| enableInSleep | Configures whether or not the VMON is enabled in Standby or Power-Down sleep. |
| useFullPowerMode | Configures whether the VMON uses Full Power Mode or Auto Mode. |
MW_GetClearVmonDisabledError and MW_GetClearVmonSleepEntryError respectively.