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