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