General description of the CPUFreq core and CPUFreq notifiers

もともと、Linux Kernelのソースコードの一部なので、GPLv2扱いになる（はずの認識）。

> https://www.kernel.org/doc/html/latest/index.html
> 
> Licensing documentation
> 
> The following describes the license of the Linux kernel source code (GPLv2), how to properly mark the license of individual files in the source tree, as well as links to the full license text.
> 
> https://www.kernel.org/doc/html/latest/process/license-rules.html#kernel-licensing


https://www.kernel.org/doc/html/latest/cpu-freq/core.html
を読んでいく。

-----

# General description of the CPUFreq core and CPUFreq notifiers


Authors:
　Dominik Brodowski <linux@brodo.de>
　David Kimdon <dwhedon@debian.org>
　Rafael J. Wysocki <rafael.j.wysocki@intel.com>
　Viresh Kumar <viresh.kumar@linaro.org>

## 1. General Information
> The CPUFreq core code is located in drivers/cpufreq/cpufreq.c. This cpufreq code offers a standardized interface for the CPUFreq architecture drivers (those pieces of code that do actual frequency transitions), as well as to “notifiers”. These are device drivers or other part of the kernel that need to be informed of policy changes (ex. thermal modules like ACPI) or of all frequency changes (ex. timing code) or even need to force certain speed limits (like LCD drivers on ARM architecture). Additionally, the kernel “constant” loops_per_jiffy is updated on frequency changes here.

CPUFreq core codeは、derivers/cpufreq/cpufreq.cに位置する。この、CPUFreq core codeは、CPUFreq architecture driversに対する標準的なインタフェイスを提供する。（コードの一部は、周波数変更を実行する）また、同様に"notifiers"も含む。デバイスドライバ―やカーネルの一部では必要に応じて、policyの変更(例えばACPIのようなサーマルモジュール）やや、すべての周波数の変更（タイミングコード等）あるいは特定の速度制限の強制（例えばARM architectureにおけるLCD driver)が必要となる。更に、カーネルの定数"loops_per_jiffy"は周波数変更タイミングで更新されます。


> Reference counting of the cpufreq policies is done by cpufreq_cpu_get and cpufreq_cpu_put, which make sure that the cpufreq driver is correctly registered with the core, and will not be unloaded until cpufreq_put_cpu is called. That also ensures that the respective cpufreq policy doesn’t get freed while being used.

cpufreqポリシーの参照カウンタは、cpufreq_cpu_get()とcpufreq_cpu_put()によって実現されます。これにより、cpufreqドライバがコアに正しく登録され、cpufreq_put_cpu()が呼び出されるまでアンロードされません。これにより、それぞれのcpufreq policyが使用中に開放されないことを保証できます。

## 2. CPUFreq notifiers
> CPUFreq notifiers conform to the standard kernel notifier interface. See linux/include/linux/notifier.h for details on notifiers.

CPUFreq notifiersは、標準的なカーネルのnotifier interfaceに準じます。notifiersの詳細に関しては、linux/include/linux/notifier.hを参照してください。

> There are two different CPUFreq notifiers - policy notifiers and transition notifiers.

2つの異なるCPUFreq notifiersがあります。１つは、policy notifiersであり、もう一つはtransition notifiersです。

### 2.1 CPUFreq policy notifiers
> These are notified when a new policy is created or removed.
新しいpolicyが作成された、あるいは削除されたときのnotifyがあります。

> The phase is specified in the second argument to the notifier. The phase is CPUFREQ_CREATE_POLICY when the policy is first created and it is CPUFREQ_REMOVE_POLICY when the policy is removed.

このphaseはnotifierに対する二番目の引数に示されます。このphaseは、最初にpolicyが作れられたときに、CPUFREQ_CREATE_POLCYです。そして、policyが削除されたときにCPUFREQ_REMOVE_POLICYです。

> The third argument, a void *pointer, points to a struct cpufreq_policy consisting of several values, including min, max (the lower and upper frequencies (in kHz) of the new policy).

三番目の引数は、void * pointer型です。これは、新しいpolicyのmin, max周波数(最低と最大の周波数(kHz単位)を含むいくつかの値で構成された、cpufreq_policy 構造体へのポインタです。

### 2.2 CPUFreq transition notifiers

>These are notified twice for each online CPU in the policy, when the CPUfreq driver switches the CPU core frequency and this change has no any external implications.

policyにおいて、それぞれのonline CPUに対して再びnotifyすることがあります。これは、CPUFreq driverがCPU core freencyを切り替え、この変更が外部に影響を与える事はありません。

> The second argument specifies the phase - CPUFREQ_PRECHANGE or CPUFREQ_POSTCHANGE.

第二引数は、phaseを示します。CPUFREQ_PRECHANGE あるいは、CPUFREQ_POSTCHANGE。

> The third argument is a struct cpufreq_freqs with the following values:

三番目の引数は、下記の値を含むcpufreq_freqs構造体です。

```
cpu	number of the affected CPU
old	old frequency
new	new frequency
flags	flags of the cpufreq driver
```

## 3. CPUFreq Table Generation with Operating Performance Point (OPP)

>For details about OPP, see Documentation/power/opp.rst

OPPについて詳しい説明は、Documentation/power/opp.rstを参照してください。

### dev_pm_opp_init_cpufreq_table -

> This function provides a ready to use conversion routine to translate the OPP layer’s internal information about the available frequencies into a format readily providable to cpufreq.

この関数は、現在有効となっている周波数に関するOPP layersの内部情報を、cpufreqが解読可能となるフォーマットに変換する変換ルーチンを利用できるようにするものです。

> Warning
> Do not use this function in interrupt context.

この関数は、割り込みコンテクスト内で利用しないこと。

> Example

```C
soc_pm_init()
{
       /* Do things */
       r = dev_pm_opp_init_cpufreq_table(dev, &freq_table);
       if (!r)
               policy->freq_table = freq_table;
       /* Do other things */
}
```

> Note
> This function is available only if CONFIG_CPU_FREQ is enabled in addition to CONFIG_PM_OPP.

この関数は、CONFIG_CPUFREQが有効でかつ、CONFIG_PM_OPPも追加されているときにだけ有効です。

### dev_pm_opp_free_cpufreq_table

> Free up the table allocated by dev_pm_opp_init_cpufreq_table

dev_pm_opp_init_cpufreq_tableで確保したテーブルを開放します。