14ccffd9d4
Some arguments passed to the functions disabled with LPM_CONF_ENABLE == 0 could trigger build warnings because they became unused with this configuration option. Disable these functions by using empty static inline functions instead of empty macros, so that the function arguments are always considered by the compiler as used, without having to #if-out code in many places. Signed-off-by: Benoît Thébaudeau <benoit.thebaudeau.dev@gmail.com>
231 lines
8.6 KiB
C
231 lines
8.6 KiB
C
/*
|
|
* Copyright (c) 2013, Texas Instruments Incorporated - http://www.ti.com/
|
|
* All rights reserved.
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions
|
|
* are met:
|
|
* 1. Redistributions of source code must retain the above copyright
|
|
* notice, this list of conditions and the following disclaimer.
|
|
* 2. Redistributions in binary form must reproduce the above copyright
|
|
* notice, this list of conditions and the following disclaimer in the
|
|
* documentation and/or other materials provided with the distribution.
|
|
*
|
|
* 3. Neither the name of the copyright holder nor the names of its
|
|
* contributors may be used to endorse or promote products derived
|
|
* from this software without specific prior written permission.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
|
|
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
|
|
* COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
|
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
|
|
* OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
*/
|
|
/**
|
|
* \addtogroup cc2538
|
|
* @{
|
|
*
|
|
* \defgroup cc2538-lpm cc2538 Low Power Modes
|
|
*
|
|
* Driver for the cc2538 power modes
|
|
* @{
|
|
*
|
|
* \file
|
|
* Header file with register, macro and function declarations for the cc2538
|
|
* low power module
|
|
*/
|
|
#ifndef LPM_H_
|
|
#define LPM_H_
|
|
|
|
#include "contiki-conf.h"
|
|
#include "rtimer.h"
|
|
|
|
#include <stdbool.h>
|
|
#include <stdint.h>
|
|
/*---------------------------------------------------------------------------*/
|
|
/**
|
|
* \name LPM stats
|
|
*
|
|
* Maintains a record of how many rtimer ticks spent in each Power Mode.
|
|
* Mainly used for debugging the module
|
|
* @{
|
|
*/
|
|
#if LPM_CONF_STATS
|
|
extern rtimer_clock_t lpm_stats[3];
|
|
|
|
/**
|
|
* \brief Read the time spent in a PM in rtimer ticks
|
|
* \param pm The pm as a value in [0,2]
|
|
*/
|
|
#define LPM_STATS_GET(pm) lpm_stats[pm]
|
|
#else
|
|
#define LPM_STATS_GET(pm)
|
|
#endif
|
|
/** @} */
|
|
/*---------------------------------------------------------------------------*/
|
|
/**
|
|
* \name Constants to be used as arguments to lpm_set_max_pm()
|
|
* @{
|
|
*/
|
|
#define LPM_PM0 0
|
|
#define LPM_PM1 1
|
|
#define LPM_PM2 2
|
|
/** @} */
|
|
/*---------------------------------------------------------------------------*/
|
|
typedef bool (*lpm_periph_permit_pm1_func_t)(void);
|
|
|
|
#if LPM_CONF_ENABLE
|
|
/**
|
|
* \brief Initialise the LPM module
|
|
*/
|
|
void lpm_init(void);
|
|
|
|
/**
|
|
* \brief Drop to Deep Sleep
|
|
*
|
|
* This function triggers a sequence to enter Deep Sleep. The sequence involves
|
|
* determining the most suitable PM and switching the system clock source to
|
|
* the 16MHz if required. If the energest module is enabled, the sequence also
|
|
* performs some simple energest calculations.
|
|
*
|
|
* Broadly speaking, this function will be called from the main loop when all
|
|
* events have been serviced. This functions aims to be clever enough in order
|
|
* to be able to choose between PMs 0/1/2 depending on chip status and
|
|
* anticipated sleep duration. This choice is made subject to configuration
|
|
* restrictions and subject to restrictions imposed by calls to
|
|
* lpm_set_max_pm().
|
|
*
|
|
* This PM selection heuristic has the following primary criteria:
|
|
* - Is the RF off?
|
|
* - Are all registered peripherals permitting PM1+?
|
|
* - Is the Sleep Timer scheduled to fire an interrupt?
|
|
*
|
|
* If the answer to any of those questions is no, we will drop to PM0 and
|
|
* will wake up to any interrupt. Best case scenario (if nothing else happens),
|
|
* we will idle until the next SysTick in no more than 1000/CLOCK_SECOND ms
|
|
* (7.8125ms).
|
|
*
|
|
* If all can be answered with 'yes', we can drop to PM1/2 knowing that the
|
|
* Sleep Timer will wake us up. Depending on the estimated deep sleep duration
|
|
* and the max PM allowed by user configuration, we select the most efficient
|
|
* Power Mode to drop to. If the duration is too short, we simply IDLE in PM0.
|
|
*
|
|
* Dropping to PM1/2 requires a switch to the 16MHz OSC. We have the option of
|
|
* letting the SoC do this for us automatically. However, if an interrupt fires
|
|
* during this automatic switch, we will need to re-assert WFI. To avoid this
|
|
* complexity, we perform the switch to the 16MHz OSC manually in software and
|
|
* we assert WFI after the transition has been completed. This gives us a
|
|
* chance to bail out if an interrupt fires or an event is raised during the
|
|
* transition. If nothing happens, dropping to PM1+ is un-interruptible and
|
|
* with a deterministic duration. When we wake up, we switch back to the 32MHz
|
|
* OSC manually before handing control back to main. This is implemented in
|
|
* lpm_exit(), which will always be called from within the Sleep Timer ISR
|
|
* context.
|
|
*
|
|
* \note Dropping to PM2 means that data in the SRAM non-retention area will
|
|
* be lost. It is recommended to disable PM2 if the total RAM footprint is
|
|
* larger than what will fit in the retention area.
|
|
* .nrdata* sections can be used to place uninitialized data in the SRAM
|
|
* non-retention area.
|
|
*
|
|
* \sa main(), rtimer_arch_next_trigger(), lpm_exit(), lpm_set_max_pm()
|
|
*/
|
|
void lpm_enter(void);
|
|
|
|
/**
|
|
* \brief Perform an 'Exit Deep Sleep' sequence
|
|
*
|
|
* This routine is called from within the context of the ISR that caused us to
|
|
* come out of PM1/2. It performs a wake up sequence to make sure the 32MHz OSC
|
|
* is back on and the system clock is sourced on it.
|
|
*
|
|
* While in PMs 1 and 2, the system clock stops ticking. This functions adjusts
|
|
* it when we wake up.
|
|
*
|
|
* We always exit PM1/2 as a result of a scheduled rtimer task or a GPIO
|
|
* interrupt. This may lead to other parts of the code trying to use the RF,
|
|
* so we need to switch the clock source \e before said code gets executed.
|
|
*
|
|
* This function also makes sure that the sleep timer value is up-to-date
|
|
* following wake-up from PM1/2 so that RTIMER_NOW() works.
|
|
*
|
|
* \note This function should be called at the very beginning of ISRs waking up
|
|
* the SoC in order to restore all clocks and timers.
|
|
*
|
|
* \sa lpm_enter(), rtimer_isr()
|
|
*/
|
|
void lpm_exit(void);
|
|
|
|
/**
|
|
* \brief Prevent the SoC from dropping to a PM higher than \e max_pm
|
|
* \param pm The highest PM we are allowed to enter, specified as a
|
|
* number in [0, 2]
|
|
*
|
|
* Defines for the \e pm argument are LPM_PMx.
|
|
*
|
|
* This function can be used by software in situations where some power
|
|
* modes are undesirable. If, for example, an application needs to avoid PM2,
|
|
* it would call lpm_set_max_pm(LPM_PM1).
|
|
* If an application wants to avoid PM1 as well, it would call
|
|
* lpm_set_max_pm(LPM_PM0)
|
|
*
|
|
* PM0 can not be disabled at runtime. Use LPM_CONF_ENABLE to disable LPM
|
|
* support altogether
|
|
*
|
|
* \note If the value of argument \e pm is greater than the value of the
|
|
* LPM_CONF_MAX_PM configuration directive, LPM_CONF_MAX_PM is used. Thus
|
|
* if LPM_CONF_MAX_PM==1, calling lpm_set_max_pm(LPM_PM2) would
|
|
* result in a maximum PM set to 1 and all subsequent Deep Sleeps would
|
|
* be limited to either PM0 or PM1.
|
|
*
|
|
* \sa lpm_enter()
|
|
*/
|
|
void lpm_set_max_pm(uint8_t pm);
|
|
|
|
/**
|
|
* \brief Register a peripheral function which will get called by the LPM
|
|
* module to get 'permission' to drop to PM1+
|
|
* \param permit_pm1_func Pointer to the function
|
|
*
|
|
* Some peripherals are sensitive to PM changes. For instance, we don't want to
|
|
* drop to PM1+ if the USB PLL is active or if the UART TX FIFO is not clear.
|
|
*
|
|
* When changing power modes, the LPM driver will call all FPs registered with
|
|
* this function. The peripheral's function will return true or false to permit
|
|
* / prohibit PM1+ respectively. If at least one peripheral returns false, the
|
|
* SoC will drop to PM0 Deep Sleep instead.
|
|
*
|
|
* Registering several times the same function makes the LPM module behave as if
|
|
* the function had been registered once.
|
|
*/
|
|
void lpm_register_peripheral(lpm_periph_permit_pm1_func_t permit_pm1_func);
|
|
/*---------------------------------------------------------------------------*/
|
|
/* Disable the entire module if required */
|
|
#else
|
|
#define lpm_init()
|
|
#define lpm_enter()
|
|
#define lpm_exit()
|
|
static inline void
|
|
lpm_set_max_pm(uint8_t pm)
|
|
{
|
|
}
|
|
static inline void
|
|
lpm_register_peripheral(lpm_periph_permit_pm1_func_t permit_pm1_func)
|
|
{
|
|
}
|
|
#endif
|
|
|
|
#endif /* LPM_H_ */
|
|
|
|
/**
|
|
* @}
|
|
* @}
|
|
*/
|