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 informations: 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 91This is still under the construction. So for the API description, please refer 92to the header file. 93 94As an example of the pmic driver, please refer to the MAX77686 driver. 95 96Please pay attention for the driver's '.bind' method. Exactly the function call: 97'pmic_bind_childs()', which is used to bind the regulators by using the array of 98regulator's node, compatible prefixes. 99 100The 'pmic; command also supports the new API. So the pmic command can be enabled 101by adding CONFIG_CMD_PMIC. 102The new pmic command allows to: 103- list pmic devices 104- choose the current device (like the mmc command) 105- read or write the pmic register 106- dump all pmic registers 107 108This command can use only UCLASS_PMIC devices, since this uclass is designed 109for pmic I/O operations only. 110 111For more informations, please refer to the file: 'common/cmd_pmic.c'. 112 1134. Regulator uclass 114=================== 115The basic informations: 116* Uclass: 'UCLASS_REGULATOR' 117* Header: 'include/power/regulator.h' 118* Core: 'drivers/power/regulator/regulator-uclass.c' 119 config: 'CONFIG_DM_REGULATOR' 120 binding: 'doc/device-tree-bindings/regulator/regulator.txt' 121* Command: 'common/cmd_regulator.c' 122 config: 'CONFIG_CMD_REGULATOR' 123* Example: 'drivers/power/regulator/max77686.c' 124 'drivers/power/pmic/max77686.c' (required I/O driver for the above) 125* Example: 'drivers/power/regulator/fixed.c' 126 config" 'CONFIG_DM_REGULATOR_FIXED' 127 128This is still under the construction. So for the API description, please refer 129to the header file. 130 131For the example regulator driver, please refer to the MAX77686 regulator driver, 132but this driver can't operate without pmic's example driver, which provides an 133I/O interface for MAX77686 regulator. 134 135The second example is a fixed Voltage/Current regulator for a common use. 136 137The 'regulator' command also supports the new API. The command allow: 138- list regulator devices 139- choose the current device (like the mmc command) 140- do all regulator-specific operations 141 142For more informations, please refer to the file: 'common/cmd_regulator.c' 143