1#
2# (C) Copyright 2014-2015 Samsung Electronics
3# Przemyslaw Marczak <p.marczak@samsung.com>
4#
5# SPDX-License-Identifier:      GPL-2.0+
6#
7
8PMIC framework based on Driver Model
9====================================
10TOC:
111. Introduction
122. How does it work
133. Pmic uclass
144. Regulator uclass
15
161. Introduction
17===============
18This is an introduction to driver-model multi uclass PMIC IC's support.
19At present it's based on two uclass types:
20- UCLASS_PMIC      - basic uclass type for PMIC I/O, which provides common
21                     read/write interface.
22- UCLASS_REGULATOR - additional uclass type for specific PMIC features,
23                     which are Voltage/Current regulators.
24
25New files:
26UCLASS_PMIC:
27- drivers/power/pmic/pmic-uclass.c
28- include/power/pmic.h
29UCLASS_REGULATOR:
30- drivers/power/regulator/regulator-uclass.c
31- include/power/regulator.h
32
33Commands:
34- common/cmd_pmic.c
35- common/cmd_regulator.c
36
372. How doees it work
38====================
39The Power Management Integrated Circuits (PMIC) are used in embedded systems
40to provide stable, precise and specific voltage power source with over-voltage
41and thermal protection circuits.
42
43The single PMIC can provide various functions by single or multiple interfaces,
44like in the example below.
45
46-- SoC
47 |
48 |            ______________________________________
49 | BUS 0     |       Multi interface PMIC IC        |--> LDO out 1
50 | e.g.I2C0  |                                      |--> LDO out N
51 |-----------|---- PMIC device 0 (READ/WRITE ops)   |
52 | or SPI0   |    |_ REGULATOR device (ldo/... ops) |--> BUCK out 1
53 |           |    |_ CHARGER device (charger ops)   |--> BUCK out M
54 |           |    |_ MUIC device (microUSB con ops) |
55 | BUS 1     |    |_ ...                            |---> BATTERY
56 | e.g.I2C1  |                                      |
57 |-----------|---- PMIC device 1 (READ/WRITE ops)   |---> USB in 1
58 . or SPI1   |    |_ RTC device (rtc ops)           |---> USB in 2
59 .           |______________________________________|---> USB out
60 .
61
62Since U-Boot provides driver model features for I2C and SPI bus drivers,
63the PMIC devices should also support this. By the pmic and regulator API's,
64PMIC drivers can simply provide a common functions, for multi-interface and
65and multi-instance device support.
66
67Basic design assumptions:
68
69- Common I/O API - UCLASS_PMIC
70For the multi-function PMIC devices, this can be used as parent I/O device
71for each IC's interface. Then, each children uses the same dev for read/write.
72
73- Common regulator API - UCLASS_REGULATOR
74For driving the regulator attributes, auto setting function or command line
75interface, based on kernel-style regulator device tree constraints.
76
77For simple implementations, regulator drivers are not required, so the code can
78use pmic read/write directly.
79
803. Pmic uclass
81==============
82The basic information:
83* Uclass:   'UCLASS_PMIC'
84* Header:   'include/power/pmic.h'
85* Core:     'drivers/power/pmic/pmic-uclass.c'
86  config:   'CONFIG_DM_PMIC'
87* Command:  'common/cmd_pmic.c'
88  config:   'CONFIG_CMD_PMIC'
89* Example:  'drivers/power/pmic/max77686.c'
90
91For detailed API description, please refer to the header file.
92
93As an example of the pmic driver, please refer to the MAX77686 driver.
94
95Please pay attention for the driver's bind() method. Exactly the function call:
96'pmic_bind_children()', which is used to bind the regulators by using the array
97of regulator's node, compatible prefixes.
98
99The 'pmic; command also supports the new API. So the pmic command can be enabled
100by adding CONFIG_CMD_PMIC.
101The new pmic command allows to:
102- list pmic devices
103- choose the current device (like the mmc command)
104- read or write the pmic register
105- dump all pmic registers
106
107This command can use only UCLASS_PMIC devices, since this uclass is designed
108for pmic I/O operations only.
109
110For more information, please refer to the core file.
111
1124. Regulator uclass
113===================
114The basic information:
115* Uclass:  'UCLASS_REGULATOR'
116* Header:  'include/power/regulator.h'
117* Core:    'drivers/power/regulator/regulator-uclass.c'
118  config:  'CONFIG_DM_REGULATOR'
119  binding: 'doc/device-tree-bindings/regulator/regulator.txt'
120* Command: 'common/cmd_regulator.c'
121  config:  'CONFIG_CMD_REGULATOR'
122* Example: 'drivers/power/regulator/max77686.c'
123           'drivers/power/pmic/max77686.c' (required I/O driver for the above)
124* Example: 'drivers/power/regulator/fixed.c'
125  config"  'CONFIG_DM_REGULATOR_FIXED'
126
127For detailed API description, please refer to the header file.
128
129For the example regulator driver, please refer to the MAX77686 regulator driver,
130but this driver can't operate without pmic's example driver, which provides an
131I/O interface for MAX77686 regulator.
132
133The second example is a fixed Voltage/Current regulator for a common use.
134
135The 'regulator' command also supports the new API. The command allow:
136- list regulator devices
137- choose the current device (like the mmc command)
138- do all regulator-specific operations
139
140For more information, please refer to the command file.
141