From mboxrd@z Thu Jan 1 00:00:00 1970 From: Przemyslaw Marczak Date: Thu, 23 Apr 2015 13:33:28 +0200 Subject: [U-Boot] [PATCH v4 12/16] doc: driver-model: pmic and regulator uclass documentation In-Reply-To: References: <1427229051-20170-1-git-send-email-p.marczak@samsung.com> <1429553273-6453-1-git-send-email-p.marczak@samsung.com> <1429553273-6453-13-git-send-email-p.marczak@samsung.com> Message-ID: <5538D888.8090700@samsung.com> List-Id: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit To: u-boot@lists.denx.de Hello, On 04/22/2015 06:31 PM, Simon Glass wrote: > Hi Przemyslaw, > > On 20 April 2015 at 12:07, Przemyslaw Marczak wrote: >> Since this framework is still under the construction, the main >> documentation is kept in the header files. >> >> Signed-off-by: Przemyslaw Marczak >> --- >> 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 > >> >> 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 >> +# >> +# 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? > We need add muic, charger, etc., so the whole framework isn't finished yet. >> + >> +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 > Thank you, I will fix the mistakes. Best regards, -- Przemyslaw Marczak Samsung R&D Institute Poland Samsung Electronics p.marczak at samsung.com