Eric Lee / smarc-uboot | Embedian Git Server

Commit ccfc89cb16ef1407a475cfce1dac1555745d8268

Authored by Łukasz Majewski 2014-04-07 20:34:44 +0800

Committed by Tom Rini 2014-04-18 22:42:30 +0800

Exists in v2017.01-smarct4x and in 40 other branches

doc:power:pmic: Add doc entry for PMIC(v2) framework

Well written documentation for PMIC framework was missing and hence
it has been probably difficult and time consuming for other developers
to understand rationale for key design decisions and overall design
structure.
This commit provides proper documentation entry.

Signed-off-by: Lukasz Majewski <l.majewski@samsung.com>
Acked-by: Simon Glass <sjg@chromium.org>

Showing 1 changed file with 166 additions and 0 deletions Side-by-side Diff

doc/README.power-framework

doc/README.power-framework

Diff comments View file @ ccfc89c

	1	+#
	2	+# (C) Copyright 2014 Samsung Electronics
	3	+# Lukasz Majewski <l.majewski@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.