€•©Û      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”(hhŒparent”hubaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ/translations/zh_CN/power/opp”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”(hhhh2ubah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ/translations/zh_TW/power/opp”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”(hhhhFubah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ/translations/it_IT/power/opp”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”(hhhhZubah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ/translations/ja_JP/power/opp”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”(hhhhnubah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ/translations/ko_KR/power/opp”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”(hhhh‚ubah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ/translations/sp_SP/power/opp”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒ*Operating Performance Points (OPP) Library”h]”hŒ*Operating Performance Points (OPP) Library”…””}”(hhªhh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒ7/var/lib/git/docbuild/linux/Documentation/power/opp.rst”h KubhŒenumerated_list”“”)”}”(hhh]”hŒ	list_item”“”)”}”(hŒE2009-2010 Nishanth Menon <nm@ti.com>, Texas Instruments Incorporated
”h]”hŒ	paragraph”“”)”}”(hŒD2009-2010 Nishanth Menon <nm@ti.com>, Texas Instruments Incorporated”h]”(hŒ2009-2010 Nishanth Menon <”…””}”(hŒ2009-2010 Nishanth Menon <”hhÄhžhhŸNh NubhŒ	reference”“”)”}”(hŒ	nm@ti.com”h]”hŒ	nm@ti.com”…””}”(hhhhÏhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:nm@ti.com”uh1hÍhhÄubhŒ!>, Texas Instruments Incorporated”…””}”(hŒ!>, Texas Instruments Incorporated”hhÄhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h Khh¾ubah}”(h]”h ]”h"]”h$]”h&]”uh1h¼hh¹hžhhŸh¶h Nubah}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œ
upperalpha”Œprefix”Œ(”Œsuffix”Œ)”Œstart”Kuh1h·hh£hžhhŸh¶h KubhŒcomment”“”)”}”(hŒ«Contents

1. Introduction
2. Initial OPP List Registration
3. OPP Search Functions
4. OPP Availability Control Functions
5. OPP Data Retrieval Functions
6. Data Structures”h]”hŒ«Contents

1. Introduction
2. Initial OPP List Registration
3. OPP Search Functions
4. OPP Availability Control Functions
5. OPP Data Retrieval Functions
6. Data Structures”…””}”(hhhhÿubah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1hýhh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ1. Introduction”h]”hŒ1. Introduction”…””}”(hj  hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ11.1 What is an Operating Performance Point (OPP)?”h]”hŒ11.1 What is an Operating Performance Point (OPP)?”…””}”(hj%  hj#  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj   hžhhŸh¶h KubhÃ)”}”(hX¨  Complex SoCs of today consists of a multiple sub-modules working in conjunction.
In an operational system executing varied use cases, not all modules in the SoC
need to function at their highest performing frequency all the time. To
facilitate this, sub-modules in a SoC are grouped into domains, allowing some
domains to run at lower voltage and frequency while other domains run at
voltage/frequency pairs that are higher.”h]”hX¨  Complex SoCs of today consists of a multiple sub-modules working in conjunction.
In an operational system executing varied use cases, not all modules in the SoC
need to function at their highest performing frequency all the time. To
facilitate this, sub-modules in a SoC are grouped into domains, allowing some
domains to run at lower voltage and frequency while other domains run at
voltage/frequency pairs that are higher.”…””}”(hj3  hj1  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h Khj   hžhubhÃ)”}”(hŒThe set of discrete tuples consisting of frequency and voltage pairs that
the device will support per domain are called Operating Performance Points or
OPPs.”h]”hŒThe set of discrete tuples consisting of frequency and voltage pairs that
the device will support per domain are called Operating Performance Points or
OPPs.”…””}”(hjA  hj?  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h Khj   hžhubhÃ)”}”(hŒAs an example:”h]”hŒAs an example:”…””}”(hjO  hjM  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h K!hj   hžhubhÃ)”}”(hŒ¥Let us consider an MPU device which supports the following:
{300MHz at minimum voltage of 1V}, {800MHz at minimum voltage of 1.2V},
{1GHz at minimum voltage of 1.3V}”h]”hŒ¥Let us consider an MPU device which supports the following:
{300MHz at minimum voltage of 1V}, {800MHz at minimum voltage of 1.2V},
{1GHz at minimum voltage of 1.3V}”…””}”(hj]  hj[  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h K#hj   hžhubhÃ)”}”(hŒFWe can represent these as three OPPs as the following {Hz, uV} tuples:”h]”hŒFWe can represent these as three OPPs as the following {Hz, uV} tuples:”…””}”(hjk  hji  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h K'hj   hžhubhŒbullet_list”“”)”}”(hhh]”(h½)”}”(hŒ{300000000, 1000000}”h]”hÃ)”}”(hj~  h]”hŒ{300000000, 1000000}”…””}”(hj~  hj€  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h K)hj|  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h¼hjy  hžhhŸh¶h Nubh½)”}”(hŒ{800000000, 1200000}”h]”hÃ)”}”(hj•  h]”hŒ{800000000, 1200000}”…””}”(hj•  hj—  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h K*hj“  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h¼hjy  hžhhŸh¶h Nubh½)”}”(hŒ{1000000000, 1300000}
”h]”hÃ)”}”(hŒ{1000000000, 1300000}”h]”hŒ{1000000000, 1300000}”…””}”(hj°  hj®  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h K+hjª  ubah}”(h]”h ]”h"]”h$]”h&]”uh1h¼hjy  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1jw  hŸh¶h K)hj   hžhubeh}”(h]”Œ*what-is-an-operating-performance-point-opp”ah ]”h"]”Œ11.1 what is an operating performance point (opp)?”ah$]”h&]”uh1h¡hj  hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ(1.2 Operating Performance Points Library”h]”hŒ(1.2 Operating Performance Points Library”…””}”(hj×  hjÕ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjÒ  hžhhŸh¶h K.ubhÃ)”}”(hX–  OPP library provides a set of helper functions to organize and query the OPP
information. The library is located in drivers/opp/ directory and the header
is located in include/linux/pm_opp.h. OPP library can be enabled by enabling
CONFIG_PM_OPP from power management menuconfig menu. Certain SoCs such as Texas
Instrument's OMAP framework allows to optionally boot at a certain OPP without
needing cpufreq.”h]”hX˜  OPP library provides a set of helper functions to organize and query the OPP
information. The library is located in drivers/opp/ directory and the header
is located in include/linux/pm_opp.h. OPP library can be enabled by enabling
CONFIG_PM_OPP from power management menuconfig menu. Certain SoCs such as Texas
Instrumentâ€™s OMAP framework allows to optionally boot at a certain OPP without
needing cpufreq.”…””}”(hjå  hjã  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h K0hjÒ  hžhubhÃ)”}”(hŒ0Typical usage of the OPP library is as follows::”h]”hŒ/Typical usage of the OPP library is as follows:”…””}”(hŒ/Typical usage of the OPP library is as follows:”hjñ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h K7hjÒ  hžhubhŒliteral_block”“”)”}”(hŒÙ(users)        -> registers a set of default OPPs              -> (library)
SoC framework  -> modifies on required cases certain OPPs      -> OPP layer
               -> queries to search/retrieve information       ->”h]”hŒÙ(users)        -> registers a set of default OPPs              -> (library)
SoC framework  -> modifies on required cases certain OPPs      -> OPP layer
               -> queries to search/retrieve information       ->”…””}”(hhhj  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1j   hŸh¶h K9hjÒ  hžhubhÃ)”}”(hX`  OPP layer expects each domain to be represented by a unique device pointer. SoC
framework registers a set of initial OPPs per device with the OPP layer. This
list is expected to be an optimally small number typically around 5 per device.
This initial list contains a set of OPPs that the framework expects to be safely
enabled by default in the system.”h]”hX`  OPP layer expects each domain to be represented by a unique device pointer. SoC
framework registers a set of initial OPPs per device with the OPP layer. This
list is expected to be an optimally small number typically around 5 per device.
This initial list contains a set of OPPs that the framework expects to be safely
enabled by default in the system.”…””}”(hj  hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h K=hjÒ  hžhubh¢)”}”(hhh]”(h§)”}”(hŒNote on OPP Availability”h]”hŒNote on OPP Availability”…””}”(hj#  hj!  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h KDubhÃ)”}”(hXp  As the system proceeds to operate, SoC framework may choose to make certain
OPPs available or not available on each device based on various external
factors. Example usage: Thermal management or other exceptional situations where
SoC framework might choose to disable a higher frequency OPP to safely continue
operations until that OPP could be re-enabled if possible.”h]”hXp  As the system proceeds to operate, SoC framework may choose to make certain
OPPs available or not available on each device based on various external
factors. Example usage: Thermal management or other exceptional situations where
SoC framework might choose to disable a higher frequency OPP to safely continue
operations until that OPP could be re-enabled if possible.”…””}”(hj1  hj/  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h KFhj  hžhubhÃ)”}”(hŒêOPP library facilitates this concept in its implementation. The following
operational functions operate only on available opps:
dev_pm_opp_find_freq_{ceil, floor}, dev_pm_opp_get_voltage, dev_pm_opp_get_freq,
dev_pm_opp_get_opp_count.”h]”hŒêOPP library facilitates this concept in its implementation. The following
operational functions operate only on available opps:
dev_pm_opp_find_freq_{ceil, floor}, dev_pm_opp_get_voltage, dev_pm_opp_get_freq,
dev_pm_opp_get_opp_count.”…””}”(hj?  hj=  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h KLhj  hžhubhÃ)”}”(hŒ«dev_pm_opp_find_freq_exact is meant to be used to find the opp pointer
which can then be used for dev_pm_opp_enable/disable functions to make an
opp available as required.”h]”hŒ«dev_pm_opp_find_freq_exact is meant to be used to find the opp pointer
which can then be used for dev_pm_opp_enable/disable functions to make an
opp available as required.”…””}”(hjM  hjK  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h KQhj  hžhubhÃ)”}”(hX¿  WARNING: Users of OPP library should refresh their availability count using
get_opp_count if dev_pm_opp_enable/disable functions are invoked for a
device, the exact mechanism to trigger these or the notification mechanism
to other dependent subsystems such as cpufreq are left to the discretion of
the SoC specific framework which uses the OPP library. Similar care needs
to be taken care to refresh the cpufreq table in cases of these operations.”h]”hX¿  WARNING: Users of OPP library should refresh their availability count using
get_opp_count if dev_pm_opp_enable/disable functions are invoked for a
device, the exact mechanism to trigger these or the notification mechanism
to other dependent subsystems such as cpufreq are left to the discretion of
the SoC specific framework which uses the OPP library. Similar care needs
to be taken care to refresh the cpufreq table in cases of these operations.”…””}”(hj[  hjY  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h KUhj  hžhubeh}”(h]”Œnote-on-opp-availability”ah ]”h"]”Œnote on opp availability”ah$]”h&]”uh1h¡hjÒ  hžhhŸh¶h KDubeh}”(h]”Œ$operating-performance-points-library”ah ]”h"]”Œ(1.2 operating performance points library”ah$]”h&]”uh1h¡hj  hžhhŸh¶h K.ubeh}”(h]”Œintroduction”ah ]”h"]”Œ1. introduction”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ 2. Initial OPP List Registration”h]”hŒ 2. Initial OPP List Registration”…””}”(hj„  hj‚  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h K]ubhÃ)”}”(hX¾  The SoC implementation calls dev_pm_opp_add function iteratively to add OPPs per
device. It is expected that the SoC framework will register the OPP entries
optimally- typical numbers range to be less than 5. The list generated by
registering the OPPs is maintained by OPP library throughout the device
operation. The SoC framework can subsequently control the availability of the
OPPs dynamically using the dev_pm_opp_enable / disable functions.”h]”hX¾  The SoC implementation calls dev_pm_opp_add function iteratively to add OPPs per
device. It is expected that the SoC framework will register the OPP entries
optimally- typical numbers range to be less than 5. The list generated by
registering the OPPs is maintained by OPP library throughout the device
operation. The SoC framework can subsequently control the availability of the
OPPs dynamically using the dev_pm_opp_enable / disable functions.”…””}”(hj’  hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h K^hj  hžhubhŒdefinition_list”“”)”}”(hhh]”hŒdefinition_list_item”“”)”}”(hXX  dev_pm_opp_add
Add a new OPP for a specific domain represented by the device pointer.
The OPP is defined using the frequency and voltage. Once added, the OPP
is assumed to be available and control of its availability can be done
with the dev_pm_opp_enable/disable functions. OPP library
internally stores and manages this information in the dev_pm_opp struct.
This function may be used by SoC framework to define a optimal list
as per the demands of SoC usage environment.

WARNING:
        Do not use this function in interrupt context.

Example::

 soc_pm_init()
 {
        /* Do things */
        r = dev_pm_opp_add(mpu_dev, 1000000, 900000);
        if (!r) {
                pr_err("%s: unable to register mpu opp(%d)\n", r);
                goto no_cpufreq;
        }
        /* Do cpufreq things */
 no_cpufreq:
        /* Do remaining things */
 }
”h]”(hŒterm”“”)”}”(hŒdev_pm_opp_add”h]”hŒdev_pm_opp_add”…””}”(hj­  hj«  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©  hŸh¶h K~hj¥  ubhŒ
definition”“”)”}”(hhh]”(hÃ)”}”(hXÉ  Add a new OPP for a specific domain represented by the device pointer.
The OPP is defined using the frequency and voltage. Once added, the OPP
is assumed to be available and control of its availability can be done
with the dev_pm_opp_enable/disable functions. OPP library
internally stores and manages this information in the dev_pm_opp struct.
This function may be used by SoC framework to define a optimal list
as per the demands of SoC usage environment.”h]”hXÉ  Add a new OPP for a specific domain represented by the device pointer.
The OPP is defined using the frequency and voltage. Once added, the OPP
is assumed to be available and control of its availability can be done
with the dev_pm_opp_enable/disable functions. OPP library
internally stores and manages this information in the dev_pm_opp struct.
This function may be used by SoC framework to define a optimal list
as per the demands of SoC usage environment.”…””}”(hjÀ  hj¾  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h Kfhj»  ubjŸ  )”}”(hhh]”j¤  )”}”(hŒ8WARNING:
Do not use this function in interrupt context.
”h]”(jª  )”}”(hŒWARNING:”h]”hŒWARNING:”…””}”(hjÕ  hjÓ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©  hŸh¶h KohjÏ  ubjº  )”}”(hhh]”hÃ)”}”(hŒ.Do not use this function in interrupt context.”h]”hŒ.Do not use this function in interrupt context.”…””}”(hjæ  hjä  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h Kohjá  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¹  hjÏ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j£  hŸh¶h KohjÌ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jž  hj»  ubhÃ)”}”(hŒ	Example::”h]”hŒExample:”…””}”(hŒExample:”hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h Kqhj»  ubj  )”}”(hX%  soc_pm_init()
{
       /* Do things */
       r = dev_pm_opp_add(mpu_dev, 1000000, 900000);
       if (!r) {
               pr_err("%s: unable to register mpu opp(%d)\n", r);
               goto no_cpufreq;
       }
       /* Do cpufreq things */
no_cpufreq:
       /* Do remaining things */
}”h]”hX%  soc_pm_init()
{
       /* Do things */
       r = dev_pm_opp_add(mpu_dev, 1000000, 900000);
       if (!r) {
               pr_err("%s: unable to register mpu opp(%d)\n", r);
               goto no_cpufreq;
       }
       /* Do cpufreq things */
no_cpufreq:
       /* Do remaining things */
}”…””}”(hhhj  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1j   hŸh¶h Kshj»  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j¹  hj¥  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j£  hŸh¶h K~hj   ubah}”(h]”h ]”h"]”h$]”h&]”uh1jž  hj  hžhhŸh¶h Nubeh}”(h]”Œinitial-opp-list-registration”ah ]”h"]”Œ 2. initial opp list registration”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K]ubh¢)”}”(hhh]”(h§)”}”(hŒ3. OPP Search Functions”h]”hŒ3. OPP Search Functions”…””}”(hj@  hj>  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj;  hžhhŸh¶h KubhÃ)”}”(hXÂ  High level framework such as cpufreq operates on frequencies. To map the
frequency back to the corresponding OPP, OPP library provides handy functions
to search the OPP list that OPP library internally manages. These search
functions return the matching pointer representing the opp if a match is
found, else returns error. These errors are expected to be handled by standard
error checks such as IS_ERR() and appropriate actions taken by the caller.”h]”hXÂ  High level framework such as cpufreq operates on frequencies. To map the
frequency back to the corresponding OPP, OPP library provides handy functions
to search the OPP list that OPP library internally manages. These search
functions return the matching pointer representing the opp if a match is
found, else returns error. These errors are expected to be handled by standard
error checks such as IS_ERR() and appropriate actions taken by the caller.”…””}”(hjN  hjL  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h K‚hj;  hžhubhÃ)”}”(hŒ¡Callers of these functions shall call dev_pm_opp_put() after they have used the
OPP. Otherwise the memory for the OPP will never get freed and result in
memleak.”h]”hŒ¡Callers of these functions shall call dev_pm_opp_put() after they have used the
OPP. Otherwise the memory for the OPP will never get freed and result in
memleak.”…””}”(hj\  hjZ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h K‰hj;  hžhubjŸ  )”}”(hhh]”(j¤  )”}”(hX  dev_pm_opp_find_freq_exact
Search for an OPP based on an *exact* frequency and
availability. This function is especially useful to enable an OPP which
is not available by default.
Example: In a case when SoC framework detects a situation where a
higher frequency could be made available, it can use this function to
find the OPP prior to call the dev_pm_opp_enable to actually make
it available::

 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
 dev_pm_opp_put(opp);
 /* dont operate on the pointer.. just do a sanity check.. */
 if (IS_ERR(opp)) {
        pr_err("frequency not disabled!\n");
        /* trigger appropriate actions.. */
 } else {
        dev_pm_opp_enable(dev,1000000000);
 }

NOTE:
  This is the only search function that operates on OPPs which are
  not available.
”h]”(jª  )”}”(hŒdev_pm_opp_find_freq_exact”h]”hŒdev_pm_opp_find_freq_exact”…””}”(hjq  hjo  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©  hŸh¶h K¢hjk  ubjº  )”}”(hhh]”(hÃ)”}”(hXq  Search for an OPP based on an *exact* frequency and
availability. This function is especially useful to enable an OPP which
is not available by default.
Example: In a case when SoC framework detects a situation where a
higher frequency could be made available, it can use this function to
find the OPP prior to call the dev_pm_opp_enable to actually make
it available::”h]”(hŒSearch for an OPP based on an ”…””}”(hŒSearch for an OPP based on an ”hj€  hžhhŸNh NubhŒemphasis”“”)”}”(hŒ*exact*”h]”hŒexact”…””}”(hhhj‹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j‰  hj€  ubhXK   frequency and
availability. This function is especially useful to enable an OPP which
is not available by default.
Example: In a case when SoC framework detects a situation where a
higher frequency could be made available, it can use this function to
find the OPP prior to call the dev_pm_opp_enable to actually make
it available:”…””}”(hXK   frequency and
availability. This function is especially useful to enable an OPP which
is not available by default.
Example: In a case when SoC framework detects a situation where a
higher frequency could be made available, it can use this function to
find the OPP prior to call the dev_pm_opp_enable to actually make
it available:”hj€  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h KŽhj}  ubj  )”}”(hX*  opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
dev_pm_opp_put(opp);
/* dont operate on the pointer.. just do a sanity check.. */
if (IS_ERR(opp)) {
       pr_err("frequency not disabled!\n");
       /* trigger appropriate actions.. */
} else {
       dev_pm_opp_enable(dev,1000000000);
}”h]”hX*  opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
dev_pm_opp_put(opp);
/* dont operate on the pointer.. just do a sanity check.. */
if (IS_ERR(opp)) {
       pr_err("frequency not disabled!\n");
       /* trigger appropriate actions.. */
} else {
       dev_pm_opp_enable(dev,1000000000);
}”…””}”(hhhj¤  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1j   hŸh¶h K–hj}  ubjŸ  )”}”(hhh]”j¤  )”}”(hŒVNOTE:
This is the only search function that operates on OPPs which are
not available.
”h]”(jª  )”}”(hŒNOTE:”h]”hŒNOTE:”…””}”(hj»  hj¹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©  hŸh¶h K¢hjµ  ubjº  )”}”(hhh]”hÃ)”}”(hŒOThis is the only search function that operates on OPPs which are
not available.”h]”hŒOThis is the only search function that operates on OPPs which are
not available.”…””}”(hjÌ  hjÊ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h K¡hjÇ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¹  hjµ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j£  hŸh¶h K¢hj²  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jž  hj}  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j¹  hjk  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j£  hŸh¶h K¢hjh  ubj¤  )”}”(hXl  dev_pm_opp_find_freq_floor
Search for an available OPP which is *at most* the
provided frequency. This function is useful while searching for a lesser
match OR operating on OPP information in the order of decreasing
frequency.
Example: To find the highest opp for a device::

 freq = ULONG_MAX;
 opp = dev_pm_opp_find_freq_floor(dev, &freq);
 dev_pm_opp_put(opp);
”h]”(jª  )”}”(hŒdev_pm_opp_find_freq_floor”h]”hŒdev_pm_opp_find_freq_floor”…””}”(hjü  hjú  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©  hŸh¶h K­hjö  ubjº  )”}”(hhh]”(hÃ)”}”(hŒ÷Search for an available OPP which is *at most* the
provided frequency. This function is useful while searching for a lesser
match OR operating on OPP information in the order of decreasing
frequency.
Example: To find the highest opp for a device::”h]”(hŒ%Search for an available OPP which is ”…””}”(hŒ%Search for an available OPP which is ”hj  hžhhŸNh NubjŠ  )”}”(hŒ	*at most*”h]”hŒat most”…””}”(hhhj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j‰  hj  ubhŒÈ the
provided frequency. This function is useful while searching for a lesser
match OR operating on OPP information in the order of decreasing
frequency.
Example: To find the highest opp for a device:”…””}”(hŒÈ the
provided frequency. This function is useful while searching for a lesser
match OR operating on OPP information in the order of decreasing
frequency.
Example: To find the highest opp for a device:”hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h K¥hj  ubj  )”}”(hŒTfreq = ULONG_MAX;
opp = dev_pm_opp_find_freq_floor(dev, &freq);
dev_pm_opp_put(opp);”h]”hŒTfreq = ULONG_MAX;
opp = dev_pm_opp_find_freq_floor(dev, &freq);
dev_pm_opp_put(opp);”…””}”(hhhj-  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1j   hŸh¶h K«hj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j¹  hjö  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j£  hŸh¶h K­hjh  hžhubj¤  )”}”(hX=  dev_pm_opp_find_freq_ceil
Search for an available OPP which is *at least* the
provided frequency. This function is useful while searching for a
higher match OR operating on OPP information in the order of increasing
frequency.
Example 1: To find the lowest opp for a device::

 freq = 0;
 opp = dev_pm_opp_find_freq_ceil(dev, &freq);
 dev_pm_opp_put(opp);

Example 2: A simplified implementation of a SoC cpufreq_driver->target::

 soc_cpufreq_target(..)
 {
        /* Do stuff like policy checks etc. */
        /* Find the best frequency match for the req */
        opp = dev_pm_opp_find_freq_ceil(dev, &freq);
        dev_pm_opp_put(opp);
        if (!IS_ERR(opp))
                soc_switch_to_freq_voltage(freq);
        else
                /* do something when we can't satisfy the req */
        /* do other stuff */
 }
”h]”(jª  )”}”(hŒdev_pm_opp_find_freq_ceil”h]”hŒdev_pm_opp_find_freq_ceil”…””}”(hjM  hjK  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©  hŸh¶h KÇhjG  ubjº  )”}”(hhh]”(hÃ)”}”(hŒùSearch for an available OPP which is *at least* the
provided frequency. This function is useful while searching for a
higher match OR operating on OPP information in the order of increasing
frequency.
Example 1: To find the lowest opp for a device::”h]”(hŒ%Search for an available OPP which is ”…””}”(hŒ%Search for an available OPP which is ”hj\  hžhhŸNh NubjŠ  )”}”(hŒ
*at least*”h]”hŒat least”…””}”(hhhje  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j‰  hj\  ubhŒÉ the
provided frequency. This function is useful while searching for a
higher match OR operating on OPP information in the order of increasing
frequency.
Example 1: To find the lowest opp for a device:”…””}”(hŒÉ the
provided frequency. This function is useful while searching for a
higher match OR operating on OPP information in the order of increasing
frequency.
Example 1: To find the lowest opp for a device:”hj\  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h K°hjY  ubj  )”}”(hŒKfreq = 0;
opp = dev_pm_opp_find_freq_ceil(dev, &freq);
dev_pm_opp_put(opp);”h]”hŒKfreq = 0;
opp = dev_pm_opp_find_freq_ceil(dev, &freq);
dev_pm_opp_put(opp);”…””}”(hhhj~  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1j   hŸh¶h K¶hjY  ubhÃ)”}”(hŒHExample 2: A simplified implementation of a SoC cpufreq_driver->target::”h]”hŒGExample 2: A simplified implementation of a SoC cpufreq_driver->target:”…””}”(hŒGExample 2: A simplified implementation of a SoC cpufreq_driver->target:”hjŒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h KºhjY  ubj  )”}”(hX  soc_cpufreq_target(..)
{
       /* Do stuff like policy checks etc. */
       /* Find the best frequency match for the req */
       opp = dev_pm_opp_find_freq_ceil(dev, &freq);
       dev_pm_opp_put(opp);
       if (!IS_ERR(opp))
               soc_switch_to_freq_voltage(freq);
       else
               /* do something when we can't satisfy the req */
       /* do other stuff */
}”h]”hX  soc_cpufreq_target(..)
{
       /* Do stuff like policy checks etc. */
       /* Find the best frequency match for the req */
       opp = dev_pm_opp_find_freq_ceil(dev, &freq);
       dev_pm_opp_put(opp);
       if (!IS_ERR(opp))
               soc_switch_to_freq_voltage(freq);
       else
               /* do something when we can't satisfy the req */
       /* do other stuff */
}”…””}”(hhhj›  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1j   hŸh¶h K¼hjY  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j¹  hjG  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j£  hŸh¶h KÇhjh  hžhubeh}”(h]”h ]”h"]”h$]”h&]”uh1jž  hj;  hžhhŸNh Nubeh}”(h]”Œopp-search-functions”ah ]”h"]”Œ3. opp search functions”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ%4. OPP Availability Control Functions”h]”hŒ%4. OPP Availability Control Functions”…””}”(hjÈ  hjÆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjÃ  hžhhŸh¶h KÊubhÃ)”}”(hXÏ  A default OPP list registered with the OPP library may not cater to all possible
situation. The OPP library provides a set of functions to modify the
availability of a OPP within the OPP list. This allows SoC frameworks to have
fine grained dynamic control of which sets of OPPs are operationally available.
These functions are intended to *temporarily* remove an OPP in conditions such
as thermal considerations (e.g. don't use OPPx until the temperature drops).”h]”(hXT  A default OPP list registered with the OPP library may not cater to all possible
situation. The OPP library provides a set of functions to modify the
availability of a OPP within the OPP list. This allows SoC frameworks to have
fine grained dynamic control of which sets of OPPs are operationally available.
These functions are intended to ”…””}”(hXT  A default OPP list registered with the OPP library may not cater to all possible
situation. The OPP library provides a set of functions to modify the
availability of a OPP within the OPP list. This allows SoC frameworks to have
fine grained dynamic control of which sets of OPPs are operationally available.
These functions are intended to ”hjÔ  hžhhŸNh NubjŠ  )”}”(hŒ*temporarily*”h]”hŒtemporarily”…””}”(hhhjÝ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j‰  hjÔ  ubhŒp remove an OPP in conditions such
as thermal considerations (e.g. donâ€™t use OPPx until the temperature drops).”…””}”(hŒn remove an OPP in conditions such
as thermal considerations (e.g. don't use OPPx until the temperature drops).”hjÔ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h KËhjÃ  hžhubjŸ  )”}”(hhh]”(j¤  )”}”(hŒ:WARNING:
Do not use these functions in interrupt context.
”h]”(jª  )”}”(hŒWARNING:”h]”hŒWARNING:”…””}”(hjÿ  hjý  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©  hŸh¶h KÓhjù  ubjº  )”}”(hhh]”hÃ)”}”(hŒ0Do not use these functions in interrupt context.”h]”hŒ0Do not use these functions in interrupt context.”…””}”(hj  hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h KÓhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¹  hjù  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j£  hŸh¶h KÓhjö  ubj¤  )”}”(hXT  dev_pm_opp_enable
Make a OPP available for operation.
Example: Lets say that 1GHz OPP is to be made available only if the
SoC temperature is lower than a certain threshold. The SoC framework
implementation might choose to do something as follows::

 if (cur_temp < temp_low_thresh) {
        /* Enable 1GHz if it was disabled */
        opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
        dev_pm_opp_put(opp);
        /* just error check */
        if (!IS_ERR(opp))
                ret = dev_pm_opp_enable(dev, 1000000000);
        else
                goto try_something_else;
 }
”h]”(jª  )”}”(hŒdev_pm_opp_enable”h]”hŒdev_pm_opp_enable”…””}”(hj.  hj,  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©  hŸh¶h Kähj(  ubjº  )”}”(hhh]”(hÃ)”}”(hŒåMake a OPP available for operation.
Example: Lets say that 1GHz OPP is to be made available only if the
SoC temperature is lower than a certain threshold. The SoC framework
implementation might choose to do something as follows::”h]”hŒäMake a OPP available for operation.
Example: Lets say that 1GHz OPP is to be made available only if the
SoC temperature is lower than a certain threshold. The SoC framework
implementation might choose to do something as follows:”…””}”(hŒäMake a OPP available for operation.
Example: Lets say that 1GHz OPP is to be made available only if the
SoC temperature is lower than a certain threshold. The SoC framework
implementation might choose to do something as follows:”hj=  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h KÖhj:  ubj  )”}”(hXP  if (cur_temp < temp_low_thresh) {
       /* Enable 1GHz if it was disabled */
       opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
       dev_pm_opp_put(opp);
       /* just error check */
       if (!IS_ERR(opp))
               ret = dev_pm_opp_enable(dev, 1000000000);
       else
               goto try_something_else;
}”h]”hXP  if (cur_temp < temp_low_thresh) {
       /* Enable 1GHz if it was disabled */
       opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
       dev_pm_opp_put(opp);
       /* just error check */
       if (!IS_ERR(opp))
               ret = dev_pm_opp_enable(dev, 1000000000);
       else
               goto try_something_else;
}”…””}”(hhhjL  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1j   hŸh¶h KÛhj:  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j¹  hj(  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j£  hŸh¶h Kähjö  hžhubj¤  )”}”(hXI  dev_pm_opp_disable
Make an OPP to be not available for operation
Example: Lets say that 1GHz OPP is to be disabled if the temperature
exceeds a threshold value. The SoC framework implementation might
choose to do something as follows::

 if (cur_temp > temp_high_thresh) {
        /* Disable 1GHz if it was enabled */
        opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true);
        dev_pm_opp_put(opp);
        /* just error check */
        if (!IS_ERR(opp))
                ret = dev_pm_opp_disable(dev, 1000000000);
        else
                goto try_something_else;
 }
”h]”(jª  )”}”(hŒdev_pm_opp_disable”h]”hŒdev_pm_opp_disable”…””}”(hjl  hjj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©  hŸh¶h Kõhjf  ubjº  )”}”(hhh]”(hÃ)”}”(hŒØMake an OPP to be not available for operation
Example: Lets say that 1GHz OPP is to be disabled if the temperature
exceeds a threshold value. The SoC framework implementation might
choose to do something as follows::”h]”hŒ×Make an OPP to be not available for operation
Example: Lets say that 1GHz OPP is to be disabled if the temperature
exceeds a threshold value. The SoC framework implementation might
choose to do something as follows:”…””}”(hŒ×Make an OPP to be not available for operation
Example: Lets say that 1GHz OPP is to be disabled if the temperature
exceeds a threshold value. The SoC framework implementation might
choose to do something as follows:”hj{  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h Kçhjx  ubj  )”}”(hXQ  if (cur_temp > temp_high_thresh) {
       /* Disable 1GHz if it was enabled */
       opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true);
       dev_pm_opp_put(opp);
       /* just error check */
       if (!IS_ERR(opp))
               ret = dev_pm_opp_disable(dev, 1000000000);
       else
               goto try_something_else;
}”h]”hXQ  if (cur_temp > temp_high_thresh) {
       /* Disable 1GHz if it was enabled */
       opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true);
       dev_pm_opp_put(opp);
       /* just error check */
       if (!IS_ERR(opp))
               ret = dev_pm_opp_disable(dev, 1000000000);
       else
               goto try_something_else;
}”…””}”(hhhjŠ  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1j   hŸh¶h Kìhjx  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j¹  hjf  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j£  hŸh¶h Kõhjö  hžhubeh}”(h]”h ]”h"]”h$]”h&]”uh1jž  hjÃ  hžhhŸh¶h Nubeh}”(h]”Œ"opp-availability-control-functions”ah ]”h"]”Œ%4. opp availability control functions”ah$]”h&]”uh1h¡hh£hžhhŸh¶h KÊubh¢)”}”(hhh]”(h§)”}”(hŒ5. OPP Data Retrieval Functions”h]”hŒ5. OPP Data Retrieval Functions”…””}”(hj·  hjµ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj²  hžhhŸh¶h KøubhÃ)”}”(hX8  Since OPP library abstracts away the OPP information, a set of functions to pull
information from the dev_pm_opp structure is necessary. Once an OPP pointer is
retrieved using the search functions, the following functions can be used by SoC
framework to retrieve the information represented inside the OPP layer.”h]”hX8  Since OPP library abstracts away the OPP information, a set of functions to pull
information from the dev_pm_opp structure is necessary. Once an OPP pointer is
retrieved using the search functions, the following functions can be used by SoC
framework to retrieve the information represented inside the OPP layer.”…””}”(hjÅ  hjÃ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h Kùhj²  hžhubjŸ  )”}”(hhh]”(j¤  )”}”(hX2  dev_pm_opp_get_voltage
Retrieve the voltage represented by the opp pointer.
Example: At a cpufreq transition to a different frequency, SoC
framework requires to set the voltage represented by the OPP using
the regulator framework to the Power Management chip providing the
voltage::

 soc_switch_to_freq_voltage(freq)
 {
        /* do things */
        opp = dev_pm_opp_find_freq_ceil(dev, &freq);
        v = dev_pm_opp_get_voltage(opp);
        dev_pm_opp_put(opp);
        if (v)
                regulator_set_voltage(.., v);
        /* do other things */
 }
”h]”(jª  )”}”(hŒdev_pm_opp_get_voltage”h]”hŒdev_pm_opp_get_voltage”…””}”(hjÚ  hjØ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©  hŸh¶h MhjÔ  ubjº  )”}”(hhh]”(hÃ)”}”(hX  Retrieve the voltage represented by the opp pointer.
Example: At a cpufreq transition to a different frequency, SoC
framework requires to set the voltage represented by the OPP using
the regulator framework to the Power Management chip providing the
voltage::”h]”hX  Retrieve the voltage represented by the opp pointer.
Example: At a cpufreq transition to a different frequency, SoC
framework requires to set the voltage represented by the OPP using
the regulator framework to the Power Management chip providing the
voltage:”…””}”(hX  Retrieve the voltage represented by the opp pointer.
Example: At a cpufreq transition to a different frequency, SoC
framework requires to set the voltage represented by the OPP using
the regulator framework to the Power Management chip providing the
voltage:”hjé  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h Kÿhjæ  ubj  )”}”(hX  soc_switch_to_freq_voltage(freq)
{
       /* do things */
       opp = dev_pm_opp_find_freq_ceil(dev, &freq);
       v = dev_pm_opp_get_voltage(opp);
       dev_pm_opp_put(opp);
       if (v)
               regulator_set_voltage(.., v);
       /* do other things */
}”h]”hX  soc_switch_to_freq_voltage(freq)
{
       /* do things */
       opp = dev_pm_opp_find_freq_ceil(dev, &freq);
       v = dev_pm_opp_get_voltage(opp);
       dev_pm_opp_put(opp);
       if (v)
               regulator_set_voltage(.., v);
       /* do other things */
}”…””}”(hhhjø  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1j   hŸh¶h Mhjæ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j¹  hjÔ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j£  hŸh¶h MhjÑ  ubj¤  )”}”(hXË  dev_pm_opp_get_freq
Retrieve the freq represented by the opp pointer.
Example: Lets say the SoC framework uses a couple of helper functions
we could pass opp pointers instead of doing additional parameters to
handle quiet a bit of data parameters::

 soc_cpufreq_target(..)
 {
        /* do things.. */
         max_freq = ULONG_MAX;
         max_opp = dev_pm_opp_find_freq_floor(dev,&max_freq);
         requested_opp = dev_pm_opp_find_freq_ceil(dev,&freq);
         if (!IS_ERR(max_opp) && !IS_ERR(requested_opp))
                r = soc_test_validity(max_opp, requested_opp);
         dev_pm_opp_put(max_opp);
         dev_pm_opp_put(requested_opp);
        /* do other things */
 }
 soc_test_validity(..)
 {
         if(dev_pm_opp_get_voltage(max_opp) < dev_pm_opp_get_voltage(requested_opp))
                 return -EINVAL;
         if(dev_pm_opp_get_freq(max_opp) < dev_pm_opp_get_freq(requested_opp))
                 return -EINVAL;
        /* do things.. */
 }
”h]”(jª  )”}”(hŒdev_pm_opp_get_freq”h]”hŒdev_pm_opp_get_freq”…””}”(hj  hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©  hŸh¶h M)hj  ubjº  )”}”(hhh]”(hÃ)”}”(hŒäRetrieve the freq represented by the opp pointer.
Example: Lets say the SoC framework uses a couple of helper functions
we could pass opp pointers instead of doing additional parameters to
handle quiet a bit of data parameters::”h]”hŒãRetrieve the freq represented by the opp pointer.
Example: Lets say the SoC framework uses a couple of helper functions
we could pass opp pointers instead of doing additional parameters to
handle quiet a bit of data parameters:”…””}”(hŒãRetrieve the freq represented by the opp pointer.
Example: Lets say the SoC framework uses a couple of helper functions
we could pass opp pointers instead of doing additional parameters to
handle quiet a bit of data parameters:”hj'  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h Mhj$  ubj  )”}”(hX¼  soc_cpufreq_target(..)
{
       /* do things.. */
        max_freq = ULONG_MAX;
        max_opp = dev_pm_opp_find_freq_floor(dev,&max_freq);
        requested_opp = dev_pm_opp_find_freq_ceil(dev,&freq);
        if (!IS_ERR(max_opp) && !IS_ERR(requested_opp))
               r = soc_test_validity(max_opp, requested_opp);
        dev_pm_opp_put(max_opp);
        dev_pm_opp_put(requested_opp);
       /* do other things */
}
soc_test_validity(..)
{
        if(dev_pm_opp_get_voltage(max_opp) < dev_pm_opp_get_voltage(requested_opp))
                return -EINVAL;
        if(dev_pm_opp_get_freq(max_opp) < dev_pm_opp_get_freq(requested_opp))
                return -EINVAL;
       /* do things.. */
}”h]”hX¼  soc_cpufreq_target(..)
{
       /* do things.. */
        max_freq = ULONG_MAX;
        max_opp = dev_pm_opp_find_freq_floor(dev,&max_freq);
        requested_opp = dev_pm_opp_find_freq_ceil(dev,&freq);
        if (!IS_ERR(max_opp) && !IS_ERR(requested_opp))
               r = soc_test_validity(max_opp, requested_opp);
        dev_pm_opp_put(max_opp);
        dev_pm_opp_put(requested_opp);
       /* do other things */
}
soc_test_validity(..)
{
        if(dev_pm_opp_get_voltage(max_opp) < dev_pm_opp_get_voltage(requested_opp))
                return -EINVAL;
        if(dev_pm_opp_get_freq(max_opp) < dev_pm_opp_get_freq(requested_opp))
                return -EINVAL;
       /* do things.. */
}”…””}”(hhhj6  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1j   hŸh¶h Mhj$  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j¹  hj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j£  hŸh¶h M)hjÑ  hžhubj¤  )”}”(hX
  dev_pm_opp_get_opp_count
Retrieve the number of available opps for a device
Example: Lets say a co-processor in the SoC needs to know the available
frequencies in a table, the main processor can notify as following::

 soc_notify_coproc_available_frequencies()
 {
        /* Do things */
        num_available = dev_pm_opp_get_opp_count(dev);
        speeds = kcalloc(num_available, sizeof(u32), GFP_KERNEL);
        /* populate the table in increasing order */
        freq = 0;
        while (!IS_ERR(opp = dev_pm_opp_find_freq_ceil(dev, &freq))) {
                speeds[i] = freq;
                freq++;
                i++;
                dev_pm_opp_put(opp);
        }

        soc_notify_coproc(AVAILABLE_FREQs, speeds, num_available);
        /* Do other things */
 }
”h]”(jª  )”}”(hŒdev_pm_opp_get_opp_count”h]”hŒdev_pm_opp_get_opp_count”…””}”(hjV  hjT  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©  hŸh¶h M@hjP  ubjº  )”}”(hhh]”(hÃ)”}”(hŒ¿Retrieve the number of available opps for a device
Example: Lets say a co-processor in the SoC needs to know the available
frequencies in a table, the main processor can notify as following::”h]”hŒ¾Retrieve the number of available opps for a device
Example: Lets say a co-processor in the SoC needs to know the available
frequencies in a table, the main processor can notify as following:”…””}”(hŒ¾Retrieve the number of available opps for a device
Example: Lets say a co-processor in the SoC needs to know the available
frequencies in a table, the main processor can notify as following:”hje  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h M,hjb  ubj  )”}”(hX  soc_notify_coproc_available_frequencies()
{
       /* Do things */
       num_available = dev_pm_opp_get_opp_count(dev);
       speeds = kcalloc(num_available, sizeof(u32), GFP_KERNEL);
       /* populate the table in increasing order */
       freq = 0;
       while (!IS_ERR(opp = dev_pm_opp_find_freq_ceil(dev, &freq))) {
               speeds[i] = freq;
               freq++;
               i++;
               dev_pm_opp_put(opp);
       }

       soc_notify_coproc(AVAILABLE_FREQs, speeds, num_available);
       /* Do other things */
}”h]”hX  soc_notify_coproc_available_frequencies()
{
       /* Do things */
       num_available = dev_pm_opp_get_opp_count(dev);
       speeds = kcalloc(num_available, sizeof(u32), GFP_KERNEL);
       /* populate the table in increasing order */
       freq = 0;
       while (!IS_ERR(opp = dev_pm_opp_find_freq_ceil(dev, &freq))) {
               speeds[i] = freq;
               freq++;
               i++;
               dev_pm_opp_put(opp);
       }

       soc_notify_coproc(AVAILABLE_FREQs, speeds, num_available);
       /* Do other things */
}”…””}”(hhhjt  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1j   hŸh¶h M0hjb  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j¹  hjP  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j£  hŸh¶h M@hjÑ  hžhubeh}”(h]”h ]”h"]”h$]”h&]”uh1jž  hj²  hžhhŸh¶h Nubeh}”(h]”Œopp-data-retrieval-functions”ah ]”h"]”Œ5. opp data retrieval functions”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Køubh¢)”}”(hhh]”(h§)”}”(hŒ6. Data Structures”h]”hŒ6. Data Structures”…””}”(hj¡  hjŸ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjœ  hžhhŸh¶h MCubhÃ)”}”(hŒ®Typically an SoC contains multiple voltage domains which are variable. Each
domain is represented by a device pointer. The relationship to OPP can be
represented as follows::”h]”hŒ­Typically an SoC contains multiple voltage domains which are variable. Each
domain is represented by a device pointer. The relationship to OPP can be
represented as follows:”…””}”(hŒ­Typically an SoC contains multiple voltage domains which are variable. Each
domain is represented by a device pointer. The relationship to OPP can be
represented as follows:”hj­  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h MDhjœ  hžhubj  )”}”(hŒŠSoC
 |- device 1
 |    |- opp 1 (availability, freq, voltage)
 |    |- opp 2 ..
 ...  ...
 |    `- opp n ..
 |- device 2
 ...
 `- device m”h]”hŒŠSoC
 |- device 1
 |    |- opp 1 (availability, freq, voltage)
 |    |- opp 2 ..
 ...  ...
 |    `- opp n ..
 |- device 2
 ...
 `- device m”…””}”(hhhj¼  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1j   hŸh¶h MHhjœ  hžhubhÃ)”}”(hX  OPP library maintains a internal list that the SoC framework populates and
accessed by various functions as described above. However, the structures
representing the actual OPPs and domains are internal to the OPP library itself
to allow for suitable abstraction reusable across systems.”h]”hX  OPP library maintains a internal list that the SoC framework populates and
accessed by various functions as described above. However, the structures
representing the actual OPPs and domains are internal to the OPP library itself
to allow for suitable abstraction reusable across systems.”…””}”(hjÌ  hjÊ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h MRhjœ  hžhubjŸ  )”}”(hhh]”(j¤  )”}”(hXˆ  struct dev_pm_opp
The internal data structure of OPP library which is used to
represent an OPP. In addition to the freq, voltage, availability
information, it also contains internal book keeping information required
for the OPP library to operate on.  Pointer to this structure is
provided back to the users such as SoC framework to be used as a
identifier for OPP in the interactions with OPP layer.

WARNING:
  The struct dev_pm_opp pointer should not be parsed or modified by the
  users. The defaults of for an instance is populated by
  dev_pm_opp_add, but the availability of the OPP can be modified
  by dev_pm_opp_enable/disable functions.
”h]”(jª  )”}”(hŒstruct dev_pm_opp”h]”hŒstruct dev_pm_opp”…””}”(hjá  hjß  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©  hŸh¶h MchjÛ  ubjº  )”}”(hhh]”(hÃ)”}”(hX~  The internal data structure of OPP library which is used to
represent an OPP. In addition to the freq, voltage, availability
information, it also contains internal book keeping information required
for the OPP library to operate on.  Pointer to this structure is
provided back to the users such as SoC framework to be used as a
identifier for OPP in the interactions with OPP layer.”h]”hX~  The internal data structure of OPP library which is used to
represent an OPP. In addition to the freq, voltage, availability
information, it also contains internal book keeping information required
for the OPP library to operate on.  Pointer to this structure is
provided back to the users such as SoC framework to be used as a
identifier for OPP in the interactions with OPP layer.”…””}”(hjò  hjð  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h MXhjí  ubjŸ  )”}”(hhh]”j¤  )”}”(hŒîWARNING:
The struct dev_pm_opp pointer should not be parsed or modified by the
users. The defaults of for an instance is populated by
dev_pm_opp_add, but the availability of the OPP can be modified
by dev_pm_opp_enable/disable functions.
”h]”(jª  )”}”(hŒWARNING:”h]”hŒWARNING:”…””}”(hj  hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©  hŸh¶h Mchj  ubjº  )”}”(hhh]”hÃ)”}”(hŒäThe struct dev_pm_opp pointer should not be parsed or modified by the
users. The defaults of for an instance is populated by
dev_pm_opp_add, but the availability of the OPP can be modified
by dev_pm_opp_enable/disable functions.”h]”hŒäThe struct dev_pm_opp pointer should not be parsed or modified by the
users. The defaults of for an instance is populated by
dev_pm_opp_add, but the availability of the OPP can be modified
by dev_pm_opp_enable/disable functions.”…””}”(hj  hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h M`hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¹  hj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j£  hŸh¶h Mchjþ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jž  hjí  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j¹  hjÛ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j£  hŸh¶h MchjØ  ubj¤  )”}”(hŒ°struct device
This is used to identify a domain to the OPP layer. The
nature of the device and its implementation is left to the user of
OPP library such as the SoC framework.
”h]”(jª  )”}”(hŒstruct device”h]”hŒstruct device”…””}”(hjH  hjF  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j©  hŸh¶h MhhjB  ubjº  )”}”(hhh]”hÃ)”}”(hŒ¡This is used to identify a domain to the OPP layer. The
nature of the device and its implementation is left to the user of
OPP library such as the SoC framework.”h]”hŒ¡This is used to identify a domain to the OPP layer. The
nature of the device and its implementation is left to the user of
OPP library such as the SoC framework.”…””}”(hjY  hjW  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h MfhjT  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¹  hjB  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j£  hŸh¶h MhhjØ  hžhubeh}”(h]”h ]”h"]”h$]”h&]”uh1jž  hjœ  hžhhŸNh NubhÃ)”}”(hŒZOverall, in a simplistic view, the data structure operations is represented as
following::”h]”hŒYOverall, in a simplistic view, the data structure operations is represented as
following:”…””}”(hŒYOverall, in a simplistic view, the data structure operations is represented as
following:”hjw  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhŸh¶h Mjhjœ  hžhubj  )”}”(hX  Initialization / modification:
            +-----+        /- dev_pm_opp_enable
dev_pm_opp_add --> | opp | <-------
  |         +-----+        \- dev_pm_opp_disable
  \-------> domain_info(device)

Search functions:
             /-- dev_pm_opp_find_freq_ceil  ---\   +-----+
domain_info<---- dev_pm_opp_find_freq_exact -----> | opp |
             \-- dev_pm_opp_find_freq_floor ---/   +-----+

Retrieval functions:
+-----+     /- dev_pm_opp_get_voltage
| opp | <---
+-----+     \- dev_pm_opp_get_freq

domain_info <- dev_pm_opp_get_opp_count”h]”hX  Initialization / modification:
            +-----+        /- dev_pm_opp_enable
dev_pm_opp_add --> | opp | <-------
  |         +-----+        \- dev_pm_opp_disable
  \-------> domain_info(device)

Search functions:
             /-- dev_pm_opp_find_freq_ceil  ---\   +-----+
domain_info<---- dev_pm_opp_find_freq_exact -----> | opp |
             \-- dev_pm_opp_find_freq_floor ---/   +-----+

Retrieval functions:
+-----+     /- dev_pm_opp_get_voltage
| opp | <---
+-----+     \- dev_pm_opp_get_freq

domain_info <- dev_pm_opp_get_opp_count”…””}”(hhhj†  ubah}”(h]”h ]”h"]”h$]”h&]”j  j  uh1j   hŸh¶h Mmhjœ  hžhubeh}”(h]”Œdata-structures”ah ]”h"]”Œ6. data structures”ah$]”h&]”uh1h¡hh£hžhhŸh¶h MCubeh}”(h]”Œ(operating-performance-points-opp-library”ah ]”h"]”Œ*operating performance points (opp) library”ah$]”h&]”uh1h¡hhhžhhŸh¶h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h¶uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¦NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jÇ  Œerror_encoding”ŒUTF-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h¶Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œembed_images”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(j¡  jž  j|  jy  jÏ  jÌ  jt  jq  jl  ji  j8  j5  jÀ  j½  j¯  j¬  j™  j–  j™  j–  uŒ	nametypes”}”(j¡  Nj|  NjÏ  Njt  Njl  Nj8  NjÀ  Nj¯  Nj™  Nj™  Nuh}”(jž  h£jy  j  jÌ  j   jq  jÒ  ji  j  j5  j  j½  j;  j¬  jÃ  j–  j²  j–  jœ  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”hŒsystem_message”“”)”}”(hhh]”hÃ)”}”(hŒ:Enumerated list start value not ordinal-1: "C" (ordinal 3)”h]”hŒ>Enumerated list start value not ordinal-1: â€œCâ€ (ordinal 3)”…””}”(hhhj/  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÂhj,  ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”ŒINFO”Œsource”h¶Œline”Kuh1j*  hh£hžhhŸh¶h KubaŒtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.