doc/driver-model/pmic-framework.txt

   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
   8 PMIC framework based on Driver Model
   9 ====================================
  10 TOC:
  11 1. Introduction
  12 2. How does it work
  13 3. Pmic uclass
  14 4. Regulator uclass
  15
  16 1. Introduction
  17 ===============
  18 This is an introduction to driver-model multi uclass PMIC IC's support.
  19 At 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
  25 New files:
  26 UCLASS_PMIC:
  27 - drivers/power/pmic/pmic-uclass.c
  28 - include/power/pmic.h
  29 UCLASS_REGULATOR:
  30 - drivers/power/regulator/regulator-uclass.c
  31 - include/power/regulator.h
  32
  33 Commands:
  34 - common/cmd_pmic.c
  35 - common/cmd_regulator.c
  36
  37 2. How doees it work
  38 ====================
  39 The Power Management Integrated Circuits (PMIC) are used in embedded systems
  40 to provide stable, precise and specific voltage power source with over-voltage
  41 and thermal protection circuits.
  42
  43 The single PMIC can provide various functions by single or multiple interfaces,
  44 like 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
  62 Since U-Boot provides driver model features for I2C and SPI bus drivers,
  63 the PMIC devices should also support this. By the pmic and regulator API's,
  64 PMIC drivers can simply provide a common functions, for multi-interface and
  65 and multi-instance device support.
  66
  67 Basic design assumptions:
  68
  69 - Common I/O API - UCLASS_PMIC
  70 For the multi-function PMIC devices, this can be used as parent I/O device
  71 for each IC's interface. Then, each children uses the same dev for read/write.
  72
  73 - Common regulator API - UCLASS_REGULATOR
  74 For driving the regulator attributes, auto setting function or command line
  75 interface, based on kernel-style regulator device tree constraints.
  76
  77 For simple implementations, regulator drivers are not required, so the code can
  78 use pmic read/write directly.
  79
  80 3. Pmic uclass
  81 ==============
  82 The 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
  91 For detailed API description, please refer to the header file.
  92
  93 As an example of the pmic driver, please refer to the MAX77686 driver.
  94
  95 Please 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
  97 of regulator's node, compatible prefixes.
  98
  99 The 'pmic; command also supports the new API. So the pmic command can be enabled
 100 by adding CONFIG_CMD_PMIC.
 101 The 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
 107 This command can use only UCLASS_PMIC devices, since this uclass is designed
 108 for pmic I/O operations only.
 109
 110 For more information, please refer to the core file.
 111
 112 4. Regulator uclass
 113 ===================
 114 The 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
 127 For detailed API description, please refer to the header file.
 128
 129 For the example regulator driver, please refer to the MAX77686 regulator driver,
 130 but this driver can't operate without pmic's example driver, which provides an
 131 I/O interface for MAX77686 regulator.
 132
 133 The second example is a fixed Voltage/Current regulator for a common use.
 134
 135 The '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
 140 For more information, please refer to the command file.