Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 .. include:: ../disclaimer-zh_TW.rst
   4
   5 :Original: Documentation/cpu-freq/cpu-drivers.rst
   6
   7 :翻譯:
   8
   9  司延騰 Yanteng Si <siyanteng@loongson.cn>
  10
  11 :校譯:
  12
  13  唐藝舟 Tang Yizhou <tangyeechou@gmail.com>
  14
  15 =======================================
  16 如何實現一個新的CPUFreq處理器驅動程序？
  17 =======================================
  18
  19 作者:
  20
  21
  22         - Dominik Brodowski  <linux@brodo.de>
  23         - Rafael J. Wysocki <rafael.j.wysocki@intel.com>
  24         - Viresh Kumar <viresh.kumar@linaro.org>
  25
  26 .. Contents
  27
  28    1.   怎麼做？
  29    1.1  初始化
  30    1.2  Per-CPU 初始化
  31    1.3  驗證
  32    1.4  target/target_index 或 setpolicy?
  33    1.5  target/target_index
  34    1.6  setpolicy
  35    1.7  get_intermediate 與 target_intermediate
  36    2.   頻率表助手
  37
  38
  39
  40 1. 怎麼做？
  41 ===========
  42
  43 如果，你剛剛得到了一個全新的CPU/芯片組及其數據手冊，並希望爲這個CPU/芯片組添加cpufreq
  44 支持？很好，這裏有一些至關重要的提示：
  45
  46
  47 1.1 初始化
  48 ----------
  49
  50 首先，在 __initcall level 7 (module_init())或更靠後的函數中檢查這個內核是否
  51 運行在正確的CPU和正確的芯片組上。如果是，則使用cpufreq_register_driver()向
  52 CPUfreq核心層註冊一個cpufreq_driver結構體。
  53
  54 結構體cpufreq_driver應該包含什麼成員?
  55
  56  .name - 驅動的名字。
  57
  58  .init - 一個指向per-policy初始化函數的指針。
  59
  60  .verify - 一個指向"verification"函數的指針。
  61
  62  .setpolicy 或 .fast_switch 或 .target 或 .target_index - 差異見
  63  下文。
  64
  65 其它可選成員
  66
  67  .flags - 給cpufreq核心的提示。
  68
  69  .driver_data - cpufreq驅動程序的特有數據。
  70
  71  .get_intermediate 和 target_intermediate - 用於在改變CPU頻率時切換到穩定
  72  的頻率。
  73
  74  .get - 返回CPU的當前頻率。
  75
  76  .bios_limit - 返回HW/BIOS對CPU的最大頻率限制值。
  77
  78  .exit - 一個指向per-policy清理函數的指針，該函數在CPU熱插拔過程的CPU_POST_DEAD
  79  階段被調用。
  80
  81  .suspend - 一個指向per-policy暫停函數的指針，該函數在關中斷且在該策略的調節器停止
  82  後被調用。
  83
  84  .resume - 一個指向per-policy恢復函數的指針，該函數在關中斷且在調節器再一次啓動前被
  85  調用。
  86
  87  .ready - 一個指向per-policy準備函數的指針，該函數在策略完全初始化之後被調用。
  88
  89  .attr - 一個指向NULL結尾的"struct freq_attr"列表的指針，該列表允許導出值到
  90  sysfs。
  91
  92  .boost_enabled - 如果設置，則啓用提升(boost)頻率。
  93
  94  .set_boost - 一個指向per-policy函數的指針，該函數用來開啓/關閉提升(boost)頻率功能。
  95
  96
  97 1.2 Per-CPU 初始化
  98 ------------------
  99
 100 每當一個新的CPU被註冊到設備模型中，或者當cpufreq驅動註冊自身之後，如果此CPU的cpufreq策
 101 略不存在，則會調用per-policy的初始化函數cpufreq_driver.init。請注意，.init()和.exit()例程
 102 只爲某個策略調用一次，而不是對該策略管理的每個CPU調用一次。它需要一個 ``struct cpufreq_policy
 103 *policy`` 作爲參數。現在該怎麼做呢？
 104
 105 如果有必要，請在你的CPU上激活CPUfreq功能支持。
 106
 107 然後，驅動程序必須填寫以下值:
 108
 109 +-----------------------------------+--------------------------------------+
 110 |policy->cpuinfo.min_freq和         | 該CPU支持的最低和最高頻率（kHz）     |
 111 |policy->cpuinfo.max_freq           |                                      |
 112 |                                   |                                      |
 113 +-----------------------------------+--------------------------------------+
 114 |policy->cpuinfo.transition_latency | CPU在兩個頻率之間切換所需的時間，以  |
 115 |                                   | 納秒爲單位（如不適用，設定爲         |
 116 |                                   | CPUFREQ_ETERNAL）                    |
 117 |                                   |                                      |
 118 +-----------------------------------+--------------------------------------+
 119 |policy->cur                        | 該CPU當前的工作頻率(如適用)          |
 120 |                                   |                                      |
 121 +-----------------------------------+--------------------------------------+
 122 |policy->min,                       | 必須包含該CPU的"默認策略"。稍後      |
 123 |policy->max,                       | 會用這些值調用                       |
 124 |policy->policy and, if necessary,  | cpufreq_driver.verify和下面函數      |
 125 |policy->governor                   | 之一：cpufreq_driver.setpolicy或     |
 126 |                                   | cpufreq_driver.target/target_index   |
 127 |                                   |                                      |
 128 +-----------------------------------+--------------------------------------+
 129 |policy->cpus                       | 該policy通過DVFS框架影響的全部CPU    |
 130 |                                   | (即與本CPU共享"時鐘/電壓"對)構成     |
 131 |                                   | 掩碼(同時包含在線和離線CPU)，用掩碼  |
 132 |                                   | 更新本字段                           |
 133 |                                   |                                      |
 134 +-----------------------------------+--------------------------------------+
 135
 136 對於設置其中的一些值(cpuinfo.min[max]_freq, policy->min[max])，頻率表輔助函數可能會有幫
 137 助。關於它們的更多信息，請參見第2節。
 138
 139
 140 1.3 驗證
 141 --------
 142
 143 當用戶決定設置一個新的策略(由"policy,governor,min,max組成")時，必須對這個策略進行驗證，
 144 以便糾正不兼容的值。爲了驗證這些值，cpufreq_verify_within_limits(``struct cpufreq_policy
 145 *policy``, ``unsigned int min_freq``, ``unsigned int max_freq``)函數可能會有幫助。
 146 關於頻率表輔助函數的詳細內容請參見第2節。
 147
 148 您需要確保至少有一個有效頻率（或工作範圍）在 policy->min 和 policy->max 範圍內。如果有必
 149 要，先增大policy->max，只有在沒有解決方案的情況下，才減小policy->min。
 150
 151
 152 1.4 target 或 target_index 或 setpolicy 或 fast_switch?
 153 -------------------------------------------------------
 154
 155 大多數cpufreq驅動甚至大多數CPU頻率升降算法只允許將CPU頻率設置爲預定義的固定值。對於這些，你
 156 可以使用->target()，->target_index()或->fast_switch()回調。
 157
 158 有些具有硬件調頻能力的處理器可以自行依據某些限制來切換CPU頻率。它們應使用->setpolicy()回調。
 159
 160
 161 1.5. target/target_index
 162 ------------------------
 163
 164 target_index調用有兩個參數： ``struct cpufreq_policy * policy`` 和 ``unsigned int``
 165 索引(用於索引頻率表項)。
 166
 167 當調用這裏時，CPUfreq驅動必須設置新的頻率。實際頻率必須由freq_table[index].frequency決定。
 168
 169 在發生錯誤的情況下總是應該恢復到之前的頻率(即policy->restore_freq)，即使我們已經切換到了
 170 中間頻率。
 171
 172 已棄用
 173 ----------
 174 target調用有三個參數。``struct cpufreq_policy * policy``, unsigned int target_frequency,
 175 unsigned int relation.
 176
 177 CPUfreq驅動在調用這裏時必須設置新的頻率。實際的頻率必須使用以下規則來確定。
 178
 179 - 儘量貼近"目標頻率"。
 180 - policy->min <= new_freq <= policy->max (這必須是有效的!!!)
 181 - 如果 relation==CPUFREQ_REL_L，嘗試選擇一個高於或等於 target_freq 的 new_freq。("L代表
 182   最低，但不能低於")
 183 - 如果 relation==CPUFREQ_REL_H，嘗試選擇一個低於或等於 target_freq 的 new_freq。("H代表
 184   最高，但不能高於")
 185
 186 這裏，頻率表輔助函數可能會幫助你 -- 詳見第2節。
 187
 188 1.6. fast_switch
 189 ----------------
 190
 191 這個函數用於從調度器的上下文進行頻率切換。並非所有的驅動都要實現它，因爲不允許在這個回調中睡眠。這
 192 個回調必須經過高度優化，以儘可能快地進行切換。
 193
 194 這個函數有兩個參數： ``struct cpufreq_policy *policy`` 和 ``unsigned int target_frequency``。
 195
 196
 197 1.7 setpolicy
 198 -------------
 199
 200 setpolicy調用只需要一個 ``struct cpufreq_policy * policy`` 作爲參數。需要將處理器內或芯片組內動態頻
 201 率切換的下限設置爲policy->min，上限設置爲policy->max，如果支持的話，當policy->policy爲
 202 CPUFREQ_POLICY_PERFORMANCE時選擇面向性能的設置，爲CPUFREQ_POLICY_POWERSAVE時選擇面向省電的設置。
 203 也可以查看drivers/cpufreq/longrun.c中的參考實現。
 204
 205 1.8 get_intermediate 和 target_intermediate
 206 --------------------------------------------
 207
 208 僅適用於未設置 target_index() 和 CPUFREQ_ASYNC_NOTIFICATION 的驅動。
 209
 210 get_intermediate應該返回一個平臺想要切換到的穩定的中間頻率，target_intermediate()應該將CPU設置爲
 211 該頻率，然後再跳轉到'index'對應的頻率。cpufreq核心會負責發送通知，驅動不必在
 212 target_intermediate()或target_index()中處理它們。
 213
 214 在驅動程序不想爲某個目標頻率切換到中間頻率的情況下，它們可以讓get_intermediate()返回'0'。
 215 在這種情況下，cpufreq核心將直接調用->target_index()。
 216
 217 注意：->target_index()應該在發生失敗的情況下將頻率恢復到policy->restore_freq，
 218 因爲cpufreq核心會爲此發送通知。
 219
 220
 221 2. 頻率表輔助函數
 222 =================
 223
 224 由於大多數支持cpufreq的處理器只允許被設置爲幾個特定的頻率，因此，"頻率表"和一些相關函數可能會輔助處理器驅動
 225 程序的一些工作。這樣的"頻率表"是一個由struct cpufreq_frequency_table的條目構成的數組，"driver_data"成員包
 226 含驅動程序的專用值，"frequency"成員包含了相應的頻率，此外還有標誌成員。在表的最後，需要添加一個
 227 cpufreq_frequency_table條目，頻率設置爲CPUFREQ_TABLE_END。如果想跳過表中的一個條目，則將頻率設置爲
 228 CPUFREQ_ENTRY_INVALID。這些條目不需要按照任何特定的順序排序，如果排序了，cpufreq核心執行DVFS會更快一點，
 229 因爲搜索最佳匹配會更快。
 230
 231 如果在policy->freq_table字段中包含一個有效的頻率表指針，頻率表就會被cpufreq核心自動驗證。
 232
 233 cpufreq_frequency_table_verify()保證至少有一個有效的頻率在policy->min和policy->max範圍內，並且所有其他
 234 準則都被滿足。這對->verify調用很有幫助。
 235
 236 cpufreq_frequency_table_target()是對應於->target階段的頻率表輔助函數。只要把值傳遞給這個函數，這個函數就會返
 237 回包含CPU要設置的頻率的頻率表條目。
 238
 239 以下宏可以作爲cpufreq_frequency_table的迭代器。
 240
 241 cpufreq_for_each_entry(pos, table) - 遍歷頻率表的所有條目。
 242
 243 cpufreq_for_each_valid_entry(pos, table) - 該函數遍歷所有條目，不包括CPUFREQ_ENTRY_INVALID頻率。
 244 使用參數"pos" -- 一個 ``cpufreq_frequency_table *`` 作爲循環指針，使用參數"table" -- 作爲你想迭代
 245 的 ``cpufreq_frequency_table *`` 。
 246
 247 例如::
 248
 249         struct cpufreq_frequency_table *pos, *driver_freq_table;
 250
 251         cpufreq_for_each_entry(pos, driver_freq_table) {
 252                 /* Do something with pos */
 253                 pos->frequency = ...
 254         }
 255
 256 如果你需要在driver_freq_table中處理pos的位置，不要做指針減法，因爲它的代價相當高。作爲替代，使用宏
 257 cpufreq_for_each_entry_idx() 和 cpufreq_for_each_valid_entry_idx() 。
 258