| Message ID | 1429553273-6453-13-git-send-email-p.marczak@samsung.com |
|---|---|
| State | Accepted |
| Delegated to: | Simon Glass |
| Headers | show |
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
On 22 April 2015 at 10:31, Simon Glass <sjg@chromium.org> wrote: > 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> Applied to u-boot-dm/next, thanks!
Hello, On 04/22/2015 06:31 PM, Simon Glass wrote: > 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? > 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,
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: +'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'
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