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