1.. SPDX-License-Identifier: GPL-2.0 2.. include:: ../disclaimer-zh_CN.rst 3 4:Original: Documentation/power/opp.rst 5 6:翻译: 7 8 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> 9 10====================== 11操作性能值（OPP）库 12====================== 13 14(C) 2009-2010 Nishanth Menon <nm@ti.com>, 德州仪器公司 15 16.. 目录 17 18 1. 简介 19 2. OPP链表初始注册 20 3. OPP搜索函数 21 4. OPP可用性控制函数 22 5. OPP数据检索函数 23 6. 数据结构 24 251. 简介 26======= 27 281.1 何为操作性能值（OPP）？ 29------------------------------ 30 31当今复杂的单片系统（SoC）由多个子模块组成，这些子模块会联合工作。在一个执行不同用例 32的操作系统中，并不是SoC中的所有模块都需要一直以最高频率工作。为了促成这一点，SoC中 33的子模块被分组为不同域，允许一些域以较低的电压和频率运行，而其它域则以较高的“电压/ 34频率对”运行。 35 36设备按域支持的由频率电压对组成的离散的元组的集合，被称为操作性能值（组），或OPPs。 37 38举例来说： 39 40让我们考虑一个支持下述频率、电压值的内存保护单元（MPU）设备： 41{300MHz，最低电压为1V}, {800MHz，最低电压为1.2V}, {1GHz，最低电压为1.3V} 42 43我们能将它们表示为3个OPP，如下述{Hz, uV}元组（译注：频率的单位是赫兹，电压的单位是 44微伏）。 45 46- {300000000, 1000000} 47- {800000000, 1200000} 48- {1000000000, 1300000} 49 501.2 操作性能值库 51---------------- 52 53OPP库提供了一组辅助函数来组织和查询OPP信息。该库位于drivers/opp/目录下，其头文件 54位于include/linux/pm_opp.h中。OPP库可以通过开启CONFIG_PM_OPP来启用。某些SoC， 55如德州仪器的OMAP框架允许在不需要cpufreq的情况下可选地在某一OPP下启动。 56 57OPP库的典型用法如下:: 58 59 （用户） -> 注册一个默认的OPP集合 -> （库） 60 （SoC框架） -> 在必要的情况下，对某些OPP进行修改 -> OPP layer 61 -> 搜索/检索信息的查询 -> 62 63OPP层期望每个域由一个唯一的设备指针来表示。SoC框架在OPP层为每个设备注册了一组初始 64OPP。这个链表的长度被期望是一个最优化的小数字，通常每个设备大约5个。初始链表包含了 65一个OPP集合，这个集合被期望能在系统中安全使能。 66 67关于OPP可用性的说明 68^^^^^^^^^^^^^^^^^^^ 69 70随着系统的运行，SoC框架可能会基于各种外部因素选择让某些OPP在每个设备上可用或不可用， 71示例：温度管理或其它异常场景中，SoC框架可能会选择禁用一个较高频率的OPP以安全地继续 72运行，直到该OPP被重新启用（如果可能）。 73 74OPP库在它的实现中达成了这个概念。以下操作函数只能对可用的OPP使用： 75dev_pm_opp_find_freq_{ceil, floor}, dev_pm_opp_get_voltage, 76dev_pm_opp_get_freq, dev_pm_opp_get_opp_count。 77 78dev_pm_opp_find_freq_exact是用来查找OPP指针的，该指针可被用在dev_pm_opp_enable/ 79disable函数，使一个OPP在被需要时变为可用。 80 81警告：如果对一个设备调用dev_pm_opp_enable/disable函数，OPP库的用户应该使用 82dev_pm_opp_get_opp_count来刷新OPP的可用性计数。触发这些的具体机制，或者对有依赖的 83子系统（比如cpufreq）的通知机制，都是由使用OPP库的SoC特定框架酌情处理的。在这些操作 84中，同样需要注意刷新cpufreq表。 85 862. OPP链表初始注册 87================== 88SoC的实现会迭代调用dev_pm_opp_add函数来增加每个设备的OPP。预期SoC框架将以最优的 89方式注册OPP条目 - 典型的数字范围小于5。通过注册OPP生成的OPP链表，在整个设备运行过程 90中由OPP库维护。SoC框架随后可以使用dev_pm_opp_enable / disable函数动态地 91控制OPP的可用性。 92 93dev_pm_opp_add 94 为设备指针所指向的特定域添加一个新的OPP。OPP是用频率和电压定义的。一旦完成 95 添加，OPP被认为是可用的，可以用dev_pm_opp_enable/disable函数来控制其可用性。 96 OPP库内部用dev_pm_opp结构体存储并管理这些信息。这个函数可以被SoC框架根据SoC 97 的使用环境的需求来定义一个最优链表。 98 99 警告： 100 不要在中断上下文使用这个函数。 101 102 示例:: 103 104 soc_pm_init() 105 { 106 /* 做一些事情 */ 107 r = dev_pm_opp_add(mpu_dev, 1000000, 900000); 108 if (!r) { 109 pr_err("%s: unable to register mpu opp(%d)\n", r); 110 goto no_cpufreq; 111 } 112 /* 做一些和cpufreq相关的事情 */ 113 no_cpufreq: 114 /* 做剩余的事情 */ 115 } 116 1173. OPP搜索函数 118============== 119cpufreq等高层框架对频率进行操作，为了将频率映射到相应的OPP，OPP库提供了便利的函数 120来搜索OPP库内部管理的OPP链表。这些搜索函数如果找到匹配的OPP，将返回指向该OPP的指针， 121否则返回错误。这些错误预计由标准的错误检查，如IS_ERR()来处理，并由调用者采取适当的 122行动。 123 124这些函数的调用者应在使用完OPP后调用dev_pm_opp_put()。否则，OPP的内存将永远不会 125被释放，并导致内存泄露。 126 127dev_pm_opp_find_freq_exact 128 根据 *精确的* 频率和可用性来搜索OPP。这个函数对默认不可用的OPP特别有用。 129 例子：在SoC框架检测到更高频率可用的情况下，它可以使用这个函数在调用 130 dev_pm_opp_enable之前找到OPP:: 131 132 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false); 133 dev_pm_opp_put(opp); 134 /* 不要操作指针.. 只是做有效性检查.. */ 135 if (IS_ERR(opp)) { 136 pr_err("frequency not disabled!\n"); 137 /* 触发合适的操作.. */ 138 } else { 139 dev_pm_opp_enable(dev,1000000000); 140 } 141 142 注意： 143 这是唯一一个可以搜索不可用OPP的函数。 144 145dev_pm_opp_find_freq_floor 146 搜索一个 *最多* 提供指定频率的可用OPP。这个函数在搜索较小的匹配或按频率 147 递减的顺序操作OPP信息时很有用。 148 例子：要找的一个设备的最高OPP:: 149 150 freq = ULONG_MAX; 151 opp = dev_pm_opp_find_freq_floor(dev, &freq); 152 dev_pm_opp_put(opp); 153 154dev_pm_opp_find_freq_ceil 155 搜索一个 *最少* 提供指定频率的可用OPP。这个函数在搜索较大的匹配或按频率 156 递增的顺序操作OPP信息时很有用。 157 例1：找到一个设备最小的OPP:: 158 159 freq = 0; 160 opp = dev_pm_opp_find_freq_ceil(dev, &freq); 161 dev_pm_opp_put(opp); 162 163 例: 一个SoC的cpufreq_driver->target的简易实现:: 164 165 soc_cpufreq_target(..) 166 { 167 /* 做策略检查等操作 */ 168 /* 找到和请求最接近的频率 */ 169 opp = dev_pm_opp_find_freq_ceil(dev, &freq); 170 dev_pm_opp_put(opp); 171 if (!IS_ERR(opp)) 172 soc_switch_to_freq_voltage(freq); 173 else 174 /* 当不能满足请求时，要做的事 */ 175 /* 做其它事 */ 176 } 177 1784. OPP可用性控制函数 179==================== 180在OPP库中注册的默认OPP链表也许无法满足所有可能的场景。OPP库提供了一套函数来修改 181OPP链表中的某个OPP的可用性。这使得SoC框架能够精细地动态控制哪一组OPP是可用于操作 182的。设计这些函数的目的是在诸如考虑温度时 *暂时地* 删除某个OPP（例如，在温度下降 183之前不要使用某OPP）。 184 185警告： 186 不要在中断上下文使用这些函数。 187 188dev_pm_opp_enable 189 使一个OPP可用于操作。 190 例子：假设1GHz的OPP只有在SoC温度低于某个阈值时才可用。SoC框架的实现可能 191 会选择做以下事情:: 192 193 if (cur_temp < temp_low_thresh) { 194 /* 若1GHz未使能，则使能 */ 195 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false); 196 dev_pm_opp_put(opp); 197 /* 仅仅是错误检查 */ 198 if (!IS_ERR(opp)) 199 ret = dev_pm_opp_enable(dev, 1000000000); 200 else 201 goto try_something_else; 202 } 203 204dev_pm_opp_disable 205 使一个OPP不可用于操作。 206 例子：假设1GHz的OPP只有在SoC温度高于某个阈值时才可用。SoC框架的实现可能 207 会选择做以下事情:: 208 209 if (cur_temp > temp_high_thresh) { 210 /* 若1GHz已使能，则关闭 */ 211 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true); 212 dev_pm_opp_put(opp); 213 /* 仅仅是错误检查 */ 214 if (!IS_ERR(opp)) 215 ret = dev_pm_opp_disable(dev, 1000000000); 216 else 217 goto try_something_else; 218 } 219 2205. OPP数据检索函数 221================== 222由于OPP库对OPP信息进行了抽象化处理，因此需要一组函数来从dev_pm_opp结构体中提取 223信息。一旦使用搜索函数检索到一个OPP指针，以下函数就可以被SoC框架用来检索OPP层 224内部描述的信息。 225 226dev_pm_opp_get_voltage 227 检索OPP指针描述的电压。 228 例子: 当cpufreq切换到到不同频率时，SoC框架需要用稳压器框架将OPP描述 229 的电压设置到提供电压的电源管理芯片中:: 230 231 soc_switch_to_freq_voltage(freq) 232 { 233 /* 做一些事情 */ 234 opp = dev_pm_opp_find_freq_ceil(dev, &freq); 235 v = dev_pm_opp_get_voltage(opp); 236 dev_pm_opp_put(opp); 237 if (v) 238 regulator_set_voltage(.., v); 239 /* 做其它事 */ 240 } 241 242dev_pm_opp_get_freq 243 检索OPP指针描述的频率。 244 例子：比方说，SoC框架使用了几个辅助函数，通过这些函数，我们可以将OPP 245 指针传入，而不是传入额外的参数，用来处理一系列数据参数:: 246 247 soc_cpufreq_target(..) 248 { 249 /* 做一些事情.. */ 250 max_freq = ULONG_MAX; 251 max_opp = dev_pm_opp_find_freq_floor(dev,&max_freq); 252 requested_opp = dev_pm_opp_find_freq_ceil(dev,&freq); 253 if (!IS_ERR(max_opp) && !IS_ERR(requested_opp)) 254 r = soc_test_validity(max_opp, requested_opp); 255 dev_pm_opp_put(max_opp); 256 dev_pm_opp_put(requested_opp); 257 /* 做其它事 */ 258 } 259 soc_test_validity(..) 260 { 261 if(dev_pm_opp_get_voltage(max_opp) < dev_pm_opp_get_voltage(requested_opp)) 262 return -EINVAL; 263 if(dev_pm_opp_get_freq(max_opp) < dev_pm_opp_get_freq(requested_opp)) 264 return -EINVAL; 265 /* 做一些事情.. */ 266 } 267 268dev_pm_opp_get_opp_count 269 检索某个设备可用的OPP数量。 270 例子：假设SoC中的一个协处理器需要知道某个表中的可用频率，主处理器可以 271 按如下方式发出通知:: 272 273 soc_notify_coproc_available_frequencies() 274 { 275 /* 做一些事情 */ 276 num_available = dev_pm_opp_get_opp_count(dev); 277 speeds = kcalloc(num_available, sizeof(u32), GFP_KERNEL); 278 /* 按升序填充表 */ 279 freq = 0; 280 while (!IS_ERR(opp = dev_pm_opp_find_freq_ceil(dev, &freq))) { 281 speeds[i] = freq; 282 freq++; 283 i++; 284 dev_pm_opp_put(opp); 285 } 286 287 soc_notify_coproc(AVAILABLE_FREQs, speeds, num_available); 288 /* 做其它事 */ 289 } 290 2916. 数据结构 292=========== 293通常，一个SoC包含多个可变电压域。每个域由一个设备指针描述。和OPP之间的关系可以 294按以下方式描述:: 295 296 SoC 297 |- device 1 298 | |- opp 1 (availability, freq, voltage) 299 | |- opp 2 .. 300 ... ... 301 | `- opp n .. 302 |- device 2 303 ... 304 `- device m 305 306OPP库维护着一个内部链表，SoC框架使用上文描述的各个函数来填充和访问。然而，描述 307真实OPP和域的结构体是OPP库自身的内部组成，以允许合适的抽象在不同系统中得到复用。 308 309struct dev_pm_opp 310 OPP库的内部数据结构，用于表示一个OPP。除了频率、电压、可用性信息外， 311 它还包含OPP库运行所需的内部统计信息。指向这个结构体的指针被提供给 312 用户（比如SoC框架）使用，在与OPP层的交互中作为OPP的标识符。 313 314 警告： 315 结构体dev_pm_opp的指针不应该由用户解析或修改。一个实例的默认值由 316 dev_pm_opp_add填充，但OPP的可用性由dev_pm_opp_enable/disable函数 317 修改。 318 319struct device 320 这用于向OPP层标识一个域。设备的性质和它的实现是由OPP库的用户决定的， 321 如SoC框架。 322 323总体来说，以一个简化的视角看，对数据结构的操作可以描述为下面各图:: 324 325 初始化 / 修改: 326 +-----+ /- dev_pm_opp_enable 327 dev_pm_opp_add --> | opp | <------- 328 | +-----+ \- dev_pm_opp_disable 329 \-------> domain_info(device) 330 331 搜索函数: 332 /-- dev_pm_opp_find_freq_ceil ---\ +-----+ 333 domain_info<---- dev_pm_opp_find_freq_exact -----> | opp | 334 \-- dev_pm_opp_find_freq_floor ---/ +-----+ 335 336 检索函数: 337 +-----+ /- dev_pm_opp_get_voltage 338 | opp | <--- 339 +-----+ \- dev_pm_opp_get_freq 340 341 domain_info <- dev_pm_opp_get_opp_count 342