PageRenderTime 61ms CodeModel.GetById 28ms RepoModel.GetById 0ms app.codeStats 0ms

/Documentation/power/opp.rst

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