PowerExtended.h

   1 /*
   2  * Copyright (c) 2016, Texas Instruments Incorporated
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * *  Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  12  * *  Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * *  Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32
  33 /**
  34  * \ingroup PM_RTOS PMRTOS
  35  *
  36  * ============================================================================
  37  *  @file       PowerExtended.h
  38  *
  39  *  @brief      Power manager interface extension
  40  *
  41  *  The Power header file should be included in an application as follows:
  42  *  @code
  43  *  #include <ti/drv/pm/Power.h>
  44  *  #include <ti/drv/pm/PowerExtended.h>
  45  *  @endcode
  46  *
  47  *  Refer to @ref Power.h for a complete description of APIs.
  48  *
  49  *  ============================================================================
  50  * @{
  51  *
  52  */
  53
  54 #ifndef POWEREXTENDED_H
  55 #define POWEREXTENDED_H
  56
  57 #include <stdint.h>
  58
  59 #ifdef __cplusplus
  60 extern "C" {
  61 #endif
  62
  63 /* Power constraints */
  64 /*! Power Constraint to Disallow sleep */
  65 #define Power_DISALLOW_SLEEP             (0U)
  66 /*! Power Constraint to Disallow deep sleep */
  67 #define Power_DISALLOW_DEEPSLEEP         (1U)
  68 /*! Power Constraint to Disallow shutdown */
  69 #define Power_DISALLOW_SHUTDOWN          (2U)
  70 /*! Power Constraint to Disallow performance level low */
  71 #define Power_DISALLOW_PERFLEVEL_LOW     (3U)
  72 /*! Power Constraint to Disallow performance level nom */
  73 #define Power_DISALLOW_PERFLEVEL_NOM     (4U)
  74 /*! Power Constraint to Disallow performance level OD */
  75 #define Power_DISALLOW_PERFLEVEL_OD      (5U)
  76 /*! Power Constraint to Disallow performance level High */
  77 #define Power_DISALLOW_PERFLEVEL_HIGH    (6U)
  78 /*! Power Constraint to Disallow performance level changes */
  79 #define Power_DISALLOW_PERF_CHANGES      (7U)
  80 /*! Total number of Power Constraints */
  81 #define Power_NUMCONSTRAINTS             (8U)
  82
  83 /* Performance levels */
  84 /*! Power Performance level low */
  85 #define Power_PERFLEVEL_LOW              (0U)
  86 /*! Power Performance level Nom */
  87 #define Power_PERFLEVEL_NOM              (1U)
  88 /*! Power Performance level Od */
  89 #define Power_PERFLEVEL_OD               (2U)
  90 /*! Power Performance level High */
  91 #define Power_PERFLEVEL_HIGH             (3U)
  92 /*! Total number of Power Performance levels */
  93 #define Power_NUMPERFLEVELS              (4U)
  94
  95 /* Power events */
  96 /*! Power Event to enter sleep */
  97 #define Power_EV_ENTERING_SLEEP          (1U)
  98 /*! Power Event to enter deep sleep */
  99 #define Power_EV_ENTERING_DEEPSLEEP      (2U)
 100 /*! Power Event to enter shutdown */
 101 #define Power_EV_ENTERING_SHUTDOWN       (4U)
 102 /*! Power Event to wake up from sleep */
 103 #define Power_EV_AWAKE_SLEEP             (8U)
 104 /*! Power Event to wake up from deep sleep */
 105 #define Power_EV_AWAKE_DEEPSLEEP         (16U)
 106 /*! Power Event to start changing performance level */
 107 #define Power_EV_START_CHANGE_PERF_LEVEL (32U)
 108 /*! Power Event to finish changing performance level */
 109 #define Power_EV_DONE_CHANGE_PERF_LEVEL  (64U)
 110 /*! Power Event to finish AVS configuration */
 111 #define Power_EV_DONE_AVSCONFIG          (128U)
 112 /*! Power Event to finish DPLL configuration */
 113 #define Power_EV_DONE_DPLLCONFIG         (256U)
 114 /*! Power Event to finish setting module power state */
 115 #define Power_EV_DONE_MODULEPOWERSTATE   (512U)
 116
 117 /*! Total number of power events */
 118 #define Power_NUMEVENTS                  (10U)
 119 /*! Macro for Power Events */
 120 #define Power_EVENT_ALL                  (1023U)
 121
 122 /* Power sleep states */
 123 /*! Power State for sleep */
 124 #define Power_SLEEP                      (0x1)
 125 /*! Power State for deep sleep */
 126 #define Power_DEEPSLEEP                  (0x2)
 127
 128 /* Power shutdown states */
 129 /*! Power State for shutdown */
 130 #define Power_SHUTDOWN                   (0x0)
 131
 132 /*! Additional error code for api failure condition
 133  *  Error type defines invalid input */
 134 #define Power_INVALIDINPUT               (0xFFFFFFFFU)
 135
 136 /*!
 137  *  @brief      Power policy deinitialization function pointer
 138  */
 139 typedef void (*Power_PolicyDeinitFxn)(void);
 140
 141 /*!
 142  *  @brief  Power de-initialization function
 143  *
 144  *  This function de-initializes Power manager internal state configured in
 145  *  Power_init.
 146  *
 147  *  @return Power_SOK
 148  */
 149 unsigned int Power_deinit(void);
 150
 151 /*!
 152  *  @brief  Disable the configured power policy running when the CPU is idle
 153  *
 154  *  Calling this function unsets a flag, disabling the configured power
 155  *  policy function from being invoked on each pass through the Idle loop.
 156  *
 157  */
 158 void Power_disablePolicy(void);
 159
 160 /*!
 161  *  @brief  Get the current temperature range at a temperature sensor
 162  *
 163  *  Returns the current temperature range measured at a temperature sensor.
 164  *  The sensor to read is based on the set point index.
 165  *
 166  *  In the case, a temperature sensor is able to return an exact value
 167  *  the pTempMin and pTempMax dereferenced values will be equivalent.
 168  *
 169  *  Temperatures are returned in milli-degree Celsius.
 170  *
 171  *  @param  setPointIdx      set point index (device-specific)
 172  *
 173  *  @param  pTempMin         pointer to returned min temperature
 174  *
 175  *  @param  pTempMax         pointer to returned max temperature
 176  *
 177  *  @return Power_SOK
 178  *
 179  *  @sa     Power_getCurrentTemp
 180  */
 181 unsigned int Power_getCurrentTemp(unsigned int  setPointIdx,
 182                                   int          *pTempMin,
 183                                   int          *pTempMax);
 184
 185 /*!
 186  *  @brief  Get a programmed temperature threshold
 187  *
 188  *  Returns the programmed threshold temperature range.  The threshold whose
 189  *  temperature to return is decided based on the set point index.
 190  *
 191  *  In the case, a temperature threshold is able to return an exact value
 192  *  the pTempMin and pTempMax dereferenced values will be equivalent.
 193  *
 194  *  Temperatures are returned in milli-degree Celsius.
 195  *
 196  *  @param  setPointIdx      set point index (device-specific)
 197  *
 198  *  @param  pTempMin         pointer to min set point temperature
 199  *
 200  *  @param  pTempMax         pointer to max set point temperature
 201  *
 202  *  @return Power_SOK
 203  *
 204  *  @sa     Power_getThermalSetPoint
 205  */
 206 unsigned int Power_getThermalSetPoint(unsigned int  setPointIdx,
 207                                       int          *pTempMin,
 208                                       int          *pTempMax);
 209
 210 /*!
 211  *  @brief  Programs temperature threshold
 212  *
 213  *  Configures a temperature threshold.  The threshold temperature to
 214  *  configure is decided based on the set point index. A registered thermal
 215  *  event handling function will be invoked when a temperature event is
 216  *  triggered.  The function will take actions appropriate for the triggered
 217  *  thermal event (i.e. for high - reducing power consumption in order to lower
 218  *  the device temperature; for low - returning device operation to normal
 219  *  after cooldown is achieved from a previous thermal high point).
 220  *
 221  *  The temperature is input in milli-degree Celsius.
 222  *
 223  *  @param  setPointIdx     set point index (device-specific)
 224  *
 225  *  @param  temp            temperature to set
 226  *
 227  *  @return Power_SOK
 228  *
 229  *  @sa     Power_enableThermalSetPoint
 230  */
 231 unsigned int Power_enableThermalSetPoint(unsigned int setPointIdx,
 232                                          int          temp);
 233
 234 /*!
 235  *  @brief  Disables a previously configured temperature threshold
 236  *
 237  *  Disables a previously configured temperature threshold.  The threshold
 238  *  to disable is decided based on the set point index.
 239  *
 240  *  @param  setPointIdx     set point index (device-specific)
 241  *
 242  *  @return Power_SOK
 243  *
 244  *  @sa     Power_disableThermalSetPoint
 245  */
 246 unsigned int Power_disableThermalSetPoint(unsigned int setPointIdx);
 247
 248 /*!
 249  *  @brief  Power function to be added plugged as thermal alert ISR handler
 250  *
 251  *  This function should be registered as the handler for the device's thermal
 252  *  alert mechanism. (The method to do this depends upon the operating system
 253  *  being used.)  This function will invoke basic thermal event handling logic
 254  *  and then notifications will be sent to any clients who've registered
 255  *  (with Power_registerNotify()) to invoke client-specific thermal management
 256  *  logic.
 257  *
 258  */
 259 void Power_ThermalAlertFunc(void);
 260
 261 #ifdef __cplusplus
 262 }
 263 #endif
 264
 265 #endif /* POWEREXTENDED_H */
 266
 267 /* @} */
 268
 269 /**
 270  *  \defgroup PM_RTOS PMRTOS
 271  *
 272  *  PMRTOS provides application interface to power management
 273  *     - The Power manager facilitates the transition of the CPU from
 274  *       active state to one of the sleep states and vice versa.
 275  *     - It provides drivers the ability to set and release dependencies
 276  *       on hardware resources and keeps a reference count on each resource
 277  *       to know when to enable or disable the peripheral clock to the
 278  *       resource.
 279  *     - It provides drivers the ability to register a callback function
 280  *       upon a specific power event.
 281  *     - Drivers and apps can set or release constraints to prevent the CPU
 282  *       from transitioning into a particular sleep state.
 283  *
 284  *  <b> Refer to @ref Power.h for a complete description of APIs. </b>
 285  *
 286  */