Macros
#define	DELAY_USECS 95

#define	LOOP_CYCLES 3

Functions
void	HibernateEnableExpClk (uint32_t ui32HibClk)

void	HibernateDisable (void)

void	HibernateClockConfig (uint32_t ui32Config)

void	HibernateRTCEnable (void)

void	HibernateRTCDisable (void)

void	HibernateBatCheckStart (void)

uint32_t	HibernateBatCheckDone (void)

void	HibernateWakeSet (uint32_t ui32WakeFlags)

uint32_t	HibernateWakeGet (void)

void	HibernateLowBatSet (uint32_t ui32LowBatFlags)

uint32_t	HibernateLowBatGet (void)

void	HibernateRTCSet (uint32_t ui32RTCValue)

uint32_t	HibernateRTCGet (void)

void	HibernateRTCMatchSet (uint32_t ui32Match, uint32_t ui32Value)

uint32_t	HibernateRTCMatchGet (uint32_t ui32Match)

void	HibernateRTCSSMatchSet (uint32_t ui32Match, uint32_t ui32Value)

uint32_t	HibernateRTCSSMatchGet (uint32_t ui32Match)

uint32_t	HibernateRTCSSGet (void)

void	HibernateRTCTrimSet (uint32_t ui32Trim)

uint32_t	HibernateRTCTrimGet (void)

void	HibernateDataSet (uint32_t *pui32Data, uint32_t ui32Count)

void	HibernateDataGet (uint32_t *pui32Data, uint32_t ui32Count)

void	HibernateRequest (void)

void	HibernateIntEnable (uint32_t ui32IntFlags)

void	HibernateIntDisable (uint32_t ui32IntFlags)

void	HibernateIntRegister (void(*pfnHandler)(void))

void	HibernateIntUnregister (void)

uint32_t	HibernateIntStatus (bool bMasked)

void	HibernateIntClear (uint32_t ui32IntFlags)

uint32_t	HibernateIsActive (void)

void	HibernateGPIORetentionEnable (void)

void	HibernateGPIORetentionDisable (void)

bool	HibernateGPIORetentionGet (void)

void	HibernateCounterMode (uint32_t ui32Config)

void	HibernateCalendarSet (struct tm *psTime)

int	HibernateCalendarGet (struct tm *psTime)

void	HibernateCalendarMatchSet (uint32_t ui32Index, struct tm *psTime)

void	HibernateCalendarMatchGet (uint32_t ui32Index, struct tm *psTime)

void	HibernateTamperEventsConfig (uint32_t ui32Config)

void	HibernateTamperEnable (void)

void	HibernateTamperDisable (void)

void	HibernateTamperIOEnable (uint32_t ui32Input, uint32_t ui32Config)

void	HibernateTamperIODisable (uint32_t ui32Input)

void	HibernateTamperEventsClear (void)

void	HibernateTamperEventsClearNoLock (void)

void	HibernateTamperUnLock (void)

void	HibernateTamperLock (void)

uint32_t	HibernateTamperStatusGet (void)

bool	HibernateTamperEventsGet (uint32_t ui32Index, uint32_t pui32RTC, uint32_t pui32Event)

void	HibernateTamperExtOscRecover (void)

bool	HibernateTamperExtOscValid (void)

Detailed Description

Macro Definition Documentation

§ DELAY_USECS

#define DELAY_USECS 95

§ LOOP_CYCLES

#define LOOP_CYCLES 3

Function Documentation

§ HibernateEnableExpClk()

void HibernateEnableExpClk ( uint32_t ui32HibClk )

Enables the Hibernation module for operation.

Parameters

ui32HibClk is the rate of the clock supplied to the Hibernation module.

This function enables the Hibernation module for operation. This function should be called before any of the Hibernation module features are used.

The peripheral clock is the same as the processor clock. The frequency of the system clock is the value returned by SysCtlClockFreqSet(), or it can be explicitly hard coded if it is constant and known (to save the code/execution overhead of fetch of the variable call holding the return value of SysCtlClockFreqSet()).

Returns: None.

References HIB_CTL, HIB_CTL_CLK32EN, and HWREG.

§ HibernateDisable()

void HibernateDisable ( void )

Disables the Hibernation module for operation.

This function disables the Hibernation module. After this function is called, none of the Hibernation module features are available.

Returns: None.

References HIB_CTL, HIB_CTL_CLK32EN, and HWREG.

§ HibernateClockConfig()

void HibernateClockConfig ( uint32_t ui32Config )

Configures the clock input for the Hibernation module.

Parameters

ui32Config is one of the possible configuration options for the clock input listed below.

This function is used to configure the clock input for the Hibernation module. The ui32Config parameter can be one of the following values:

HIBERNATE_OSC_DISABLE specifies that the internal oscillator is powered off. This option is used when an externally supplied oscillator is connected to the XOSC0 pin or to save power when the LFIOSC is used.
HIBERNATE_OSC_HIGHDRIVE specifies a higher drive strength when a 24-pF filter capacitor is used with a crystal.
HIBERNATE_OSC_LOWDRIVE specifies a lower drive strength when a 12-pF filter capacitor is used with a crystal.

There is an option to use an internal low frequency oscillator (LFIOSC) as the clock source for the Hibernation module. Because of the low accuracy of this oscillator, this option should not be used when the system requires a real time counter. Adding the HIBERNATE_OSC_LFIOSC value enables the LFIOSC as the clock source to the Hibernation module.

HIBERNATE_OSC_LFIOSC enables the Hibernation module's internal low frequency oscillator as the clock to the Hibernation module.

This ui32Config also configures how the clock output from the hibernation is used to clock other peripherals in the system. The ALT clock settings allow clocking a subset of the peripherals. The ui32Config parameter can have any combination of the following values:

HIBERNATE_OUT_SYSCLK enables the hibernate clock output to the system clock.

The HIBERNATE_OSC_DISABLE option is used to disable and power down the internal oscillator if an external clock source or no clock source is used instead of a 32.768-kHz crystal. In the case where an external crystal is used, either the HIBERNATE_OSC_HIGHDRIVE or HIBERNATE_OSC_LOWDRIVE is used. These settings optimizes the oscillator drive strength to match the size of the filter capacitor that is used with the external crystal circuit.

Returns: None.

References ASSERT, HIB_CTL, HIB_CTL_CLK32EN, HIBERNATE_OSC_DISABLE, HIBERNATE_OSC_HIGHDRIVE, HIBERNATE_OSC_LFIOSC, HIBERNATE_OSC_LOWDRIVE, and HWREG.

§ HibernateRTCEnable()

void HibernateRTCEnable ( void )

Enables the RTC feature of the Hibernation module.

This function enables the RTC in the Hibernation module. The RTC can be used to wake the processor from hibernation at a certain time, or to generate interrupts at certain times. This function must be called before using any of the RTC features of the Hibernation module.

Returns: None.

References HIB_CTL, HIB_CTL_RTCEN, and HWREG.

§ HibernateRTCDisable()

void HibernateRTCDisable ( void )

Disables the RTC feature of the Hibernation module.

This function disables the RTC in the Hibernation module. After calling this function, the RTC features of the Hibernation module are not available.

Returns: None.

References HIB_CTL, HIB_CTL_RTCEN, and HWREG.

§ HibernateBatCheckStart()

void HibernateBatCheckStart ( void )

Forces the Hibernation module to initiate a check of the battery voltage.

This function forces the Hibernation module to initiate a check of the battery voltage immediately rather than waiting for the next check interval to pass. After calling this function, the application should call the HibernateBatCheckDone() function and wait for the function to return a zero value before calling the HibernateIntStatus() to check if the return code has the HIBERNATE_INT_LOW_BAT set. If HIBERNATE_INT_LOW_BAT is set, the battery level is low. The application can also enable the HIBERNATE_INT_LOW_BAT interrupt and wait for an interrupt to indicate that the battery level is low.

Note: A hibernation request is held off if a battery check is in progress.

Returns: None.

References HIB_CTL, HIB_CTL_BATCHK, and HWREG.

§ HibernateBatCheckDone()

uint32_t HibernateBatCheckDone ( void )

Determines whether or not a forced battery check has completed.

This function determines whether the forced battery check initiated by a call to the HibernateBatCheckStart() function has completed. This function returns a non-zero value until the battery level check has completed. Once this function returns a value of zero, the Hibernation module has completed the battery check and the HibernateIntStatus() function can be used to check if the battery was low by checking if the value returned has the HIBERNATE_INT_LOW_BAT set.

Returns: The value is zero when the battery level check has completed or non-zero if the check is still in process.

References HIB_CTL, HIB_CTL_BATCHK, and HWREG.

§ HibernateWakeSet()

void HibernateWakeSet ( uint32_t ui32WakeFlags )

Configures the wake conditions for the Hibernation module.

Parameters

ui32WakeFlags specifies which conditions should be used for waking.

This function enables the conditions under which the Hibernation module wakes. The ui32WakeFlags parameter is the logical OR of any combination of the following:

HIBERNATE_WAKE_PIN - wake when the external wake pin is asserted.
HIBERNATE_WAKE_RTC - wake when the RTC match occurs.
HIBERNATE_WAKE_LOW_BAT - wake from hibernate due to a low-battery level being detected.
HIBERNATE_WAKE_GPIO - wake when a GPIO pin is asserted.
HIBERNATE_WAKE_RESET - wake when a reset pin is asserted.

Note: A tamper event can act as a wake source for the Hibernate module. Refer to the function HibernateTamperEventsConfig() to wake from hibernation on a tamper event.

If the HIBERNATE_WAKE_GPIO flag is set, then one of the GPIO configuration functions GPIOPinTypeWakeHigh() or GPIOPinTypeWakeLow() must be called to properly configure and enable a GPIO as a wake source for hibernation.

Returns: None.

References ASSERT, HIB_CTL, HIBERNATE_WAKE_GPIO, HIBERNATE_WAKE_LOW_BAT, HIBERNATE_WAKE_PIN, HIBERNATE_WAKE_RESET, HIBERNATE_WAKE_RTC, and HWREG.

§ HibernateWakeGet()

uint32_t HibernateWakeGet ( void )

Gets the currently configured wake conditions for the Hibernation module.

This function returns the flags representing the wake configuration for the Hibernation module. The return value is a combination of the following flags:

HIBERNATE_WAKE_PIN - wake when the external wake pin is asserted
HIBERNATE_WAKE_RTC - wake when the RTC matches occurs
HIBERNATE_WAKE_LOW_BAT - wake from hibernation due to a low-battery level being detected
HIBERNATE_WAKE_GPIO - wake when a GPIO pin is asserted
HIBERNATE_WAKE_RESET - wake when a reset pin is asserted

Note: A tamper event can act as a wake source for the Hibernate module. Refer to the function HibernateTamperEventsConfig() to wake from hibernation on a tamper event.

Returns: Returns flags indicating the configured wake conditions.

References HIB_CTL, HIB_IO, HIBERNATE_WAKE_GPIO, HIBERNATE_WAKE_LOW_BAT, HIBERNATE_WAKE_PIN, HIBERNATE_WAKE_RESET, HIBERNATE_WAKE_RTC, and HWREG.

§ HibernateLowBatSet()

void HibernateLowBatSet ( uint32_t ui32LowBatFlags )

Configures the low-battery detection.

Parameters

ui32LowBatFlags specifies behavior of low-battery detection.

This function enables the low-battery detection and whether hibernation is allowed if a low battery is detected. If low-battery detection is enabled, then a low-battery condition is indicated in the raw interrupt status register, which can be enabled to trigger an interrupt. Optionally, hibernation can be aborted if a low battery condition is detected.

The ui32LowBatFlags parameter is one of the following values:

HIBERNATE_LOW_BAT_DETECT - detect a low-battery condition
HIBERNATE_LOW_BAT_ABORT - detect a low-battery condition and abort hibernation if low-battery is detected

The other setting in the ui32LowBatFlags allows the caller to set one of the following voltage level trigger values :

HIBERNATE_LOW_BAT_1_9V - voltage low level is 1.9 V
HIBERNATE_LOW_BAT_2_1V - voltage low level is 2.1 V
HIBERNATE_LOW_BAT_2_3V - voltage low level is 2.3 V
HIBERNATE_LOW_BAT_2_5V - voltage low level is 2.5 V

Example: Abort hibernate if the voltage level is below 2.1 V.

//! HibernateLowBatSet(HIBERNATE_LOW_BAT_ABORT | HIBERNATE_LOW_BAT_2_1V);
//!

\return None.

References ASSERT, HIB_CTL, HIB_CTL_VBATSEL_M, HIBERNATE_LOW_BAT_ABORT, and HWREG.

§ HibernateLowBatGet()

uint32_t HibernateLowBatGet ( void )

Gets the currently configured low-battery detection behavior.

This function returns a value representing the currently configured low battery detection behavior.

The return value is a combination of the values described in the HibernateLowBatSet() function.

Returns: Returns a value indicating the configured low-battery detection.

References HIB_CTL, HIB_CTL_VBATSEL_M, HIBERNATE_LOW_BAT_ABORT, and HWREG.

§ HibernateRTCSet()

void HibernateRTCSet ( uint32_t ui32RTCValue )

Sets the value of the real time clock (RTC) counter.

Parameters

ui32RTCValue is the new value for the RTC.

This function sets the value of the RTC. The RTC counter contains the count in seconds when a 32.768kHz clock source is in use. The RTC must be enabled by calling HibernateRTCEnable() before calling this function.

Returns: None.

References HIB_LOCK, HIB_LOCK_HIBLOCK_KEY, and HWREG.

§ HibernateRTCGet()

uint32_t HibernateRTCGet ( void )

Gets the value of the real time clock (RTC) counter.

This function gets the value of the RTC and returns it to the caller.

Returns: Returns the value of the RTC counter in seconds.

References HIB_RTCC, and HWREG.

§ HibernateRTCMatchSet()

void HibernateRTCMatchSet	(	uint32_t	ui32Match,
		uint32_t	ui32Value
	)

Sets the value of the RTC match register.

Parameters

ui32Match	is the index of the match register.
ui32Value	is the value for the match register.

This function sets a match register for the RTC. The Hibernation module can be configured to wake from hibernation, and/or generate an interrupt when the value of the RTC counter is the same as the match register.

Returns: None.

References ASSERT, HIB_RTCM0, and HWREG.

§ HibernateRTCMatchGet()

uint32_t HibernateRTCMatchGet ( uint32_t ui32Match )

Gets the value of the requested RTC match register.

Parameters

ui32Match is the index of the match register.

This function gets the value of the match register for the RTC. The only value that can be used with the ui32Match parameter is zero, other values are reserved for future use.

Returns: Returns the value of the requested match register.

References ASSERT, HIB_RTCM0, and HWREG.

§ HibernateRTCSSMatchSet()

void HibernateRTCSSMatchSet	(	uint32_t	ui32Match,
		uint32_t	ui32Value
	)

Sets the value of the RTC sub second match register.

Parameters

ui32Match	is the index of the match register.
ui32Value	is the value for the sub second match register.

This function sets the sub second match register for the RTC in 1/32768 of a second increments. The Hibernation module can be configured to wake from hibernation, and/or generate an interrupt when the value of the RTC counter is the same as the match combined with the sub second match register. The only value that can be used with the ui32Match parameter is zero, other values are reserved for future use.

Returns: None.

References ASSERT, HIB_RTCSS, HIB_RTCSS_RTCSSM_S, and HWREG.

§ HibernateRTCSSMatchGet()

uint32_t HibernateRTCSSMatchGet ( uint32_t ui32Match )

Returns the value of the requested RTC sub second match register.

Parameters

ui32Match is the index of the match register.

This function returns the current value of the sub second match register for the RTC. The value returned is in 1/32768 second increments. The only value that can be used with the ui32Match parameter is zero, other values are reserved for future use.

Returns: Returns the value of the requested sub section match register.

References ASSERT, HIB_RTCSS, HIB_RTCSS_RTCSSM_S, and HWREG.

§ HibernateRTCSSGet()

uint32_t HibernateRTCSSGet ( void )

Returns the current value of the RTC sub second count.

This function returns the current value of the sub second count for the RTC in 1/32768 of a second increments. The only value that can be used with the ui32Match parameter is zero, other values are reserved for future use.

Returns: The current RTC sub second count in 1/32768 seconds.

References HIB_RTCSS, HIB_RTCSS_RTCSSC_M, and HWREG.

§ HibernateRTCTrimSet()

void HibernateRTCTrimSet ( uint32_t ui32Trim )

Sets the value of the RTC pre-divider trim register.

Parameters

ui32Trim is the new value for the pre-divider trim register.

This function sets the value of the pre-divider trim register. The input time source is divided by the pre-divider to achieve a one-second clock rate. Once every 64 seconds, the value of the pre-divider trim register is applied to the pre-divider to allow fine-tuning of the RTC rate, in order to make corrections to the rate. The software application can make adjustments to the pre-divider trim register to account for variations in the accuracy of the input time source. The nominal value is 0x7FFF, and it can be adjusted up or down in order to fine-tune the RTC rate.

Returns: None.

References ASSERT, HIB_RTCT, and HWREG.

§ HibernateRTCTrimGet()

uint32_t HibernateRTCTrimGet ( void )

Gets the value of the RTC pre-divider trim register.

This function gets the value of the pre-divider trim register. This function can be used to get the current value of the trim register prior to making an adjustment by using the HibernateRTCTrimSet() function.

Returns: None.

References HIB_RTCT, and HWREG.

§ HibernateDataSet()

void HibernateDataSet	(	uint32_t *	pui32Data,
		uint32_t	ui32Count
	)

Stores data in the battery-backed memory of the Hibernation module.

Parameters

pui32Data	points to the data that the caller wants to store in the memory of the Hibernation module.
ui32Count	is the count of 32-bit words to store.

Stores a set of data in the Hibernation module battery-backed memory. This memory is preserved when the power to the processor is turned off and can be used to store application state information that is needed when the processor wakes. Up to 16 32-bit words can be stored in the battery-backed memory. The data can be restored by calling the HibernateDataGet() function.

Returns: None.

References ASSERT, HIB_DATA, and HWREG.

§ HibernateDataGet()

void HibernateDataGet	(	uint32_t *	pui32Data,
		uint32_t	ui32Count
	)

Reads a set of data from the battery-backed memory of the Hibernation module.

Parameters

pui32Data	points to a location where the data that is read from the Hibernation module is stored.
ui32Count	is the count of 32-bit words to read.

This function retrieves a set of data from the Hibernation module battery-backed memory that was previously stored with the HibernateDataSet() function. The caller must ensure that pui32Data points to a large enough memory block to hold all the data that is read from the battery-backed memory.

Returns: None.

References ASSERT, HIB_DATA, and HWREG.

§ HibernateRequest()

void HibernateRequest ( void )

Requests hibernation mode.

This function requests the Hibernation module to disable the external regulator, thus removing power from the processor and all peripherals. The Hibernation module remains powered from the battery or auxiliary power supply.

The Hibernation module re-enables the external regulator when one of the configured wake conditions occurs (such as RTC match or external WAKE pin). When the power is restored, the processor goes through a power-on reset although the Hibernation module is not reset. The processor can retrieve saved state information with the HibernateDataGet() function. Prior to calling the function to request hibernation mode, the conditions for waking must have already been set by using the HibernateWakeSet() function.

Note that this function may return because some time may elapse before the power is actually removed, or it may not be removed at all. For this reason, the processor continues to execute instructions for some time, and the caller should be prepared for this function to return. There are various reasons why the power may not be removed. For example, if the HibernateLowBatSet() function was used to configure an abort if low battery is detected, then the power is not removed if the battery voltage is too low. There may be other reasons related to the external circuit design, that a request for hibernation may not actually occur.

For all these reasons, the caller must be prepared for this function to return. The simplest way to handle it is to just enter an infinite loop and wait for the power to be removed.

Returns: None.

References HIB_CTL, HIB_CTL_HIBREQ, and HWREG.

§ HibernateIntEnable()

void HibernateIntEnable ( uint32_t ui32IntFlags )

Enables interrupts for the Hibernation module.

Parameters

ui32IntFlags is the bit mask of the interrupts to be enabled.

This function enables the specified interrupt sources from the Hibernation module.

The ui32IntFlags parameter must be the logical OR of any combination of the following:

HIBERNATE_INT_WR_COMPLETE - write complete interrupt
HIBERNATE_INT_PIN_WAKE - wake from pin interrupt
HIBERNATE_INT_LOW_BAT - low-battery interrupt
HIBERNATE_INT_RTC_MATCH_0 - RTC match 0 interrupt
HIBERNATE_INT_VDDFAIL - supply failure interrupt.
HIBERNATE_INT_RESET_WAKE - wake from reset pin interrupt
HIBERNATE_INT_GPIO_WAKE - wake from GPIO pin or reset pin interrupt.

Returns: None.

References ASSERT, HIB_IM, HIBERNATE_INT_GPIO_WAKE, HIBERNATE_INT_LOW_BAT, HIBERNATE_INT_PIN_WAKE, HIBERNATE_INT_RESET_WAKE, HIBERNATE_INT_RTC_MATCH_0, HIBERNATE_INT_VDDFAIL, HIBERNATE_INT_WR_COMPLETE, and HWREG.

§ HibernateIntDisable()

void HibernateIntDisable ( uint32_t ui32IntFlags )

Disables interrupts for the Hibernation module.

Parameters

ui32IntFlags is the bit mask of the interrupts to be disabled.

This function disables the specified interrupt sources from the Hibernation module.

The ui32IntFlags parameter has the same definition as the ui32IntFlags parameter to the HibernateIntEnable() function.

Returns: None.

References ASSERT, HIB_IM, HIBERNATE_INT_GPIO_WAKE, HIBERNATE_INT_LOW_BAT, HIBERNATE_INT_PIN_WAKE, HIBERNATE_INT_RESET_WAKE, HIBERNATE_INT_RTC_MATCH_0, HIBERNATE_INT_VDDFAIL, HIBERNATE_INT_WR_COMPLETE, and HWREG.

§ HibernateIntRegister()

void HibernateIntRegister ( void(*)(void) pfnHandler )

Registers an interrupt handler for the Hibernation module interrupt.

Parameters

pfnHandler points to the function to be called when a hibernation interrupt occurs.

This function registers the interrupt handler in the system interrupt controller. The interrupt is enabled at the global level, but individual interrupt sources must still be enabled with a call to HibernateIntEnable().

See also: IntRegister() for important information about registering interrupt handlers.

Returns: None.

§ HibernateIntUnregister()

void HibernateIntUnregister ( void )

Unregisters an interrupt handler for the Hibernation module interrupt.

This function unregisters the interrupt handler in the system interrupt controller. The interrupt is disabled at the global level, and the interrupt handler is no longer called.

See also: IntRegister() for important information about registering interrupt handlers.

Returns: None.

§ HibernateIntStatus()

uint32_t HibernateIntStatus ( bool bMasked )

Gets the current interrupt status of the Hibernation module.

Parameters

bMasked is false to retrieve the raw interrupt status, and true to retrieve the masked interrupt status.

This function returns the interrupt status of the Hibernation module. The caller can use this function to determine the cause of a hibernation interrupt. Either the masked or raw interrupt status can be returned.

Note: A wake from reset pin also signals a wake from GPIO pin with the value returned being HIBERNATE_INT_GPIO_WAKE | HIBERNATE_INT_RESET_WAKE. Hence a wake from reset pin should take priority over wake from GPIO pin.

Returns: Returns the interrupt status as a bit field with the values as described in the HibernateIntEnable() function.

References HIB_MIS, HIB_RIS, and HWREG.

§ HibernateIntClear()

void HibernateIntClear ( uint32_t ui32IntFlags )

Clears pending interrupts from the Hibernation module.

Parameters

ui32IntFlags is the bit mask of the interrupts to be cleared.

This function clears the specified interrupt sources. This function must be called within the interrupt handler or else the handler is called again upon exit.

The ui32IntFlags parameter has the same definition as the ui32IntFlags parameter to the HibernateIntEnable() function.

Note: Because there is a write buffer in the Cortex-M processor, it may take several clock cycles before the interrupt source is actually cleared. Therefore, it is recommended that the interrupt source be cleared early in the interrupt handler (as opposed to the very last action) to avoid returning from the interrupt handler before the interrupt source is actually cleared. Failure to do so may result in the interrupt handler being immediately reentered (because the interrupt controller still sees the interrupt source asserted).

Returns: None.

References ASSERT, HIB_IC, HIBERNATE_INT_GPIO_WAKE, HIBERNATE_INT_LOW_BAT, HIBERNATE_INT_PIN_WAKE, HIBERNATE_INT_RESET_WAKE, HIBERNATE_INT_RTC_MATCH_0, HIBERNATE_INT_VDDFAIL, HIBERNATE_INT_WR_COMPLETE, and HWREG.

§ HibernateIsActive()

uint32_t HibernateIsActive ( void )

Checks to see if the Hibernation module is already powered up.

This function queries the control register to determine if the module is already active. This function can be called at a power-on reset to help determine if the reset is due to a wake from hibernation or a cold start. If the Hibernation module is already active, then it does not need to be re-enabled, and its status can be queried immediately.

The software application should also use the HibernateIntStatus() function to read the raw interrupt status to determine the cause of the wake. The HibernateDataGet() function can be used to restore state. These combinations of functions can be used by the software to determine if the processor is waking from hibernation and the appropriate action to take as a result.

Returns: Returns true if the module is already active, and false if not.

References HIB_CTL, HIB_CTL_CLK32EN, and HWREG.

§ HibernateGPIORetentionEnable()

void HibernateGPIORetentionEnable ( void )

Enables GPIO retention after wake from hibernation.

This function enables the GPIO pin state to be maintained during hibernation and remain active even when waking from hibernation. The GPIO module itself is reset upon entering hibernation and no longer controls the output pins. To maintain the current output level after waking from hibernation, the GPIO module must be reconfigured and then the HibernateGPIORetentionDisable() function must be called to return control of the GPIO pin to the GPIO module.

Returns: None.

References HIB_CTL, HIB_CTL_RETCLR, HIB_CTL_VDD3ON, and HWREG.

§ HibernateGPIORetentionDisable()

void HibernateGPIORetentionDisable ( void )

Disables GPIO retention after wake from hibernation.

This function disables the retention of the GPIO pin state during hibernation and allows the GPIO pins to be controlled by the system. If the HibernateGPIORetentionEnable() function is called before entering hibernation, this function must be called after returning from hibernation to allow the GPIO pins to be controlled by GPIO module.

Returns: None.

References HIB_CTL, HIB_CTL_RETCLR, HIB_CTL_VDD3ON, and HWREG.

§ HibernateGPIORetentionGet()

bool HibernateGPIORetentionGet ( void )

Returns the current setting for GPIO retention.

This function returns the current setting for GPIO retention in the hibernate module.

Returns: Returns true if GPIO retention is enabled and false if GPIO retention is disabled.

References HIB_CTL, HIB_CTL_RETCLR, HIB_CTL_VDD3ON, and HWREG.

§ HibernateCounterMode()

void HibernateCounterMode ( uint32_t ui32Config )

Configures the Hibernation module's internal counter mode.

Parameters

ui32Config is the configuration to use for the Hibernation module's counter.

This function configures the Hibernate module's counter mode to operate as a standard RTC counter or to operate in a calendar mode. The ui32Config parameter is used to provide the configuration for the counter and must include only one of the following values:

HIBERNATE_COUNTER_24HR specifies 24-hour calendar mode.
HIBERNATE_COUNTER_12HR specifies 12-hour AM/PM calendar mode.
HIBERNATE_COUNTER_RTC specifies RTC counter mode.

The HibernateCalendar functions can only be called when either HIBERNATE_COUNTER_24HR or HIBERNATE_COUNTER_12HR is specified.

Example: Configure hibernate counter to 24-hour calendar mode.

//!
//! //
//! // Configure the hibernate module counter to 24-hour calendar mode.
//! //
//! HibernateCounterMode(HIBERNATE_COUNTER_24HR);
//!
//!

\return None.

References HIB_CALCTL, and HWREG.

§ HibernateCalendarSet()

void HibernateCalendarSet ( struct tm * psTime )

Sets the Hibernation module's date and time in calendar mode.

Parameters

psTime is the structure that holds the information for the current date and time.

This function uses the psTime parameter to set the current date and time when the Hibernation module is in calendar mode. Regardless of whether 24-hour or 12-hour mode is in use, the psTime structure uses a 24-hour representation of the time. This function can only be called when the hibernate counter is configured in calendar mode using the HibernateCounterMode() function with one of the calendar modes.

Returns: None.

§ HibernateCalendarGet()

int HibernateCalendarGet ( struct tm * psTime )

Returns the Hibernation module's date and time in calendar mode.

Parameters

psTime is the structure that is filled with the current date and time.

This function returns the current date and time in the structure provided by the psTime parameter. Regardless of the calendar mode, the psTime parameter uses a 24-hour representation of the time. This function can only be called when the Hibernation module is configured in calendar mode using the HibernateCounterMode() function with one of the calendar modes.

The only case where this function fails and returns a non-zero value is when the function detects that the counter is passing from the last second of the day to the first second of the next day. This exception must be handled in the application by waiting at least one second before calling again to get the updated calendar information.

Returns: Returns zero if the time and date were read successfully and returns a non-zero value if the psTime structure was not updated.

References ASSERT, HIB_CAL0, HIB_CAL0_AMPM, HIB_CAL0_HR_M, HIB_CAL0_HR_S, HIB_CAL0_MIN_M, HIB_CAL0_MIN_S, HIB_CAL0_SEC_M, HIB_CAL0_SEC_S, HIB_CAL0_VALID, HIB_CAL1, HIB_CAL1_DOM_M, HIB_CAL1_DOM_S, HIB_CAL1_DOW_M, HIB_CAL1_DOW_S, HIB_CAL1_MON_M, HIB_CAL1_MON_S, HIB_CAL1_VALID, HIB_CAL1_YEAR_M, HIB_CAL1_YEAR_S, HIB_CALCTL, HIB_CALCTL_CAL24, HIB_CALCTL_CALEN, and HWREG.

§ HibernateCalendarMatchSet()

void HibernateCalendarMatchSet	(	uint32_t	ui32Index,
		struct tm *	psTime
	)

Sets the Hibernation module's date and time match value in calendar mode.

Parameters

ui32Index	indicates which match register to access.
psTime	is the structure that holds all of the information to set the current date and time match values.

This function uses the psTime parameter to set the current date and time match value in the Hibernation module's calendar. Regardless of the mode, the psTime parameter uses a 24-hour clock representation of time. This function can only be called when the Hibernation module is configured in calendar mode using the HibernateCounterMode() function. The ui32Index value is reserved for future use and should always be zero. Calendar match can be enabled for every day, every hour, every minute or every second, setting any of these fields to 0xFF causes a match for that field. For example, setting the day of month field to 0xFF results in a calendar match daily at the same time.

Returns: None.

§ HibernateCalendarMatchGet()

void HibernateCalendarMatchGet	(	uint32_t	ui32Index,
		struct tm *	psTime
	)

Returns the Hibernation module's date and time match value in calendar mode.

Parameters

ui32Index	indicates which match register to access.
psTime	is the structure to fill with the current date and time match value.

This function returns the current date and time match value in the structure provided by the psTime parameter. Regardless of the mode, the psTime parameter uses a 24-hour clock representation of time. This function can only be called when the Hibernation module is configured in calendar mode using the HibernateCounterMode() function. The ui32Index value is reserved for future use and should always be zero.

Returns: Returns zero if the time and date match value were read successfully and returns a non-zero value if the psTime structure was not updated.

References ASSERT, HIB_CAL0_AMPM, HIB_CAL0_HR_M, HIB_CAL0_HR_S, HIB_CAL0_MIN_M, HIB_CAL0_MIN_S, HIB_CAL0_SEC_M, HIB_CAL0_SEC_S, HIB_CAL1_DOM_M, HIB_CAL1_DOM_S, HIB_CALCTL, HIB_CALCTL_CAL24, HIB_CALCTL_CALEN, HIB_CALM0, HIB_CALM1, and HWREG.

§ HibernateTamperEventsConfig()

void HibernateTamperEventsConfig ( uint32_t ui32Config )

Configures the tamper feature event response.

Parameters

ui32Config specifies the configuration options for tamper events.

This function is used to configure the event response options for the tamper feature. The ui32Config parameter provides a combination of the HIBERNATE_TAMPER_EVENTS_* features to set these options. The application should choose from the following set of defines to determine what happens to the system when a tamper event occurs:

HIBERNATE_TAMPER_EVENTS_ERASE_ALL_HIB_MEM all of the Hibernation module's battery-backed RAM is cleared due to a tamper event
HIBERNATE_TAMPER_EVENTS_ERASE_HIGH_HIB_MEM the upper half of the Hibernation module's battery-backed RAM is cleared due to a tamper event
HIBERNATE_TAMPER_EVENTS_ERASE_LOW_HIB_MEM the lower half of the Hibernation module's battery-backed RAM is cleared due to a tamper event
HIBERNATE_TAMPER_EVENTS_ERASE_NO_HIB_MEM the Hibernation module's battery-backed RAM is not changed due to a tamper event
HIBERNATE_TAMPER_EVENTS_HIB_WAKE a tamper event wakes the MCU from hibernation
HIBERNATE_TAMPER_EVENTS_NO_HIB_WAKE a tamper event does not wake the MCU from hibernation

Returns: None.

References HIB_LOCK, HIB_LOCK_HIBLOCK_KEY, HIB_TPCTL, HIB_TPCTL_MEMCLR_M, and HWREG.

§ HibernateTamperEnable()

void HibernateTamperEnable ( void )

Enables the tamper feature.

This function is used to enable the tamper feature functionality. This function should only be called after the global configuration is set with a call to HibernateTamperEventsConfig() and the tamper inputs have been configured with a call to HibernateTamperIOEnable().

Returns: None.

References HIB_LOCK, HIB_LOCK_HIBLOCK_KEY, and HWREG.

§ HibernateTamperDisable()

void HibernateTamperDisable ( void )

Disables the tamper feature.

This function is used to disable the tamper feature functionality. All other configuration settings are left unmodified, allowing a call to HibernateTamperEnable() to quickly enable the tamper feature with its previous configuration.

Returns: None.

References HIB_LOCK, HIB_LOCK_HIBLOCK_KEY, and HWREG.

§ HibernateTamperIOEnable()

void HibernateTamperIOEnable	(	uint32_t	ui32Input,
		uint32_t	ui32Config
	)

Configures an input to the tamper feature.

Parameters

ui32Input	is the tamper input to configure.
ui32Config	holds the configuration options for a given input to the tamper feature.

This function is used to configure an input to the tamper feature. The ui32Input parameter specifies the tamper signal to configure and has a valid range of 0-3. The ui32Config parameter provides the set of tamper features in the HIBERNATE_TAMPER_IO_* values. The values that are valid in the ui32Config parameter are:

HIBERNATE_TAMPER_IO_MATCH_SHORT configures the trigger to match after 2 hibernation clocks
HIBERNATE_TAMPER_IO_MATCH_LONG configures the trigger to match after 3071 hibernation clocks
HIBERNATE_TAMPER_IO_WPU_ENABLED turns on an internal weak pull up
HIBERNATE_TAMPER_IO_WPU_DISABLED turns off an internal weak pull up
HIBERNATE_TAMPER_IO_TRIGGER_HIGH sets the tamper event to active high
HIBERNATE_TAMPER_IO_TRIGGER_LOW sets the tamper event to active low

Note: None of the GPIO API functions are needed to configure the tamper pins. The tamper pins configured by using this function overrides any configuration by GPIO APIs.

Returns: None.

References ASSERT, HIB_LOCK, HIB_LOCK_HIBLOCK_KEY, HIB_TPIO, HIB_TPIO_EN0, HIB_TPIO_GFLTR0, HIB_TPIO_LEV0, HIB_TPIO_PUEN0, and HWREG.

§ HibernateTamperIODisable()

void HibernateTamperIODisable ( uint32_t ui32Input )

Disables an input to the tamper feature.

Parameters

ui32Input is the tamper input to disable.

This function is used to disable an input to the tamper feature. The ui32Input parameter specifies the tamper signal to disable and has a valid range of 0-3.

Note: None of the GPIO API functions are needed to configure the tamper pins. The tamper pins configured by using this function overrides any configuration by GPIO APIs.

Returns: None.

References ASSERT, HIB_LOCK, HIB_LOCK_HIBLOCK_KEY, and HWREG.

§ HibernateTamperEventsClear()

void HibernateTamperEventsClear ( void )

Clears the tamper feature events.

This function is used to clear all tamper events. This function always clears the tamper feature event state indicator along with all tamper log entries. Logged event data should be retrieved with HibernateTamperEventsGet() prior to requesting a event clear.

HibernateTamperEventsClear() should be called prior to clearing the system control NMI that resulted from the tamper event.

Returns: None.

References HIB_LOCK, HIB_LOCK_HIBLOCK_KEY, and HWREG.

§ HibernateTamperEventsClearNoLock()

void HibernateTamperEventsClearNoLock ( void )

Clears the tamper feature events without Unlock and Lock.

This function is used to clear all tamper events without unlock/locking the tamper control registers, so API HibernateTamperUnLock() should be called before this function, and API HibernateTamperLock() should be called after to ensure that tamper control registers are locked.

This function doesn't block until the write is complete. Therefore, care must be taken to ensure the next immediate write will occure only after the write complete bit is set.

This function is used to implement a software workaround in NMI interrupt handler to fix an issue when a new tamper event could be missed during the clear of current tamper event.

Returns: None.

§ HibernateTamperUnLock()

void HibernateTamperUnLock ( void )

Unlock temper registers.

This function is used to unlock the temper control registers. This function should be only used before calling API HibernateTamperEventsClearNoLock().

Returns: None.

References HIB_LOCK, HIB_LOCK_HIBLOCK_KEY, and HWREG.

§ HibernateTamperLock()

void HibernateTamperLock ( void )

Lock temper registers.

This function is used to lock the temper control registers. This function should be used after calling API HibernateTamperEventsClearNoLock().

Returns: None.

§ HibernateTamperStatusGet()

uint32_t HibernateTamperStatusGet ( void )

Returns the current tamper feature status.

This function is used to return the tamper feature status. This function returns one of the values from this group of options:

HIBERNATE_TAMPER_STATUS_INACTIVE indicates tamper detection is disabled
HIBERNATE_TAMPER_STATUS_ACTIVE indicates tamper detection is enabled and ready
HIBERNATE_TAMPER_STATUS_EVENT indicates tamper event was detected

In addition, one of the values is included from this group:

HIBERNATE_TAMPER_STATUS_EXT_OSC_INACTIVE indicates the external oscillator is not active
HIBERNATE_TAMPER_STATUS_EXT_OSC_ACTIVE indicates the external oscillator is active

And one of the values is included from this group:

HIBERNATE_TAMPER_STATUS_EXT_OSC_FAILED indicates the external oscillator signal has transitioned from valid to invalid
HIBERNATE_TAMPER_STATUS_EXT_OSC_VALID indicates the external oscillator is providing a valid signal

Returns: Returns a combination of the HIBERNATE_TAMPER_STATUS_* values.

References HIB_TPSTAT, HIB_TPSTAT_STATE_M, HIB_TPSTAT_XOSCFAIL, HIB_TPSTAT_XOSCST, HIBERNATE_TAMPER_STATUS_EXT_OSC_ACTIVE, HIBERNATE_TAMPER_STATUS_EXT_OSC_VALID, HIBERNATE_TAMPER_STATUS_INACTIVE, and HWREG.

Referenced by HibernateTamperExtOscValid().

§ HibernateTamperEventsGet()

bool HibernateTamperEventsGet	(	uint32_t	ui32Index,
		uint32_t *	pui32RTC,
		uint32_t *	pui32Event
	)

Returns a tamper log entry.

Parameters

ui32Index	is the index of the log entry to return.
pui32RTC	is a pointer to the memory to store the logged RTC data.
pui32Event	is a pointer to the memory to store the logged tamper event.

This function is used to return a tamper log entry from the hibernate feature. The ui32Index specifies the zero-based index of the log entry to query and has a valid range of 0-3.

When this function returns, the pui32RTC value contains the time value and pui32Event parameter contains the tamper I/O event that triggered this log.

The format of the returned pui32RTC data is dependent on the configuration of the RTC within the Hibernation module. If the RTC is configured for counter mode, the returned data contains counted seconds from the RTC enable. If the RTC is configured for calendar mode, the data returned is formatted as follows:

//! +----------------------------------------------------------------------+
//! |  31:26  |  25:22  |     21:17      |  16:12  |   11:6    |    5:0    |
//! +----------------------------------------------------------------------+
//! |  year   |  month  |  day of month  |  hours  |  minutes  |  seconds  |
//! +----------------------------------------------------------------------+
//!

The data returned in the \e pui32Events parameter could include any of the
following flags:

- \b HIBERNATE_TAMPER_EVENT_0 indicates a tamper event was triggered on I/O
signal 0
- \b HIBERNATE_TAMPER_EVENT_1 indicates a tamper event was triggered on I/O
signal 1
- \b HIBERNATE_TAMPER_EVENT_2 indicates a tamper event was triggered on I/O
signal 2
- \b HIBERNATE_TAMPER_EVENT_3 indicates a tamper event was triggered on I/O
signal 3
- \b HIBERNATE_TAMPER_EVENT_XOSC indicates an external oscillator failure
triggered the tamper event

\note Tamper event logs are not consumed when read and remain available
until cleared.  Events are only logged if unused log space is available.

\return Returns \b true if the \e pui32RTC and \e pui32Events were updated
successfully and returns \b false if the values were not updated.

References ASSERT, HIB_CAL0, HIB_CAL0_AMPM, HIB_CALCTL, HIB_CALCTL_CAL24, HIB_CALCTL_CALEN, HIB_TPLOG0, and HWREG.

§ HibernateTamperExtOscRecover()

void HibernateTamperExtOscRecover ( void )

Attempts to recover the external oscillator.

This function is used to attempt to recover the external oscillator after a HIBERNATE_TAMPER_STATUS_EXT_OSC_FAILED status is reported. This function must not be called if the external oscillator is not used as the hibernation clock input. HibernateTamperExtOscValid() should be called before calling this function.

Returns: None.

References HIB_LOCK, HIB_LOCK_HIBLOCK_KEY, and HWREG.

§ HibernateTamperExtOscValid()

bool HibernateTamperExtOscValid ( void )

Reports if the external oscillator signal is active and stable.

This function should be used to verify the external oscillator is active and valid before attempting to recover from a HIBERNATE_TAMPER_STATUS_EXT_OSC_FAILED status by calling HibernateTamperExtOscRecover().

Returns: Returns true if the external oscillator is both active and stable, otherwise a false indicator is returned.

References HIBERNATE_TAMPER_STATUS_EXT_OSC_ACTIVE, HIBERNATE_TAMPER_STATUS_EXT_OSC_VALID, and HibernateTamperStatusGet().

Macros

Functions

Detailed Description

Macro Definition Documentation

§ DELAY_USECS

§ LOOP_CYCLES

Function Documentation

§ HibernateEnableExpClk()

§ HibernateDisable()

§ HibernateClockConfig()

§ HibernateRTCEnable()

§ HibernateRTCDisable()

§ HibernateBatCheckStart()

§ HibernateBatCheckDone()

§ HibernateWakeSet()

§ HibernateWakeGet()

§ HibernateLowBatSet()

§ HibernateLowBatGet()

§ HibernateRTCSet()

§ HibernateRTCGet()

§ HibernateRTCMatchSet()

§ HibernateRTCMatchGet()

§ HibernateRTCSSMatchSet()

§ HibernateRTCSSMatchGet()

§ HibernateRTCSSGet()

§ HibernateRTCTrimSet()

§ HibernateRTCTrimGet()

§ HibernateDataSet()

§ HibernateDataGet()

§ HibernateRequest()

§ HibernateIntEnable()

§ HibernateIntDisable()

§ HibernateIntRegister()

§ HibernateIntUnregister()

§ HibernateIntStatus()

§ HibernateIntClear()

§ HibernateIsActive()

§ HibernateGPIORetentionEnable()

§ HibernateGPIORetentionDisable()

§ HibernateGPIORetentionGet()

§ HibernateCounterMode()

§ HibernateCalendarSet()

§ HibernateCalendarGet()

§ HibernateCalendarMatchSet()

§ HibernateCalendarMatchGet()

§ HibernateTamperEventsConfig()

§ HibernateTamperEnable()

§ HibernateTamperDisable()

§ HibernateTamperIOEnable()

§ HibernateTamperIODisable()

§ HibernateTamperEventsClear()

§ HibernateTamperEventsClearNoLock()

§ HibernateTamperUnLock()

§ HibernateTamperLock()

§ HibernateTamperStatusGet()

§ HibernateTamperEventsGet()

§ HibernateTamperExtOscRecover()

§ HibernateTamperExtOscValid()