[U-Boot] [PATCH v4 12/16] doc: driver-model: pmic and regulator uclass documentation

[Przemyslaw Marczak]

Since this framework is still under the construction, the main
documentation is kept in the header files.

Signed-off-by: Przemyslaw Marczak <p.marczak at samsung.com>
---
Changes v2, V3:
- update documentation with the framework api changes
- remove doc file name 'dm' prefix

Changes V4:
- move the description to the headers and leave only general info

---
 doc/driver-model/pmic-framework.txt | 142 ++++++++++++++++++++++++++++++++++++
 1 file changed, 142 insertions(+)
 create mode 100644 doc/driver-model/pmic-framework.txt

diff --git a/doc/driver-model/pmic-framework.txt b/doc/driver-model/pmic-framework.txt
new file mode 100644
index 0000000..cc82236
--- /dev/null
+++ b/doc/driver-model/pmic-framework.txt
@@ -0,0 +1,142 @@
+#
+# (C) Copyright 2014-2015 Samsung Electronics
+# Przemyslaw Marczak <p.marczak at samsung.com>
+#
+# SPDX-License-Identifier:      GPL-2.0+
+#
+
+PMIC framework based on Driver Model
+====================================
+TOC:
+1. Introduction
+2. How does it work
+3. Pmic uclass
+4. Regulator uclass
+
+1. Introduction
+===============
+This is an introduction to driver-model multi uclass PMIC IC's support.
+At present it's based on two uclass types:
+- UCLASS_PMIC      - basic uclass type for PMIC I/O, which provides common
+                     read/write interface.
+- UCLASS_REGULATOR - additional uclass type for specific PMIC features,
+                     which are Voltage/Current regulators.
+
+New files:
+UCLASS_PMIC:
+- drivers/power/pmic/pmic-uclass.c
+- include/power/pmic.h
+UCLASS_REGULATOR:
+- drivers/power/regulator/regulator-uclass.c
+- include/power/regulator.h
+
+Commands:
+- common/cmd_pmic.c
+- common/cmd_regulator.c
+
+2. How doees it work
+====================
+The Power Management Integrated Circuits (PMIC) are used in embedded systems
+to provide stable, precise and specific voltage power source with over-voltage
+and thermal protection circuits.
+
+The single PMIC can provide various functions by single or multiple interfaces,
+like in the example below.
+
+-- SoC
+ |
+ |            ______________________________________
+ | BUS 0     |       Multi interface PMIC IC        |--> LDO out 1
+ | e.g.I2C0  |                                      |--> LDO out N
+ |-----------|---- PMIC device 0 (READ/WRITE ops)   |
+ | or SPI0   |    |_ REGULATOR device (ldo/... ops) |--> BUCK out 1
+ |           |    |_ CHARGER device (charger ops)   |--> BUCK out M
+ |           |    |_ MUIC device (microUSB con ops) |
+ | BUS 1     |    |_ ...                            |---> BATTERY
+ | e.g.I2C1  |                                      |
+ |-----------|---- PMIC device 1 (READ/WRITE ops)   |---> USB in 1
+ . or SPI1   |    |_ RTC device (rtc ops)           |---> USB in 2
+ .           |______________________________________|---> USB out
+ .
+
+Since U-Boot provides driver model features for I2C and SPI bus drivers,
+the PMIC devices should also support this. By the pmic and regulator API's,
+PMIC drivers can simply provide a common functions, for multi-interface and
+and multi-instance device support.
+
+Basic design assumptions:
+
+- Common I/O API - UCLASS_PMIC
+For the multi-function PMIC devices, this can be used as parent I/O device
+for each IC's interface. Then, each children uses the same dev for read/write.
+
+- Common regulator API - UCLASS_REGULATOR
+For driving the regulator attributes, auto setting function or command line
+interface, based on kernel-style regulator device tree constraints.
+
+For simple implementations, regulator drivers are not required, so the code can
+use pmic read/write directly.
+
+3. Pmic uclass
+==============
+The basic informations:
+* Uclass:   'UCLASS_PMIC'
+* Header:   'include/power/pmic.h'
+* Core:     'drivers/power/pmic/pmic-uclass.c'
+  config:   'CONFIG_DM_PMIC'
+* Command:  'common/cmd_pmic.c'
+  config:   'CONFIG_CMD_PMIC'
+* Example:  'drivers/power/pmic/max77686.c'
+
+This is still under the construction. So for the API description, please refer
+to the header file.
+
+As an example of the pmic driver, please refer to the MAX77686 driver.
+
+Please pay attention for the driver's '.bind' method. Exactly the function call:
+'pmic_bind_childs()', which is used to bind the regulators by using the array of
+regulator's node, compatible prefixes.
+
+The 'pmic; command also supports the new API. So the pmic command can be enabled
+by adding CONFIG_CMD_PMIC.
+The new pmic command allows to:
+- list pmic devices
+- choose the current device (like the mmc command)
+- read or write the pmic register
+- dump all pmic registers
+
+This command can use only UCLASS_PMIC devices, since this uclass is designed
+for pmic I/O operations only.
+
+For more informations, please refer to the file: 'common/cmd_pmic.c'.
+
+4. Regulator uclass
+===================
+The basic informations:
+* Uclass:  'UCLASS_REGULATOR'
+* Header:  'include/power/regulator.h'
+* Core:    'drivers/power/regulator/regulator-uclass.c'
+  config:  'CONFIG_DM_REGULATOR'
+  binding: 'doc/device-tree-bindings/regulator/regulator.txt'
+* Command: 'common/cmd_regulator.c'
+  config:  'CONFIG_CMD_REGULATOR'
+* Example: 'drivers/power/regulator/max77686.c'
+           'drivers/power/pmic/max77686.c' (required I/O driver for the above)
+* Example: 'drivers/power/regulator/fixed.c'
+  config"  'CONFIG_DM_REGULATOR_FIXED'
+
+This is still under the construction. So for the API description, please refer
+to the header file.
+
+For the example regulator driver, please refer to the MAX77686 regulator driver,
+but this driver can't operate without pmic's example driver, which provides an
+I/O interface for MAX77686 regulator.
+
+The second example is a fixed Voltage/Current regulator for a common use.
+
+The 'regulator' command also supports the new API. The command allow:
+- list regulator devices
+- choose the current device (like the mmc command)
+- do all regulator-specific operations
+
+For more informations, please refer to the file: 'common/cmd_regulator.c'
-- 
1.9.1