Documentation/power/opp.txt

   1 Operating Performance Points (OPP) Library
   2 ==========================================
   3
   4 (C) 2009-2010 Nishanth Menon <nm@ti.com>, Texas Instruments Incorporated
   5
   6 Contents
   7 --------
   8 1. Introduction
   9 2. Initial OPP List Registration
  10 3. OPP Search Functions
  11 4. OPP Availability Control Functions
  12 5. OPP Data Retrieval Functions
  13 6. Data Structures
  14
  15 1. Introduction
  16 ===============
  17 1.1 What is an Operating Performance Point (OPP)?
  18
  19 Complex SoCs of today consists of a multiple sub-modules working in conjunction.
  20 In an operational system executing varied use cases, not all modules in the SoC
  21 need to function at their highest performing frequency all the time. To
  22 facilitate this, sub-modules in a SoC are grouped into domains, allowing some
  23 domains to run at lower voltage and frequency while other domains run at
  24 voltage/frequency pairs that are higher.
  25
  26 The set of discrete tuples consisting of frequency and voltage pairs that
  27 the device will support per domain are called Operating Performance Points or
  28 OPPs.
  29
  30 As an example:
  31 Let us consider an MPU device which supports the following:
  32 {300MHz at minimum voltage of 1V}, {800MHz at minimum voltage of 1.2V},
  33 {1GHz at minimum voltage of 1.3V}
  34
  35 We can represent these as three OPPs as the following {Hz, uV} tuples:
  36 {300000000, 1000000}
  37 {800000000, 1200000}
  38 {1000000000, 1300000}
  39
  40 1.2 Operating Performance Points Library
  41
  42 OPP library provides a set of helper functions to organize and query the OPP
  43 information. The library is located in drivers/base/power/opp.c and the header
  44 is located in include/linux/pm_opp.h. OPP library can be enabled by enabling
  45 CONFIG_PM_OPP from power management menuconfig menu. OPP library depends on
  46 CONFIG_PM as certain SoCs such as Texas Instrument's OMAP framework allows to
  47 optionally boot at a certain OPP without needing cpufreq.
  48
  49 Typical usage of the OPP library is as follows:
  50 (users)         -> registers a set of default OPPs              -> (library)
  51 SoC framework   -> modifies on required cases certain OPPs      -> OPP layer
  52                 -> queries to search/retrieve information       ->
  53
  54 OPP layer expects each domain to be represented by a unique device pointer. SoC
  55 framework registers a set of initial OPPs per device with the OPP layer. This
  56 list is expected to be an optimally small number typically around 5 per device.
  57 This initial list contains a set of OPPs that the framework expects to be safely
  58 enabled by default in the system.
  59
  60 Note on OPP Availability:
  61 ------------------------
  62 As the system proceeds to operate, SoC framework may choose to make certain
  63 OPPs available or not available on each device based on various external
  64 factors. Example usage: Thermal management or other exceptional situations where
  65 SoC framework might choose to disable a higher frequency OPP to safely continue
  66 operations until that OPP could be re-enabled if possible.
  67
  68 OPP library facilitates this concept in it's implementation. The following
  69 operational functions operate only on available opps:
  70 opp_find_freq_{ceil, floor}, dev_pm_opp_get_voltage, dev_pm_opp_get_freq, dev_pm_opp_get_opp_count
  71
  72 dev_pm_opp_find_freq_exact is meant to be used to find the opp pointer which can then
  73 be used for dev_pm_opp_enable/disable functions to make an opp available as required.
  74
  75 WARNING: Users of OPP library should refresh their availability count using
  76 get_opp_count if dev_pm_opp_enable/disable functions are invoked for a device, the
  77 exact mechanism to trigger these or the notification mechanism to other
  78 dependent subsystems such as cpufreq are left to the discretion of the SoC
  79 specific framework which uses the OPP library. Similar care needs to be taken
  80 care to refresh the cpufreq table in cases of these operations.
  81
  82 2. Initial OPP List Registration
  83 ================================
  84 The SoC implementation calls dev_pm_opp_add function iteratively to add OPPs per
  85 device. It is expected that the SoC framework will register the OPP entries
  86 optimally- typical numbers range to be less than 5. The list generated by
  87 registering the OPPs is maintained by OPP library throughout the device
  88 operation. The SoC framework can subsequently control the availability of the
  89 OPPs dynamically using the dev_pm_opp_enable / disable functions.
  90
  91 dev_pm_opp_add - Add a new OPP for a specific domain represented by the device pointer.
  92         The OPP is defined using the frequency and voltage. Once added, the OPP
  93         is assumed to be available and control of it's availability can be done
  94         with the dev_pm_opp_enable/disable functions. OPP library internally stores
  95         and manages this information in the opp struct. This function may be
  96         used by SoC framework to define a optimal list as per the demands of
  97         SoC usage environment.
  98
  99         WARNING: Do not use this function in interrupt context.
 100
 101         Example:
 102          soc_pm_init()
 103          {
 104                 /* Do things */
 105                 r = dev_pm_opp_add(mpu_dev, 1000000, 900000);
 106                 if (!r) {
 107                         pr_err("%s: unable to register mpu opp(%d)\n", r);
 108                         goto no_cpufreq;
 109                 }
 110                 /* Do cpufreq things */
 111          no_cpufreq:
 112                 /* Do remaining things */
 113          }
 114
 115 3. OPP Search Functions
 116 =======================
 117 High level framework such as cpufreq operates on frequencies. To map the
 118 frequency back to the corresponding OPP, OPP library provides handy functions
 119 to search the OPP list that OPP library internally manages. These search
 120 functions return the matching pointer representing the opp if a match is
 121 found, else returns error. These errors are expected to be handled by standard
 122 error checks such as IS_ERR() and appropriate actions taken by the caller.
 123
 124 Callers of these functions shall call dev_pm_opp_put() after they have used the
 125 OPP. Otherwise the memory for the OPP will never get freed and result in
 126 memleak.
 127
 128 dev_pm_opp_find_freq_exact - Search for an OPP based on an *exact* frequency and
 129         availability. This function is especially useful to enable an OPP which
 130         is not available by default.
 131         Example: In a case when SoC framework detects a situation where a
 132         higher frequency could be made available, it can use this function to
 133         find the OPP prior to call the dev_pm_opp_enable to actually make it available.
 134          opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
 135          dev_pm_opp_put(opp);
 136          /* dont operate on the pointer.. just do a sanity check.. */
 137          if (IS_ERR(opp)) {
 138                 pr_err("frequency not disabled!\n");
 139                 /* trigger appropriate actions.. */
 140          } else {
 141                 dev_pm_opp_enable(dev,1000000000);
 142          }
 143
 144         NOTE: This is the only search function that operates on OPPs which are
 145         not available.
 146
 147 dev_pm_opp_find_freq_floor - Search for an available OPP which is *at most* the
 148         provided frequency. This function is useful while searching for a lesser
 149         match OR operating on OPP information in the order of decreasing
 150         frequency.
 151         Example: To find the highest opp for a device:
 152          freq = ULONG_MAX;
 153          opp = dev_pm_opp_find_freq_floor(dev, &freq);
 154          dev_pm_opp_put(opp);
 155
 156 dev_pm_opp_find_freq_ceil - Search for an available OPP which is *at least* the
 157         provided frequency. This function is useful while searching for a
 158         higher match OR operating on OPP information in the order of increasing
 159         frequency.
 160         Example 1: To find the lowest opp for a device:
 161          freq = 0;
 162          opp = dev_pm_opp_find_freq_ceil(dev, &freq);
 163          dev_pm_opp_put(opp);
 164         Example 2: A simplified implementation of a SoC cpufreq_driver->target:
 165          soc_cpufreq_target(..)
 166          {
 167                 /* Do stuff like policy checks etc. */
 168                 /* Find the best frequency match for the req */
 169                 opp = dev_pm_opp_find_freq_ceil(dev, &freq);
 170                 dev_pm_opp_put(opp);
 171                 if (!IS_ERR(opp))
 172                         soc_switch_to_freq_voltage(freq);
 173                 else
 174                         /* do something when we can't satisfy the req */
 175                 /* do other stuff */
 176          }
 177
 178 4. OPP Availability Control Functions
 179 =====================================
 180 A default OPP list registered with the OPP library may not cater to all possible
 181 situation. The OPP library provides a set of functions to modify the
 182 availability of a OPP within the OPP list. This allows SoC frameworks to have
 183 fine grained dynamic control of which sets of OPPs are operationally available.
 184 These functions are intended to *temporarily* remove an OPP in conditions such
 185 as thermal considerations (e.g. don't use OPPx until the temperature drops).
 186
 187 WARNING: Do not use these functions in interrupt context.
 188
 189 dev_pm_opp_enable - Make a OPP available for operation.
 190         Example: Lets say that 1GHz OPP is to be made available only if the
 191         SoC temperature is lower than a certain threshold. The SoC framework
 192         implementation might choose to do something as follows:
 193          if (cur_temp < temp_low_thresh) {
 194                 /* Enable 1GHz if it was disabled */
 195                 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
 196                 dev_pm_opp_put(opp);
 197                 /* just error check */
 198                 if (!IS_ERR(opp))
 199                         ret = dev_pm_opp_enable(dev, 1000000000);
 200                 else
 201                         goto try_something_else;
 202          }
 203
 204 dev_pm_opp_disable - Make an OPP to be not available for operation
 205         Example: Lets say that 1GHz OPP is to be disabled if the temperature
 206         exceeds a threshold value. The SoC framework implementation might
 207         choose to do something as follows:
 208          if (cur_temp > temp_high_thresh) {
 209                 /* Disable 1GHz if it was enabled */
 210                 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true);
 211                 dev_pm_opp_put(opp);
 212                 /* just error check */
 213                 if (!IS_ERR(opp))
 214                         ret = dev_pm_opp_disable(dev, 1000000000);
 215                 else
 216                         goto try_something_else;
 217          }
 218
 219 5. OPP Data Retrieval Functions
 220 ===============================
 221 Since OPP library abstracts away the OPP information, a set of functions to pull
 222 information from the OPP structure is necessary. Once an OPP pointer is
 223 retrieved using the search functions, the following functions can be used by SoC
 224 framework to retrieve the information represented inside the OPP layer.
 225
 226 dev_pm_opp_get_voltage - Retrieve the voltage represented by the opp pointer.
 227         Example: At a cpufreq transition to a different frequency, SoC
 228         framework requires to set the voltage represented by the OPP using
 229         the regulator framework to the Power Management chip providing the
 230         voltage.
 231          soc_switch_to_freq_voltage(freq)
 232          {
 233                 /* do things */
 234                 opp = dev_pm_opp_find_freq_ceil(dev, &freq);
 235                 v = dev_pm_opp_get_voltage(opp);
 236                 dev_pm_opp_put(opp);
 237                 if (v)
 238                         regulator_set_voltage(.., v);
 239                 /* do other things */
 240          }
 241
 242 dev_pm_opp_get_freq - Retrieve the freq represented by the opp pointer.
 243         Example: Lets say the SoC framework uses a couple of helper functions
 244         we could pass opp pointers instead of doing additional parameters to
 245         handle quiet a bit of data parameters.
 246          soc_cpufreq_target(..)
 247          {
 248                 /* do things.. */
 249                  max_freq = ULONG_MAX;
 250                  max_opp = dev_pm_opp_find_freq_floor(dev,&max_freq);
 251                  requested_opp = dev_pm_opp_find_freq_ceil(dev,&freq);
 252                  if (!IS_ERR(max_opp) && !IS_ERR(requested_opp))
 253                         r = soc_test_validity(max_opp, requested_opp);
 254                  dev_pm_opp_put(max_opp);
 255                  dev_pm_opp_put(requested_opp);
 256                 /* do other things */
 257          }
 258          soc_test_validity(..)
 259          {
 260                  if(dev_pm_opp_get_voltage(max_opp) < dev_pm_opp_get_voltage(requested_opp))
 261                          return -EINVAL;
 262                  if(dev_pm_opp_get_freq(max_opp) < dev_pm_opp_get_freq(requested_opp))
 263                          return -EINVAL;
 264                 /* do things.. */
 265          }
 266
 267 dev_pm_opp_get_opp_count - Retrieve the number of available opps for a device
 268         Example: Lets say a co-processor in the SoC needs to know the available
 269         frequencies in a table, the main processor can notify as following:
 270          soc_notify_coproc_available_frequencies()
 271          {
 272                 /* Do things */
 273                 num_available = dev_pm_opp_get_opp_count(dev);
 274                 speeds = kzalloc(sizeof(u32) * num_available, GFP_KERNEL);
 275                 /* populate the table in increasing order */
 276                 freq = 0;
 277                 while (!IS_ERR(opp = dev_pm_opp_find_freq_ceil(dev, &freq))) {
 278                         speeds[i] = freq;
 279                         freq++;
 280                         i++;
 281                         dev_pm_opp_put(opp);
 282                 }
 283
 284                 soc_notify_coproc(AVAILABLE_FREQs, speeds, num_available);
 285                 /* Do other things */
 286          }
 287
 288 6. Data Structures
 289 ==================
 290 Typically an SoC contains multiple voltage domains which are variable. Each
 291 domain is represented by a device pointer. The relationship to OPP can be
 292 represented as follows:
 293 SoC
 294  |- device 1
 295  |      |- opp 1 (availability, freq, voltage)
 296  |      |- opp 2 ..
 297  ...    ...
 298  |      `- opp n ..
 299  |- device 2
 300  ...
 301  `- device m
 302
 303 OPP library maintains a internal list that the SoC framework populates and
 304 accessed by various functions as described above. However, the structures
 305 representing the actual OPPs and domains are internal to the OPP library itself
 306 to allow for suitable abstraction reusable across systems.
 307
 308 struct dev_pm_opp - The internal data structure of OPP library which is used to
 309         represent an OPP. In addition to the freq, voltage, availability
 310         information, it also contains internal book keeping information required
 311         for the OPP library to operate on.  Pointer to this structure is
 312         provided back to the users such as SoC framework to be used as a
 313         identifier for OPP in the interactions with OPP layer.
 314
 315         WARNING: The struct dev_pm_opp pointer should not be parsed or modified by the
 316         users. The defaults of for an instance is populated by dev_pm_opp_add, but the
 317         availability of the OPP can be modified by dev_pm_opp_enable/disable functions.
 318
 319 struct device - This is used to identify a domain to the OPP layer. The
 320         nature of the device and it's implementation is left to the user of
 321         OPP library such as the SoC framework.
 322
 323 Overall, in a simplistic view, the data structure operations is represented as
 324 following:
 325
 326 Initialization / modification:
 327             +-----+        /- dev_pm_opp_enable
 328 dev_pm_opp_add --> | opp | <-------
 329   |         +-----+        \- dev_pm_opp_disable
 330   \-------> domain_info(device)
 331
 332 Search functions:
 333              /-- dev_pm_opp_find_freq_ceil  ---\   +-----+
 334 domain_info<---- dev_pm_opp_find_freq_exact -----> | opp |
 335              \-- dev_pm_opp_find_freq_floor ---/   +-----+
 336
 337 Retrieval functions:
 338 +-----+     /- dev_pm_opp_get_voltage
 339 | opp | <---
 340 +-----+     \- dev_pm_opp_get_freq
 341
 342 domain_info <- dev_pm_opp_get_opp_count