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

[Simon Glass]

Hi Przemyslaw,

On 20 April 2015 at 12:07, Przemyslaw Marczak <p.marczak at 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 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

Acked-by: Simon Glass <sjg at 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 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:

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