pm.h

Go to the documentation of this file.

#ifndef EVE_PM_H_INCLUDED
#define EVE_PM_H_INCLUDED
/**********************************************************************/
/*
 * Copyright (c) 2013-2015, Jetro AS
 * 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. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONRIBUTORS ``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 AUTHOR 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.
 *
 * This file is part of the EVE platform.
 */

 /**
 * \file
 * \brief Header file for the EVE power management framework.
 *
 * \author DT, Jetro AS
 */ /******************************************************************/

/* #define DEBUG_PM */

#include <stdbool.h>
#ifdef DEBUG_PM
#include <lib/dlist.h>
#endif

/**
 * \addtogroup pm
 * @{
 * EVE power management framework
 */

/**********************************************************************/
/**
 * System power level.
 */
enum pm_level_t
{
  PM_LEVEL_RUNNING,                     /**< System is kept spinning when idle. Høyest power consumption. */
  PM_LEVEL_CONSTLAT,                    /**< System ON, Constant latency mode. */
  PM_LEVEL_LOWPWR,                      /**< System ON, Low power mode. */
  PM_LEVEL_CLOCKLESS,                   /**< System ON, Low power mode, 32 kHz clock off. */
  PM_LEVEL_OFF,                         /**< System OFF. */
  PM_LEVEL__COUNT,                      /**< Number of elements in the \ref pm_level_t enum. */
};

/**********************************************************************/
/**
 * System power lock structure.
 *
 * The power lock structure represents a request for a power level the system
 * should be kept on while CPU is in idle.
 *
 * The structure must be instantiated in the RAM memory using
 * one of \ref PM_LOCK_INIT() or \ref DECLARE_PM_LOCK().
 * Note that the power request is not active unless \ref PM_LOCK() is called for it.
 */
struct pm_lock_t
{
#ifdef DEBUG_PM
  struct dlist_t link;                  /**< Linked list of all locked requests at all lock levels. */
  const char *file;                     /**< Debug field: file name the lock was touched last time in. */
  int line;                             /**< Debug field: line number the lock was touched last time at. */
#endif
  struct pm_lock_t *next;               /**< Linked list of the unlocked requests waiting for suspend. */
  bool (*ready_cb)(uint32_t data);      /**< Ready callback. \see PM_UNLOCK(), \see pm_relax() for details. */
  uint32_t data;                        /**< User data for the ready callback */
  uint8_t level;                        /**< \ref pm_level_t, the given power level */
  uint8_t locked;                       /**< Lock counter for the lock request */
};

/**********************************************************************/
/** \def PM_LOCK_INIT(l, pm, cb, d)
 * Initializes a power lock structure.
 *
 * The macro is used to initialize a power lock structure instance.
 *
 * \param l power level
 * \param pm power lock structure
 * \param cb user callback to be called before the system goes suspend
 * \param d data for the user callback
 *
 * Usage:
 * \code
  struct pm_lock_t MyConstLatPowerLock = PM_LOCK_INIT(PM_LEVEL_CONSTLAT, MyConstLatPowerLock, NULL, 0);
 * \endcode
 */

/**********************************************************************/
/** \def DECLARE_PM_LOCK(l, pm, cb, d)
 * Declares a power lock structure instance
 *
 * \param l power level
 * \param pm power lock structure
 * \param cb user callback to be called before the system goes suspend
 * \param d data for the user callback
 *
 * Usage:
 * \code
  DECLARE_PM_LOCK(PM_LEVEL_CONSTLAT, MyConstLatPowerLock, NULL, 0);
  // The above line is an equivalint of
  struct pm_lock_t MyConstLatPowerLock = PM_LOCK_INIT(PM_LEVEL_CONSTLAT, MyConstLatPowerLock, NULL, 0);
 * \endcode
 */

/**********************************************************************/
/** \def PM_LOCK(pm)
 * Request the power level
 *
 * The macro is used to request power at the given power level.
 *
 * \param pm power lock structure
 *
 * Usage:
 * \code
  PM_LOCK(MyConstLatPowerLock);
 * \endcode
 */

/**********************************************************************/
/** \def PM_UNLOCK(pm)
 * Release the power
 *
 * The macro is used to release previously taken power request at the given power level.
 *
 * If the power lock structure provides a user-defined callback, the PM_UNLOCK() puts
 * the structure into a linked list of unlocked requests, waiting for suspend.
 * During the following suspend (\ref pm_relax()), the list is traversed and the callbacks
 * are called by the framework. The callbacks can prevent system from suspend by returning
 * `false`.
 *
 * \param pm power lock structure
 *
 * Usage:
 * \code
  PM_UNLOCK(MyConstLatPowerLock);
 * \endcode
 */

/**********************************************************************/
/** \def PM_AUTO_LOCK(l)
 * Declares an anonymous auto lock, which holds power request in the auto variable visibility block
 *
 * \param l power level
 *
 * Usage:
 * \code
  {
    PM_AUTO_LOCK(PM_LEVEL_CONSTLAT);
    clock_delay(MS_TO_TICKS(10)); // The delay will be executed at at least CONSTLAT level.
  }
  // The lock is released here
 * \endcode
 */

#ifdef DEBUG_PM
  #define PM_LOCK_INIT(l, pm, cb, d)    \
    {                                   \
      .link = DLIST_INIT(pm.link),      \
      .file = __FILE__,                 \
      .line = __LINE__,                 \
      .next = NULL,                     \
      .level = l,                       \
      .ready_cb = cb,                   \
      .data = d,                        \
      .locked = 0,                      \
    }
  #define PM_LOCK(pm) pm_lock_dbg(&pm, __FILE__, __LINE__)
  #define PM_UNLOCK(pm) pm_unlock_dbg(&pm, __FILE__, __LINE__)
  #define PM_AUTO_LOCK(l)              \
      inline void pm_unlock_dbg_adapter(struct pm_lock_t *pm) { pm_unlock_dbg(pm, __FILE__, __LINE__); } \
      struct pm_lock_t EvePmAutoLock __attribute__((cleanup(pm_unlock_dbg_adapter))); \
      do { EvePmAutoLock = (struct pm_lock_t) PM_LOCK_INIT(l, EvePmAutoLock, NULL, 0); } while (0)
#else
  #define PM_LOCK_INIT(l, pm, cb, d)    \
    {                                   \
      .next = NULL,                     \
      .level = l,                       \
      .ready_cb = cb,                   \
      .data = d,                        \
      .locked = 0,                      \
    }
  #define PM_LOCK(pm) pm_lock(&pm)
  #define PM_UNLOCK(pm) pm_unlock(&pm)
  #define PM_AUTO_LOCK(l)              \
      struct pm_lock_t EvePmAutoLock __attribute__((cleanup(pm_unlock))); \
      do { EvePmAutoLock = (struct pm_lock_t) PM_LOCK_INIT(l, EvePmAutoLock, NULL, 0); } while (0)
#endif

#define DECLARE_PM_LOCK(l, pm, cb, d) \
  static struct pm_lock_t pm = PM_LOCK_INIT(l, pm, cb, d)

/**********************************************************************/
/**
 * Enters the lowest power level.
 *
 * Before entring low-power mode, pm_relax() traverses via the list of
 * lock structures, registered by PM_UNLOCK(), and calls user-defined callbacks.
 * If a callback returns `false`, then the ongoing suspend is cancelled.
 *
 * While interrupt handling is performed, pm_relax() does not return to the
 * operating system until a wakeup is requested by pm_wakeup() call.
 */
void pm_relax(void);

/**********************************************************************/
/**
 * Wakeups the system from suspend state.
 *
 * Interrupt handlers must call this function if they want to wake up
 * operating system from suspend state.
 */
void pm_wakeup(void);

/**********************************************************************/
/**
 * \internal
 *
 */ /******************************************************************/

/**********************************************************************/
/**
 * Restrict deepness of suspend to the given power level
 *
 * \param pm pointer to the power lock structure
 */
void pm_lock(struct pm_lock_t *pm);

/**********************************************************************/
/**
 * Release a previously taken power lock
 *
 * \param pm pointer to the power lock structure
 */
void pm_unlock(struct pm_lock_t *pm);

/**********************************************************************/
/**
 * Query the level the system can be put down to sleep taking in mind currently taken locks.
 */
enum pm_level_t pm_waterlevel(void);

#ifdef DEBUG_PM
/**********************************************************************/
/**
 * Requests the power lock: debug version
 *
 * \param pm pointer to the power lock structure
 * \param file current file name
 * \param line current line number
 */
  void pm_lock_dbg(struct pm_lock_t *pm, const char *file, int line);

/**********************************************************************/
/**
 * Release the power lock: debug version
 *
 * \param pm pointer to the power lock structure
 * \param file current file name
 * \param line current line number
 */
  void pm_unlock_dbg(struct pm_lock_t *pm, const char *file, int line);
#endif

/** @} */ /* pm */

#endif