sysfs 檔案命名和資料格式標準

libsensors 庫透過 sysfs 介面提供對原始感測器資料的訪問。自 lm-sensors 3.0.0 起，libsensors 完全與晶片無關。它假定所有核心驅動都實現了本文件中描述的標準 sysfs 介面。這使得新增或更新對任何給定晶片的支援都非常容易，因為 libsensors 和使用它的應用程式無需修改。與 lm-sensors 2 相比，這是一個重大改進。

請注意，主機板上與感測器晶片的連線方式差異很大。沒有標準可以確保，例如，第二個溫度感測器連線到 CPU，或者第二個風扇位於 CPU 上。此外，晶片報告的一些值需要經過計算才能完全理解。例如，大多數晶片只能測量 0 到 +4V 之間的電壓。其他電壓則透過外部電阻縮放到該範圍。由於這些電阻的值可能因主機板而異，因此轉換不能硬編碼到驅動程式中，必須在使用者空間中完成。

因此，即使我們致力於開發一個與晶片無關的 libsensors，它仍然需要一個配置檔案（例如 /etc/sensors.conf）來進行正確的值轉換、輸入標籤和隱藏未使用的輸入。

一些程式使用的另一種方法是直接訪問 sysfs 檔案。本文件簡要描述了驅動程式遵循的標準，以便應用程式能夠以簡單一致的方式掃描條目並訪問這些資料。儘管如此，此類程式必須實現輸入的轉換、標籤和隱藏。因此，仍然不建議繞過庫。

每個晶片在 sysfs /sys/devices 樹中都有自己的目錄。要查詢所有感測器晶片，更簡單的方法是遵循 /sys/class/hwmon/hwmon* 中的裝置符號連結。

在 lm-sensors 3.0.0 之前，libsensors 在“物理”裝置目錄中查詢硬體監控屬性。自 lm-sensors 3.0.1 起，hwmon“類”裝置目錄中找到的屬性也受支援。複雜的驅動程式（例如，多功能晶片的驅動程式）可能希望利用此功能來避免名稱空間汙染。唯一的缺點是舊版本的 libsensors 不支援該驅動程式。

所有 sysfs 值都是定點數。

每個檔案只有一個值，這與舊的 /proc 規範不同。檔案命名的通用方案是：<type><number>_<item>。感測器晶片的常見型別有“in”（電壓）、“temp”（溫度）和“fan”（風扇）。常見專案有“input”（測量值）、“max”（高閾值）、“min”（低閾值）。編號通常從 1 開始，除了電壓從 0 開始（因為大多數資料表都使用此編號）。對於可以出現多次的元素，即使給定型別在特定晶片上只有一個元素，也總是使用數字。其他檔案不引用特定元素，因此它們只有一個簡單的名稱，沒有數字。

警報是直接從晶片讀取的指示。驅動程式不進行讀數與閾值的比較。這允許捕獲讀數之間的違規併發出警報。警報的確切定義（例如，是否必須達到或超過閾值才能觸發警報）取決於晶片。

設定 hwmon sysfs 屬性的值時，必須寫入所需值的字串表示形式，請注意，非數字的字串將被解釋為 0！有關寫入字串如何解釋的更多資訊，請參閱此檔案末尾的“sysfs 屬性寫入解釋”部分。

屬性訪問

硬體監控 sysfs 屬性由不受限制的使用者空間應用程式顯示。因此，所有標準 ABI 屬性都應為全域性可讀。可寫的標準 ABI 屬性應僅對特權使用者可寫。

[0-*]

表示從 0 開始的任何正數

[1-*]

表示從 1 開始的任何正數

RO

只讀值

WO

只寫值

RW

讀/寫值

讀/寫值對於某些晶片可能是隻讀的，具體取決於硬體實現。

所有條目（名稱除外）都是可選的，並且只有在晶片具有該功能時才應在給定驅動程式中建立。

有關屬性的完整描述，請參閱ABI 檔案測試/sysfs-class-hwmon。

全域性屬性

name

晶片名稱。

label

一個描述性標籤，允許在系統中唯一標識裝置。

update_interval

晶片更新讀數的間隔。

電壓

in[0-*]_min

電壓最小值。

in[0-*]_lcrit

電壓臨界最小值。

in[0-*]_max

電壓最大值。

in[0-*]_crit

電壓臨界最大值。

in[0-*]_input

電壓輸入值。

in[0-*]_average

平均電壓

in[0-*]_lowest

歷史最低電壓

in[0-*]_highest

歷史最高電壓

in[0-*]_reset_history

重置 inX_lowest 和 inX_highest

in_reset_history

重置所有感測器的 inX_lowest 和 inX_highest

in[0-*]_label

建議的電壓通道標籤。

in[0-*]_enable

啟用或停用感測器。

cpu[0-*]_vid

CPU 核心參考電壓。

vrm

電壓調節模組版本號。

in[0-*]_rated_min

額定最小電壓。

in[0-*]_rated_max

額定最大電壓。

另請參閱“警報”部分，瞭解與電壓相關的狀態標誌。

風扇

fan[1-*]_min

風扇最小值

fan[1-*]_max

風扇最大值

fan[1-*]_input

風扇輸入值。

fan[1-*]_div

風扇分頻器。

fan[1-*]_pulses

每轉風扇的轉速計脈衝數。

fan[1-*]_target

期望的風扇速度

fan[1-*]_label

建議的風扇通道標籤。

fan[1-*]_enable

啟用或停用感測器。

另請參閱“警報”部分，瞭解與風扇相關的狀態標誌。

PWM

pwm[1-*]

脈衝寬度調製風扇控制。

pwm[1-*]_enable

風扇速度控制方法。

pwm[1-*]_mode

直流或脈衝寬度調製。

pwm[1-*]_freq

基本 PWM 頻率，單位 Hz。

pwm[1-*]_auto_channels_temp

選擇在自動模式下哪些溫度通道影響此 PWM 輸出。

pwm[1-*]_auto_point[1-*]_pwm / pwm[1-*]_auto_point[1-*]_temp / pwm[1-*]_auto_point[1-*]_temp_hyst

定義 PWM 與溫度曲線。

temp[1-*]_auto_point[1-*]_pwm / temp[1-*]_auto_point[1-*]_temp / temp[1-*]_auto_point[1-*]_temp_hyst

定義 PWM 與溫度曲線。

還有第三種情況，即跳變點與 PWM 輸出通道和溫度通道都相關聯：PWM 值與 PWM 輸出通道相關聯，而溫度值與溫度通道相關聯。在這種情況下，結果由溫度輸入和 PWM 輸出之間的對映決定。當多個溫度輸入對映到給定 PWM 輸出時，這會導致多個候選 PWM 值。實際結果取決於晶片，但通常最高的候選值（最快的風扇速度）勝出。

溫度

temp[1-*]_type

感測器型別選擇。

temp[1-*]_max

溫度最大值。

temp[1-*]_min

溫度最小值。

temp[1-*]_max_hyst

最大限制的溫度滯後值。

temp[1-*]_min_hyst

最小限制的溫度滯後值。

temp[1-*]_input

溫度輸入值。

temp[1-*]_crit

溫度臨界最大值，通常高於相應的 temp_max 值。

temp[1-*]_crit_hyst

臨界限制的溫度滯後值。

temp[1-*]_emergency

溫度緊急最大值，適用於支援兩個以上上限溫度的晶片。

temp[1-*]_emergency_hyst

緊急限制的溫度滯後值。

temp[1-*]_lcrit

溫度臨界最小值，通常低於相應的 temp_min 值。

temp[1-*]_lcrit_hyst

臨界最小值限制的溫度滯後值。

temp[1-*]_offset

晶片新增到溫度讀數中的溫度偏移量。

temp[1-*]_label

建議的溫度通道標籤。

temp[1-*]_lowest

歷史最低溫度

temp[1-*]_highest

歷史最高溫度

temp[1-*]_reset_history

重置 temp_lowest 和 temp_highest

temp_reset_history

重置所有感測器的 temp_lowest 和 temp_highest

temp[1-*]_enable

啟用或停用感測器。

temp[1-*]_rated_min

額定最小溫度。

temp[1-*]_rated_max

額定最大溫度。

有些晶片使用外部熱敏電阻和 ADC 測量溫度，並將溫度測量結果報告為電壓。將此電壓轉換回溫度（或反向用於限制）需要核心中不可用的數學函式，因此轉換必須在使用者空間中進行。對於這些晶片，上述所有 temp* 檔案應包含以毫伏而不是毫攝氏度表示的值。換句話說，這些溫度通道由驅動程式作為電壓通道處理。

另請參閱“警報”部分，瞭解與溫度相關的狀態標誌。

電流

curr[1-*]_max

電流最大值。

curr[1-*]_min

電流最小值。

curr[1-*]_lcrit

電流臨界低值

curr[1-*]_crit

電流臨界高值。

curr[1-*]_input

電流輸入值。

curr[1-*]_average

平均電流使用量。

curr[1-*]_lowest

歷史最低電流。

curr[1-*]_highest

歷史最高電流。

curr[1-*]_reset_history

重置 currX_lowest 和 currX_highest

WO

curr_reset_history

重置所有感測器的 currX_lowest 和 currX_highest。

curr[1-*]_enable

啟用或停用感測器。

curr[1-*]_rated_min

額定最小電流。

curr[1-*]_rated_max

額定最大電流。

另請參閱“警報”部分，瞭解與電流相關的狀態標誌。

功率

power[1-*]_average

平均功率使用量。

power[1-*]_average_interval

功率使用平均間隔。

power[1-*]_average_interval_max

最大功率使用平均間隔。

power[1-*]_average_interval_min

最小功率使用平均間隔。

power[1-*]_average_highest

歷史平均最大功率使用量

power[1-*]_average_lowest

歷史平均最小功率使用量

power[1-*]_average_max

當功率使用量上升到此值以上時，會向 power[1-*]_average 傳送輪詢通知。

power[1-*]_average_min

當功率使用量下降到此值以下時，會向 power[1-*]_average 傳送輪詢通知。

power[1-*]_input

瞬時功率使用量。

power[1-*]_input_highest

歷史最大功率使用量

power[1-*]_input_lowest

歷史最小功率使用量。

power[1-*]_reset_history

重置 input_highest、input_lowest、average_highest 和 average_lowest。

power[1-*]_accuracy

功率計的準確度。

power[1-*]_cap

如果功率使用量上升到此限制以上，系統應採取措施降低功率使用量。

power[1-*]_cap_hyst

圍繞功率限制和通知構建的滯後裕度。

power[1-*]_cap_max

可設定的最大功率限制。

power[1-*]_cap_min

可設定的最小功率限制。

power[1-*]_max

最大功率。

power[1-*]_crit

臨界最大功率。

如果功率上升到或超過此限制，系統應採取劇烈措施降低功耗，例如系統關機或強制某些裝置斷電。

單位：微瓦 (microWatt)

RW

power[1-*]_enable

啟用或停用感測器。

停用時，感測器讀取將返回 -ENODATA。

  • 1：啟用

  • 0：停用

RW

power[1-*]_rated_min

額定最小功率。

單位：微瓦 (microWatt)

RO

power[1-*]_rated_max

額定最大功率。

單位：微瓦 (microWatt)

RO

另請參閱“警報”部分，瞭解與功率讀數相關的狀態標誌。

能量

energy[1-*]_input

累計能量使用量

單位：微焦耳 (microJoule)

RO

energy[1-*]_enable

啟用或停用感測器。

停用時，感測器讀取將返回 -ENODATA。

  • 1：啟用

  • 0：停用

RW

溼度

humidity[1-*]_input

溼度。

humidity[1-*]_enable

啟用或停用感測器。

humidity[1-*]_rated_min

額定最小溼度。

humidity[1-*]_rated_max

額定最大溼度。

警報

每個通道或限制可能有一個關聯的警報檔案，其中包含一個布林值。1 表示存在警報條件，0 表示沒有警報。

通常，給定晶片會使用通道相關警報或限制相關警報，而不會同時使用兩者。驅動程式應僅反映硬體實現。

`in[0-*]_alarm`、`curr[1-*]_alarm`、`power[1-*]_alarm`、`fan[1-*]_alarm`、`temp[1-*]_alarm`

通道警報

  • 0：無警報

  • 1：有警報

RO

或者

`in[0-*]_min_alarm`、`in[0-*]_max_alarm`、`in[0-*]_lcrit_alarm`、`in[0-*]_crit_alarm`、`curr[1-*]_min_alarm`、`curr[1-*]_max_alarm`、`curr[1-*]_lcrit_alarm`、`curr[1-*]_crit_alarm`、`power[1-*]_cap_alarm`、`power[1-*]_max_alarm`、`power[1-*]_crit_alarm`、`fan[1-*]_min_alarm`、`fan[1-*]_max_alarm`、`temp[1-*]_min_alarm`、`temp[1-*]_max_alarm`、`temp[1-*]_lcrit_alarm`、`temp[1-*]_crit_alarm`、`temp[1-*]_emergency_alarm`

限制警報

  • 0：無警報

  • 1：有警報

RO

每個輸入通道可能有一個關聯的故障檔案。這可用於通知開路二極體、未連線的風扇等（如果硬體支援）。當此布林值為 1 時，該通道的測量值不應被信任。

fan[1-*]_fault / temp[1-*]_fault

輸入故障條件。

一些晶片還提供在發生警報時發出蜂鳴聲的可能性

beep_enable

主蜂鳴啟用。

in[0-*]_beep、curr[1-*]_beep、fan[1-*]_beep、temp[1-*]_beep、

通道蜂鳴。

理論上，晶片可以提供每個限制的蜂鳴遮蔽，但到目前為止尚未見到此類晶片。

舊驅動程式為警報和蜂鳴提供了不同的、非標準介面。這些介面檔案已被棄用，但將保留以保持相容性

alarms

警報位掩碼。

beep_mask

蜂鳴位掩碼。

入侵檢測

intrusion[0-*]_alarm

機箱入侵檢測。

intrusion[0-*]_beep

機箱入侵蜂鳴。

平均取樣配置

允許讀取 {in,power,curr,temp}_average 值的裝置可能會匯出屬性來控制用於計算平均值的樣本數。

samples

設定所有測量型別的平均樣本數。

RW

in_samples power_samples curr_samples temp_samples

設定特定測量型別的平均樣本數。

請注意，在某些裝置上，無法將所有這些值設定為不同的值，因此更改其中一個也可能會更改其他一些值。

RW

sysfs 屬性寫入解釋

hwmon sysfs 屬性始終包含數字，因此首先要做的是將輸入轉換為數字，根據數字是否可以是負數有兩種方法

unsigned long u = simple_strtoul(buf, NULL, 10);
long s = simple_strtol(buf, NULL, 10);

其中 buf 是核心傳遞的使用者輸入緩衝區。請注意，我們不使用 strto[u]l 的第二個引數，因此無法判斷何時返回 0，是確實為 0 還是由無效輸入引起。這是有意為之的，因為在所有地方檢查這會給核心增加大量程式碼。

請注意，將轉換後的值始終儲存在 unsigned long 或 long 中非常重要，這樣在進行任何進一步檢查之前就不會發生迴繞。

在將輸入字串轉換為 (unsigned) long 後，應檢查其值是否可接受。在檢查值有效性之前，請注意對值進行進一步轉換，因為這些轉換仍可能在檢查之前導致迴繞。例如，不要將結果相乘，並且只有在加/減之前已進行除法運算時才進行加/減。

如果發現某個值無效，如何處理取決於要設定的 sysfs 屬性的型別。如果它是連續設定，例如 tempX_max 或 inX_max 屬性，則應使用 clamp_val(value, min_limit, max_limit) 將值鉗位到其限制。如果它不是連續的，例如 tempX_type，則當寫入無效值時，應返回 -EINVAL。

示例1，temp1_max，暫存器是帶符號的 8 位值（-128 - 127 攝氏度）

long v = simple_strtol(buf, NULL, 10) / 1000;
v = clamp_val(v, -128, 127);
/* write v to register */

示例2，風扇分頻器設定，有效值為 2、4 和 8

unsigned long v = simple_strtoul(buf, NULL, 10);

switch (v) {
case 2: v = 1; break;
case 4: v = 2; break;
case 8: v = 3; break;
default:
        return -EINVAL;
}
/* write v to register */