hibernate.c

uCOS-II V2.84 LM3S6965 TCPIP Demo

//! Sets the value of the RTC match 1 register.
//!
//! \param ulMatch is the value for the match register.
//!
//! Sets the match 1 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.
//!
//! \return None.
//
//*****************************************************************************
void
HibernateRTCMatch1Set(unsigned long ulMatch)
{
    //
    // Write the new match value to the match register.
    //
    HWREG(HIB_RTCM1) = ulMatch;

    //
    // Add a delay here to enforce the required delay between write
    // accesses to certain hibernation module registers.
    //
    HibernateWriteDelay(ulWriteDelay);
}

//*****************************************************************************
//
//! Gets the value of the RTC match 1 register.
//!
//! Gets the value of the match 1 register for the RTC.
//!
//! \return the value of the match register.
//
//*****************************************************************************
unsigned long
HibernateRTCMatch1Get(void)
{
    //
    // Return the value of the match register to the caller.
    //
    return(HWREG(HIB_RTCM1));
}

//*****************************************************************************
//
//! Sets the value of the RTC predivider trim register.
//!
//! \param ulTrim is the new value for the pre-divider trim register.
//!
//! Sets the value of the pre-divider trim register.  The input time source
//! is divided by the value in this register to achieve a once per second
//! count rate for the RTC counter.  The software application can make
//! adjustments to the predivider 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.
//!
//! \return None.
//
//*****************************************************************************
void
HibernateRTCTrimSet(unsigned long ulTrim)
{
    //
    // Check the arguments.
    //
    ASSERT(ulTrim < 0x10000);

    //
    // Write the new trim value to the trim register.
    //
    HWREG(HIB_RTCT) = ulTrim;

    //
    // Add a delay here to enforce the required delay between write
    // accesses to certain hibernation module registers.
    //
    HibernateWriteDelay(ulWriteDelay);
}

//*****************************************************************************
//
//! Gets the value of the RTC predivider trim register.
//!
//! 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.
//!
//! \return None.
//
//*****************************************************************************
unsigned long
HibernateRTCTrimGet(void)
{
    //
    // Return the value of the trim register to the caller.
    //
    return(HWREG(HIB_RTCT));
}

//*****************************************************************************
//
//! Stores data in the non-volatile memory of the hibernation module.
//!
//! \param pulData points to the data that the caller wants to store
//! in the memory of the hibernation module.
//! \param ulCount is the count of 32 bit words to store.
//!
//! Stores a set of data in the hibernation module non-volatile memory.
//! This memory will be preserved when the power to the processor is turned
//! off, and can be used to store application state information which will
//! be available when the processor wakes.  Up to 64 32-bit words can be
//! stored in the non-volatile memory.  The data can be restored by
//! calling the HibernateDataGet() function.
//!
//! \return None.
//
//*****************************************************************************
void
HibernateDataSet(unsigned long *pulData, unsigned long ulCount)
{
    unsigned int uIdx;

    //
    // Check the arguments.
    //
    ASSERT(ulCount <= 64);
    ASSERT(pulData != 0);

    //
    // Loop through all the words to be stored, storing one at a time.
    //
    for(uIdx = 0; uIdx < ulCount; uIdx++)
    {
        //
        // Write a word to the non-volatile storage area.
        //
        HWREG(HIB_DATA + (uIdx * 4)) = pulData[uIdx];

        //
        // Add a delay between writes to the data area.
        //
        HibernateWriteDelay(ulWriteDelay);
    }
}

//*****************************************************************************
//
//! Reads a set of data from the non-volatile memory of the hibernation module.
//!
//! \param pulData points to a location where the data that is read from the
//! hibernation module will be stored.
//! \param ulCount is the count of 32 bit words to read.
//!
//! Retrieves a set of data from the hibernation module non-volatile memory
//! that was previously stored with the HibernateDataSet() function.  The
//! caller must ensure that \e pulData points to a large enough memory block
//! to hold all the data that is read from the non-volatile memory.
//!
//! \return None.
//
//*****************************************************************************
void
HibernateDataGet(unsigned long *pulData, unsigned long ulCount)
{
    unsigned int uIdx;

    //
    // Check the arguments.
    //
    ASSERT(ulCount <= 64);
    ASSERT(pulData != 0);

    //
    // Loop through all the words to be restored, reading one at a time.
    //
    for(uIdx = 0; uIdx < ulCount; uIdx++)
    {
        //
        // Read a word from the non-volatile storage area.
        // No delay is required between reads.
        //
        pulData[uIdx] = HWREG(HIB_DATA + (uIdx * 4));
    }
}

//*****************************************************************************
//
//! 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 will remain powered from the battery or auxiliary
//! power supply.
//!
//! The hibernation module will re-enable 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 will go through a
//! normal power-on 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 will continue 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
//! HibernationLowBatSet() function was used to configure an abort if low
//! battery is detected, then the power will not be removed if the battery
//! voltage is too low.  There may be other reasons, related to the external
//! circuit design, why 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.
//!
//! \return None.
//
//*****************************************************************************
void
HibernateRequest(void)
{
    //
    // Set the bit in the control register to cut main power to the processor.
    //
    HWREG(HIB_CTL) |= HIB_CTL_HIBREQ;
}

//*****************************************************************************
//
//! Enables interrupts for the Hibernation module.
//!
//! \param ulIntFlags is the bit mask of the interrupts to be enabled.
//!
//! Enables the specified interrupt sources from the hibernation module.
//!
//! The parameter \e ulIntFlags must be the logical OR of any combination of
//! the following:
//!
//! - 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_RTC_MATCH_1 - RTC match 1 interrupt
//!
//! \return None.
//
//*****************************************************************************
void
HibernateIntEnable(unsigned long ulIntFlags)
{
    //
    // Check the arguments.
    //
    ASSERT(!(ulIntFlags & ~(HIBERNATE_INT_PIN_WAKE | HIBERNATE_INT_LOW_BAT |
                            HIBERNATE_INT_RTC_MATCH_0 |
                            HIBERNATE_INT_RTC_MATCH_1)));

    //
    // Set the specified interrupt mask bits.
    //
    HWREG(HIB_IM) |= ulIntFlags;
}

//*****************************************************************************
//
//! Disables interrupts for the Hibernation module.
//!
//! \param ulIntFlags is the bit mask of the interrupts to be disabled.
//!
//! Disables the specified interrupt sources from the hibernation module.
//!
//! The parameter \e ulIntFlags has the same definition as in the
//! HibernateIntEnable() function.
//!
//! \return None.
//
//*****************************************************************************
void
HibernateIntDisable(unsigned long ulIntFlags)
{
    //
    // Check the arguments.
    //
    ASSERT(!(ulIntFlags & ~(HIBERNATE_INT_PIN_WAKE | HIBERNATE_INT_LOW_BAT |
                            HIBERNATE_INT_RTC_MATCH_0 |
                            HIBERNATE_INT_RTC_MATCH_1)));

    //
    // Clear the specified interrupt mask bits.
    //
    HWREG(HIB_IM) &= ~ulIntFlags;
}

//*****************************************************************************
//
//! Registers an interrupt handler for the hibernation module interrupt.
//!
//! \param pfnHandler points to the function to be called when a
//! hibernation interrupt occurs.
//!
//! 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().
//! This function will call IntRegister() to register the handler.
//!
//! \return None.
//
//*****************************************************************************
void
HibernateIntRegister(void (*pfnHandler)(void))
{
    //
    // Register the interrupt handler.
    //
    IntRegister(INT_HIBERNATE, pfnHandler);

    //
    // Enable the hibernate module interrupt.
    //
    IntEnable(INT_HIBERNATE);
}

//*****************************************************************************
//
//! Unregisters an interrupt handler for the hibernation module interrupt.
//!
//! Unregisters the interrupt handler in the system interrupt controller.
//! The interrupt is disabled at the global level, and the interrupt
//! handler will no longer be called.
//!
//! \return None.
//
//*****************************************************************************
void
HibernateIntUnregister(void)
{
    //
    // Disable the hibernate interrupt.
    //
    IntDisable(INT_HIBERNATE);

    //
    // Unregister the interrupt handler.
    //
    IntUnregister(INT_HIBERNATE);
}

//*****************************************************************************
//
//! Gets the current interrupt status of the Hibernation module.
//!
//! \param bMasked is false to retrieve the raw interrupt status, and true
//! to retrieve the masked interrupt status.
//!
//! Returns the interrupt status of the hibernation module.  The caller
//! can use this to determine the cause of a hibernation interrupt.  Either
//! the masked or raw interrupt status can be returned.
//!
//! \return the interrupt status as a bit field with the values as
//!         described in the HibernateIntEnable() function.
//
//*****************************************************************************
unsigned long
HibernateIntStatus(tBoolean bMasked)
{
    //
    // Read and return the hibernation module raw or masked interrupt
    // status.
    //
    if(bMasked == true)
    {
        return(HWREG(HIB_MIS) & 0xf);
    }
    else
    {
        return(HWREG(HIB_RIS) & 0xf);
    }
}

//*****************************************************************************
//
//! Clears pending interrupts from the Hibernation module.
//!
//! \param ulIntFlags is the bit mask of the interrupts to be cleared.
//!
//! Clears the specified interrupt sources.  This must be done from within
//! the interrupt handler or else the handler will be called again upon exit.
//!
//! The parameter \e ulIntFlags has the same definition as in the
//! HibernateIntEnable() function.
//!
//! \return None.
//
//*****************************************************************************
void
HibernateIntClear(unsigned long ulIntFlags)
{
    //
    // Check the arguments.
    //
    ASSERT(!(ulIntFlags & ~(HIBERNATE_INT_PIN_WAKE | HIBERNATE_INT_LOW_BAT |
                            HIBERNATE_INT_RTC_MATCH_0 |
                            HIBERNATE_INT_RTC_MATCH_1)));

    //
    // Write the specified interrupt bits into the interrupt clear register.
    //
    HWREG(HIB_IC) |= ulIntFlags;
}

//*****************************************************************************
//
//! 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 it's 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.
//!
//! \return True if the module is already active, false if not.
//
//*****************************************************************************
unsigned int
HibernateIsActive(void)
{
    //
    // Read the control register, and return true if the module is enabled.
    //
    return(HWREG(HIB_CTL) & HIB_CTL_CLK32EN ? 1 : 0);
}

//*****************************************************************************
//
// Close the Doxygen group.
//! @}
//
//*****************************************************************************