power_supply: Add initial Charger-Manager driver

Charger Manager

	(C) 2011 MyungJoo Ham <myungjoo.ham@samsung.com>, GPL

Charger Manager provides in-kernel battery charger management that

requires temperature monitoring during suspend-to-RAM state

and where each battery may have multiple chargers attached and the userland

wants to look at the aggregated information of the multiple chargers.

Charger Manager is a platform_driver with power-supply-class entries.

An instance of Charger Manager (a platform-device created with Charger-Manager)

represents an independent battery with chargers. If there are multiple

batteries with their own chargers acting independently in a system,

the system may need multiple instances of Charger Manager.

1. Introduction

===============

Charger Manager supports the following:

* Support for multiple chargers (e.g., a device with USB, AC, and solar panels)

	A system may have multiple chargers (or power sources) and some of

	they may be activated at the same time. Each charger may have its

	own power-supply-class and each power-supply-class can provide

	different information about the battery status. This framework

	aggregates charger-related information from multiple sources and

	shows combined information as a single power-supply-class.

* Support for in suspend-to-RAM polling (with suspend_again callback)

	While the battery is being charged and the system is in suspend-to-RAM,

	we may need to monitor the battery health by looking at the ambient or

	battery temperature. We can accomplish this by waking up the system

	periodically. However, such a method wakes up devices unncessary for

	monitoring the battery health and tasks, and user processes that are

	supposed to be kept suspended. That, in turn, incurs unnecessary power

	consumption and slow down charging process. Or even, such peak power

	consumption can stop chargers in the middle of charging

	(external power input < device power consumption), which not

	only affects the charging time, but the lifespan of the battery.

	Charger Manager provides a function "cm_suspend_again" that can be

	used as suspend_again callback of platform_suspend_ops. If the platform

	requires tasks other than cm_suspend_again, it may implement its own

	suspend_again callback that calls cm_suspend_again in the middle.

	Normally, the platform will need to resume and suspend some devices

	that are used by Charger Manager.

2. Global Charger-Manager Data related with suspend_again

========================================================

In order to setup Charger Manager with suspend-again feature

(in-suspend monitoring), the user should provide charger_global_desc

with setup_charger_manager(struct charger_global_desc *).

This charger_global_desc data for in-suspend monitoring is global

as the name suggests. Thus, the user needs to provide only once even

if there are multiple batteries. If there are multiple batteries, the

multiple instances of Charger Manager share the same charger_global_desc

and it will manage in-suspend monitoring for all instances of Charger Manager.

The user needs to provide all the two entries properly in order to activate

in-suspend monitoring:

struct charger_global_desc {

char *rtc_name;

	: The name of rtc (e.g., "rtc0") used to wakeup the system from

	suspend for Charger Manager. The alarm interrupt (AIE) of the rtc

	should be able to wake up the system from suspend. Charger Manager

	saves and restores the alarm value and use the previously-defined

	alarm if it is going to go off earlier than Charger Manager so that

	Charger Manager does not interfere with previously-defined alarms.

bool (*rtc_only_wakeup)(void);

	: This callback should let CM know whether

	the wakeup-from-suspend is caused only by the alarm of "rtc" in the

	same struct. If there is any other wakeup source triggered the

	wakeup, it should return false. If the "rtc" is the only wakeup

	reason, it should return true.

};

3. How to setup suspend_again

=============================

Charger Manager provides a function "extern bool cm_suspend_again(void)".

When cm_suspend_again is called, it monitors every battery. The suspend_ops

callback of the system's platform_suspend_ops can call cm_suspend_again

function to know whether Charger Manager wants to suspend again or not.

If there are no other devices or tasks that want to use suspend_again

feature, the platform_suspend_ops may directly refer to cm_suspend_again

for its suspend_again callback.

The cm_suspend_again() returns true (meaning "I want to suspend again")

if the system was woken up by Charger Manager and the polling

(in-suspend monitoring) results in "normal".

4. Charger-Manager Data (struct charger_desc)

=============================================

For each battery charged independently from other batteries (if a series of

batteries are charged by a single charger, they are counted as one independent

battery), an instance of Charger Manager is attached to it.

struct charger_desc {

enum polling_modes polling_mode;

	: CM_POLL_DISABLE: do not poll this battery.

	  CM_POLL_ALWAYS: always poll this battery.

	  CM_POLL_EXTERNAL_POWER_ONLY: poll this battery if and only if

				       an external power source is attached.

	  CM_POLL_CHARGING_ONLY: poll this battery if and only if the

				 battery is being charged.

unsigned int polling_interval_ms;

	: Required polling interval in ms. Charger Manager will poll

	this battery every polling_interval_ms or more frequently.

enum data_source battery_present;

	CM_FUEL_GAUGE: get battery presence information from fuel gauge.

	CM_CHARGER_STAT: get battery presence from chargers.

char **psy_charger_stat;

	: An array ending with NULL that has power-supply-class names of

	chargers. Each power-supply-class should provide "PRESENT" (if

	battery_present is "CM_CHARGER_STAT"), "ONLINE" (shows whether an

	external power source is attached or not), and "STATUS" (shows whether

	the battery is {"FULL" or not FULL} or {"FULL", "Charging",

	"Discharging", "NotCharging"}).

int num_charger_regulators;

struct regulator_bulk_data *charger_regulators;

	: Regulators representing the chargers in the form for

	regulator framework's bulk functions.

char *psy_fuel_gauge;

	: Power-supply-class name of the fuel gauge.

int (*temperature_out_of_range)(int *mC);

	: This callback returns 0 if the temperature is safe for charging,

	a positive number if it is too hot to charge, and a negative number

	if it is too cold to charge. With the variable mC, the callback returns

	the temperature in 1/1000 of centigrade.

};

5. Other Considerations

=======================

At the charger/battery-related events such as battery-pulled-out,

charger-pulled-out, charger-inserted, DCIN-over/under-voltage, charger-stopped,

and others critical to chargers, the system should be configured to wake up.

At least the following should wake up the system from a suspend:

a) charger-on/off b) external-power-in/out c) battery-in/out (while charging)

It is usually accomplished by configuring the PMIC as a wakeup source.

	  This driver can be build as a module. If so, the module will be

	  called gpio-charger.

config CHARGER_MANAGER

	bool "Battery charger manager for multiple chargers"

	depends on REGULATOR && RTC_CLASS

	help

          Say Y to enable charger-manager support, which allows multiple

          chargers attached to a battery and multiple batteries attached to a

          system. The charger-manager also can monitor charging status in

          runtime and in suspend-to-RAM by waking up the system periodically

          with help of suspend_again support.

config CHARGER_MAX8997

	tristate "Maxim MAX8997/MAX8966 PMIC battery charger driver"

	depends on MFD_MAX8997 && REGULATOR_MAX8997

obj-$(CONFIG_CHARGER_MAX8903)	+= max8903_charger.o

obj-$(CONFIG_CHARGER_TWL4030)	+= twl4030_charger.o

obj-$(CONFIG_CHARGER_GPIO)	+= gpio-charger.o

obj-$(CONFIG_CHARGER_MANAGER)	+= charger-manager.o

obj-$(CONFIG_CHARGER_MAX8997)	+= max8997_charger.o

obj-$(CONFIG_CHARGER_MAX8998)	+= max8998_charger.o

/*

 * Copyright (C) 2011 Samsung Electronics Co., Ltd.

 * MyungJoo.Ham <myungjoo.ham@samsung.com>

 *

 * Charger Manager.

 * This framework enables to control and multiple chargers and to

 * monitor charging even in the context of suspend-to-RAM with

 * an interface combining the chargers.

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License version 2 as

 * published by the Free Software Foundation.

**/

#ifndef _CHARGER_MANAGER_H

#define _CHARGER_MANAGER_H

#include <linux/power_supply.h>

enum data_source {

	CM_FUEL_GAUGE,

	CM_CHARGER_STAT,

};

enum polling_modes {

	CM_POLL_DISABLE = 0,

	CM_POLL_ALWAYS,

	CM_POLL_EXTERNAL_POWER_ONLY,

	CM_POLL_CHARGING_ONLY,

};

/**

 * struct charger_global_desc

 * @rtc_name: the name of RTC used to wake up the system from suspend.

 * @rtc_only_wakeup:

 *	If the system is woken up by waekup-sources other than the RTC or

 *	callbacks, Charger Manager should recognize with

 *	rtc_only_wakeup() returning false.

 *	If the RTC given to CM is the only wakeup reason,

 *	rtc_only_wakeup should return true.

 */

struct charger_global_desc {

	char *rtc_name;

	bool (*rtc_only_wakeup)(void);

};

/**

 * struct charger_desc

 * @polling_mode:

 *	Determine which polling mode will be used

 * @polling_interval_ms: interval in millisecond at which

 *	charger manager will monitor battery health

 * @battery_present:

 *	Specify where information for existance of battery can be obtained

 * @psy_charger_stat: the names of power-supply for chargers

 * @num_charger_regulator: the number of entries in charger_regulators

 * @charger_regulators: array of regulator_bulk_data for chargers

 * @psy_fuel_gauge: the name of power-supply for fuel gauge

 * @temperature_out_of_range:

 *	Determine whether the status is overheat or cold or normal.

 *	return_value > 0: overheat

 *	return_value == 0: normal

 *	return_value < 0: cold

 */

struct charger_desc {

	enum polling_modes polling_mode;

	unsigned int polling_interval_ms;

	enum data_source battery_present;

	char **psy_charger_stat;

	int num_charger_regulators;

	struct regulator_bulk_data *charger_regulators;

	char *psy_fuel_gauge;

	int (*temperature_out_of_range)(int *mC);

};

#define PSY_NAME_MAX	30

/**

 * struct charger_manager

 * @entry: entry for list

 * @dev: device pointer

 * @desc: instance of charger_desc

 * @fuel_gauge: power_supply for fuel gauge

 * @charger_stat: array of power_supply for chargers

 * @charger_enabled: the state of charger

 * @emergency_stop:

 *	When setting true, stop charging

 * @last_temp_mC: the measured temperature in milli-Celsius

 * @status_save_ext_pwr_inserted:

 *	saved status of external power before entering suspend-to-RAM

 * @status_save_batt:

 *	saved status of battery before entering suspend-to-RAM

 */

struct charger_manager {

	struct list_head entry;

	struct device *dev;

	struct charger_desc *desc;

	struct power_supply *fuel_gauge;

	struct power_supply **charger_stat;

	bool charger_enabled;

	int emergency_stop;

	int last_temp_mC;

	bool status_save_ext_pwr_inserted;

	bool status_save_batt;

};

#ifdef CONFIG_CHARGER_MANAGER

extern int setup_charger_manager(struct charger_global_desc *gd);

extern bool cm_suspend_again(void);

#else

static void __maybe_unused setup_charger_manager(struct charger_global_desc *gd)

{ }

static bool __maybe_unused cm_suspend_again(void)

{

	return false;

}

#endif

#endif /* _CHARGER_MANAGER_H */