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 Architectures that provide a SoC framework for OPP should select ARCH_HAS_OPP
  55 to make the OPP layer available.
  56
  57 OPP layer expects each domain to be represented by a unique device pointer. SoC
  58 framework registers a set of initial OPPs per device with the OPP layer. This
  59 list is expected to be an optimally small number typically around 5 per device.
  60 This initial list contains a set of OPPs that the framework expects to be safely
  61 enabled by default in the system.
  62
  63 Note on OPP Availability:
  64 ------------------------
  65 As the system proceeds to operate, SoC framework may choose to make certain
  66 OPPs available or not available on each device based on various external
  67 factors. Example usage: Thermal management or other exceptional situations where
  68 SoC framework might choose to disable a higher frequency OPP to safely continue
  69 operations until that OPP could be re-enabled if possible.
  70
  71 OPP library facilitates this concept in it's implementation. The following
  72 operational functions operate only on available opps:
  73 opp_find_freq_{ceil, floor}, dev_pm_opp_get_voltage, dev_pm_opp_get_freq, dev_pm_opp_get_opp_count
  74
  75 dev_pm_opp_find_freq_exact is meant to be used to find the opp pointer which can then
  76 be used for dev_pm_opp_enable/disable functions to make an opp available as required.
  77
  78 WARNING: Users of OPP library should refresh their availability count using
  79 get_opp_count if dev_pm_opp_enable/disable functions are invoked for a device, the
  80 exact mechanism to trigger these or the notification mechanism to other
  81 dependent subsystems such as cpufreq are left to the discretion of the SoC
  82 specific framework which uses the OPP library. Similar care needs to be taken
  83 care to refresh the cpufreq table in cases of these operations.
  84
  85 WARNING on OPP List locking mechanism:
  86 -------------------------------------------------
  87 OPP library uses RCU for exclusivity. RCU allows the query functions to operate
  88 in multiple contexts and this synchronization mechanism is optimal for a read
  89 intensive operations on data structure as the OPP library caters to.
  90
  91 To ensure that the data retrieved are sane, the users such as SoC framework
  92 should ensure that the section of code operating on OPP queries are locked
  93 using RCU read locks. The opp_find_freq_{exact,ceil,floor},
  94 opp_get_{voltage, freq, opp_count} fall into this category.
  95
  96 opp_{add,enable,disable} are updaters which use mutex and implement it's own
  97 RCU locking mechanisms. These functions should *NOT* be called under RCU locks
  98 and other contexts that prevent blocking functions in RCU or mutex operations
  99 from working.
 100
 101 2. Initial OPP List Registration
 102 ================================
 103 The SoC implementation calls dev_pm_opp_add function iteratively to add OPPs per
 104 device. It is expected that the SoC framework will register the OPP entries
 105 optimally- typical numbers range to be less than 5. The list generated by
 106 registering the OPPs is maintained by OPP library throughout the device
 107 operation. The SoC framework can subsequently control the availability of the
 108 OPPs dynamically using the dev_pm_opp_enable / disable functions.
 109
 110 dev_pm_opp_add - Add a new OPP for a specific domain represented by the device pointer.
 111         The OPP is defined using the frequency and voltage. Once added, the OPP
 112         is assumed to be available and control of it's availability can be done
 113         with the dev_pm_opp_enable/disable functions. OPP library internally stores
 114         and manages this information in the opp struct. This function may be
 115         used by SoC framework to define a optimal list as per the demands of
 116         SoC usage environment.
 117
 118         WARNING: Do not use this function in interrupt context.
 119
 120         Example:
 121          soc_pm_init()
 122          {
 123                 /* Do things */
 124                 r = dev_pm_opp_add(mpu_dev, 1000000, 900000);
 125                 if (!r) {
 126                         pr_err("%s: unable to register mpu opp(%d)\n", r);
 127                         goto no_cpufreq;
 128                 }
 129                 /* Do cpufreq things */
 130          no_cpufreq:
 131                 /* Do remaining things */
 132          }
 133
 134 3. OPP Search Functions
 135 =======================
 136 High level framework such as cpufreq operates on frequencies. To map the
 137 frequency back to the corresponding OPP, OPP library provides handy functions
 138 to search the OPP list that OPP library internally manages. These search
 139 functions return the matching pointer representing the opp if a match is
 140 found, else returns error. These errors are expected to be handled by standard
 141 error checks such as IS_ERR() and appropriate actions taken by the caller.
 142
 143 dev_pm_opp_find_freq_exact - Search for an OPP based on an *exact* frequency and
 144         availability. This function is especially useful to enable an OPP which
 145         is not available by default.
 146         Example: In a case when SoC framework detects a situation where a
 147         higher frequency could be made available, it can use this function to
 148         find the OPP prior to call the dev_pm_opp_enable to actually make it available.
 149          rcu_read_lock();
 150          opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
 151          rcu_read_unlock();
 152          /* dont operate on the pointer.. just do a sanity check.. */
 153          if (IS_ERR(opp)) {
 154                 pr_err("frequency not disabled!\n");
 155                 /* trigger appropriate actions.. */
 156          } else {
 157                 dev_pm_opp_enable(dev,1000000000);
 158          }
 159
 160         NOTE: This is the only search function that operates on OPPs which are
 161         not available.
 162
 163 dev_pm_opp_find_freq_floor - Search for an available OPP which is *at most* the
 164         provided frequency. This function is useful while searching for a lesser
 165         match OR operating on OPP information in the order of decreasing
 166         frequency.
 167         Example: To find the highest opp for a device:
 168          freq = ULONG_MAX;
 169          rcu_read_lock();
 170          dev_pm_opp_find_freq_floor(dev, &freq);
 171          rcu_read_unlock();
 172
 173 dev_pm_opp_find_freq_ceil - Search for an available OPP which is *at least* the
 174         provided frequency. This function is useful while searching for a
 175         higher match OR operating on OPP information in the order of increasing
 176         frequency.
 177         Example 1: To find the lowest opp for a device:
 178          freq = 0;
 179          rcu_read_lock();
 180          dev_pm_opp_find_freq_ceil(dev, &freq);
 181          rcu_read_unlock();
 182         Example 2: A simplified implementation of a SoC cpufreq_driver->target:
 183          soc_cpufreq_target(..)
 184          {
 185                 /* Do stuff like policy checks etc. */
 186                 /* Find the best frequency match for the req */
 187                 rcu_read_lock();
 188                 opp = dev_pm_opp_find_freq_ceil(dev, &freq);
 189                 rcu_read_unlock();
 190                 if (!IS_ERR(opp))
 191                         soc_switch_to_freq_voltage(freq);
 192                 else
 193                         /* do something when we can't satisfy the req */
 194                 /* do other stuff */
 195          }
 196
 197 4. OPP Availability Control Functions
 198 =====================================
 199 A default OPP list registered with the OPP library may not cater to all possible
 200 situation. The OPP library provides a set of functions to modify the
 201 availability of a OPP within the OPP list. This allows SoC frameworks to have
 202 fine grained dynamic control of which sets of OPPs are operationally available.
 203 These functions are intended to *temporarily* remove an OPP in conditions such
 204 as thermal considerations (e.g. don't use OPPx until the temperature drops).
 205
 206 WARNING: Do not use these functions in interrupt context.
 207
 208 dev_pm_opp_enable - Make a OPP available for operation.
 209         Example: Lets say that 1GHz OPP is to be made available only if the
 210         SoC temperature is lower than a certain threshold. The SoC framework
 211         implementation might choose to do something as follows:
 212          if (cur_temp < temp_low_thresh) {
 213                 /* Enable 1GHz if it was disabled */
 214                 rcu_read_lock();
 215                 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
 216                 rcu_read_unlock();
 217                 /* just error check */
 218                 if (!IS_ERR(opp))
 219                         ret = dev_pm_opp_enable(dev, 1000000000);
 220                 else
 221                         goto try_something_else;
 222          }
 223
 224 dev_pm_opp_disable - Make an OPP to be not available for operation
 225         Example: Lets say that 1GHz OPP is to be disabled if the temperature
 226         exceeds a threshold value. The SoC framework implementation might
 227         choose to do something as follows:
 228          if (cur_temp > temp_high_thresh) {
 229                 /* Disable 1GHz if it was enabled */
 230                 rcu_read_lock();
 231                 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true);
 232                 rcu_read_unlock();
 233                 /* just error check */
 234                 if (!IS_ERR(opp))
 235                         ret = dev_pm_opp_disable(dev, 1000000000);
 236                 else
 237                         goto try_something_else;
 238          }
 239
 240 5. OPP Data Retrieval Functions
 241 ===============================
 242 Since OPP library abstracts away the OPP information, a set of functions to pull
 243 information from the OPP structure is necessary. Once an OPP pointer is
 244 retrieved using the search functions, the following functions can be used by SoC
 245 framework to retrieve the information represented inside the OPP layer.
 246
 247 dev_pm_opp_get_voltage - Retrieve the voltage represented by the opp pointer.
 248         Example: At a cpufreq transition to a different frequency, SoC
 249         framework requires to set the voltage represented by the OPP using
 250         the regulator framework to the Power Management chip providing the
 251         voltage.
 252          soc_switch_to_freq_voltage(freq)
 253          {
 254                 /* do things */
 255                 rcu_read_lock();
 256                 opp = dev_pm_opp_find_freq_ceil(dev, &freq);
 257                 v = dev_pm_opp_get_voltage(opp);
 258                 rcu_read_unlock();
 259                 if (v)
 260                         regulator_set_voltage(.., v);
 261                 /* do other things */
 262          }
 263
 264 dev_pm_opp_get_freq - Retrieve the freq represented by the opp pointer.
 265         Example: Lets say the SoC framework uses a couple of helper functions
 266         we could pass opp pointers instead of doing additional parameters to
 267         handle quiet a bit of data parameters.
 268          soc_cpufreq_target(..)
 269          {
 270                 /* do things.. */
 271                  max_freq = ULONG_MAX;
 272                  rcu_read_lock();
 273                  max_opp = dev_pm_opp_find_freq_floor(dev,&max_freq);
 274                  requested_opp = dev_pm_opp_find_freq_ceil(dev,&freq);
 275                  if (!IS_ERR(max_opp) && !IS_ERR(requested_opp))
 276                         r = soc_test_validity(max_opp, requested_opp);
 277                  rcu_read_unlock();
 278                 /* do other things */
 279          }
 280          soc_test_validity(..)
 281          {
 282                  if(dev_pm_opp_get_voltage(max_opp) < dev_pm_opp_get_voltage(requested_opp))
 283                          return -EINVAL;
 284                  if(dev_pm_opp_get_freq(max_opp) < dev_pm_opp_get_freq(requested_opp))
 285                          return -EINVAL;
 286                 /* do things.. */
 287          }
 288
 289 dev_pm_opp_get_opp_count - Retrieve the number of available opps for a device
 290         Example: Lets say a co-processor in the SoC needs to know the available
 291         frequencies in a table, the main processor can notify as following:
 292          soc_notify_coproc_available_frequencies()
 293          {
 294                 /* Do things */
 295                 rcu_read_lock();
 296                 num_available = dev_pm_opp_get_opp_count(dev);
 297                 speeds = kzalloc(sizeof(u32) * num_available, GFP_KERNEL);
 298                 /* populate the table in increasing order */
 299                 freq = 0;
 300                 while (!IS_ERR(opp = dev_pm_opp_find_freq_ceil(dev, &freq))) {
 301                         speeds[i] = freq;
 302                         freq++;
 303                         i++;
 304                 }
 305                 rcu_read_unlock();
 306
 307                 soc_notify_coproc(AVAILABLE_FREQs, speeds, num_available);
 308                 /* Do other things */
 309          }
 310
 311 6. Data Structures
 312 ==================
 313 Typically an SoC contains multiple voltage domains which are variable. Each
 314 domain is represented by a device pointer. The relationship to OPP can be
 315 represented as follows:
 316 SoC
 317  |- device 1
 318  |      |- opp 1 (availability, freq, voltage)
 319  |      |- opp 2 ..
 320  ...    ...
 321  |      `- opp n ..
 322  |- device 2
 323  ...
 324  `- device m
 325
 326 OPP library maintains a internal list that the SoC framework populates and
 327 accessed by various functions as described above. However, the structures
 328 representing the actual OPPs and domains are internal to the OPP library itself
 329 to allow for suitable abstraction reusable across systems.
 330
 331 struct dev_pm_opp - The internal data structure of OPP library which is used to
 332         represent an OPP. In addition to the freq, voltage, availability
 333         information, it also contains internal book keeping information required
 334         for the OPP library to operate on.  Pointer to this structure is
 335         provided back to the users such as SoC framework to be used as a
 336         identifier for OPP in the interactions with OPP layer.
 337
 338         WARNING: The struct dev_pm_opp pointer should not be parsed or modified by the
 339         users. The defaults of for an instance is populated by dev_pm_opp_add, but the
 340         availability of the OPP can be modified by dev_pm_opp_enable/disable functions.
 341
 342 struct device - This is used to identify a domain to the OPP layer. The
 343         nature of the device and it's implementation is left to the user of
 344         OPP library such as the SoC framework.
 345
 346 Overall, in a simplistic view, the data structure operations is represented as
 347 following:
 348
 349 Initialization / modification:
 350             +-----+        /- dev_pm_opp_enable
 351 dev_pm_opp_add --> | opp | <-------
 352   |         +-----+        \- dev_pm_opp_disable
 353   \-------> domain_info(device)
 354
 355 Search functions:
 356              /-- dev_pm_opp_find_freq_ceil  ---\   +-----+
 357 domain_info<---- dev_pm_opp_find_freq_exact -----> | opp |
 358              \-- dev_pm_opp_find_freq_floor ---/   +-----+
 359
 360 Retrieval functions:
 361 +-----+     /- dev_pm_opp_get_voltage
 362 | opp | <---
 363 +-----+     \- dev_pm_opp_get_freq
 364
 365 domain_info <- dev_pm_opp_get_opp_count