clk.h

Go to the documentation of this file.

#ifndef EVE_CLK_H_INCLUDED
#define EVE_CLK_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 clock management framework.
 *
 * \author DT, Jetro AS
 */ /******************************************************************/

/* #define DEBUG_CLK */

#include <stdbool.h>
#include <stdint.h>
#include <lib/dlist.h>

/**
 * \addtogroup clk
 * @{
 * EVE clock management framework.
 */

/**********************************************************************/
/**
 * Indicates that the given clock should be kept running when system is in the suspend state.
 *
 * The modifier can be applied to level field of the \ref clk_lock_t instantiation
 * to indicate that the clock should not be switched off at system suspend.
 *
 * Usage:
 * \code
  struct clk_lock_t MyPersistentClockLock = CLK_LOCK_INIT(CLK_PERSISTENT(CLK_LEVEL_XO), MyPersistentClockLock);
 * \endcode
 *
 * \param x The actual clock level, \ref clk_level_t.
 */
#define CLK_PERSISTENT(x) ((enum clk_level_t) ((x) | 0x80))

/**********************************************************************/
/**
 * Clock level.
 *
 * The system can use one two high frequency clock sources: a 64 MHz internal
 * oscillator (RC) or a 32 MHz crystal oscillator (XO). The crystal oscillator
 * typically gives better stability, but drains more power from battery.
 *
 * Clock level is an abstraction for the clock source the system is running on.
 */
enum clk_level_t
{
  CLK_LEVEL_MIN,                        /**< Minimal possible clock level. */
  CLK_LEVEL_RC = CLK_LEVEL_MIN,         /**< System uses 64 MHz internal oscillator as a clock source. */
  CLK_LEVEL_XO,                         /**< System uses 32 MHz crystal oscillator as a clock source. */
  CLK_LEVEL__COUNT,                     /**< Number of elements in the \ref clk_level_t enum. */
};

/**********************************************************************/
/**
 * Clock lock structure.
 *
 * The clock lock structure represents a clock request for a given clock level.
 * The structure must be instantiated in the RAM memory using
 * one of \ref CLK_LOCK_INIT() or \ref DECLARE_CLK_LOCK().
 * Note that the clock request is not active unless \ref CLK_LOCK() is called for it.
 */
struct clk_lock_t
{
#ifdef DEBUG_CLK
  const char *dbg_file;                 /**< Debug field: file name the lock was touched last time in */
  int dbg_line;                         /**< Debug field: line number the lock was touched last time at */
  struct dlist_t dbg_link;              /**< Linked list of all locked requests at all lock levels */
#endif
  struct dlist_t link;                  /**< Linked list of all locked requests at the given lock level */
  uint8_t level;                        /**< \ref clk_level_t, the given lock level */
  uint8_t locked;                       /**< Lock counter for the lock request */
};

/**********************************************************************/
/** \def CLK_LOCK_INIT(l, clk)
 * Initializes a clock lock structure.
 *
 * The macro is used to initialize a clock lock structure instance.
 *
 * \param l clock level
 * \param clk clock lock structure
 *
 * Usage:
 * \code
  struct clk_lock_t MyXOClockLock = CLK_LOCK_INIT(CLK_LEVEL_XO, MyXOClockLock);
 * \endcode
 */

/**********************************************************************/
/** \def CLK_LOCK(clk)
 * Request the clock
 *
 * The macro is used to request clock at the given clock level.
 *
 * \param clk clock lock structure
 *
 * Usage:
 * \code
  CLK_LOCK(MyXOClockLock);
 * \endcode
 */

/**********************************************************************/
/** \def CLK_UNLOCK(clk)
 * Release the clock
 *
 * The macro is used to release clock at the given clock level.
 *
 * The clock actually continues to run after the last lock is released until
 * \ref clk_relax() is called explicitly or by \ref pm_relax().
 *
 * \param clk clock lock structure
 *
 * Usage:
 * \code
  CLK_UNLOCK(MyXOClockLock);
 * \endcode
 */

/**********************************************************************/
/** \def CLK_AUTO_LOCK(l)
 * Declares an anonymous auto lock, which holds clock request in the auto variable visibility block
 *
 * \param l clock level
 *
 * Usage:
 * \code
  {
    CLK_AUTO_LOCK(CLK_LEVEL_XO);
    // Do something protected by the lock
  }
  // The lock is released here
 * \endcode
 *
 * Note: taking in mind lazy nature of releasing the clock locks, use of auto clock locks is negligible. 
 */

#ifdef DEBUG_CLK
  #define CLK_LOCK_INIT(l, clk)         \
    {                                   \
      .dbg_link = DLIST_INIT(clk.dbg_link), \
      .dbg_file = __FILE__,             \
      .dbg_line = __LINE__,             \
      .link = DLIST_INIT(clk.link),     \
      .level = l,                       \
      .locked = 0,                      \
    }
  #define CLK_LOCK(pm) clk_lock_dbg(&pm, __FILE__, __LINE__)
  #define CLK_UNLOCK(pm) clk_unlock_dbg(&pm, __FILE__, __LINE__)
  #define CLK_AUTO_LOCK(l)              \
      inline void clk_unlock_dbg_adapter(struct clk_lock_t *clk) { clk_unlock_dbg(clk, __FILE__, __LINE__); } \
      struct clk_lock_t EveClkAutoLock __attribute__((cleanup(clk_unlock_dbg_adapter))); \
      do { EveClkAutoLock = (struct clk_lock_t) CLK_LOCK_INIT(l, EveClkAutoLock); } while (0)
#else
  #define CLK_LOCK_INIT(l, clk)         \
    {                                   \
      .link = DLIST_INIT(clk.link),     \
      .level = l,                       \
      .locked = 0,                      \
    }
  #define CLK_LOCK(clk) clk_lock(&clk)
  #define CLK_UNLOCK(clk) clk_unlock(&clk)
  #define CLK_AUTO_LOCK(l)              \
      struct clk_lock_t EveClkAutoLock __attribute__((cleanup(clk_unlock))); \
      do { EveClkAutoLock = (struct clk_lock_t) CLK_LOCK_INIT(l, EveClkAutoLock); } while (0)
#endif

/**********************************************************************/
/**
 * Instantiates a clock lock structure.
 *
 * The macro is used to instantiate a clock lock structure.
 *
 * \param l clock level
 * \param clk clock lock structure
 *
 * Usage:
 * \code
  DECLARE_CLK_LOCK(CLK_LEVEL_XO, MyXOClockLock);
 * \endcode
 */
#define DECLARE_CLK_LOCK(l, clk)\
  static struct clk_lock_t clk = CLK_LOCK_INIT(l, clk)

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


/**********************************************************************/
/**
 * Initializes the clock management framework.
 */
void clk_init(void);

/**********************************************************************/
/**
 * Switches off released clocks and enters the lowest allowed clock level.
 */
void clk_relax(void);

/**********************************************************************/
/**
 * Requests the clock.
 *
 * \param clk pointer to the clock lock structure
 */
void clk_lock(struct clk_lock_t *clk);

/**********************************************************************/
/**
 * Releases the clock.
 *
 * \param clk pointer to the clock lock structure
 */
void clk_unlock(struct clk_lock_t *clk);

#ifdef DEBUG_CLK
/**********************************************************************/
/**
 * Requests the clock: debug version.
 *
 * \param clk pointer to the clock lock structure
 * \param file current file name
 * \param line current line number
 */
  void clk_lock_dbg(struct clk_lock_t *clk, const char *file, int line);

/**********************************************************************/
/**
 * Releases the clock: debug version.
 *
 * \param clk pointer to the clock lock structure
 * \param file current file name
 * \param line current line number
 */
  void clk_unlock_dbg(struct clk_lock_t *clk, const char *file, int line);
#endif

/** @} */ /* clk */

#endif