git.sur5r.net Git - freertos/blob

   1 /***************************************************************************//**\r
   2  * @file sleep.h\r
   3  * @brief Energy Modes management driver\r
   4  * @version 4.0.0\r
   5  * @details\r
   6  * This is a energy modes management module consisting of sleep.c and sleep.h\r
   7  * source files. The main purpose of the module is to ease energy\r
   8  * optimization with a simple API. The module allows the system to always sleep\r
   9  * in the lowest possible energy mode. Users could set up callbacks that are\r
  10  * being called before and after each and every sleep. A counting semaphore is\r
  11  * available for each low energy mode (EM1/EM2/EM3) to protect certain system\r
  12  * states from being corrupted. This semaphore has limit set to maximum 255 locks.\r
  13  *\r
  14  * The module provides the following public API to the users:\r
  15  * SLEEP_Init()\r
  16  * SLEEP_Sleep()\r
  17  * SLEEP_SleepBlockBegin()\r
  18  * SLEEP_SleepBlockEnd()\r
  19  * SLEEP_ForceSleepInEM4()\r
  20  *\r
  21  *******************************************************************************\r
  22  * @section License\r
  23  * <b>(C) Copyright 2014 Silicon Labs, http://www.silabs.com</b>\r
  24  *******************************************************************************\r
  25  *\r
  26  * This file is licensed under the Silabs License Agreement. See the file\r
  27  * "Silabs_License_Agreement.txt" for details. Before using this software for\r
  28  * any purpose, you must agree to the terms of that agreement.\r
  29  *\r
  30  ******************************************************************************/\r
  31 \r
  32 #ifndef __SLEEP_H\r
  33 #define __SLEEP_H\r
  34 \r
  35 #include <stdint.h>\r
  36 #include <stdbool.h>\r
  37 \r
  38 /* Device specific header file(s). */\r
  39 #include "em_device.h"\r
  40 \r
  41 #ifdef __cplusplus\r
  42 extern "C" {\r
  43 #endif\r
  44 \r
  45 /***************************************************************************//**\r
  46  * @addtogroup EM_Drivers\r
  47  * @{\r
  48  ******************************************************************************/\r
  49 \r
  50 /***************************************************************************//**\r
  51  * @addtogroup SLEEP\r
  52  * @brief Energy Modes management driver.\r
  53  * @details\r
  54  * This is a energy modes management module consisting of sleep.c and sleep.h\r
  55  * source files. The main purpose of the module is to ease energy\r
  56  * optimization with a simple API. The module allows the system to always sleep\r
  57  * in the lowest possible energy mode. Users could set up callbacks that are\r
  58  * being called before and after each and every sleep. A counting semaphore is\r
  59  * available for each low energy mode (EM1/EM2/EM3) to protect certain system\r
  60  * states from being corrupted. This semaphore has limit set to maximum 255 locks.\r
  61  * @{\r
  62  ******************************************************************************/\r
  63 \r
  64 /*******************************************************************************\r
  65  *******************************   MACROS   ************************************\r
  66  ******************************************************************************/\r
  67 \r
  68 \r
  69 /*******************************************************************************\r
  70  ****************************   CONFIGURATION   ********************************\r
  71  ******************************************************************************/\r
  72 \r
  73 /** Enable/disable the HW block for protecting accidental setting of low energy\r
  74  *  modes (recommended to be set to true). */\r
  75 #ifndef SLEEP_HW_LOW_ENERGY_BLOCK_ENABLED\r
  76 #define SLEEP_HW_LOW_ENERGY_BLOCK_ENABLED    true\r
  77 #endif\r
  78 \r
  79 /** Enable/disable calling wakeup callback after EM4 reset. */\r
  80 #ifndef SLEEP_EM4_WAKEUP_CALLBACK_ENABLED\r
  81 #define SLEEP_EM4_WAKEUP_CALLBACK_ENABLED    true\r
  82 #endif\r
  83 \r
  84 /** Configure default lowest energy mode that the system can be set to.\r
  85  *  Possible values:\r
  86  *  @li sleepEM1 - EM1, the CPU core is turned off.\r
  87  *  @li sleepEM2 - EM2, like EM1 + all HF clocks are turned off, LF clocks are on.\r
  88  *  @li sleepEM3 - EM3, like EM2 + LF clocks are off, RAM retention, GPIO and ACMP\r
  89  *                   interrupt is on. */\r
  90 #ifndef SLEEP_LOWEST_ENERGY_MODE_DEFAULT\r
  91 #define SLEEP_LOWEST_ENERGY_MODE_DEFAULT    sleepEM3\r
  92 #endif\r
  93 \r
  94 /*******************************************************************************\r
  95  ******************************   TYPEDEFS   ***********************************\r
  96  ******************************************************************************/\r
  97 \r
  98 /** Status value used for showing the Energy Mode the device is currently in. */\r
  99 typedef enum\r
 100 {\r
 101   /** Status value for EM0. */\r
 102   sleepEM0 = 0,\r
 103 \r
 104   /** Status value for EM1. */\r
 105   sleepEM1 = 1,\r
 106 \r
 107   /** Status value for EM2. */\r
 108   sleepEM2 = 2,\r
 109 \r
 110   /** Status value for EM3. */\r
 111   sleepEM3 = 3,\r
 112 \r
 113   /** Status value for EM4. */\r
 114   sleepEM4 = 4\r
 115 } SLEEP_EnergyMode_t;\r
 116 \r
 117 /** Callback function pointer type. */\r
 118 typedef void (*SLEEP_CbFuncPtr_t)(SLEEP_EnergyMode_t);\r
 119 \r
 120 \r
 121 /*******************************************************************************\r
 122  ******************************   PROTOTYPES   *********************************\r
 123  ******************************************************************************/\r
 124 \r
 125 /***************************************************************************//**\r
 126  * @brief\r
 127  *   Initialize the Sleep module.\r
 128  *\r
 129  * @details\r
 130  *   Use this function to initialize the Sleep module, should be called\r
 131  *   only once! Pointers to sleep and wake-up callback functions shall be\r
 132  *   provided when calling this function.\r
 133  *   If SLEEP_EM4_WAKEUP_CALLBACK_ENABLED is set to true, this function checks\r
 134  *   for the cause of the reset that implicitly called it and calls the wakeup\r
 135  *   callback if the reset was a wakeup from EM4 (does not work on Gecko MCU).\r
 136  *\r
 137  * @param[in] pSleepCb\r
 138  *   Pointer to the callback function that is being called before the device is\r
 139  *   going to sleep.\r
 140  *\r
 141  * @param[in] pWakeUpCb\r
 142  *   Pointer to the callback function that is being called after wake up.\r
 143  ******************************************************************************/\r
 144 void SLEEP_Init(SLEEP_CbFuncPtr_t pSleepCb, SLEEP_CbFuncPtr_t pWakeUpCb);\r
 145 \r
 146 /***************************************************************************//**\r
 147  * @brief\r
 148  *   Gets the lowest energy mode that the system is allowed to be set to.\r
 149  *\r
 150  * @details\r
 151  *   This function uses the low energy mode block counters to determine the\r
 152  *   lowest possible that the system is allowed to be set to.\r
 153  *\r
 154  * @return\r
 155  *   Lowest energy mode that the system can be set to. Possible values:\r
 156  *   @li sleepEM0\r
 157  *   @li sleepEM1\r
 158  *   @li sleepEM2\r
 159  *   @li sleepEM3\r
 160  ******************************************************************************/\r
 161 SLEEP_EnergyMode_t SLEEP_LowestEnergyModeGet(void);\r
 162 \r
 163 /***************************************************************************//**\r
 164  * @brief\r
 165  *   Sets the system to sleep into the lowest possible energy mode.\r
 166  *\r
 167  * @details\r
 168  *   This function takes care of the system states protected by the sleep block\r
 169  *   provided by SLEEP_SleepBlockBegin() / SLEEP_SleepBlockEnd(). It allows\r
 170  *   the system to go into the lowest possible energy mode that the device can\r
 171  *   be set into at the time of the call of this function.\r
 172  *   This function will not go lower than EM3 because leaving EM4 requires\r
 173  *   resetting MCU. To enter into EM4 call SLEEP_ForceSleepInEM4().\r
 174  *\r
 175  * @return\r
 176  *   Energy Mode that was entered. Possible values:\r
 177  *   @li sleepEM0\r
 178  *   @li sleepEM1\r
 179  *   @li sleepEM2\r
 180  *   @li sleepEM3\r
 181  ******************************************************************************/\r
 182 SLEEP_EnergyMode_t SLEEP_Sleep(void);\r
 183 \r
 184 \r
 185 /***************************************************************************//**\r
 186  * @brief\r
 187  *   Force the device to go to EM4 without doing any checks.\r
 188  *\r
 189  * @details\r
 190  *   This function unblocks the low energy sleep block then goes to EM4.\r
 191  *\r
 192  * @note\r
 193  *   Regular RAM is not retained in EM4 and the wake up causes a reset.\r
 194  *   If the configuration option SLEEP_EM4_WAKEUP_CALLBACK_ENABLED is set to\r
 195  *   true, the SLEEP_Init() function checks for the reset cause and calls the\r
 196  *   EM4 wakeup callback.\r
 197  ******************************************************************************/\r
 198 void SLEEP_ForceSleepInEM4(void);\r
 199 \r
 200 \r
 201 /***************************************************************************//**\r
 202  * @brief\r
 203  *   Begin sleep block in the requested energy mode.\r
 204  *\r
 205  * @details\r
 206  *   Blocking a critical system state from a certain energy mode makes sure that\r
 207  *   the system is not set to that energy mode while the block is not being\r
 208  *   released.\r
 209  *   Every SLEEP_SleepBlockBegin() increases the corresponding counter and\r
 210  *   every SLEEP_SleepBlockEnd() decreases it.\r
 211  *\r
 212  *   Example:\code\r
 213  *      SLEEP_SleepBlockBegin(sleepEM2);  // do not allow EM2 or higher\r
 214  *      // do some stuff that requires EM1 at least, like ADC sampling\r
 215  *      SLEEP_SleepBlockEnd(sleepEM2);    // remove restriction for EM2\endcode\r
 216  *\r
 217  * @note\r
 218  *   Be aware that there is limit of maximum blocks nesting to 255.\r
 219  *\r
 220  * @param[in] eMode\r
 221  *   Energy mode to begin to block. Possible values:\r
 222  *   @li sleepEM1 - Begin to block the system from being set to EM1 (and EM2..4).\r
 223  *   @li sleepEM2 - Begin to block the system from being set to EM2 (and EM3/EM4).\r
 224  *   @li sleepEM3 - Begin to block the system from being set to EM3 (and EM4).\r
 225  ******************************************************************************/\r
 226 void SLEEP_SleepBlockBegin(SLEEP_EnergyMode_t eMode);\r
 227 \r
 228 \r
 229 /***************************************************************************//**\r
 230  * @brief\r
 231  *   End sleep block in the requested energy mode.\r
 232  *\r
 233  * @details\r
 234  *   Release restriction for entering certain energy mode. Every call of this\r
 235  *   function reduce blocking counter by 1. Once the counter for specific energy\r
 236  *   mode is 0 and all counters for lower energy modes are 0 as well, using\r
 237  *   particular energy mode is allowed.\r
 238  *   Every SLEEP_SleepBlockBegin() increases the corresponding counter and\r
 239  *   every SLEEP_SleepBlockEnd() decreases it.\r
 240  *\r
 241  *   Example:\code\r
 242  *      // at start all energy modes are allowed\r
 243  *      SLEEP_SleepBlockBegin(sleepEM2); // EM2, EM3, EM4 are blocked\r
 244  *      SLEEP_SleepBlockBegin(sleepEM1); // EM1, EM2, EM3, EM4 are blocked\r
 245  *      SLEEP_SleepBlockBegin(sleepEM1); // EM1, EM2, EM3, EM4 are blocked\r
 246  *      SLEEP_SleepBlockEnd(sleepEM2);   // still EM1, EM2, EM3, EM4 are blocked\r
 247  *      SLEEP_SleepBlockEnd(sleepEM1);   // still EM1, EM2, EM3, EM4 are blocked\r
 248  *      SLEEP_SleepBlockEnd(sleepEM1);   // all energy modes are allowed now\endcode\r
 249  *\r
 250  * @param[in] eMode\r
 251  *   Energy mode to end to block. Possible values:\r
 252  *   @li sleepEM1 - End to block the system from being set to EM1 (and EM2..4).\r
 253  *   @li sleepEM2 - End to block the system from being set to EM2 (and EM3/EM4).\r
 254  *   @li sleepEM3 - End to block the system from being set to EM3 (and EM4).\r
 255  ******************************************************************************/\r
 256 void SLEEP_SleepBlockEnd(SLEEP_EnergyMode_t eMode);\r
 257 \r
 258 \r
 259 /** @} (end addtogroup SLEEP) */\r
 260 /** @} (end addtogroup EM_Drivers) */\r
 261 \r
 262 #ifdef __cplusplus\r
 263 }\r
 264 #endif\r
 265 #endif /* __SLEEP_H */\r