Linux Power supply子系统分析之一

转自：http://www.wowotech.net/pm_subsystem/psy_class_overview.html

1.概述

对于便携式设备，如手机或者pad来说，battery都是必不可少的一个组成部分。kernel中为了方便对battery的管理，专门提供了power supply framework。battery管理我觉得可以分开为两个部分，一个是电池监控（fuelgauge），另一个是充放电管理（charger），所以我们在内核中也是把它分成了两个驱动来管理。fuelgauge驱动主要是负责向上层android系统提供当前电池的电量以及健康状态信息等等，另外除了这个以外，它也向charger驱动提供电池的相关信息；charger驱动主要负责电源线的插拔检测，以及充放电的过程管理。对于battery管理，硬件上有电量计IC和充放电IC。

2.Power Supply设计思路

先来回答一个问题：kernel中设备驱动的目的，是管理设备，并提供给用户空间程序使用，那么对PSY设备而言，kernel要管理什么？用户空间程序要使用什么？

其实PSY设备是一个特例，它的目的很单纯，就为系统供电。如果只考虑这个目的，就不需要任何驱动了，但情况会稍微复杂，因为：

1.PSY设备可能是电池，这引申出来电量检测， 充电管理等多个议题。此时，PSY driver需要管理的事情包括：检测电池类型，检测电池电量；检测充电状态等等。而用户空间则需要将检测到的结果显示给用户。

2.系统中可能有多个PSY设备，这些设备可能还有级联关系，如有些平板电脑中，可能同时存在DC-charger、USB-charger和battery供电。此时，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.Power Supply软件架构

power supply framework在kernel/drivers/power/下。内核抽象出来power supply子系统为驱动提供了统一的框架。功能包括：1.抽象PSY设备的共性，向用户空间提供统一的API

       2.为底层PSY驱动的编写，提供简单、统一的方式。同事封装并实现公共逻辑。

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/目录下。

接着来看一下核心数据结构

1.struct power_supply

struct power_supply为power supply class的核心数据结构，用于抽象PSY设备，定义如下：

struct power_supply {
	const char *name;   //该PSY的名称
	enum power_supply_type type; //该PSY的类型，枚举类型，一般包括:battery、USB-charger、DC-charger。
	enum power_supply_property *properties; //该PSY具有的属性列表，枚举型。
	size_t num_properties;  //属性的个数

	char **supplied_to; //一个字符串数组，保存了由该PSY供电的PSY列表，以此可将PAY组成互相级联的PSY链表。这些被供电的PSY，称作supplicant（客户端，乞求者）
	size_t num_supplicants;//supplicant的个数。

	char **supplied_from; //一个字符串数组，保存了该PSY供电的PSY列表，也称作supply（提供者），从另外一个方向组织PSY之间的级联关系。
	size_t num_supplies; //supply的个数
#ifdef CONFIG_OF
	struct device_node *of_node; //用于保存of_node指针。
#endif

	int (*get_property)(struct power_supply *psy, //PSY driver需要实现的回调函数，用于获取属性值。
			    enum power_supply_property psp,
			    union power_supply_propval *val);
	int (*set_property)(struct power_supply *psy,  //PSY driver需要实现的回调函数，用于设置属性值。
                            enum power_supply_property psp,
			    const union power_supply_propval *val);
	int (*property_is_writeable)(struct power_supply *psy,  //返回指定的属性值是否可写（用于sysfs）；
				     enum power_supply_property psp);
	void (*external_power_changed)(struct power_supply *psy); //当一个PSY设备存在supply PSY，且该supply PSY的属性发生改变（如online offline）时，power supply core会调用该回调函数，通知PSY driver以便让它做出相应处理。
	void (*set_charged)(struct power_supply *psy);     //该回调函数的应用场景有点奇怪，外部模块通知PAY driver，该PSY设备的状态改变了，自己改变了自己不知道，要外部通知，希望大家在实际工作中不要遇到，太纠结了。

	/* For APM emulation, think legacy userspace. */
	int use_for_apm;

	/* private */
	struct device *dev;
	struct work_struct changed_work; //用户处理状态改变的work queue，主要思路是当该PSY的状态发生改变，启动一个workqueue，查询并通知所有的supplicants。
	spinlock_t changed_lock;
	bool changed;
#ifdef CONFIG_THERMAL
	struct thermal_zone_device *tzd;
	struct thermal_cooling_device *tcd;
#endif

#ifdef CONFIG_LEDS_TRIGGERS
	struct led_trigger *charging_full_trig;
	char *charging_full_trig_name;
	struct led_trigger *charging_trig;
	char *charging_trig_name;
	struct led_trigger *full_trig;
	char *full_trig_name;
	struct led_trigger *online_trig; //如果配置了CONFIC_LED_TRIGGERS，则调用的linux led class的接口，注册相应的LED设备，用于PSY状态指示。
	char *online_trig_name;
	struct led_trigger *charging_blink_full_solid_trig;
	char *charging_blink_full_solid_trig_name;
#endif
};

2.PSY的类型

PSY类型由enum power_supply_type定义：

enum power_supply_type {
	POWER_SUPPLY_TYPE_UNKNOWN = 0, //未知
	POWER_SUPPLY_TYPE_BATTERY,     //电池，手机平板上面最常用的
	POWER_SUPPLY_TYPE_UPS,         //不间断供电的，一般用户服务器   
	POWER_SUPPLY_TYPE_MAINS,        //主供电设备，如笔记本电脑适配器，特点是可以单独供电，当其断开时，再由辅助设备供电。
	POWER_SUPPLY_TYPE_USB,		/* Standard Downstream Port */
	POWER_SUPPLY_TYPE_USB_DCP,	/* Dedicated Charging Port */
	POWER_SUPPLY_TYPE_USB_CDP,	/* Charging Downstream Port */
	POWER_SUPPLY_TYPE_USB_ACA,	/* Accessory Charger Adapters */
};

3.PSY属性

power supply class将所有可能PSY属性，以枚举型变量形式抽象出来，PSY driver可以根据设备的实际情况，从中选取一些。

enum power_supply_property {
	/* Properties of type `int' */
	POWER_SUPPLY_PROP_STATUS = 0, //该PSY的status，主要是充电状态，包括：unknown,charging,discharging,not charging full,
	POWER_SUPPLY_PROP_CHARGE_TYPE,//充电类型
	POWER_SUPPLY_PROP_HEALTH, //健康状况，包括：good dead  over voltage等
	POWER_SUPPLY_PROP_PRESENT, //电量百分比
	POWER_SUPPLY_PROP_ONLINE,  //是否在线
	POWER_SUPPLY_PROP_AUTHENTIC,
	POWER_SUPPLY_PROP_TECHNOLOGY, //采用的技术
	POWER_SUPPLY_PROP_CYCLE_COUNT,
	POWER_SUPPLY_PROP_VOLTAGE_MAX,
	POWER_SUPPLY_PROP_VOLTAGE_MIN,
	POWER_SUPPLY_PROP_VOLTAGE_MAX_DESIGN,
	POWER_SUPPLY_PROP_VOLTAGE_MIN_DESIGN,
	POWER_SUPPLY_PROP_VOLTAGE_NOW,
	POWER_SUPPLY_PROP_VOLTAGE_AVG,
	POWER_SUPPLY_PROP_VOLTAGE_OCV,
	POWER_SUPPLY_PROP_CURRENT_MAX,
	POWER_SUPPLY_PROP_CURRENT_NOW,
	POWER_SUPPLY_PROP_CURRENT_AVG,
	POWER_SUPPLY_PROP_POWER_NOW,
	POWER_SUPPLY_PROP_POWER_AVG,
	POWER_SUPPLY_PROP_CHARGE_FULL_DESIGN,
	POWER_SUPPLY_PROP_CHARGE_EMPTY_DESIGN,
	POWER_SUPPLY_PROP_CHARGE_FULL,
	POWER_SUPPLY_PROP_CHARGE_EMPTY,
	POWER_SUPPLY_PROP_CHARGE_NOW,
	POWER_SUPPLY_PROP_CHARGE_AVG,
	POWER_SUPPLY_PROP_CHARGE_COUNTER,
	POWER_SUPPLY_PROP_CONSTANT_CHARGE_CURRENT,
	POWER_SUPPLY_PROP_CONSTANT_CHARGE_CURRENT_MAX,
	POWER_SUPPLY_PROP_CONSTANT_CHARGE_VOLTAGE,
	POWER_SUPPLY_PROP_CONSTANT_CHARGE_VOLTAGE_MAX,
	POWER_SUPPLY_PROP_CHARGE_CONTROL_LIMIT,
	POWER_SUPPLY_PROP_CHARGE_CONTROL_LIMIT_MAX,
	POWER_SUPPLY_PROP_ENERGY_FULL_DESIGN,
	POWER_SUPPLY_PROP_ENERGY_EMPTY_DESIGN,
	POWER_SUPPLY_PROP_ENERGY_FULL,
	POWER_SUPPLY_PROP_ENERGY_EMPTY,
	POWER_SUPPLY_PROP_ENERGY_NOW,
	POWER_SUPPLY_PROP_ENERGY_AVG,
	POWER_SUPPLY_PROP_CAPACITY, /* in percents! */
	POWER_SUPPLY_PROP_CAPACITY_ALERT_MIN, /* in percents! */
	POWER_SUPPLY_PROP_CAPACITY_ALERT_MAX, /* in percents! */
	POWER_SUPPLY_PROP_CAPACITY_LEVEL, //容量
	POWER_SUPPLY_PROP_TEMP,
	POWER_SUPPLY_PROP_TEMP_ALERT_MIN,
	POWER_SUPPLY_PROP_TEMP_ALERT_MAX,
	POWER_SUPPLY_PROP_TEMP_AMBIENT,
	POWER_SUPPLY_PROP_TEMP_AMBIENT_ALERT_MIN,
	POWER_SUPPLY_PROP_TEMP_AMBIENT_ALERT_MAX,
	POWER_SUPPLY_PROP_TIME_TO_EMPTY_NOW,
	POWER_SUPPLY_PROP_TIME_TO_EMPTY_AVG,
	POWER_SUPPLY_PROP_TIME_TO_FULL_NOW,
	POWER_SUPPLY_PROP_TIME_TO_FULL_AVG,
	POWER_SUPPLY_PROP_TYPE, /* use power_supply.type instead */
	POWER_SUPPLY_PROP_SCOPE,
	/* Local extensions */
	POWER_SUPPLY_PROP_USB_HC,
	POWER_SUPPLY_PROP_USB_OTG,
	POWER_SUPPLY_PROP_CHARGE_ENABLED,
	/* Local extensions of type int64_t */
	POWER_SUPPLY_PROP_CHARGE_COUNTER_EXT,
	/* Properties of type `const char *' */
	POWER_SUPPLY_PROP_MODEL_NAME,
	POWER_SUPPLY_PROP_MANUFACTURER,
	POWER_SUPPLY_PROP_SERIAL_NUMBER,
};

4.向具体的PSY driver提供的API

power supply class 首要任务，是向PSY driver提供统一的驱动编程接口，主要包括：

1.PSY 的register/unregister API

extern int power_supply_register(struct device *parent,
				 struct power_supply *psy);
extern void power_supply_unregister(struct power_supply *psy);
extern int power_supply_powers(struct power_supply *psy, struct device *dev);

2.PSY状态改变时通知power supply core的API

extern void power_supply_changed(struct power_supply *psy);

当PSY driver检测到该设备某些属性改变时，需要调用这个接口，通知power supply core，power supply core会有如下动作

如果该PSY是其他PSY的供电源，调用这些PSY的external_power_changed回调函数，通知他们（这些PSY具体要做什么，由他们自身的逻辑决定）；

发生notifier通知那些关心PSY设备状态的drivers；

以统一的格式向用户空间发送uevent。（这就是设备模型中ckass的魅力，对外接口由class core提供，可以节省driver的工作量，同时确保了接口的一致性）。

3.其他杂项接口

extern struct power_supply *power_supply_get_by_name(const char *name); //通过名字获取PSY指针
extern int power_supply_am_i_supplied(struct power_supply *psy);//查询自己是否由其他PSY供电
extern int power_supply_set_battery_charged(struct power_supply *psy);//调用指定的PSY的set_changed回调。
extern int power_supply_is_system_supplied(void); //检查系统中是否有有效的或者处于online状态的PSY，如果没有，可能为桌面系统、

extern int power_supply_powers(struct power_supply *psy, struct device *dev);//在指定的设备的sysfs目录下创建指定的PSY符合连接。

4.向用户空间提供的API

power supply class通过两种形式向用户空间提供接口。

（1）uevent，以“名字=value”的形式，上报所有property的值，格式如下：

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

uevent一般会在PSY设备添加到kernel时，或者PSY属性发生改变时发生。

（2）sysfs

power supply class在power_supply_class.c中，定义了相当多的默认attribute，如果某个PSY设备具有某个属性，该属性对应的attribute就会体现在sysfs中（一般位于“/sys/class/power_suooly/xxx/”中）

/* Must be in the same order as POWER_SUPPLY_PROP_* */
static struct device_attribute power_supply_attrs[] = {
	/* Properties of type `int' */
	POWER_SUPPLY_ATTR(status),
	POWER_SUPPLY_ATTR(charge_type),
	POWER_SUPPLY_ATTR(health),
	POWER_SUPPLY_ATTR(present),
	POWER_SUPPLY_ATTR(online),
	POWER_SUPPLY_ATTR(authentic),
	POWER_SUPPLY_ATTR(technology),
	POWER_SUPPLY_ATTR(cycle_count),
	POWER_SUPPLY_ATTR(voltage_max),
	POWER_SUPPLY_ATTR(voltage_min),
	POWER_SUPPLY_ATTR(voltage_max_design),
	POWER_SUPPLY_ATTR(voltage_min_design),
	POWER_SUPPLY_ATTR(voltage_now),
	POWER_SUPPLY_ATTR(voltage_avg),
	POWER_SUPPLY_ATTR(voltage_ocv),
	POWER_SUPPLY_ATTR(current_max),
	POWER_SUPPLY_ATTR(current_now),
	POWER_SUPPLY_ATTR(current_avg),
	POWER_SUPPLY_ATTR(power_now),
	POWER_SUPPLY_ATTR(power_avg),
	POWER_SUPPLY_ATTR(charge_full_design),
	POWER_SUPPLY_ATTR(charge_empty_design),
	POWER_SUPPLY_ATTR(charge_full),
	POWER_SUPPLY_ATTR(charge_empty),
	POWER_SUPPLY_ATTR(charge_now),
	POWER_SUPPLY_ATTR(charge_avg),
	POWER_SUPPLY_ATTR(charge_counter),
	POWER_SUPPLY_ATTR(constant_charge_current),
	POWER_SUPPLY_ATTR(constant_charge_current_max),
	POWER_SUPPLY_ATTR(constant_charge_voltage),
	POWER_SUPPLY_ATTR(constant_charge_voltage_max),
	POWER_SUPPLY_ATTR(charge_control_limit),
	POWER_SUPPLY_ATTR(charge_control_limit_max),
	POWER_SUPPLY_ATTR(energy_full_design),
	POWER_SUPPLY_ATTR(energy_empty_design),
	POWER_SUPPLY_ATTR(energy_full),
	POWER_SUPPLY_ATTR(energy_empty),
	POWER_SUPPLY_ATTR(energy_now),
	POWER_SUPPLY_ATTR(energy_avg),
	POWER_SUPPLY_ATTR(capacity),
	POWER_SUPPLY_ATTR(capacity_alert_min),
	POWER_SUPPLY_ATTR(capacity_alert_max),
	POWER_SUPPLY_ATTR(capacity_level),
	POWER_SUPPLY_ATTR(temp),
	POWER_SUPPLY_ATTR(temp_alert_min),
	POWER_SUPPLY_ATTR(temp_alert_max),
	POWER_SUPPLY_ATTR(temp_ambient),
	POWER_SUPPLY_ATTR(temp_ambient_alert_min),
	POWER_SUPPLY_ATTR(temp_ambient_alert_max),
	POWER_SUPPLY_ATTR(time_to_empty_now),
	POWER_SUPPLY_ATTR(time_to_empty_avg),
	POWER_SUPPLY_ATTR(time_to_full_now),
	POWER_SUPPLY_ATTR(time_to_full_avg),
	POWER_SUPPLY_ATTR(type),
	POWER_SUPPLY_ATTR(scope),
	/* Local extensions */
	POWER_SUPPLY_ATTR(usb_hc),
	POWER_SUPPLY_ATTR(usb_otg),
	POWER_SUPPLY_ATTR(charge_enabled),
	/* Local extensions of type int64_t */
	POWER_SUPPLY_ATTR(charge_counter_ext),
	/* Properties of type `const char *' */
	POWER_SUPPLY_ATTR(model_name),
	POWER_SUPPLY_ATTR(manufacturer),
	POWER_SUPPLY_ATTR(serial_number),
};

5.怎样基于power supply class编写PSY driver

最后从PSY driver的角度，说明一下怎么基于power supply class编写驱动：

（1）根据硬件spec，确定PSY设备具备哪些特性，并把他们和enum power_supply_property对应。

（2）根据实际情况，实现这些properties的get/set接口。

（3）定义一个struct power_supply 变量，并初始化必要字段后，调用power_supply_register或者power_supply_register_no_ws，将其注册到kernel中。

（4）根据实际情况，启动设备属性变化的监控逻辑，例如中断，轮询等，并在发生改变时，调用power_supply_changed，通知power suopply core。

也许你会笑，说简单啊！确实如此，不变的原则，framework只能给们提供良好的机制，便捷的方式等等，但是设备要做什么事情，只有设备驱动最清楚，永远都不可能偷懒啊！