Regeultor核心文件翻譯
一、Documentation\power\regulator\overview.txt
1.命名規則
(1) Regulator - 為其他裝置供電的電子裝置。大多數調節器可以啟用和禁用其輸出，而某些調節器可以控制其輸出電壓和/或電流。
Input Voltage -> Regulator -> Output Voltage
(2) PMIC - 電源管理IC。一個pmic裡面包含大量regulator且通常包含其他子系統的IC。
(3) Consumer -由調節器供電的電子裝置，Consumers可分為兩類：
靜態：消費者不更改其電源電壓或電流限制。它只需要啟用或禁用電源即可。它的電源電壓由硬體，啟動程式，韌體或核心板初始化程式碼設定。
動態：消費者需要更改其電源電壓或電流限制，以滿足操作需求。
(4) Power Domain - 由調節器、開關或其他電源域的輸出功率提供其輸入功率的電子電路。電源調節器可能在開關後面。即：
Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A] | | | +-> [Consumer B], [Consumer C] | +-> [Consumer D], [Consumer E]
這是一個調節器和三個電源域：
域1：Switch-1，消費者D和E。
域2：Switch-2，消費者B和C。
域3：消費者A。
這表示一種“供應”關係：
Domain-1 --> Domain-2 --> Domain-3.
電源域可能具有由其他調節器供電的調節器。即：
Regulator-1 -+-> Regulator-2 -+-> [Consumer A] | +-> [Consumer B]
這為我們提供了兩個調節器和兩個電源域：
Domain 1: Regulator-2, Consumer B.
Domain 2: Consumer A.
和“供應”關係：
Domain-1 --> Domain-2
(5) Constraints - 約束用於定義功耗效能和硬體保護的功率級別。 約束存在三個層次：
a. 調節器級別：這由調節器硬體操作引數定義，並在調節器資料表中指定。 即：
-電壓輸出範圍為800mV-> 3500mV。
-電流輸出限制為20mA@5V，但為10mA@10V。
b. 電源域級別：這是在軟體中由核心級板初始化程式碼定義的。 它用於將電源域限制為特定的範圍內。即：
-域1電壓為3300mV
-域2電壓為1400mV->1600mV
-域3的電流限制為0mA->20mA。
c. 消費者級別：由Consumer的驅動程式動態設定電壓或電流的限制水平的定義。
例如，消費者背光碟機動器要求電流從5mA增加到10mA以增加LCD照明，通過以下級別：
消費者：需要增加LCD的亮度。在亮度表中查詢並請求下一個電流mA值（基於相同的參考裝置，使用者驅動程式可以用於幾種不同的方式）。
電源域：是對此域和系統狀態（例如電池電源，USB電源）進行限制的一種新的電流限制方式。
調節器域：是在調節器工作引數中調節輸入/輸出電壓的一種新的電流限制方式。
如果對調節器的請求通過了所有約束測試，則將應用新的調節器值。
2. 設計
該框架旨在針對基於SoC的裝置而設計的，但也可能與非SoC裝置相關，並且分為以下四個介面：
(1) 消費者驅動介面（Consumer driver interface）。
這使用了與核心時鐘介面類似的API，因為消費者驅動程式可以獲取和釋放一個調節器（就像使用atm時鐘一樣）並獲取/設定電壓電流限制，模式，啟用和禁用。 這應該使消費者驅動能夠完全控制其電源電壓和電流限制。 如果不使用，這也可以不編譯進去，因此驅動程式可以在不基於調節器的電源控制的系統中重用。
請看 Documentation/power/regulator/consumer.txt
(2) 調節器驅動程式介面（Regulator driver interface）。
這使調節器驅動程式可以註冊其調節器並向核心提供操作。 它還具有一個通知鏈，用於將調節事件傳播給客戶(clients)。
請看 Documentation/power/regulator/regulator.txt
(3) 機器介面（Machine interface）
該介面特定用於機器的程式碼，並允許為每個調節器建立電壓/電流域（帶有約束）。它可以提供調節器約束，以防止由於錯誤的客戶端驅動器引起的過電壓或過電流而損壞裝置。它還允許建立一個調節器樹，其中一些調節器由其他調節器供電（類似於時鐘樹）。
請看 /power/regulator/machine.txt
(4) 使用者空間ABI。
該框架還通過sysfs將大量有用的電壓/電流/opmode資料匯出到使用者空間。 這可用於幫助監視裝置的功耗和狀態。
請看 Documentation/ABI/testing/sysfs-class-regulator
二、Documentation\power\regulator\consumer.txt
穩壓器消費者驅動程式介面
==================================
本文介紹了消費類裝置驅動程式的調節器介面。請參閱overview.txt以獲取本文中所用術語的描述。
1.消費者驅動獲取調節器（靜態和動態驅動程式）
=======================================================
(1) 消費者驅動程式可以通過以下方式訪問為其供電的調節器：
regulator = regulator_get(dev, "Vcc"); //Vcc-supply = <&XXX>
使用者傳遞其dev結構裝置指標和supplyID。 然後，核心通過查詢機器特定的查詢表來找到正確的調節器。如果查詢成功，則此呼叫將返回一個指標，該指標指向此使用者的調節器結構。
(2) 要釋放調節器，消費者驅動程式可以呼叫：
regulator_put(regulator);
消費者可能存在同時由多個調節器供電的情況，例如，具有需要進行模擬供電和數字供電的編解碼器：
digital = regulator_get(dev, "Vcc"); /* digital core */ analog = regulator_get(dev, "Avdd"); /* analog */
通常在消費者驅動的probe()中呼叫regulator_get()，在消費者驅動的remove()中呼叫regulator_put()。
2.調節器輸出的使能和禁止（靜態和動態驅動）
=======================================================
(1) 消費者可以通過以下方式啟用電源：
int regulator_enable(regulator);
注意：在呼叫regulator_enabled()之前，電源可能已經啟用。如果使用者共享調節器，或者先前已通過引導載入程式或核心板初始化程式碼啟用了調節器，則可能會發生這種情況。
(2) 消費者驅動可以通過以下方式確定是否已經使能了調節器：
int regulator_is_enabled(regulator); //若調節器是使能的，返回0
(3) 消費者驅動可以通過以下方式禁用不再需要的電源：
int regulator_disable(regulator);
注意：如果與其他使用者共享電源，則可能不會禁用電源。僅當啟用的引用計數為零時，才會真正禁用此調節器。
(4) 在緊急情況下，可以強制禁用調節器：
int regulator_force_disable(regulator);
注意：這將立即強制關閉調節器輸出。所有使用此調節器的消費者都會下電。
3.調節器的電壓控制和狀態（動態驅動）
======================================================
一些消費者驅動程式需要能夠動態更改其電源電壓以匹配系統工作狀態。例如CPUfreq驅動程式可以隨頻率縮放電壓以節省功耗，SD驅動程式可能需要選擇正確的卡電壓等。
(1) 消費者驅動可以通過以下方式控制其電源電壓：
int regulator_set_voltage(regulator, min_uV, max_uV); //其中min_uV和max_uV是可接受的最小和最大電壓，以微伏為單位。
注意：可以在啟用或禁用調節器時呼叫此函式。如果在啟用時呼叫，則電壓會立即改變，否則電壓配置會改變，並且在下次使能調節器時會實際設定電壓。
(2) 調節器配置的電壓輸出值可通過以下方法查到：
int regulator_get_voltage(regulator);
注意：無論是啟用還是禁用調節器的狀態，get_voltage()都將返回配置的輸出電壓，因此不應將其用於確定調節器的輸出狀態。但是，可以將其與is_enabled()結合使用以確定調節器的物理輸出電壓。
4.調節器電流限制控制和狀態（動態驅動）
======================================================
一些消費者驅動程式需要能夠動態更改其電源電流限制以匹配系統工作狀態。例如LCD背光碟機動器可以更改電流限制以改變背光亮度，USB驅動器可能需要在供電時將限制設定為500mA。
(1) 消費者可以通過以下方式控制其電源電流限制：
int regulator_set_current_limit(regulator, min_uA, max_uA); //其中min_uA和max_uA是微安的最小和最大可接受電流限制。
注意：在啟用或禁用調節器的狀態下都可以呼叫此函式。如果在啟用時呼叫，則電流限制會立即生效，否則電流限制配置會更改，並且在下次啟用調節器時會實際設定電流限制。
(3) 可以通過以下方法查詢調節器的電流限制：
int regulator_get_current_limit(regulator);
注意：無論是啟用還是禁用調節器的狀態，get_current_limit()都將返回電流限制，因此不應將其用於確定調節器實際電流值。
5. 調節器操作模式控制和狀態（動態驅動器）
======================================================
一些使用者可以通過更改其電源調節器的工作模式來進一步節省系統功率，從而在使用者工作狀態發生變化時更加高效。 例如 消費者驅動程式處於空閒狀態，因此消耗的電流更少
調節器的執行模式可以間接或直接更改。
(1) 間接操作模式控制。
--------------------------------
消費者驅動可以通過呼叫這個函式更改其供應調節器的執行模式
int regulator_set_load(struct regulator *regulator, int load_uA);
這將導致核心重新計算調節器上的總負載（基於其所有consumers），並更改執行模式（如果需要並允許）以最佳地匹配當前的執行負載。
可以從consumer的資料表中確定load_uA值。 例如 大多數資料手冊都有表格顯示某些情況下的最大消耗電流。
大多數消費者將使用間接操作模式控制，因為他們不瞭解調節器或調節器是否與其他消費者共享。
(2) 直接操作模式控制。
------------------------------
定製或緊密耦合的驅動器可能希望根據其工作點直接控制調節器的工作模式。 這可以通過呼叫這個函式實現：
int regulator_set_mode(struct regulator *regulator, unsigned int mode); unsigned int regulator_get_mode(struct regulator *regulator);
直接模式將僅由“瞭解”調節器並且不與其他使用者共享調節器的使用者使用。
6.調節器事件
===================
Regulators可以將外部事件通知消費者。 消費者可以在調節器壓力或故障條件下接收事件。
消費者可以通過以下方式註冊對調節器事件的監聽：
int regulator_register_notifier(struct regulator *regulator, struct notifier_block *nb);
消費者可以通過以下方式取消對調節器事件的監聽：
int regulator_unregister_notifier(struct regulator *regulator, struct notifier_block *nb);
調機器使用核心通知鏈框架將事件傳送給感興趣的使用者(Consumers)。
7. Regulator直接暫存器訪問
==================================
某些電源管理硬體或韌體經過設計，因此它們需要對調節器進行低階硬體訪問，而無需核心參與。 此類裝置的示例是：
-具有壓控振盪器和控制邏輯的時鐘源，用於改變I2C上的電源電壓以達到所需的輸出時鐘速率
-熱管理韌體，可以在過熱情況下發出任意I2C事務以執行系統關機
要設定此類裝置/韌體，需要為其配置各種引數，例如調節器的I2C地址，各種調節器暫存器的地址等。 調節器框架提供了以下幫助程式來查詢這些詳細資訊。
特定於匯流排的詳細資訊（例如I2C地址或傳輸速率）由regmap框架處理。 要獲取調節器的regmap（如果支援），請使用：
struct regmap *regulator_get_regmap(struct regulator *regulator);
要獲得調節器的電壓選擇器暫存器的硬體暫存器偏移量和位掩碼，請使用：
int regulator_get_hardware_vsel_register(struct regulator *regulator, unsigned *vsel_reg, unsigned *vsel_mask);
要將穩壓器框架電壓選擇器程式碼（由regulator_list_voltage使用）轉換為可以直接寫入電壓選擇器暫存器的硬體專用電壓選擇，請使用：
int regulator_list_hardware_vsel(struct regulator *regulator, unsigned selector);