Hi Przemyslaw,
On 20 April 2015 at 12:07, Przemyslaw Marczak p.marczak@samsung.com wrote:
Since this framework is still under the construction, the main documentation is kept in the header files.
Signed-off-by: Przemyslaw Marczak p.marczak@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
Acked-by: Simon Glass sjg@chromium.org
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@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:
I think 'driver's bind() method' is better than a quoted '.bind'.
+'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'.
information
+4. Regulator uclass +=================== +The basic informations:
information
+* 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.
What is still under construction?
+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:
allows, or maybe s/allow/allows you to/
+- 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
Regards, Simon