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