Skip to contentSkip to conversation

power_supply: Introduce generic psy charging driver

RFC New Jenny TC 1 participant 1 message May 26, 2014

Subsystems (2)
lore
Share & tools
lore

Jenny TC

author
#0 lore raw

RFC 1/1 power_supply: Introduce generic psy charging driver

RFC: Optimized string lookup, cleaned WARN_ON, removed cable_list initialization etc.

The Power Supply charging driver connects multiple subsystems
to do charging in a generic way. The subsystems involves power_supply, thermal and battery communication subsystems (1wire). With this the charging is handled in a generic way.

The driver makes use of different new features - Battery Identification interfaces, pluggable charging algorithms, charger cable arbitrations etc. The patch also introduces generic interface for charger cable notifications. Charger cable events and capabilities can be notified using the generic power_supply_notifier chain.

Overall this driver removes the charging logic out of the charger chip driver and the charger chip driver can just listen to the request from the power supply charging driver to set the charger properties. This can be implemented by exposing get_property and set property callbacks.

---
 Documentation/power/power_supply_charger.txt |  350 +++++++++
 drivers/power/Kconfig                        |    8 +
 drivers/power/Makefile                       |    1 +
 drivers/power/power_supply_charger.c         | 1022 ++++++++++++++++++++++++++
 drivers/power/power_supply_charger.h         |  226 ++++++
 drivers/power/power_supply_core.c            |    3 +
 include/linux/power/power_supply_charger.h   |  307 ++++++++
 include/linux/power_supply.h                 |  161 ++++
 8 files changed, 2078 insertions(+)
 create mode 100644 Documentation/power/power_supply_charger.txt
 create mode 100644 drivers/power/power_supply_charger.c
 create mode 100644 drivers/power/power_supply_charger.h
 create mode 100644 include/linux/power/power_supply_charger.h
Documentation/power/power_supply_charger.txt new file +350 -0
new file mode 100644
index 0000000..e81754b
@@ -0,0 +1,350 @@
+1. Introduction
+===============
+
+The Power Supply charging driver connects multiple subsystems
+to do charging in a generic way. The subsystems involves power_supply,
+thermal and battery communication subsystems (1wire). With this the charging is
+handled in a generic way by plugging the driver to power supply subsystem.
+
+The driver introduces different new features - Battery Identification
+interfaces, pluggable charging algorithms, charger cable arbitrations etc.
+
+In existing driver implementations the charging is done based on the static
+battery characteristics. This is done at the boot time by passing the battery
+properties (max_voltage, capacity) etc. as a platform data to the
+charger/battery driver. But new generation high volt batteries needs to be
+identified dynamically to do charging in a safe manner. The batteries are
+coming with different communication protocols. It become necessary to
+communicate with battery and identify it's charging profiles before setup
+charging.
+
+Also the charging algorithms can vary based on the battery characteristics
+and the platform characteristics. To handle charging in a generic way it's
+necessary to support pluggable charging algorithms. Power Supply Charging
+driver selects algorithms based on the type of battery charging profile.
+This is a simple binding and can be improved later. This may be improved to
+select the algorithms based on the platform requirements. Also we can extend
+this driver to plug algorithms from the user space.
+
+The driver also introduces the charger cable arbitration. A charger may
+supports multiple cables, but it may not be able to charge with multiple
+cables at a time (USB/AC/Wireless etc.). The arbitration logic inside the
+driver selects the cable based on it's capabilities and the maximum
+charge current the platform can support.
+
+Also the driver exposes features to control charging on different platform
+states. One such feature is thermal. The driver handles the thermal
+throttling requests for charging and control charging based on the thermal
+subsystem requirements.
+
+Overall this driver removes the charging logic out of the charger chip driver
+and the charger chip driver can just listen to the request from the power
+supply charging driver to set the charger properties. This can be implemented
+by exposing get_property and set property callbacks.
+
+2. Reading Battery charging profile
+===================================
+
+Power Supply charging driver expose APIs to retrieve battery profile of a
+battery. The battery profile can be read by battery identification driver which
+may be 1wire/I2C/SFI driver. Battery identification driver can register the
+battery profile with the power supply charging driver using the API
+psy_battery_prop_changed(). The driver also exposes API
+psy_get_battery_prop() to retrieve the battery profile which can be
+used by power supply drivers to setup the charging. Also drivers
+can register for battery removal/insertion notifications using
+power_supply_reg_notifier()
+
+3. Use Charging Driver to setup charging
+===========================================
+
+* Register the driver with the power_supply class
+* Register the driver with the power supply charging driver
+* Expose set_property and get_property functions so that charging
+  framework can control the charging
+
+3.1  Registering charger chip driver with power supply charging driver
+================================================================
+
+struct power_supply_class psy_usb;
+struct power_supply_charger psyc_usb;
+
+/* register with power supply subsystem */
+psy_usb.name = DEV_NAME;
+psy_usb.type = POWER_SUPPLY_TYPE_USB;
+
+/* pointer to power supply property structure */
+psy_usb.properties =  &psy_usb_props;
+psy_usb.num_properties = ARRAY_SIZE(psy_usb_props);
+
+/* pointer to power supply get property function */
+psy_usb.get_property = psy_usb_get_property;
+
+/* pointer to power supply set property function */
+psy_usb.set_property = psy_usb_set_property;
+
+/* pointer to the supplied_to argument to indicate the batteries
+   to which this charger is supplying power  */
+psy_usb.supplied_to = supplied_to;
+psy_usb.num_supplicants = num_supplicants;
+
+/* register with power_supply subsystem */
+power_supply_register(device, &psy_usb);
+
+/* Register with power supply charging driver */
+
+/* define supported cable types for this driver */
+psyc_usb.supported_cables = POWER_SUPPLY_CHARGER_TYPE_USB;
+
+/* pointer to power supply charger get property function */
+psyc_usb.get_property = bq24261_usb_psyc_get_property;
+
+/* pointer to power supply charger set property function */
+psyc_usb.set_property = bq24261_usb_psyc_set_property;
+
+/* pointer to throttle states */
+psyc_usb.throttle_states = chip->pdata->throttle_states;
+
+/* Number of throttle states */
+psyc_usb.num_throttle_states = chip->pdata->num_throttle_states;
+
+/*register with power supply charging */
+power_supply_register_charger(&chip->psy_usb, &chip->psyc_usb);
+
+3.2 Properties exposed to power supply class driver
+==================================================
+* POWER_SUPPLY_PROP_ONLINE
+	* Read access using get_property_function
+		* Returns the online property set using the set_property
+		  function
+	* Write access using set_property function
+		* Expose the value through get_property_function.
+* POWER_SUPPLY_PROP_PRESENT
+	* Read access using get_property_function
+		* Returns the present property set using the set_property
+		  function
+	* Write access using set_property function
+		* Expose the value through get_property_function.
+* POWER_SUPPLY_PROP_HEALTH
+	* Read access using get_property_function
+		* Returns charger health
+* POWER_SUPPLY_PROP_TYPE
+	* Read access using power_supply structure
+		* Returns charger type
+* POWER_SUPPLY_PROP_CHARGE_CONTROL_LIMIT
+	* Read access using get property
+		* Returns the present charge control limit
+	* Write access using set property
+		* Set charge control limit.
+		* Action: Driver is not expected to take any actions on this.
+			  Instead need to expose this on the read interface.
+			  Charging framework process this and notifies the
+			  charging parameters accordingly.
+* POWER_SUPPLY_PROP_CHARGE_CONTROL_LIMIT_MAX
+	* Read access using get property
+		* Returns the maximum charge control limit
+* POWER_SUPPLY_PROP_INPUT_CURRENT_LIMIT
+	* Read access using get property
+		* Returns the input current limit passed by set_property
+		  function
+		* Default value : 0
+	* Write access using set property
+		* Set input current limit
+		* Action : Write h/w register to set the input current limit
+			   based on the value
+* POWER_SUPPLY_PROP_CHARGE_CURRENT
+	* Read access using get property
+		* Returns charge current passed by set_property function
+		* Default value : 0
+	* Write access using set property
+		* Set charge current
+		* Action : Write h/w register to set the charge current based
+			   on the value
+* POWER_SUPPLY_PROP_CHARGE_VOLTAGE
+	* Read access using get property
+		* Returns charge voltage passed by set_property function
+		* Default value: 0
+	* Write access using set property
+		* Set charge voltage
+		* Action : Write h/w register to set the charge voltage based
+			   on the value
+* POWER_SUPPLY_PROP_CHARGE_TERM_CURRENT
+	* Read access using get property
+		* Returns charge termination current passed by set_property
+		  function
+		* Default value : 0
+	* Write access using set property
+		* Set charge termination current
+		* Action : Write h/w register to set the charge termination
+			   current
+			   based on the value
+* POWER_SUPPLY_PROP_TEMP_MIN
+	* Read access using get property
+		* Returns minimum charging  temperature passed by set_property
+		* Default value : Platform dependant
+	* Write access using set_property
+		* Set Minimum charging temperature
+		* Action : Write h/w register to set the minimum charging
+			   temperature based on the value
+* POWER_SUPPLY_PROP_TEMP_MAX
+	* Write access using set_property
+		* Set Maximum charging temperature
+		* Action : Write h/w register to set the maximum charging
+			   temperature based on the value
+	* Read access using get property
+		* Returns maximum charging  temperature passed by set_property
+		* Default value : Platform dependent
+* POWER_SUPPLY_PROP_MAX_CHARGE_CURRENT
+	* Read access using get property
+		* Returns maximum charging  current passed by set_property
+		* Default value : Platform dependent
+	* Write access using set_property
+		* Set Maximum charging current
+		* Action: Configure safety charging registers if any. If no h/w
+			  actions expected, report the value on the
+			  get_property interface.
+* POWER_SUPPLY_PROP_MAX_CHARGE_VOLTAGE
+	* Read access using get property
+		* Returns maximum charging  current passed by set_property
+		* Default value : Platform dependent
+	* Write access using set_property
+		* Set Maximum charging voltage
+		* Action: Configure safety charging registers if any. If not,
+			  no actions expected for this.
+
+3.3 Properties exposed to power supply charging driver
+=====================================================
+
+* POWER_SUPPLY_CHARGER_PROP_ENABLE_CHARGING
+	* Write access using set_property
+		* Enable/Disable charging. Charger supplies power to platform,
+		  but charging is disabled
+		* Action: Configure charger chip registers to enable/disable
+		  charging. Writing 0, disables charging, writing 1 enables
+		  charging
+* POWER_SUPPLY_CHARGER_PROP_ENABLE_CHARGER
+	* Write access using set_property
+		* Enable/Disable charger. Charger doesn't supply power to
+		  platform or battery and battery start to discharge.
+		* Action: Configure charger chip registers to enable/disable
+		  charger. Writing 0 disables charger, writing 1 enables
+		  charger
+* POWER_SUPPLY_CHARGER_PROP_CABLE_TYPE
+	* Write access using set_property
+		* Set charger cable type.
+		* Action: Report power supply type based on cable type
+* POWER_SUPPLY_CHARGER_PROP_RESET_WDT
+	* Write access using set_property
+		* Reset charger Watch Dog Timer
+		* Action: Reset charger Watch Dog Timer.
+* POWER_SUPPLY_CHARGER_PROP_PRIORITY
+	* Read access using get property
+		* Expose charger driver/chips priority if platform has multiple
+		  charger chip/drivers.
+
+3.4 Throttling data configuration
+=============================
+Power supply charging driver can take actions for Thermal throttling requests.
+Power supply core sends event PSY_EVENT_THROTTLE  on power_supply_notifier
+chain. Power supply charging driver handle this event and takes throttling
+actions as in the throttling configuration structure. The throttling
+configuration structure has the following format:
+
+struct psy_throttle_state {
+	enum psy_throttle_action throttle_action;
+	unsigned throttle_val;
+};
+
+enum psy_throttle_action {
+	/* Disable charger, charger doesn't supply VSYS */
+	PSY_THROTTLE_DISABLE_CHARGER = 0,
+
+	/* Disable charging, charger would supply VSYS */
+	PSY_THROTTLE_DISABLE_CHARGING,
+
+	/* Throttle charge current */
+	PSY_THROTTLE_CC_LIMIT,
+
+	/* Throttle input current limit */
+	PSY_THROTTLE_INPUT_LIMIT,
+};
+
+Throttling configuration example:
+
+struct psy_throttle_state my_throttle_states[] = {
+
+	/* Level 0:  Limit charge current to 1500mA. Normal Level */
+	{
+		.throttle_action = PSY_THROTTLE_CC_LIMIT,
+		.throttle_val = 1500,
+	},
+
+	/* Level 1: Limit charge current to 500mA */
+	{
+		.throttle_action = PSY_THROTTLE_CC_LIMIT,
+		.throttle_val = 500,
+	},
+
+	/*
+	* Level 2: Disable charging: Stop charging, charger supply power to
+	* platform.
+	*/
+	{
+		.throttle_action = PSY_THROTTLE_DISABLE_CHARGING,
+	},
+
+	/* Level 3: Disable charger: Battery start discharging */
+	{
+		.throttle_action = PSY_THROTTLE_DISABLE_CHARGER,
+	},
+
+};
+
+4. Charger Cable notifications
+==============================
+
+Charger cables can have different charging capabilities (current) depending on
+platform and cable type. The cable provider drivers detect and identify the
+cable types and notifies the power supply subsystem by posting an event
+PSY_EVENT_CABLE on the power_supply_notifier chain. The event notification
+should have a property structure pointer which indicates the cable type, event
+and capability.
+
+struct psy_cable_props cable;
+cable.chrg_evt = PSY_CHARGER_CABLE_EVENT_CONNECT;
+cable.chrg_type = PSY_CHARGER_CABLE_TYPE_USB_DCP;
+cable.ma = 1500;
+
+atomic_notifier_call_chain(&power_supply_notifier,
+				PSY_EVENT_CABLE, &cable);
+
+Power supply charging driver process this event and takes actions to setup
+charging.
+
+5. Registering new charging algorithm
+===================================
+Power supply charging driver supports pluggable charging algorithms. Charging
+algorithms processes charging profile and/or applies different logic (pulse
+charging/fast charging/relaxed charging) to decide the charging parameters (CC
+and CV).
+
+* Populate algorithm structure
+	struct psy_charging_algo new_algo;
+	/* populate the type charging profile the algorithm handles */
+	pse_algo.chrg_prof_type = PSY_CHRG_PROF_PSE;
+	pse_algo.name = "my_algo";
+	/* callback function to retrieve CC and CV */
+	pse_algo.get_next_cc_cv = my_algo_get_next_cc_cv;
+	/* callback function to retreive battery thresholds */
+	pse_algo.get_batt_thresholds = my_algo_get_bat_thresholds;
+	/* register charging algorithm */
+	power_supply_register_charging_algo(&pse_algo);
+
+When the type of charging profile reported by battery and algorithm matches,
+the algorithm will be invoked to get the charging parameters.
+
+6. TODO
+=======
+* Replace static cable array with dynamic list
+* Implement safety timer and watch dog timer features with more monitoring
+* Move charge full detection logic to psy charging driver from algorithm driver
drivers/power/Kconfig +8 -0
index 0196acf..f679f82 100644
@@ -14,6 +14,14 @@ config POWER_SUPPLY_DEBUG
 	  Say Y here to enable debugging messages for power supply class
 	  and drivers.
 
+config POWER_SUPPLY_CHARGER
+	bool "Power Supply Charger"
+	help
+	  Say Y here to enable the power supply charging control driver. Charging
+	  control supports charging in a generic way. This allows the charger
+	  drivers to keep the charging logic outside and the charger driver
+	  just need to abstract the charger hardware.
+
 config PDA_POWER
 	tristate "Generic PDA/phone power driver"
 	depends on !S390
drivers/power/Makefile +1 -0
index ee54a3e..405f0f4 100644
@@ -7,6 +7,7 @@ power_supply-$(CONFIG_LEDS_TRIGGERS)	+= power_supply_leds.o
 obj-$(CONFIG_POWER_SUPPLY)	+= power_supply.o
 obj-$(CONFIG_GENERIC_ADC_BATTERY)	+= generic-adc-battery.o
 
+obj-$(CONFIG_POWER_SUPPLY_CHARGER) += power_supply_charger.o
 obj-$(CONFIG_PDA_POWER)		+= pda_power.o
 obj-$(CONFIG_APM_POWER)		+= apm_power.o
 obj-$(CONFIG_MAX8925_POWER)	+= max8925_power.o
drivers/power/power_supply_charger.c new file +1022 -0

1,022 lines not on this page · raw message

drivers/power/power_supply_charger.h new file +226 -0

226 lines not on this page · raw message

drivers/power/power_supply_core.c +3 -0
index 2660664..1daa5c2 100644
@@ -483,6 +483,9 @@ static int ps_set_cur_charge_cntl_limit(struct thermal_cooling_device *tcd,
 	ret = psy->set_property(psy,
 		POWER_SUPPLY_PROP_CHARGE_CONTROL_LIMIT, &val);
 
+	atomic_notifier_call_chain(&power_supply_notifier,
+		PSY_EVENT_THROTTLE, psy);
+
 	return ret;
 }
 
include/linux/power/power_supply_charger.h new file +307 -0

307 lines not on this page · raw message

include/linux/power_supply.h +161 -0

177 lines not on this page · raw message

Signature · 1 line
1.7.9.5