linux/Documentation/power/opp.txt
<<
>>
Prefs
   1*=============*
   2* OPP Library *
   3*=============*
   4
   5(C) 2009-2010 Nishanth Menon <nm@ti.com>, Texas Instruments Incorporated
   6
   7Contents
   8--------
   91. Introduction
  102. Initial OPP List Registration
  113. OPP Search Functions
  124. OPP Availability Control Functions
  135. OPP Data Retrieval Functions
  146. Cpufreq Table Generation
  157. Data Structures
  16
  171. Introduction
  18===============
  19Complex SoCs of today consists of a multiple sub-modules working in conjunction.
  20In an operational system executing varied use cases, not all modules in the SoC
  21need to function at their highest performing frequency all the time. To
  22facilitate this, sub-modules in a SoC are grouped into domains, allowing some
  23domains to run at lower voltage and frequency while other domains are loaded
  24more. The set of discrete tuples consisting of frequency and voltage pairs that
  25the device will support per domain are called Operating Performance Points or
  26OPPs.
  27
  28OPP library provides a set of helper functions to organize and query the OPP
  29information. The library is located in drivers/base/power/opp.c and the header
  30is located in include/linux/opp.h. OPP library can be enabled by enabling
  31CONFIG_PM_OPP from power management menuconfig menu. OPP library depends on
  32CONFIG_PM as certain SoCs such as Texas Instrument's OMAP framework allows to
  33optionally boot at a certain OPP without needing cpufreq.
  34
  35Typical usage of the OPP library is as follows:
  36(users)         -> registers a set of default OPPs              -> (library)
  37SoC framework   -> modifies on required cases certain OPPs      -> OPP layer
  38                -> queries to search/retrieve information       ->
  39
  40Architectures that provide a SoC framework for OPP should select ARCH_HAS_OPP
  41to make the OPP layer available.
  42
  43OPP layer expects each domain to be represented by a unique device pointer. SoC
  44framework registers a set of initial OPPs per device with the OPP layer. This
  45list is expected to be an optimally small number typically around 5 per device.
  46This initial list contains a set of OPPs that the framework expects to be safely
  47enabled by default in the system.
  48
  49Note on OPP Availability:
  50------------------------
  51As the system proceeds to operate, SoC framework may choose to make certain
  52OPPs available or not available on each device based on various external
  53factors. Example usage: Thermal management or other exceptional situations where
  54SoC framework might choose to disable a higher frequency OPP to safely continue
  55operations until that OPP could be re-enabled if possible.
  56
  57OPP library facilitates this concept in it's implementation. The following
  58operational functions operate only on available opps:
  59opp_find_freq_{ceil, floor}, opp_get_voltage, opp_get_freq, opp_get_opp_count
  60and opp_init_cpufreq_table
  61
  62opp_find_freq_exact is meant to be used to find the opp pointer which can then
  63be used for opp_enable/disable functions to make an opp available as required.
  64
  65WARNING: Users of OPP library should refresh their availability count using
  66get_opp_count if opp_enable/disable functions are invoked for a device, the
  67exact mechanism to trigger these or the notification mechanism to other
  68dependent subsystems such as cpufreq are left to the discretion of the SoC
  69specific framework which uses the OPP library. Similar care needs to be taken
  70care to refresh the cpufreq table in cases of these operations.
  71
  72WARNING on OPP List locking mechanism:
  73-------------------------------------------------
  74OPP library uses RCU for exclusivity. RCU allows the query functions to operate
  75in multiple contexts and this synchronization mechanism is optimal for a read
  76intensive operations on data structure as the OPP library caters to.
  77
  78To ensure that the data retrieved are sane, the users such as SoC framework
  79should ensure that the section of code operating on OPP queries are locked
  80using RCU read locks. The opp_find_freq_{exact,ceil,floor},
  81opp_get_{voltage, freq, opp_count} fall into this category.
  82
  83opp_{add,enable,disable} are updaters which use mutex and implement it's own
  84RCU locking mechanisms. opp_init_cpufreq_table acts as an updater and uses
  85mutex to implment RCU updater strategy. These functions should *NOT* be called
  86under RCU locks and other contexts that prevent blocking functions in RCU or
  87mutex operations from working.
  88
  892. Initial OPP List Registration
  90================================
  91The SoC implementation calls opp_add function iteratively to add OPPs per
  92device. It is expected that the SoC framework will register the OPP entries
  93optimally- typical numbers range to be less than 5. The list generated by
  94registering the OPPs is maintained by OPP library throughout the device
  95operation. The SoC framework can subsequently control the availability of the
  96OPPs dynamically using the opp_enable / disable functions.
  97
  98opp_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
 1223. OPP Search Functions
 123=======================
 124High level framework such as cpufreq operates on frequencies. To map the
 125frequency back to the corresponding OPP, OPP library provides handy functions
 126to search the OPP list that OPP library internally manages. These search
 127functions return the matching pointer representing the opp if a match is
 128found, else returns error. These errors are expected to be handled by standard
 129error checks such as IS_ERR() and appropriate actions taken by the caller.
 130
 131opp_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
 151opp_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
 161opp_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 can't satisfy the req */
 182                /* do other stuff */
 183         }
 184
 1854. OPP Availability Control Functions
 186=====================================
 187A default OPP list registered with the OPP library may not cater to all possible
 188situation. The OPP library provides a set of functions to modify the
 189availability of a OPP within the OPP list. This allows SoC frameworks to have
 190fine grained dynamic control of which sets of OPPs are operationally available.
 191These functions are intended to *temporarily* remove an OPP in conditions such
 192as thermal considerations (e.g. don't use OPPx until the temperature drops).
 193
 194WARNING: Do not use these functions in interrupt context.
 195
 196opp_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
 212opp_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
 2285. OPP Data Retrieval Functions
 229===============================
 230Since OPP library abstracts away the OPP information, a set of functions to pull
 231information from the OPP structure is necessary. Once an OPP pointer is
 232retrieved using the search functions, the following functions can be used by SoC
 233framework to retrieve the information represented inside the OPP layer.
 234
 235opp_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
 252opp_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
 277opp_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
 2996. Cpufreq Table Generation
 300===========================
 301opp_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
 324opp_free_cpufreq_table - Free up the table allocated by opp_init_cpufreq_table
 325
 3267. Data Structures
 327==================
 328Typically an SoC contains multiple voltage domains which are variable. Each
 329domain is represented by a device pointer. The relationship to OPP can be
 330represented as follows:
 331SoC
 332 |- device 1
 333 |      |- opp 1 (availability, freq, voltage)
 334 |      |- opp 2 ..
 335 ...    ...
 336 |      `- opp n ..
 337 |- device 2
 338 ...
 339 `- device m
 340
 341OPP library maintains a internal list that the SoC framework populates and
 342accessed by various functions as described above. However, the structures
 343representing the actual OPPs and domains are internal to the OPP library itself
 344to allow for suitable abstraction reusable across systems.
 345
 346struct opp - The internal data structure of OPP library which is used to
 347        represent an OPP. In addition to the freq, voltage, availability
 348        information, it also contains internal book keeping information required
 349        for the OPP library to operate on.  Pointer to this structure is
 350        provided back to the users such as SoC framework to be used as a
 351        identifier for OPP in the interactions with OPP layer.
 352
 353        WARNING: The struct opp pointer should not be parsed or modified by the
 354        users. The defaults of for an instance is populated by opp_add, but the
 355        availability of the OPP can be modified by opp_enable/disable functions.
 356
 357struct device - This is used to identify a domain to the OPP layer. The
 358        nature of the device and it's implementation is left to the user of
 359        OPP library such as the SoC framework.
 360
 361Overall, in a simplistic view, the data structure operations is represented as
 362following:
 363
 364Initialization / modification:
 365            +-----+        /- opp_enable
 366opp_add --> | opp | <-------
 367  |         +-----+        \- opp_disable
 368  \-------> domain_info(device)
 369
 370Search functions:
 371             /-- opp_find_freq_ceil  ---\   +-----+
 372domain_info<---- opp_find_freq_exact -----> | opp |
 373             \-- opp_find_freq_floor ---/   +-----+
 374
 375Retrieval functions:
 376+-----+     /- opp_get_voltage
 377| opp | <---
 378+-----+     \- opp_get_freq
 379
 380domain_info <- opp_get_opp_count
 381
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.