Documentation/power/opp.txt

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