如何將您的補丁提交到 Hwmon 子系統¶
本文收集了為 hwmon 子系統編寫補丁或驅動程式的建議。遵循這些建議將大大增加您的更改被接受的機會。
1. 通則¶
無需贅述，請閱讀並遵循以下內容：
請使用 ‘checkpatch --strict’ 執行您的補丁。應該沒有錯誤、沒有警告，檢查訊息也應儘可能少。如果有任何訊息，請準備好解釋。
請使用標準的多行註釋風格。不要在同一個驅動程式中混用 C 和 C++ 風格的註釋（SPDX 許可證識別符號除外）。
如果您的補丁生成了 checkpatch 錯誤、警告或檢查訊息，請避免給出“我更喜歡那種編碼風格”之類的解釋。請記住，每個不必要的訊息都會掩蓋一個真正的問題，而一致的編碼風格則有助於他人理解和審查程式碼。
請徹底測試您的補丁。我們不是您的測試組。有時因為缺少硬體，補丁無法或無法完全測試。在這種情況下，您應該在至少一種架構上測試構建程式碼。如果未進行執行時測試，則應在補丁頭部下方明確說明。
如果您的補丁（或驅動程式）受 CONFIG_SMP 等配置選項影響，請確保它能為所有配置變體編譯。
2. 為現有驅動程式新增功能¶
確保 Documentation/hwmon/<driver_name>.rst 中的文件是最新的。
確保 Kconfig 中的資訊是最新的。
如果新增的功能需要一些清理或結構性更改，請將您的補丁拆分為清理部分和實際新增部分。這使得審查您的更改以及二分查詢任何導致的問題變得更加容易。
切勿在單個補丁中混合錯誤修復、清理和功能增強。
3. 新驅動程式¶
即使您的補丁或驅動程式檔案透過 checkpatch 檢查，也並不意味著其格式是乾淨的。如果您不確定新驅動程式的格式，請透過 Lindent 執行它。Lindent 並非完美，您可能需要進行一些小的清理，但這是一個好的開始。
考慮將自己新增到 MAINTAINERS 檔案中。
在 Documentation/hwmon/<driver_name>.rst 中記錄驅動程式。
將驅動程式按字母順序新增到 Kconfig 和 Makefile 中。
確保所有依賴項都列在 Kconfig 中。
請按字母順序排列標頭檔案。
請將續行與前一行中的 ‘(’ 對齊。
儘可能避免前向宣告。如有必要，請重新安排程式碼。
避免使用宏來生成成組的感測器屬性。這不僅會使 checkpatch 混淆，還會使程式碼審查更加困難。
避免在宏和宏生成的函式中進行計算。雖然此類宏可能在原始碼中節省一兩行，但它會使程式碼變得模糊，並使程式碼審查更加困難。它也可能導致程式碼比必要更復雜。請改用行內函數或普通函式。
限制核心日誌訊息的數量。通常，您的驅動程式不應僅僅因為執行時操作失敗就生成錯誤訊息。請改為使用適當的錯誤程式碼向用戶空間報告錯誤。請記住，核心錯誤日誌訊息不僅會填滿核心日誌，而且是同步列印的，很可能在中斷停用時，通常輸出到序列控制檯。過多的日誌記錄會嚴重影響系統性能。
儘可能使用 devres 函式來分配資源。有關原理和支援的函式，請參閱 Devres - 管理的裝置資源。如果某個函式不受 devres 支援，請考慮使用 devm_add_action()。
如果驅動程式有檢測（detect）功能，請確保它是靜默的。除錯訊息和成功檢測後列印的訊息是可以接受的，但它絕不能列印“晶片 XXX 未找到/不支援”之類的訊息。
請記住，如果某個地址上檢測到晶片，則所有支援該地址的驅動程式都會執行其檢測功能。不必要的訊息只會汙染核心日誌，且不提供任何價值。
僅當晶片可以可靠檢測時才提供檢測（detect）功能。
僅應探測以下 I2C 地址：0x18-0x1f, 0x28-0x2f, 0x48-0x4f, 0x58, 0x5c, 0x73 和 0x77。強烈不建議探測其他地址，因為已知這會與其他（非 hwmon）I2C 晶片引起問題。如果您的晶片位於無法探測的地址，則必須顯式例項化裝置（無論如何，這總是更好的選擇）。
避免在檢測功能中寫入晶片暫存器。如果您必須寫入，請僅在您已收集到足夠資料以確定檢測將成功之後再進行。
請記住，晶片可能並非您的驅動程式所認為的那樣，對其進行寫入可能會導致錯誤的配置。
確保探測（probe）功能中沒有競爭條件。具體而言，請首先完全初始化您的晶片和驅動程式，然後向 hwmon 子系統註冊。
使用 devm_hwmon_device_register_with_info() 或，如果您的驅動程式需要一個 remove 函式，使用 hwmon_device_register_with_info() 來將您的驅動程式註冊到 hwmon 子系統。如果可能，嘗試使用 devm_add_action() 代替 remove 函式。不要使用任何已棄用的註冊函式。
您的驅動程式應該能夠構建為模組。如果不能，請準備好解釋為什麼它必須內建到核心中。
不要支援已棄用的 sysfs 屬性。
除非確實需要，否則不要建立非標準屬性。如果您必須使用非標準屬性，或者您認為需要使用，請先在郵件列表中討論。無論哪種情況，請提供詳細解釋為何需要非標準屬性。標準屬性在 sysfs 檔案的命名和資料格式標準 中指定。
在決定支援哪些 sysfs 屬性時，請檢視晶片的功能。雖然我們不期望您的驅動程式支援晶片可能提供的所有功能，但它至少應支援所有限制和警報。
最後但同樣重要的是，在開始編寫新驅動程式之前，請檢查您的晶片是否已有現有驅動程式。特別是對於溫度感測器，新晶片通常是先前釋出晶片的變體。在某些情況下，一個所謂的新晶片可能只是被重新貼牌了。