Linux power supply class(1)_軟件架構及API彙整【轉】

時間 2019-11-07

標籤 linux power supply class 軟件架構 api 彙整欄目 Linux 简体版

原文原文鏈接

1. 前言

power supply class爲編寫供電設備（power supply，後面簡稱PSY）的驅動提供了統一的框架，功能包括：node

1）抽象PSY設備的共性，向用戶空間提供統一的API。linux

2）爲底層PSY驅動的編寫，提供簡單、統一的方式。同時封裝並實現公共邏輯，驅動工程師只需把精力集中在和硬件相關的部分便可。android

本文將從設計思路、軟件架構、API說明以及怎麼編寫power supply driver四個角度，介紹power supply class。並會在下一篇文章中，分析power supply class的內部邏輯。若是有時間，會在第三篇文章中，以android系統爲例，介紹應用軟件怎樣利用power supply class，監控系統的供電狀態。api

注：其實全部的class（如input subsystem），思路都是這樣的----抽象共性、統一接口、屏蔽細節。咱們在「Linux設備模型(7)_Class」中介紹過，本文在介紹power supply class同時，也以此爲例，進一步理解設備模型中class的存在乎義和使用方法。數組

2. 設計思路

先來回答一個問題：kernel中設備驅動的目的，是管理設備，並提供給用戶空間程序使用，那麼對PSY設備而言，kernel要管理什麼？用戶空間程序要使用什麼？服務器

其實PSY設備是一個特例，它的目的很單純，就是爲系統供電。若是隻考慮這個目的，就不須要任何驅動了，但狀況會稍微複雜，由於：數據結構

1）PSY設備多是電池設備（battery，這在嵌入式系統中很常見），這會引伸出電量檢測、充電管理等多個議題。架構

此時，PSY driver須要管理的事情包括：檢測電池類型；檢測電池電量；檢測充電狀態；等等。而用戶空間程序則須要將檢測到的結果，顯示給用戶。框架

2）系統中可能有多個PSY設備，這些設備還可能有級聯關係，若有些平板電腦中，可能同時存在DC-charger、USB-charger和battery三個供電設備，其中DC-charger和USB-charger可能會給battery供電，再由battery向系統供電。wordpress

此時，PSY driver須要管理的事情包括：獲取外部供電設備的鏈接狀態；充電狀態；等等。一樣，用戶空間程序須要將這些信息顯示給用戶。

那麼，共性已經總結出來了：PSY driver的主要功能，就是向用戶空間程序彙整各種狀態信息。所以，power supply class的核心思路就是：

將這些狀態信息，抽象爲「屬性（properties）」。因爲狀態信息的類型是有限的，properties的個數也是有限的。

PSY driver只須要負責：該PSY設備具備哪些「屬性」；這些「屬性」的「值（value）」是什麼；當「屬性值」發生改變時，通知power supply class。

power supply class負責：將某個PSY設備支持的屬性及其value，以sysfs的形式，提供給用戶空間；當屬性值改變時，以uevent的形式，廣播給用戶空間程序。

另外，power supply class也會協助處理PSY級聯的狀況（後面會詳細描述）。

3. 軟件架構和API彙整

3.1 軟件架構

power supply class位於drivers/power/目錄中，主要由3部分組成（可參考下圖的軟件架構）：

1）power supply core，用於抽象核心數據結構、實現公共邏輯。位於drivers/power/power_supply_core.c中。

2）power supply sysfs，實現sysfs以及uevent功能。位於drivers/power/power_supply_sysfs.c中。

3）power supply leds，基於linux led class，提供PSY設備狀態指示的通用實現。位於drivers/power/power_suppply_leds.c中。

最後，驅動工程師能夠基於power supply class，實現具體的PSY drivers，主要處理平臺相關、硬件相關的邏輯。這些drivers都位於drivers/power/目錄下。

3.2 核心數據結構

1）struct power_supply

struct power_supply爲power supply class的核心數據結構，用於抽象PSY設備。其定義以下：

1: /* include/linux/power_supply.h */
   2: struct power_supply {
   3:     const char *name;
   4:     enum power_supply_type type;
   5:     enum power_supply_property *properties;
   6:     size_t num_properties;
   7:  
   8:     char **supplied_to;
   9:     size_t num_supplicants;
  10:  
  11:     char **supplied_from;
  12:     size_t num_supplies;
  13:     struct device_node *of_node;
  14:  
  15:     int (*get_property)(struct power_supply *psy,
  16:                 enum power_supply_property psp,
  17:                 union power_supply_propval *val);
  18:     int (*set_property)(struct power_supply *psy,
  19:                 enum power_supply_property psp,
  20:                 const union power_supply_propval *val);
  21:     int (*property_is_writeable)(struct power_supply *psy,
  22:                      enum power_supply_property psp);
  23:     void (*external_power_changed)(struct power_supply *psy);
  24:     void (*set_charged)(struct power_supply *psy);
  25:  
  26:     /* For APM emulation, think legacy userspace. */
  27:     int use_for_apm;
  28:  
  29:     /* private */
  30:     struct device *dev;
  31:     struct work_struct changed_work;
  32:     spinlock_t changed_lock;
  33:     bool changed;
  34: #ifdef CONFIG_THERMAL
  35:     struct thermal_zone_device *tzd;
  36:     struct thermal_cooling_device *tcd;
  37: #endif
  38:  
  39: #ifdef CONFIG_LEDS_TRIGGERS
  40:     struct led_trigger *charging_full_trig;
  41:     char *charging_full_trig_name;
  42:     struct led_trigger *charging_trig;
  43:     char *charging_trig_name;
  44:     struct led_trigger *full_trig;
  45:     char *full_trig_name;
  46:     struct led_trigger *online_trig;
  47:     char *online_trig_name;
  48:     struct led_trigger *charging_blink_full_solid_trig;
  49:     char *charging_blink_full_solid_trig_name;
  50: #endif
  51: };

name，該PSY的名稱；

type，該PSY的類型，枚舉型，包括：battery、USB charger等等（後面會詳細介紹）；

properties，該PSY具備的屬性列表，枚舉型（後面會詳細介紹）；

num_properties，屬性的個數；

supplied_to，一個字符串數組，保存了由該PSY供電的PSY列表，以此可將PSY組織成相互級聯的PSY鏈。這些「被供電」的PSY，稱做supplicant（客戶端、乞求者）；

num_supplies，supply的個數；

get_property/set_property，PSY driver須要重點實現的兩個回調函數，用於獲取/設置屬性值；

property_is_writeable，返回指定的屬性值是否可寫（用於sysfs）；

set_charged，該回調函數的應用場景有點奇怪：外部模塊通知PSY driver，該PSY設備的狀態改變了。本身改變了本身不知道，要外部通知，但願你們在實際工做中不要遇到，否則太糾結了；

changed_work/changed_lock/changed，一個用於處理狀態改變的workqueue，主要思路是：當該PSY的狀態發生改變，啓動一個workqueue，查詢並通知全部的supplicants；

tzd/tcd，若是該PSY具備溫度等屬性，則須要藉助linux generic thermal sysfs drivers（溫控子系統）的框架，註冊相應的thermal設備，後面會詳細介紹；

led triggers，若是配置了CONFIG_LEDS_TRIGGERS，則調用linux led class的接口，註冊相應的LED設備，用於PSY狀態指示；

dev/of_node，用於保存device、of_node等指針。

2）PSY類型

PSY類型由enum power_supply_type定義：

1: enum power_supply_type {
   2:     POWER_SUPPLY_TYPE_UNKNOWN = 0,
   3:     POWER_SUPPLY_TYPE_BATTERY,
   4:     POWER_SUPPLY_TYPE_UPS,
   5:     POWER_SUPPLY_TYPE_MAINS,
   6:     POWER_SUPPLY_TYPE_USB,        /* Standard Downstream Port */
   7:     POWER_SUPPLY_TYPE_USB_DCP,    /* Dedicated Charging Port */
   8:     POWER_SUPPLY_TYPE_USB_CDP,    /* Charging Downstream Port */
   9:     POWER_SUPPLY_TYPE_USB_ACA,    /* Accessory Charger Adapters */
  10: };

POWER_SUPPLY_TYPE_UNKOWN，未知；

POWER_SUPPLY_TYPE_BATTERY，電池，嵌入式設備、手持式智能設備經常使用的供電形式；

POWER_SUPPLY_TYPE_UPS，Uninterruptible Power System/Uninterruptible Power Supply，不間斷式供電設備，經過將交流電和蓄電池鏈接，正常狀況下由交流電供電，同時向蓄電池充電。當交流電斷電時，由蓄電池緊急供電。通常用於服務器等設備；

POWER_SUPPLY_TYPE_MAINS，主供電設備，如筆記本電腦的適配器，其特色是能夠單獨供電，當其斷電時，再由輔助供電設備供電（如battery）；

POWER_SUPPLY_TYPE_USB/POWER_SUPPLY_TYPE_USB_DCP

/POWER_SUPPLY_TYPE_USB_CDP/POWER_SUPPLY_TYPE_USB_ACA，USB類型的供電，不一樣點在於充電電流的限制，由USB Battery Charge Spec規定，具體可參考USB組織的規範，或者參考這個連接（http://www.cash.idv.tw/wordpress/?p=8334，因爲是臺灣博客，被和諧了，呵呵呵！感興趣的同窗能夠找我要）。

3）PSY屬性

power supply class將全部可能PSY屬性，以枚舉型變量（enum power_supply_property ）的形式抽象出來，PSY driver能夠根據設備的實際狀況，從中選取一些。

1: enum power_supply_property {
   2:     /* Properties of type `int' */
   3:     POWER_SUPPLY_PROP_STATUS = 0,
   4:     POWER_SUPPLY_PROP_CHARGE_TYPE,
   5:     POWER_SUPPLY_PROP_HEALTH,
   6:     POWER_SUPPLY_PROP_PRESENT,
   7:     POWER_SUPPLY_PROP_ONLINE,
   8:     POWER_SUPPLY_PROP_AUTHENTIC,
   9:     POWER_SUPPLY_PROP_TECHNOLOGY,
  10:     POWER_SUPPLY_PROP_CYCLE_COUNT,
  11:     POWER_SUPPLY_PROP_VOLTAGE_MAX,
  12:     POWER_SUPPLY_PROP_VOLTAGE_MIN,
  13:     POWER_SUPPLY_PROP_VOLTAGE_MAX_DESIGN,
  14:     POWER_SUPPLY_PROP_VOLTAGE_MIN_DESIGN,
  15:     POWER_SUPPLY_PROP_VOLTAGE_NOW,
  16:     POWER_SUPPLY_PROP_VOLTAGE_AVG,
  17:     POWER_SUPPLY_PROP_VOLTAGE_OCV,
  18:     POWER_SUPPLY_PROP_VOLTAGE_BOOT,
  19:     POWER_SUPPLY_PROP_CURRENT_MAX,
  20:     POWER_SUPPLY_PROP_CURRENT_NOW,
  21:     POWER_SUPPLY_PROP_CURRENT_AVG,
  22:     POWER_SUPPLY_PROP_CURRENT_BOOT,
  23:     POWER_SUPPLY_PROP_POWER_NOW,
  24:     POWER_SUPPLY_PROP_POWER_AVG,
  25:     POWER_SUPPLY_PROP_CHARGE_FULL_DESIGN,
  26:     POWER_SUPPLY_PROP_CHARGE_EMPTY_DESIGN,
  27:     POWER_SUPPLY_PROP_CHARGE_FULL,
  28:     POWER_SUPPLY_PROP_CHARGE_EMPTY,
  29:     POWER_SUPPLY_PROP_CHARGE_NOW,
  30:     POWER_SUPPLY_PROP_CHARGE_AVG,
  31:     POWER_SUPPLY_PROP_CHARGE_COUNTER,
  32:     POWER_SUPPLY_PROP_CONSTANT_CHARGE_CURRENT,
  33:     POWER_SUPPLY_PROP_CONSTANT_CHARGE_CURRENT_MAX,
  34:     POWER_SUPPLY_PROP_CONSTANT_CHARGE_VOLTAGE,
  35:     POWER_SUPPLY_PROP_CONSTANT_CHARGE_VOLTAGE_MAX,
  36:     POWER_SUPPLY_PROP_CHARGE_CONTROL_LIMIT,
  37:     POWER_SUPPLY_PROP_CHARGE_CONTROL_LIMIT_MAX,
  38:     POWER_SUPPLY_PROP_INPUT_CURRENT_LIMIT,
  39:     POWER_SUPPLY_PROP_ENERGY_FULL_DESIGN,
  40:     POWER_SUPPLY_PROP_ENERGY_EMPTY_DESIGN,
  41:     POWER_SUPPLY_PROP_ENERGY_FULL,
  42:     POWER_SUPPLY_PROP_ENERGY_EMPTY,
  43:     POWER_SUPPLY_PROP_ENERGY_NOW,
  44:     POWER_SUPPLY_PROP_ENERGY_AVG,
  45:     POWER_SUPPLY_PROP_CAPACITY, /* in percents! */
  46:     POWER_SUPPLY_PROP_CAPACITY_ALERT_MIN, /* in percents! */
  47:     POWER_SUPPLY_PROP_CAPACITY_ALERT_MAX, /* in percents! */
  48:     POWER_SUPPLY_PROP_CAPACITY_LEVEL,
  49:     POWER_SUPPLY_PROP_TEMP,
  50:     POWER_SUPPLY_PROP_TEMP_MAX,
  51:     POWER_SUPPLY_PROP_TEMP_MIN,
  52:     POWER_SUPPLY_PROP_TEMP_ALERT_MIN,
  53:     POWER_SUPPLY_PROP_TEMP_ALERT_MAX,
  54:     POWER_SUPPLY_PROP_TEMP_AMBIENT,
  55:     POWER_SUPPLY_PROP_TEMP_AMBIENT_ALERT_MIN,
  56:     POWER_SUPPLY_PROP_TEMP_AMBIENT_ALERT_MAX,
  57:     POWER_SUPPLY_PROP_TIME_TO_EMPTY_NOW,
  58:     POWER_SUPPLY_PROP_TIME_TO_EMPTY_AVG,
  59:     POWER_SUPPLY_PROP_TIME_TO_FULL_NOW,
  60:     POWER_SUPPLY_PROP_TIME_TO_FULL_AVG,
  61:     POWER_SUPPLY_PROP_TYPE, /* use power_supply.type instead */
  62:     POWER_SUPPLY_PROP_SCOPE,
  63:     POWER_SUPPLY_PROP_CHARGE_TERM_CURRENT,
  64:     POWER_SUPPLY_PROP_CALIBRATE,
  65:     /* Properties of type `const char *' */
  66:     POWER_SUPPLY_PROP_MODEL_NAME,
  67:     POWER_SUPPLY_PROP_MANUFACTURER,
  68:     POWER_SUPPLY_PROP_SERIAL_NUMBER,
  69: };

屬性值至關多，考慮到篇幅問題，本文只列舉幾個（它們也是power supply sysfs支持的屬性），其它的你們能夠自行理解。

POWER_SUPPLY_PROP_STATUS，該PSY的status，主要是充電狀態，包括："Unknown", "Charging", "Discharging", "Not charging", "Full"，由枚舉型變量（POWER_SUPPLY_STATUS_*）定義。根據設計方案的不一樣，充電類型的PSY，或者battery類型的PSY，均可能具有該屬性；

POWER_SUPPLY_PROP_CHARGE_TYPE，充電類型，包括："Unknown", "N/A", "Trickle", "Fast"，由枚舉型變量（POWER_SUPPLY_CHARGE_TYPE_*）定義；同理根據設計方案的不一樣，充電類型的PSY，或者battery類型的PSY，均可能具有該屬性；

POWER_SUPPLY_PROP_HEALTH，「健康」狀況，包括："Unknown", "Good", "Overheat", "Dead", "Over voltage"等等, 由枚舉型變量（POWER_SUPPLY_HEALTH_*）定義。通常用於battery類型的PSY；

POWER_SUPPLY_PROP_TECHNOLOGY，採用的技術，包括："Unknown", "NiMH", "Li-ion", "Li-poly", "LiFe", "NiCd", "LiMn"，由枚舉型變量（POWER_SUPPLY_TECHNOLOGY_*）定義。通常用於battery類型的PSY；

POWER_SUPPLY_PROP_CAPACITY_LEVEL，容量，包括："Unknown", "Critical", "Low", "Normal", "High", "Full"，由枚舉型變量（POWER_SUPPLY_CAPACITY_LEVEL_*）定義。通常用於battery類型的PSY；

POWER_SUPPLY_PROP_TYPE，PSY類型，比較特殊，保存在「psy->type」變量中，而不在properties數組中。

3.3 向具體的PSY driver提供的API

power supply class首要任務，是向PSY driver提供統一的驅動編寫接口，主要包括：

1）PSY的register/unregister API

1: extern int power_supply_register(struct device *parent, 
   2:                                  struct power_supply *psy); 
   3: extern int power_supply_register_no_ws(struct device *parent, 
   4:                                  struct power_supply *psy); 
   5: extern void power_supply_unregister(struct power_supply *psy);

其中power_supply_register和power_supply_register_no_ws的區別是：power_supply_register註冊的PSY，具有wakeup系統的能力，而power_supply_register_no_ws不具有。

2）PSY狀態改變時通知power supply core的API

1: extern void power_supply_changed(struct power_supply *psy);

當PSY driver檢測到該設備某些屬性值改變時，須要調用這個接口，通知power supply core，power supply core會有以下動做：

若是該PSY是其它PSY的供電源，調用這些PSY的external_power_changed回調函數，通知它們（這些PSY具體要作些什麼，由它們的自身邏輯決定）；

若是配置了CONFIG_LEDS_TRIGGERS，調用power_supply_update_leds，更新該PSY有關的led狀態；

發送notifier，通知那些關心PSY設備狀態的drivers；

以統一的格式，向用戶空間發送uevent（這就是設備模型中class的魅力，對外接口由class core提供，能夠節省driver的工做量，同時確保了接口的一致性）。>

3）其它雜項接口

1: extern struct power_supply *power_supply_get_by_name(const char *name); 
   2: extern struct power_supply *power_supply_get_by_phandle(struct device_node *np, 
   3:                                                         const char *property); 
   4: extern int power_supply_am_i_supplied(struct power_supply *psy); 
   5: extern int power_supply_set_battery_charged(struct power_supply *psy); 
   6: extern int power_supply_is_system_supplied(void); 
   7: extern int power_supply_powers(struct power_supply *psy, struct device *dev);

power_supply_get_by_name，經過名字獲取PSY指針。

power_supply_get_by_phandle，從DTS中，解析出對應dePSY指針（後面會詳細介紹）。

power_supply_am_i_supplied，查詢本身是否由其它PSY供電。

power_supply_set_battery_charged，調用指定PSY的set_charged回調。

power_supply_is_system_supplied，查詢系統是否有有效的或者處於online狀態的PSY，若是沒有，可能爲桌面系統。

power_supply_powers，在指定設備（一般是該PSY設備）的sysfs目錄（/sys/devices/xxx/）下，建立指定PSY的符號連接（/sys/devices/xxx/powers）。

3.4 向其它driver提供的用於接收PSY狀態改變notifier的API

經過notifier註冊接口註冊notifier以後，系統任何PSY設備的狀態發生改變，並調用了power_supply_changed接口，power supply core就是通知notifier的監聽者。

3.5 向用戶空間程序提供的API

power supply class經過兩種形式向用戶空間提供接口。

1）uevent（具體可參考「Linux設備模型(3)_Uevent」），以「名字=value」的形式，上報全部property的值，格式以下：

POWER_SUPPLY_NAME=xxx                     /* power supply name */ 
POWER_SUPPLY_xxx1=xxx                       /* property = value */ 
POWER_SUPPLY_xxx2=xxx 
…

uevent通常會在PSY設備添加到kernel時，或者PSY屬性發生改變時（可參考3.3中的介紹）發送。

2）sysfs

power supply class在power_supply_sysfs.c中，定義了至關多的默認attribute（見下面），若是某個PSY設備具備某個屬性，該屬性對應的attribute就會體如今sysfs中（通常位於「/sys/class/power_supply/xxx/」中）。

1: /* Must be in the same order as POWER_SUPPLY_PROP_* */
   2: static struct device_attribute power_supply_attrs[] = {
   3:     /* Properties of type `int' */
   4:     POWER_SUPPLY_ATTR(status),
   5:     POWER_SUPPLY_ATTR(charge_type),
   6:     POWER_SUPPLY_ATTR(health),
   7:     POWER_SUPPLY_ATTR(present),
   8:     POWER_SUPPLY_ATTR(online),
   9:     POWER_SUPPLY_ATTR(authentic),
  10:     POWER_SUPPLY_ATTR(technology),
  11:     POWER_SUPPLY_ATTR(cycle_count),
  12:     POWER_SUPPLY_ATTR(voltage_max),
  13:     POWER_SUPPLY_ATTR(voltage_min),
  14:     POWER_SUPPLY_ATTR(voltage_max_design),
  15:     POWER_SUPPLY_ATTR(voltage_min_design),
  16:     POWER_SUPPLY_ATTR(voltage_now),
  17:     POWER_SUPPLY_ATTR(voltage_avg),
  18:     POWER_SUPPLY_ATTR(voltage_ocv),
  19:     POWER_SUPPLY_ATTR(voltage_boot),
  20:     POWER_SUPPLY_ATTR(current_max),
  21:     POWER_SUPPLY_ATTR(current_now),
  22:     POWER_SUPPLY_ATTR(current_avg),
  23:     POWER_SUPPLY_ATTR(current_boot),
  24:     POWER_SUPPLY_ATTR(power_now),
  25:     POWER_SUPPLY_ATTR(power_avg),
  26:     POWER_SUPPLY_ATTR(charge_full_design),
  27:     POWER_SUPPLY_ATTR(charge_empty_design),
  28:     POWER_SUPPLY_ATTR(charge_full),
  29:     POWER_SUPPLY_ATTR(charge_empty),
  30:     POWER_SUPPLY_ATTR(charge_now),
  31:     POWER_SUPPLY_ATTR(charge_avg),
  32:     POWER_SUPPLY_ATTR(charge_counter),
  33:     POWER_SUPPLY_ATTR(constant_charge_current),
  34:     POWER_SUPPLY_ATTR(constant_charge_current_max),
  35:     POWER_SUPPLY_ATTR(constant_charge_voltage),
  36:     POWER_SUPPLY_ATTR(constant_charge_voltage_max),
  37:     POWER_SUPPLY_ATTR(charge_control_limit),
  38:     POWER_SUPPLY_ATTR(charge_control_limit_max),
  39:     POWER_SUPPLY_ATTR(input_current_limit),
  40:     POWER_SUPPLY_ATTR(energy_full_design),
  41:     POWER_SUPPLY_ATTR(energy_empty_design),
  42:     POWER_SUPPLY_ATTR(energy_full),
  43:     POWER_SUPPLY_ATTR(energy_empty),
  44:     POWER_SUPPLY_ATTR(energy_now),
  45:     POWER_SUPPLY_ATTR(energy_avg),
  46:     POWER_SUPPLY_ATTR(capacity),
  47:     POWER_SUPPLY_ATTR(capacity_alert_min),
  48:     POWER_SUPPLY_ATTR(capacity_alert_max),
  49:     POWER_SUPPLY_ATTR(capacity_level),
  50:     POWER_SUPPLY_ATTR(temp),
  51:     POWER_SUPPLY_ATTR(temp_max),
  52:     POWER_SUPPLY_ATTR(temp_min),
  53:     POWER_SUPPLY_ATTR(temp_alert_min),
  54:     POWER_SUPPLY_ATTR(temp_alert_max),
  55:     POWER_SUPPLY_ATTR(temp_ambient),
  56:     POWER_SUPPLY_ATTR(temp_ambient_alert_min),
  57:     POWER_SUPPLY_ATTR(temp_ambient_alert_max),
  58:     POWER_SUPPLY_ATTR(time_to_empty_now),
  59:     POWER_SUPPLY_ATTR(time_to_empty_avg),
  60:     POWER_SUPPLY_ATTR(time_to_full_now),
  61:     POWER_SUPPLY_ATTR(time_to_full_avg),
  62:     POWER_SUPPLY_ATTR(type),
  63:     POWER_SUPPLY_ATTR(scope),
  64:     POWER_SUPPLY_ATTR(charge_term_current),
  65:     POWER_SUPPLY_ATTR(calibrate),
  66:     /* Properties of type `const char *' */
  67:     POWER_SUPPLY_ATTR(model_name),
  68:     POWER_SUPPLY_ATTR(manufacturer),
  69:     POWER_SUPPLY_ATTR(serial_number),
  70: };

具體意義這裏就再也不詳細說明了。