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