cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

opp.rst (12291B)


      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 = kzalloc(sizeof(u32) * num_available, 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