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