pmic-framework.rst 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143
  1. .. SPDX-License-Identifier: GPL-2.0+
  2. .. (C) Copyright 2014-2015 Samsung Electronics
  3. .. sectionauthor:: Przemyslaw Marczak <p.marczak@samsung.com>
  4. PMIC framework based on Driver Model
  5. ====================================
  6. Introduction
  7. ------------
  8. This is an introduction to driver-model multi uclass PMIC IC's support.
  9. At present it's based on two uclass types:
  10. UCLASS_PMIC:
  11. basic uclass type for PMIC I/O, which provides common
  12. read/write interface.
  13. UCLASS_REGULATOR:
  14. additional uclass type for specific PMIC features, which are
  15. Voltage/Current regulators.
  16. New files:
  17. UCLASS_PMIC:
  18. - drivers/power/pmic/pmic-uclass.c
  19. - include/power/pmic.h
  20. UCLASS_REGULATOR:
  21. - drivers/power/regulator/regulator-uclass.c
  22. - include/power/regulator.h
  23. Commands:
  24. - common/cmd_pmic.c
  25. - common/cmd_regulator.c
  26. How doees it work
  27. -----------------
  28. The Power Management Integrated Circuits (PMIC) are used in embedded systems
  29. to provide stable, precise and specific voltage power source with over-voltage
  30. and thermal protection circuits.
  31. The single PMIC can provide various functions by single or multiple interfaces,
  32. like in the example below::
  33. -- SoC
  34. |
  35. | ______________________________________
  36. | BUS 0 | Multi interface PMIC IC |--> LDO out 1
  37. | e.g.I2C0 | |--> LDO out N
  38. |-----------|---- PMIC device 0 (READ/WRITE ops) |
  39. | or SPI0 | |_ REGULATOR device (ldo/... ops) |--> BUCK out 1
  40. | | |_ CHARGER device (charger ops) |--> BUCK out M
  41. | | |_ MUIC device (microUSB con ops) |
  42. | BUS 1 | |_ ... |---> BATTERY
  43. | e.g.I2C1 | |
  44. |-----------|---- PMIC device 1 (READ/WRITE ops) |---> USB in 1
  45. . or SPI1 | |_ RTC device (rtc ops) |---> USB in 2
  46. . |______________________________________|---> USB out
  47. .
  48. Since U-Boot provides driver model features for I2C and SPI bus drivers,
  49. the PMIC devices should also support this. By the pmic and regulator API's,
  50. PMIC drivers can simply provide a common functions, for multi-interface and
  51. and multi-instance device support.
  52. Basic design assumptions:
  53. - Common I/O API:
  54. UCLASS_PMIC. For the multi-function PMIC devices, this can be used as
  55. parent I/O device for each IC's interface. Then, each children uses the
  56. same dev for read/write.
  57. - Common regulator API:
  58. UCLASS_REGULATOR. For driving the regulator attributes, auto setting
  59. function or command line interface, based on kernel-style regulator device
  60. tree constraints.
  61. For simple implementations, regulator drivers are not required, so the code can
  62. use pmic read/write directly.
  63. Pmic uclass
  64. -----------
  65. The basic information:
  66. * Uclass: 'UCLASS_PMIC'
  67. * Header: 'include/power/pmic.h'
  68. * Core: 'drivers/power/pmic/pmic-uclass.c' (config 'CONFIG_DM_PMIC')
  69. * Command: 'common/cmd_pmic.c' (config 'CONFIG_CMD_PMIC')
  70. * Example: 'drivers/power/pmic/max77686.c'
  71. For detailed API description, please refer to the header file.
  72. As an example of the pmic driver, please refer to the MAX77686 driver.
  73. Please pay attention for the driver's bind() method. Exactly the function call:
  74. 'pmic_bind_children()', which is used to bind the regulators by using the array
  75. of regulator's node, compatible prefixes.
  76. The 'pmic; command also supports the new API. So the pmic command can be enabled
  77. by adding CONFIG_CMD_PMIC.
  78. The new pmic command allows to:
  79. - list pmic devices
  80. - choose the current device (like the mmc command)
  81. - read or write the pmic register
  82. - dump all pmic registers
  83. This command can use only UCLASS_PMIC devices, since this uclass is designed
  84. for pmic I/O operations only.
  85. For more information, please refer to the core file.
  86. Regulator uclass
  87. ----------------
  88. The basic information:
  89. * Uclass: 'UCLASS_REGULATOR'
  90. * Header: 'include/power/regulator.h'
  91. * Core: 'drivers/power/regulator/regulator-uclass.c'
  92. (config 'CONFIG_DM_REGULATOR')
  93. * Binding: 'doc/device-tree-bindings/regulator/regulator.txt'
  94. * Command: 'common/cmd_regulator.c' (config 'CONFIG_CMD_REGULATOR')
  95. * Example: 'drivers/power/regulator/max77686.c'
  96. 'drivers/power/pmic/max77686.c' (required I/O driver for the above)
  97. * Example: 'drivers/power/regulator/fixed.c'
  98. (config 'CONFIG_DM_REGULATOR_FIXED')
  99. For detailed API description, please refer to the header file.
  100. For the example regulator driver, please refer to the MAX77686 regulator driver,
  101. but this driver can't operate without pmic's example driver, which provides an
  102. I/O interface for MAX77686 regulator.
  103. The second example is a fixed Voltage/Current regulator for a common use.
  104. The 'regulator' command also supports the new API. The command allow:
  105. - list regulator devices
  106. - choose the current device (like the mmc command)
  107. - do all regulator-specific operations
  108. For more information, please refer to the command file.