mirror of
https://github.com/followmsi/android_kernel_google_msm.git
synced 2024-11-06 23:17:41 +00:00
a1f0242d41
Add the qpnp-charger documentation to supplement the existing devicetree bindings. Also, define the power supply framework properties used throughout the qpnp-charger driver and how they are impacted through other supplicants and supplier drivers. Change-Id: I7a772f25674639a2b73758ab10b2ff2f9a553563 Signed-off-by: David Keitel <dkeitel@codeaurora.org>
171 lines
7 KiB
Text
171 lines
7 KiB
Text
Introduction
|
|
============
|
|
|
|
The (Qualcomm Plug and Play) QPNP charger driver implements input and external
|
|
peripheral power management for 8974, 8x26 and 8x10 chipsets. The input can
|
|
be supplied to the device via either a DC or USB path. Output paths are
|
|
the VPH_PWR rail via the buck and a reverse boost feature on VCHG.
|
|
|
|
Hardware description
|
|
====================
|
|
|
|
Reverse Boost Feature
|
|
---------------------
|
|
|
|
The reverse boost feature is used for multiple purposes:
|
|
|
|
* USB OTG
|
|
* Voltage collapse protection (VCP)
|
|
* A regulator output for device peripherals such as LED
|
|
|
|
To handle each of these individual use cases two regulators are implemented
|
|
in the qpnp-charger driver. A boost and an OTG regulator. These regulators
|
|
represent the boost and USB OVP FET respectively. Using devicetree
|
|
configuration the corresponding hierarchy is defined on a per PMIC chip basis.
|
|
|
|
Consumers can then vote for each regulator to be enabled if necessary and
|
|
the charger handles the request appropriately.
|
|
|
|
Software description
|
|
====================
|
|
|
|
Design
|
|
======
|
|
|
|
Design Goals:
|
|
|
|
The qpnp-charger driver interacts as a consumer and producer for various
|
|
input and output power information, as well as relaying information to userspace.
|
|
|
|
Given the abundance of configurations for different board designs
|
|
it is important to distinguish between configurations which are required versus
|
|
those available to be configured at compile and at run time. The target
|
|
of this design is to achieve this as follows:
|
|
|
|
1. Compile time options are defined in the devicetree documentation.
|
|
|
|
Documentation/devicetree/bindings/power/qpnp-charger.txt
|
|
|
|
2. Runtime configuration is implemented via the power supply framework.
|
|
|
|
3. Chipset dependent features and workarounds are configured via
|
|
runtime subtype detection and are typically not changed.
|
|
|
|
|
|
Power Supply Property Implementations
|
|
-------------------------------------
|
|
|
|
While the power supply framework implementation supplies basic definitions
|
|
of each property this documentation will define the ones used in more detail.
|
|
|
|
The notification model in the power supply framework is used to notify other
|
|
consumers of information conveyed by the charger driver as outlined below.
|
|
Each notification is handled via the supply supplicant relationship.
|
|
Whenever a supply is changed and the power_supply_changed API is called the
|
|
external_power_supply_changed callback will be invoked at the supplicant.
|
|
One can picture the notification as one directional.
|
|
|
|
power_supply_changed()
|
|
+----------------------+ +------------+
|
|
| | external_power_supply_changed() | |
|
|
| supply |------------------------------------->| supplicant |
|
|
| | | |
|
|
+----------------------+ +------------+
|
|
|
|
Registered supplies in qpnp-charger:
|
|
* battery
|
|
* dc
|
|
|
|
Other supplies in other drivers:
|
|
* bms: registered in the Battery Management (BMS) qpnp-bms.c driver.
|
|
* usb: registered in the corresponding dwc3 or msm_otg driver.
|
|
|
|
Battery:
|
|
* supplicants: bms
|
|
* supplies: bms, usb, dc
|
|
* writable properties:
|
|
- POWER_SUPPLY_PROP_CHARGING_ENABLED
|
|
This bit allows to disable current from entering the battery
|
|
as well as disabling any current being drawn from external inputs.
|
|
- POWER_SUPPLY_PROP_SYSTEM_TEMP_LEVEL
|
|
The temperature level is used by the thermal daemon to configure
|
|
the maximum battery current input limit to reduce heat produced
|
|
from the battery when charging.
|
|
- POWER_SUPPLY_PROP_INPUT_CURRENT_MAX
|
|
The maximum input current limit drawn from USB. This property
|
|
is used by the charger_monitor userspace service.
|
|
- POWER_SUPPLY_PROP_INPUT_CURRENT_TRIM
|
|
The input current trim is used to further adjust the USB input
|
|
current limit. This is also utilized by the charger_monitor userspace
|
|
service.
|
|
- POWER_SUPPLY_PROP_INPUT_CURRENT_SETTLED
|
|
An indicator bit indicating that the charger_monitor has calibrated the input
|
|
current limit.
|
|
- POWER_SUPPLY_PROP_VOLTAGE_MIN
|
|
The minimum input voltage for a given input to the charger.
|
|
- POWER_SUPPLY_PROP_COOL_TEMP
|
|
Allows to configure a cool threshold notification which is configured via the
|
|
ADC battery temperature monitoring API.
|
|
- POWER_SUPPLY_PROP_WARM_TEMP
|
|
Allows to configure a warm threshold notification which is configured via the
|
|
ADC battery temperature monitoring API.
|
|
- POWER_SUPPLY_PROP_CAPACITY
|
|
This property is set by the BMS supply whenever the capacity of the battery is
|
|
changed. If there is no BMS supply present a default value is returned. This
|
|
property can also be manually overridden from userspace to set a fake capacity.
|
|
This feature allows for test environments to prevent certain userspaces from
|
|
shutting down the device.
|
|
* other notable properties:
|
|
- POWER_SUPPLY_PROP_ONLINE:
|
|
This property describes the state of the BATFET, if online is zero
|
|
the battery is effectively not supplying power to the system.
|
|
- POWER_SUPPLY_PROP_PRESENT:
|
|
Indicates whether valid voltage has been detected on either BATT_THERM or BATT_ID.
|
|
|
|
Note that the Battery Management (BMS) supply is a special case as there is
|
|
a circular notification requirement of the STATUS (battery) and the CAPACITY (bms)
|
|
properties.
|
|
|
|
The battery power supply is also a supplicant to BMS because of userspace
|
|
not being aware of the BMS power supply type. Thus the CAPACITY property needs
|
|
to be relayed through the appropriate battery supply type.
|
|
|
|
DC:
|
|
* supplicants: battery
|
|
* writable properties:
|
|
- POWER_SUPPLY_PROP_INPUT_CURRENT_MAX
|
|
The maximum input current limit drawn from USB. This property
|
|
is used by the charger_monitor userspace service.
|
|
* other notable properties:
|
|
- POWER_SUPPLY_PROP_PRESENT
|
|
The present property indicates that a valid voltage is present at
|
|
the DC in path.
|
|
- POWER_SUPPLY_PROP_ONLINE
|
|
Online indicates that there there is a valid voltage source actively
|
|
supplying current to the system or the battery.
|
|
|
|
Config options
|
|
==============
|
|
|
|
CONFIG_QPNP_CHARGER - Enables QPNP charger support.
|
|
|
|
User space utilities
|
|
====================
|
|
|
|
The power supply framework sends uevents whenever power_supply_changed is invoked.
|
|
Said event contains the name of the supply changed as well as all implemented power
|
|
supply properties.
|
|
|
|
The qpnp-charger driver takes advantage of the framework to notify userspace. There
|
|
are a few userspace applications which take advantage of this information to track
|
|
things like battery capacity, presence and health.
|
|
|
|
It is fairly straightforward to implement one's own userspace application to track
|
|
this information.
|
|
|
|
To do
|
|
=====
|
|
|
|
One possible improvement to the power supply framework is to pass the pointer of
|
|
the power supply and property changed into the external_power_supply_changed() API.
|
|
This way the supplicant would not have to figure out the origin of the changed property.
|