#
|
# (C) Copyright 2014 Samsung Electronics
|
# Lukasz Majewski <l.majewski@samsung.com>
|
#
|
# SPDX-License-Identifier: GPL-2.0+
|
#
|
|
Introduction
|
------------
|
|
This document describes the second version of the u-boot's PMIC (Power
|
Management IC) framework. As a reference boards please consider Samsungs' Trats
|
and Trats2.
|
|
Background
|
----------
|
|
Boards supported by u-boot are getting increasingly complex. Developers and
|
designers strive to cut down power consumption. Hence several different types of
|
devices are now available on the board - namely power managers (PMIC), fuel
|
gauges (FG), micro USB interface controllers (MUIC), batteries, multi-function
|
devices (MFD).
|
|
Explanation of key design decisions
|
-----------------------------------
|
|
One package can integrate PMIC and MUIC with different addresses on the I2C bus.
|
The same device - e.g. MAX8997 uses two different I2C busses and addresses.
|
|
Power devices use not only I2C for communication, but SPI as well. Additionally
|
different ICs use different endianess. For this reason struct pmic holds
|
information about I2C/SPI transmission, which is used with generic
|
pmic_req_write() function.
|
|
The "flat" hierarchy for power devices works well when each device performs only
|
one operation - e.g. PMIC enables LDO.
|
|
The problem emerges when we have a device (battery) which conceptually shall be
|
the master and uses methods exported by other devices. We need to control MUIC
|
to start charging the battery, use PMIC to reduce board's overall power
|
consumption (by disabling not needed LDOs, BUCKs) and get current state of
|
energy on the battery from FG.
|
Up till now u-boot doesn't support device model, so a simple one had to be
|
added.
|
|
The directory hierarchy has following structure:
|
./include/power/<device_name>_<device_function>.h
|
e.g. ./include/power/max8997_pmic.h
|
|
./drivers/power/pmic/power_{core files}.c
|
e.g. ./drivers/power/pmic/power_core.c
|
|
./drivers/power/pmic/<device_function>/<device_function>_<device_name>.c
|
e.g. ./drivers/power/pmic/pmic_max8997.c
|
e.g. ./drivers/power/battery/trats/bat_trats.c
|
e.g. ./drivers/power/fuel_gauge/fg_max17042.c
|
|
The framework classifies devices by their function - separate directories should
|
be maintained for different classes of devices.
|
|
Current design
|
--------------
|
|
Everything is a power device described by struct pmic. Even battery is
|
considered as a valid power device. This helps for better management of those
|
devices.
|
|
- Block diagram of the hierarchy:
|
-----------------
|
--------| BAT |------------
|
| | | |
|
| ----------------- |
|
| | |
|
\|/ \|/ \|/
|
----------- ----------------- ---------
|
|FG | |MUIC | |CHRG |
|
| | | | | |
|
----------- ----------------- ---------
|
|
|
1. When hierarchy is not needed (no complex battery charge):
|
|
Definition of the struct pmic is only required with proper name and parameters
|
for communication. This is enough to use the "pmic" command in the u-boot
|
prompt to change values of device's register (enable/disable LDO, BUCK).
|
|
The PG, MUIC and CHRG above are regarded to be in the same level in the
|
hierarchy.
|
|
2. Complex battery charging.
|
|
To charge a battery, information from several "abstract" power devices is
|
needed (defined at ./include/power/pmic.h):
|
- FG device (struct power_fg):
|
-- *fg_battery_check - check if battery is not above its limits
|
-- *fg_battery_update - update the pmic framework with current
|
battery state(voltage and current capacity)
|
|
- Charger device (struct power_chrq):
|
-- *chrg_type - type/capacity of the charger (including information
|
about USB cable disconnection)
|
-- *chrg_bat_present - detection if battery to be charged is
|
present
|
-- *chrg_state - status of the charger - if it is enabled or
|
disabled
|
|
- Battery device (struct power_battery):
|
-- *battery_init - assign proper callbacks to be used by top
|
hierarchy battery device
|
-- *battery_charge - called from "pmic" command, responsible
|
for performing the charging
|
|
Now two batteries are supported; trats and trats2 [*]. Those differ in the way
|
how they handle the exact charging. Trats uses polling (MAX8997) and trats2
|
relies on the PMIC/MUIC HW completely (MAX77693).
|
|
__Example for trats (this can be very different for other board):__
|
-- *fg_battery_check -> FG device (fg_max17042.c)
|
-- *fg_battery_update -> FG device (fg_max17042.c)
|
-- *chrg_type -> MUIC device (muic_max8997.c)
|
-- *chrg_bat_present -> PMIC device (pmic_max8997.c)
|
-- *chrg_state -> PMIC device (pmic_max8997.c)
|
-- *battery_init -> BAT device (bat_trats.c)
|
-- *battery_charge -> BAT device (bat_trats.c)
|
|
Also the struct pmic holds method (*low_power_mode) for reducing board's
|
power consumption when one calls "pmic BAT_TRATS bat charge" command.
|
|
How to add a new power device
|
-----------------------------
|
|
1. Simple device should be added with creation of file
|
<pmic_function>_<pmic_name>.c, <pmic_name>_<pmic_function>.h according to the
|
proposed and described above scheme.
|
|
Then "pmic" command supports reading/writing/dump of device's internal
|
registers.
|
|
2. Charging battery with hierarchy
|
Define devices as listed at 1.
|
|
Define battery file (bat_<board>.c). Please also note that one might need a
|
corresponding battery model description for FG.
|
|
For points 1 and 2 use a generic function power_init_board() to initialise the
|
power framework on your board.
|
|
For reference, please look into the trats/trats2 boards.
|
|
TO DO list (for PMICv3) - up till v2014.04
|
------------------------------------------
|
|
1. Description of the devices related to power via device tree is not available.
|
This is the main problem when a developer tries to build a multi-boot u-boot
|
binary. The best would be to parse the DTS from Linux kernel.
|
|
2. To support many instances of the same IC, like two MAX8997, one needs to
|
copy the corresponding pmic_max8997.c file with changed name to "MAX8997_PMICX",
|
where X is the device number. This problem will be addressed when extended
|
pmic_core.c will support storing available devices in a list.
|
|
3. Definition of batteries [*] (for trats/trats2) should be excluded from the
|
code responsible for charging them and since it in fact describes the charging
|
profile it should be put to a separate file.
|
|
4. Adjust the framework to work with the device model.
|
