通用熱Sysfs驅動程式操作指南¶

作者：Sujith Thomas <sujith.thomas@intel.com>，Zhang Rui <rui.zhang@intel.com>

0. 介紹¶

通用熱sysfs提供了一組介面，用於熱區裝置（感測器）和散熱裝置（風扇、處理器等）註冊到熱管理解決方案併成為其一部分。

本操作指南重點介紹如何使新的熱區和散熱裝置參與熱管理。該解決方案與平臺無關，任何型別的熱區裝置和散熱裝置都應能夠利用此基礎設施。

熱sysfs驅動程式的主要任務是將熱區屬性和散熱裝置屬性暴露給使用者空間。智慧熱管理應用程式可以根據熱區屬性（當前溫度和跳變點溫度）的輸入做出決策，並對相應的裝置進行節流。

[0-*] 表示從0開始的任何正數
[1-*] 表示從1開始的任何正數

1. 熱sysfs驅動程式介面函式¶

1.1 熱區裝置介面¶

struct thermal_zone_device *
thermal_zone_device_register_with_trips(const char *type,
                                const struct thermal_trip *trips,
                                int num_trips, void *devdata,
                                const struct thermal_zone_device_ops *ops,
                                const struct thermal_zone_params *tzp,
                                unsigned int passive_delay,
                                unsigned int polling_delay)
此介面函式將一個新的熱區裝置（感測器）新增到 /sys/class/thermal 資料夾，命名為 thermal_zone[0-*]。它會同時嘗試繫結所有已註冊的散熱裝置。

型別
熱區型別。

跳變點
此熱區的跳變點表。

裝置資料
裝置私有資料

操作
熱區裝置回撥。

.should_bind
檢查給定的散熱裝置是否應繫結到此熱區中的給定跳變點。

.get_temp
獲取熱區的當前溫度。

.set_trips
設定跳變點視窗。每當當前溫度更新時，都會找到緊鄰當前溫度之下和之上的跳變點。

.change_mode
更改熱區的模式（啟用/停用）。

.set_trip_temp
設定給定跳變點的溫度。

.get_crit_temp
獲取此熱區的臨界溫度。

.set_emul_temp
設定模擬溫度，這有助於除錯不同的閾值溫度點。

.get_trend
獲取最近區域溫度變化的趨勢。

.hot
熱跳變點越界處理程式。

.critical
臨界跳變點越界處理程式。

tzp
熱區平臺引數。

passive_delay
執行被動冷卻時，兩次輪詢之間等待的毫秒數。

polling_delay
檢查跳變點是否已被越過時，兩次輪詢之間等待的毫秒數（中斷驅動系統為0）。
void thermal_zone_device_unregister(struct thermal_zone_device *tz)
此介面函式移除熱區裝置。它會從 /sys/class/thermal 資料夾中刪除相應的條目，並解綁所有使用它的散熱裝置。
struct thermal_zone_device
*thermal_zone_of_sensor_register(struct device *dev, int sensor_id,
                     void *data,
                     const struct thermal_zone_of_device_ops *ops)
此介面將一個新感測器新增到DT熱區。此函式將搜尋裝置樹中描述的熱區列表，並查詢引用 dev->of_node 指向的感測器裝置作為溫度提供者的區域。對於指向感測器節點的區域，該感測器將被新增到DT熱區裝置中。

此介面的引數有

dev
感測器裝置節點，其中dev->of_node包含有效的節點指標。

sensor_id
感測器識別符號，以防感測器IP有多個感測器

資料
一個私有指標（由呼叫者擁有），當需要溫度讀數時將回傳。

操作
結構體 thermal_zone_of_device_ops *.

get_temp

指向讀取感測器溫度的函式的指標。這是感測器驅動程式提供的強制回撥。

set_trips

指向設定溫度視窗的函式的指標。當離開此視窗時，驅動程式必須透過 thermal_zone_device_update 通知熱核心。

get_trend

指向讀取感測器溫度趨勢的函式的指標。

set_emul_temp

指向設定感測器模擬溫度的函式的指標。

熱區溫度由 thermal_zone_of_device_ops 的 get_temp() 函式指標提供。當呼叫時，它將返回私有指標 @data。

如果失敗，它將返回錯誤指標，否則返回有效的熱區裝置控制代碼。呼叫者應使用 IS_ERR() 檢查返回控制代碼以判斷是否成功。
void thermal_zone_of_sensor_unregister(struct device *dev,
                                       struct thermal_zone_device *tzd)
此介面從DT熱區登出一個感測器，該感測器曾透過 thermal_zone_of_sensor_register() 介面成功新增。此函式從透過 thermal_zone_of_sensor_register() 介面註冊的熱區裝置中移除感測器回撥和私有資料。它還會透過移除 .get_temp() 和 get_trend() 熱區裝置回撥來使該區域靜默。
struct thermal_zone_device
*devm_thermal_zone_of_sensor_register(struct device *dev,
                      int sensor_id,
                      void *data,
                      const struct thermal_zone_of_device_ops *ops)
此介面是 thermal_zone_of_sensor_register() 的資源管理版本。

第1.1.3節中描述的 thermal_zone_of_sensor_register() 的所有細節都適用於此處。

使用此介面註冊感測器的好處是，不需要在錯誤路徑或驅動程式解綁期間顯式呼叫 thermal_zone_of_sensor_unregister()，因為這由驅動程式資源管理器完成。
void devm_thermal_zone_of_sensor_unregister(struct device *dev,
                                struct thermal_zone_device *tzd)
此介面是 thermal_zone_of_sensor_unregister() 的資源管理版本。第1.1.4節中描述的 thermal_zone_of_sensor_unregister() 的所有細節都適用於此處。通常不需要呼叫此函式，資源管理程式碼將確保資源被釋放。
int thermal_zone_get_slope(struct thermal_zone_device *tz)
此介面用於讀取熱區裝置的斜率屬性值，這可能對平臺驅動程式的溫度計算有用。
int thermal_zone_get_offset(struct thermal_zone_device *tz)
此介面用於讀取熱區裝置的偏移屬性值，這可能對平臺驅動程式的溫度計算有用。

1.2 散熱裝置介面¶

struct thermal_cooling_device
*thermal_cooling_device_register(char *name,
                void *devdata, struct thermal_cooling_device_ops *)
此介面函式將一個新的散熱裝置（風扇/處理器/...）新增到 /sys/class/thermal/ 資料夾，命名為 cooling_device[0-*]。它會嘗試同時將自己繫結到所有已註冊的熱區裝置。

名稱
散熱裝置名稱。

裝置資料
裝置私有資料。

操作
散熱裝置回撥。

.get_max_state
獲取散熱裝置的最大節流狀態。

.get_cur_state
獲取散熱裝置當前請求的節流狀態。

.set_cur_state
設定散熱裝置的當前節流狀態。
void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev)
此介面函式移除散熱裝置。它會從 /sys/class/thermal 資料夾中刪除相應的條目，並解綁所有使用它的熱區裝置。

1.4 熱區引數¶

struct thermal_zone_params
此結構定義了熱區的平臺級引數。這些資料，對於每個熱區，應來自平臺層。這是一個可選功能，某些平臺可以選擇不提供此資料。

.governor_name
此區域使用的熱控制器名稱

.no_hwmon
一個布林值，指示是否需要熱到hwmon sysfs介面。當no_hwmon == false時，將建立一個hwmon sysfs介面。當no_hwmon == true時，將不進行任何操作。如果 thermal_zone_params 為NULL，則將建立hwmon介面（為了向後相容）。

2. sysfs屬性結構¶

RO	只讀值
WO	只寫值
RW	讀/寫值

熱sysfs屬性將表示在 /sys/class/thermal 下。如果hwmon已編譯或作為模組構建，hwmon sysfs I/F擴充套件也可在 /sys/class/hwmon 下使用。

熱區裝置sys I/F，註冊後建立

/sys/class/thermal/thermal_zone[0-*]:
  |---type:                   Type of the thermal zone
  |---temp:                   Current temperature
  |---mode:                   Working mode of the thermal zone
  |---policy:                 Thermal governor used for this zone
  |---available_policies:     Available thermal governors for this zone
  |---trip_point_[0-*]_temp:  Trip point temperature
  |---trip_point_[0-*]_type:  Trip point type
  |---trip_point_[0-*]_hyst:  Hysteresis value for this trip point
  |---emul_temp:              Emulated temperature set node
  |---sustainable_power:      Sustainable dissipatable power
  |---k_po:                   Proportional term during temperature overshoot
  |---k_pu:                   Proportional term during temperature undershoot
  |---k_i:                    PID's integral term in the power allocator gov
  |---k_d:                    PID's derivative term in the power allocator
  |---integral_cutoff:        Offset above which errors are accumulated
  |---slope:                  Slope constant applied as linear extrapolation
  |---offset:                 Offset constant applied as linear extrapolation

散熱裝置sys I/F，註冊後建立

/sys/class/thermal/cooling_device[0-*]:
  |---type:                   Type of the cooling device(processor/fan/...)
  |---max_state:              Maximum cooling state of the cooling device
  |---cur_state:              Current cooling state of the cooling device
  |---stats:                  Directory containing cooling device's statistics
  |---stats/reset:            Writing any value resets the statistics
  |---stats/time_in_state_ms: Time (msec) spent in various cooling states
  |---stats/total_trans:      Total number of times cooling state is changed
  |---stats/trans_table:      Cooling state transition table

接下來兩個動態屬性成對建立/移除。它們表示熱區及其關聯散熱裝置之間的關係。

/sys/class/thermal/thermal_zone[0-*]:
  |---cdev[0-*]:              [0-*]th cooling device in current thermal zone
  |---cdev[0-*]_trip_point:   Trip point that cdev[0-*] is associated with
  |---cdev[0-*]_weight:       Influence of the cooling device in
                              this thermal zone

除了熱區裝置sysfs I/F和散熱裝置sysfs I/F之外，通用熱驅動程式還為每種熱區裝置型別建立一個hwmon sysfs I/F。例如，通用熱驅動程式註冊一個hwmon類裝置，併為所有已註冊的ACPI熱區構建相關的hwmon sysfs I/F。

請閱讀 ABI檔案測試/sysfs-class-thermal 以獲取熱區和散熱裝置屬性的詳細資訊。

/sys/class/hwmon/hwmon[0-*]:
  |---name:                   The type of the thermal zone devices
  |---temp[1-*]_input:        The current temperature of thermal zone [1-*]
  |---temp[1-*]_critical:     The critical trip point of thermal zone [1-*]

請閱讀 sysfs檔案命名和資料格式標準以獲取更多資訊。

3. 一個簡單的實現¶

ACPI熱區可能支援多個跳變點，例如臨界、熱、被動、主動。如果一個ACPI熱區同時支援臨界、被動、主動[0]和主動[1]，它可能會將自己註冊為 thermal_zone_device (thermal_zone1)，共包含4個跳變點。它有一個處理器和一個風扇，兩者都註冊為 thermal_cooling_device。兩者都被認為在冷卻熱區方面具有相同的效率。

如果處理器列在 _PSL 方法中，風扇列在 _AL0 方法中，則sys I/F結構將如下構建

/sys/class/thermal:
 |thermal_zone1:
   |---type:                   acpitz
   |---temp:                   37000
   |---mode:                   enabled
   |---policy:                 step_wise
   |---available_policies:     step_wise fair_share
   |---trip_point_0_temp:      100000
   |---trip_point_0_type:      critical
   |---trip_point_1_temp:      80000
   |---trip_point_1_type:      passive
   |---trip_point_2_temp:      70000
   |---trip_point_2_type:      active0
   |---trip_point_3_temp:      60000
   |---trip_point_3_type:      active1
   |---cdev0:                  --->/sys/class/thermal/cooling_device0
   |---cdev0_trip_point:       1       /* cdev0 can be used for passive */
   |---cdev0_weight:           1024
   |---cdev1:                  --->/sys/class/thermal/cooling_device3
   |---cdev1_trip_point:       2       /* cdev1 can be used for active[0]*/
   |---cdev1_weight:           1024

 |cooling_device0:
   |---type:                   Processor
   |---max_state:              8
   |---cur_state:              0

 |cooling_device3:
   |---type:                   Fan
   |---max_state:              2
   |---cur_state:              0

/sys/class/hwmon:
 |hwmon0:
   |---name:                   acpitz
   |---temp1_input:            37000
   |---temp1_crit:             100000

4. 匯出符號API¶

4.1. get_tz_trend¶

此函式返回熱區的趨勢，即熱區溫度的變化率。理想情況下，熱感測器驅動程式應該實現回撥。如果它們沒有實現，熱框架會透過比較先前和當前的溫度值來計算趨勢。

4.2. thermal_cdev_update¶

此函式用作設定散熱裝置狀態的仲裁器。如果可能，它會將散熱裝置設定為最深的冷卻狀態。

5. 臨界事件¶

當發生臨界跳變溫度越界事件時，熱框架將根據配置觸發硬體保護性關機（shutdown）或重啟。

首先，核心將嘗試有序關機或重啟，但會接受一個延遲，在此延遲之後它將分別進行強制關機或重啟。如果這失敗，將呼叫 emergency_restart() 作為最後的手段。

應仔細分析延遲時間，以確保有足夠的時間進行有序關機或重啟。

如果延遲設定為0，則不支援緊急操作。因此，為了觸發緊急操作，必須設定一個經過仔細分析的非零正值。

Linux核心

目錄

本頁