u-boot/doc/README.power-framework

5 # SPDX-License-Identifier:      GPL-2.0+
9 ------------
11 This document describes the second version of the u-boot's PMIC (Power
16 ----------
18 Boards supported by u-boot are getting increasingly complex. Developers and
20 devices are now available on the board - namely power managers (PMIC), fuel
21 gauges (FG), micro USB interface controllers (MUIC), batteries, multi-function
25 -----------------------------------
28 The same device - e.g. MAX8997 uses two different I2C busses and addresses.
36 one operation - e.g. PMIC enables LDO.
38 The problem emerges when we have a device (battery) which conceptually shall be
40 to start charging the battery, use PMIC to reduce board's overall power
42 energy on the battery from FG.
43 Up till now u-boot doesn't support device model, so a simple one had to be
55 e.g. ./drivers/power/battery/trats/bat_trats.c
58 The framework classifies devices by their function - separate directories should
62 --------------
64 Everything is a power device described by struct pmic. Even battery is
68 - Block diagram of the hierarchy:
69 			-----------------
70 		--------| BAT           |------------
72 		|       -----------------           |
75 	-----------     -----------------       ---------
78 	-----------     -----------------       ---------
81 1. When hierarchy is not needed (no complex battery charge):
84 for communication. This is enough to use the "pmic" command in the u-boot
90 2. Complex battery charging.
92 To charge a battery, information from several "abstract" power devices is
94 - FG device (struct power_fg):
95 	     -- *fg_battery_check - check if battery is not above its limits
96 	     -- *fg_battery_update - update the pmic framework with current
97 				     battery state(voltage and current capacity)
99 - Charger device (struct power_chrq):
100 	     -- *chrg_type - type/capacity of the charger (including information
102 	     -- *chrg_bat_present - detection if battery to be charged is
104 	     -- *chrg_state - status of the charger - if it is enabled or
107 - Battery device (struct power_battery):
108 	     -- *battery_init - assign proper callbacks to be used by top
109 				hierarchy battery device
110 	     -- *battery_charge - called from "pmic" command, responsible
118 	     -- *fg_battery_check       -> FG device (fg_max17042.c)
119 	     -- *fg_battery_update      -> FG device (fg_max17042.c)
120 	     -- *chrg_type              -> MUIC device (muic_max8997.c)
121 	     -- *chrg_bat_present       -> PMIC device (pmic_max8997.c)
122 	     -- *chrg_state             -> PMIC device (pmic_max8997.c)
123 	     -- *battery_init           -> BAT device (bat_trats.c)
124 	     -- *battery_charge         -> BAT device (bat_trats.c)
130 -----------------------------
132 1. Simple device should be added with creation of file
139 2. Charging battery with hierarchy
142 Define battery file (bat_<board>.c). Please also note that one might need a
143 corresponding battery model description for FG.
150 TO DO list (for PMICv3) - up till v2014.04
151 ------------------------------------------
154 This is the main problem when a developer tries to build a multi-boot u-boot