1# 2# (C) Copyright 2014 Samsung Electronics 3# Lukasz Majewski <l.majewski@samsung.com> 4# 5# SPDX-License-Identifier: GPL-2.0+ 6# 7 8Introduction 9------------ 10 11This document describes the second version of the u-boot's PMIC (Power 12Management IC) framework. As a reference boards please consider Samsungs' Trats 13and Trats2. 14 15Background 16---------- 17 18Boards supported by u-boot are getting increasingly complex. Developers and 19designers strive to cut down power consumption. Hence several different types of 20devices are now available on the board - namely power managers (PMIC), fuel 21gauges (FG), micro USB interface controllers (MUIC), batteries, multi-function 22devices (MFD). 23 24Explanation of key design decisions 25----------------------------------- 26 27One package can integrate PMIC and MUIC with different addresses on the I2C bus. 28The same device - e.g. MAX8997 uses two different I2C busses and addresses. 29 30Power devices use not only I2C for communication, but SPI as well. Additionally 31different ICs use different endianess. For this reason struct pmic holds 32information about I2C/SPI transmission, which is used with generic 33pmic_req_write() function. 34 35The "flat" hierarchy for power devices works well when each device performs only 36one operation - e.g. PMIC enables LDO. 37 38The problem emerges when we have a device (battery) which conceptually shall be 39the master and uses methods exported by other devices. We need to control MUIC 40to start charging the battery, use PMIC to reduce board's overall power 41consumption (by disabling not needed LDOs, BUCKs) and get current state of 42energy on the battery from FG. 43Up till now u-boot doesn't support device model, so a simple one had to be 44added. 45 46The directory hierarchy has following structure: 47./include/power/<device_name>_<device_function>.h 48e.g. ./include/power/max8997_pmic.h 49 50./drivers/power/pmic/power_{core files}.c 51e.g. ./drivers/power/pmic/power_core.c 52 53./drivers/power/pmic/<device_function>/<device_function>_<device_name>.c 54e.g. ./drivers/power/pmic/pmic_max8997.c 55e.g. ./drivers/power/battery/trats/bat_trats.c 56e.g. ./drivers/power/fuel_gauge/fg_max17042.c 57 58The framework classifies devices by their function - separate directories should 59be maintained for different classes of devices. 60 61Current design 62-------------- 63 64Everything is a power device described by struct pmic. Even battery is 65considered as a valid power device. This helps for better management of those 66devices. 67 68- Block diagram of the hierarchy: 69 ----------------- 70 --------| BAT |------------ 71 | | | | 72 | ----------------- | 73 | | | 74 \|/ \|/ \|/ 75 ----------- ----------------- --------- 76 |FG | |MUIC | |CHRG | 77 | | | | | | 78 ----------- ----------------- --------- 79 80 811. When hierarchy is not needed (no complex battery charge): 82 83Definition of the struct pmic is only required with proper name and parameters 84for communication. This is enough to use the "pmic" command in the u-boot 85prompt to change values of device's register (enable/disable LDO, BUCK). 86 87The PG, MUIC and CHRG above are regarded to be in the same level in the 88hierarchy. 89 902. Complex battery charging. 91 92To charge a battery, information from several "abstract" power devices is 93needed (defined at ./include/power/pmic.h): 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) 98 99- Charger device (struct power_chrq): 100 -- *chrg_type - type/capacity of the charger (including information 101 about USB cable disconnection) 102 -- *chrg_bat_present - detection if battery to be charged is 103 present 104 -- *chrg_state - status of the charger - if it is enabled or 105 disabled 106 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 111 for performing the charging 112 113Now two batteries are supported; trats and trats2 [*]. Those differ in the way 114how they handle the exact charging. Trats uses polling (MAX8997) and trats2 115relies on the PMIC/MUIC HW completely (MAX77693). 116 117__Example for trats (this can be very different for other board):__ 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) 125 126Also the struct pmic holds method (*low_power_mode) for reducing board's 127power consumption when one calls "pmic BAT_TRATS bat charge" command. 128 129How to add a new power device 130----------------------------- 131 1321. Simple device should be added with creation of file 133<pmic_function>_<pmic_name>.c, <pmic_name>_<pmic_function>.h according to the 134proposed and described above scheme. 135 136Then "pmic" command supports reading/writing/dump of device's internal 137registers. 138 1392. Charging battery with hierarchy 140Define devices as listed at 1. 141 142Define battery file (bat_<board>.c). Please also note that one might need a 143corresponding battery model description for FG. 144 145For points 1 and 2 use a generic function power_init_board() to initialise the 146power framework on your board. 147 148For reference, please look into the trats/trats2 boards. 149 150TO DO list (for PMICv3) - up till v2014.04 151------------------------------------------ 152 1531. Description of the devices related to power via device tree is not available. 154This is the main problem when a developer tries to build a multi-boot u-boot 155binary. The best would be to parse the DTS from Linux kernel. 156 1572. To support many instances of the same IC, like two MAX8997, one needs to 158copy the corresponding pmic_max8997.c file with changed name to "MAX8997_PMICX", 159where X is the device number. This problem will be addressed when extended 160pmic_core.c will support storing available devices in a list. 161 1623. Definition of batteries [*] (for trats/trats2) should be excluded from the 163code responsible for charging them and since it in fact describes the charging 164profile it should be put to a separate file. 165 1664. Adjust the framework to work with the device model. 167