Difference between revisions of "PMIC hardware components"

[quality revision] [quality revision]
m
m
 


Template:ArticleMainWriter Template:ArticleApprovedVersion

1 Article purpose[edit]

The purpose of this article is to:

  • list the PMIC hardware components that might be integrated in the different boards
  • link these components to the corresponding software framework(s)
  • point to the datasheet(s) of these components
  • explain, when necessary, how to configure these components.

2 Software frameworks[edit]

Domain Peripheral Software frameworks Comment
Cortex-A7
secure
(OP-TEE)
Cortex-A7
non-secure
(Linux)
Cortex-M4

(STM32Cube)
PMIC STPMIC1 OP-TEE overview Regulator overview Watchdog overview U-Boot

3 STPMIC1[edit]

3.1 Description[edit]

The STPMIC1 is a device that handles the power supplies for some STM32MP boards. The STPMIC1 main features are:

  • configuration via I²C bus,
  • 10 regulators of different kinds with over-current protection,
  • 3 power switches for USB supplies,
  • a power-on key input,
  • a watchdog,
  • a thermal protection,
  • a NORMAL mode and an ALTERNATE mode that is used for system suspend.

The user manual is available here: NOT YET AVAILABLE

3.2 Support in Linux Kernel[edit]

The STPMIC1 driver is used to handle STPMIC1 Power Management Integrated Circuit (PMIC). The driver is composed of several parts:

  • The core driver
  • The regulator driver
  • The watchdog driver
  • The input driver

The thermal feature is not supported.

3.2.1 Core driver[edit]

The core implements the Multi-Function Devices Framework API.

  • It is probed by the I²C framework.
  • It handles communication with the PMIC via I²C.
  • It probes the others STPMIC1 drivers (input, watchdog....).
  • It acts as an interrupt controller for the other drivers.

Source code:

 
include/linux/mfd/stpmic1.h  
 drivers/mfd/stpmic1.c  


Bindings are described in:

 
Documentation/devicetree/bindings/mfd/st,stpmic1.txt 

3.2.2 Regulator driver[edit]

The driver implements the Regulator framework API

  • Each BUCK, LDO or POWER SWITCH inside the STPMIC1 device is presented as a voltage regulator.
  • Power switches are presented as fixed voltage sources. Voltage can not be set.
  • The driver does not handle the suspend configuration. This is done by the Secure Monitor.

Source code:

 
drivers/regulator/stpmic1_regulator.c  

Bindings are described in:

 
Documentation/devicetree/bindings/regulator/st,stpmic1-regulator.txt 

3.2.3 Watchdog driver[edit]

The driver implements the Watchdog framework API

When enabled, a watchdog device is available for the user-land. As soon as a user has started to write in the watchdog it is armed in the PMIC. When the watchdog timer expires, the PMIC shuts down.

Source code:

 
drivers/watchdog/stpmic1_wdt.c  

Bindings are described in:

 
Documentation/devicetree/bindings/watchdog/st,stpmic1-wdt.txt 

3.2.4 Input driver[edit]

The driver implements the Input framework API.

The driver exposes a single key (KEY_POWER) that can be used as any standard input device in /dev/input/eventX

Source code:

 
drivers/input/misc/stpmic1_onkey.c 

Bindings are described in:

 
Documentation/devicetree/bindings/input/st,stpmic1-onkey.txt 

3.2.5 Kernel Configuration[edit]

With kernel menuconfig, enable following configurations:

  • core part: MFD_STPMIC1
  • regulator: REGULATOR_STPMIC1
  • watchdog: STPMIC1_WATCHDOG
  • input: INPUT_STPMIC1_ONKEY

3.3 Support in U-BOOT[edit]

STPMIC1 is used by U-Boot to:

  • Control regulators used by other drivers (mmc-supply for SDCard for example, usb vbus)
  • Trace pmic startup reason

STMPIC is supported with existing uclass of the 'Driver Model' described in doc/driver-model/pmic-framework.txt rst .

The STPMIC1 is available with the existing commands:

  • pmic (CONFIG_CMD_PMIC)
  • regulator (CONFIG_CMD_REGULATOR)
  • poweroff (CONFIG_CMD_POWEROFF)

SPTMIC1 driver supports configuration via device-tree; the bindings, same as kernel, are described in:

doc/device-tree-
 Documentation/devicetree/bindings/
mfd
regulator/st,stpmic1-regulator.txt 

3.4 Support in Cortex-A7 Secure[edit]

3.4.1 TF-A[edit]

STPMIC1 is used by TF-A firmware to:

  • Configure DDR power supplies.
  • Configure the regulators for system suspend and system shutdown.

Driver source code:

 
include/drivers/st/stpmic1.h  
 drivers/st/pmic/stpmic1.c  

SPTMIC1 driver supports configuration via device-tree, bindings are described in:

 
docs/fdtsdevicetree/stm32mpbindings/power/st,stpmic1.txt 

An example of PMIC configuration with device tree can be found in this file, node &i2c4:

 fdts/stm32mp15xx-edx.dtsi 

When using a PMIC on a board, TF-A is configured to use a secure I²C (I2C4 or I2C6). By default on STMicroelectronics boards, I2C4 is used.


Using another I²C (non-secure) is not supported in the TF-A implementation made by STMicroelectronics. But it is possible to modify the code and device tree files to support it.

Here is an example with I2C2:

  • Copy the chosen I²C node from Linux device tree in the TF-A device tree file for your board, as well as its dependencies (like pinctrl). You can also remove the properties not used by TF-A as done in the example below
/ {
...
	soc {
	...
 +		i2c2: i2c@40013000 {
 +			compatible = "st,stm32mp15-i2c";
 +			reg = <0x40013000 0x400>;
 +			clocks = <&rcc I2C2_K>;
 +			resets = <&rcc I2C2_R>;
 +			#address-cells = <1>;
 +			#size-cells = <0>;
 +			status = "disabled";
 +		};

  • change pmic node parent to this newly added I²C
& i2c2 {
	...
	pmic: stpmic@33 {   # You may also require to change this I²C address (33)
	...
};

  • remove in PMIC node the property:
secure-status = "okay";

#define I2C2_BASE			U(0x40013000)

	case UART7_BASE:
	case UART8_BASE:
	case IWDG2_BASE:
+	case I2C2_BASE:
		/* Allow drivers to register some non secure resources */
		VERBOSE("IO for non secure resource 0x%x\n",
			(unsigned int)base);

+	_CLK_SC_SELEC(RCC_MP_APB1ENSETR, 22, I2C2_K, _I2C12_SEL),

  • Regarding the GPIO ports used by I2C2: in this stm32mp1_clk_gate[] table, remove the #ifdef IMAGE_BL2 around GPIO banks entries if present

3.4.2 OP-TEE[edit]

STPMIC1 is used by OP-TEE OS to configure the regulators for system suspend and system shutdown.

Driver source code:

 
core/include/drivers/stpmic1.h  
 core/drivers/stpmic1.c 


<noinclude>

{{ArticleBasedOnModel | [[Contributors:Hardware components article model]]}}
{{ArticleMainWriter | PascalP}}
{{ArticleApprovedVersion | PascalP | OlivierB, PatrickD, YannG ,LionelD ,GeraldB (Passed, 10Jan'19) | No previous approved version | BrunoB - 17Jan'19 - 10277 | 18Jan'19}}
[[Category:Power and Thermal hardware components]]</noinclude>

ClonedFrom | stm32mpu}}</noinclude>
==Article purpose==
The purpose of this article is to:
* list the PMIC hardware components that might be integrated in the different [[:Category:ST boards|boards]]
* link these components to the corresponding software framework(s)
* point to the datasheet(s) of these components
* explain, when necessary, how to configure these components.

==Software frameworks==
{{:Internal_peripherals_software_table_template}}
 | {{Green|PMIC}}
 | {{Green|STPMIC1}}
 | {{Green|[[OP-TEE overview]]}}
 | {{Green|[[Regulator overview]]  [[Watchdog overview]]}}
 | 
 |
 |-
 |}
 [[U-Boot overview|U-Boot]]}}
 | 
 |
 |-
 |}== STPMIC1 ==

=== Description ===

The STPMIC1 is a device that handles the power supplies for some STM32MP boards. The STPMIC1 main features are:
* configuration via I²C bus,
* 10 regulators of different kinds with over-current protection,
* 3 power switches for USB supplies,
* a power-on key input,
* a watchdog,
* a thermal protection,
* a NORMAL mode and an ALTERNATE mode that is used for system suspend.

The user manual is available here: NOT YET AVAILABLE

=== Support in Linux Kernel ===

The STPMIC1 driver is used to handle STPMIC1 Power Management Integrated Circuit (PMIC). The driver is composed of several parts:
* The core driver
* The regulator driver
* The watchdog driver
* The input driver
The thermal feature is not supported.

==== Core driver ====
The core implements the Multi-Function Devices Framework API.
* It is probed by the I²C framework.
* It handles communication with the PMIC via I²C.
* It probes the others STPMIC1 drivers (input, watchdog....).
* It acts as an interrupt controller for the other drivers.

Source code:
  {{CodeSource | Linux kernel | include/linux/mfd/stpmic1.h}} 
  {{CodeSource | Linux kernel | drivers/mfd/stpmic1.c}} 

Bindings are described in:
  {{CodeSource | Linux kernel | Documentation/devicetree/bindings/mfd/st,stpmic1.txt}}

==== Regulator driver ====

The driver implements the [[Regulator overview|Regulator framework API]]

* Each BUCK, LDO or POWER SWITCH inside the STPMIC1 device is presented as a voltage regulator.
* Power switches are presented as fixed voltage sources. Voltage can not be set.
* The driver does not handle the suspend configuration. This is done by the Secure Monitor.

Source code:
  {{CodeSource | Linux kernel | drivers/regulator/stpmic1_regulator.c}} 

Bindings are described in:
  {{CodeSource | Linux kernel | Documentation/devicetree/bindings/regulator/st,stpmic1-regulator.txt}}

==== Watchdog driver ====

The driver implements the [[Watchdog overview|Watchdog framework API]]

When enabled, a watchdog device is available for the user-land.
As soon as a user has started to write in the watchdog it is armed
in the PMIC. When the watchdog timer expires, the PMIC shuts down.

Source code:
  {{CodeSource | Linux kernel | drivers/watchdog/stpmic1_wdt.c}} 

Bindings are described in:
  {{CodeSource | Linux kernel | Documentation/devicetree/bindings/watchdog/st,stpmic1-wdt.txt}}

==== Input driver ====
The driver implements the Input framework API. 

The driver exposes a single key (KEY_POWER) that can be used as any standard input device in /dev/input/eventX

Source code:
  {{CodeSource | Linux kernel | drivers/input/misc/stpmic1_onkey.c}}

Bindings are described in:
  {{CodeSource | Linux kernel | Documentation/devicetree/bindings/input/st,stpmic1-onkey.txt}}

==== Kernel Configuration ====

With kernel menuconfig, enable following configurations:
* core part: MFD_STPMIC1
* regulator: REGULATOR_STPMIC1
* watchdog: STPMIC1_WATCHDOG
* input: INPUT_STPMIC1_ONKEY

=== Support in U-BOOT ===

STPMIC1 is used by [[U-Boot overview|U-Boot]] to:
* Control regulators used by other drivers (mmc-supply for SDCard for example, usb vbus)
* Trace pmic startup reason

STMPIC is supported with existing uclass of the 'Driver Model' described in {{CodeSource | U-Boot | doc/driver-model/pmic-framework.txtrst}}.
* pmic :
** uclass: {{CodeSource | U-Boot | drivers/power/regulator/regulator-uclass.c}}, CONFIG_DM_PMIC
** driver: {{CodeSource | U-Boot | drivers/power/pmic/stpmic1.c}}, CONFIG_PMIC_STPMIC1
* regulator:
** uclass: {{CodeSource | U-Boot | drivers/power/pmic/pmic-uclass.c}}, CONFIG_DM_REGULATOR
** driver: {{CodeSource | U-Boot | drivers/power/regulator/stpmic1.c}}, CONFIG_DM_REGULATOR_STPMIC1
* sysreset:
** uclass:  {{CodeSource | U-Boot |drivers/sysreset/sysreset-uclass.c}}, CONFIG_SYSRESET
** code in pmic driver

The STPMIC1 is available with the existing [[U-Boot_overview#Commands|commands]]:
* pmic (CONFIG_CMD_PMIC)
* regulator (CONFIG_CMD_REGULATOR)
* poweroff (CONFIG_CMD_POWEROFF)

SPTMIC1 driver supports configuration via device-tree; the bindings, same as kernel, are described in::   {{CodeSource | U-Boot | doc/device-tree-bindings/mfd/stpmic1Linux kernel | Documentation/devicetree/bindings/regulator/st,stpmic1-regulator.txt}}

=== Support in Cortex-A7 Secure ===
==== TF-A ====
STPMIC1 is used by [[TF-A_overview|TF-A]] firmware to:
* Configure DDR power supplies.
* Configure the regulators for system suspend and system shutdown.

Driver source code:
  {{CodeSource | TF-A | include/drivers/st/stpmic1.h}} 
  {{CodeSource | TF-A | drivers/st/pmic/stpmic1.c}} 

SPTMIC1 driver supports configuration via device-tree, bindings are described in:
  {{CodeSource | TF-A | docs/fdts/stm32mp/devicetree/bindings/power/st,stpmic1.txt}}
==== An example of PMIC configuration with device tree can be found in this file, node &i2c4:
  {{CodeSource | TF-A | fdts/stm32mp15xx-edx.dtsi}}

When using a PMIC on a board, TF-A is configured to use a secure I²C (I2C4 or I2C6). By default on STMicroelectronics boards, I2C4 is used.

Using another I²C (non-secure) is not supported in the TF-A implementation made by STMicroelectronics. But it is possible to modify the code and device tree files to support it.

Here is an example with I2C2:
* Copy the chosen I²C node from Linux device tree in the TF-A device tree file for your board, as well as its dependencies (like pinctrl). You can also remove the properties not used by TF-A as done in the example below
 / {
 ...
 	soc {
 	...
  +		i2c2: i2c@40013000 {
  +			compatible = "st,stm32mp15-i2c";
  +			reg = <0x40013000 0x400>;
  +			clocks = <&rcc I2C2_K>;
  +			resets = <&rcc I2C2_R>;
  +			#address-cells = <1>;
  +			#size-cells = <0>;
  +			status = "disabled";
  +		};

* change pmic node parent to this newly added I²C
 & i2c2 {
 	...
 	pmic: stpmic@33 {   # You may also require to change this I²C address (33)
 	...
 };

* remove in PMIC node the property:
 secure-status = "okay";

* Add this I²C base address in {{CodeSource | TF-A | plat/st/stm32mp1/stm32mp1_def.h}}:
 #define I2C2_BASE			U(0x40013000)
* Add a case for this I²C in register_periph_iomem() function, in the file {{CodeSource | TF-A | plat/st/stm32mp1/stm32mp1_shared_resources.c}}. It should be placed with the other non-secure peripherals (UARTs and IWDG2):
 	case UART7_BASE:
 	case UART8_BASE:
 	case IWDG2_BASE:
 +	case I2C2_BASE:
 		/* Allow drivers to register some non secure resources */
 		VERBOSE("IO for non secure resource 0x%x\n",
 			(unsigned int)base);

* Add the clock of this I²C in the stm32mp1_clk_gate[] table in the file {{CodeSource | TF-A | drivers/st/clk/stm32mp1_clk.c}}
 +	_CLK_SC_SELEC(RCC_MP_APB1ENSETR, 22, I2C2_K, _I2C12_SEL),

* Regarding the GPIO ports used by I2C2: in this stm32mp1_clk_gate[] table, remove the #ifdef IMAGE_BL2 around GPIO banks entries if present

==== OP-TEE ====
STPMIC1 is used by [[OP-TEE_overview|OP-TEE]] OS to configure the regulators for system suspend and system shutdown.

Driver source code:
  {{CodeSource | OP-TEE_OS | core/include/drivers/stpmic1.h}} 
  {{CodeSource | OP-TEE_OS | core/drivers/stpmic1.c}}

<noinclude>

[[Category:Power and Thermal hardware components]]
{{PublicationRequestId | 10277 | 2019-01-17 | BrunoB}}
{{ArticleBasedOnModel | Hardware components article model}}</noinclude>
(14 intermediate revisions by 8 users not shown)
Line 1: Line 1:
 
<noinclude>
 
<noinclude>
{{ArticleBasedOnModel | [[Contributors:Hardware components article model]]}}
+
{{ClonedFrom | stm32mpu}}
{{ArticleMainWriter | PascalP}}
 
{{ArticleApprovedVersion | PascalP | OlivierB, PatrickD, YannG ,LionelD ,GeraldB (Passed, 10Jan'19) | No previous approved version | BrunoB - 17Jan'19 - 10277 | 18Jan'19}}
 
[[Category:Power and Thermal hardware components]]
 
 
</noinclude>
 
</noinclude>
 
 
==Article purpose==
 
==Article purpose==
 
The purpose of this article is to:
 
The purpose of this article is to:
Line 18: Line 14:
 
  | {{Green|STPMIC1}}
 
  | {{Green|STPMIC1}}
 
  | {{Green|[[OP-TEE overview]]}}
 
  | {{Green|[[OP-TEE overview]]}}
  | {{Green|[[Regulator overview]]  [[Watchdog overview]]}}
+
  | {{Green|[[Regulator overview]]  [[Watchdog overview]] [[U-Boot overview|U-Boot]]}}
 
  |  
 
  |  
 
  |
 
  |
 
  |-
 
  |-
 
  |}
 
  |}
 
 
== STPMIC1 ==
 
== STPMIC1 ==
   
Line 61: Line 56:
   
 
Bindings are described in:
 
Bindings are described in:
   {{CodeSource | Linux kernel | Documentation/devicetree/bindings/mfd/stpmic1.txt}}
+
   {{CodeSource | Linux kernel | Documentation/devicetree/bindings/mfd/st,stpmic1.txt}}
   
 
==== Regulator driver ====
 
==== Regulator driver ====
Line 75: Line 70:
   
 
Bindings are described in:
 
Bindings are described in:
   {{CodeSource | Linux kernel | Documentation/devicetree/bindings/regulator/stpmic1-regulator.txt}}
+
   {{CodeSource | Linux kernel | Documentation/devicetree/bindings/regulator/st,stpmic1-regulator.txt}}
   
 
==== Watchdog driver ====
 
==== Watchdog driver ====
Line 89: Line 84:
   
 
Bindings are described in:
 
Bindings are described in:
   {{CodeSource | Linux kernel | Documentation/devicetree/bindings/watchdog/stpmic1-wdt.txt}}
+
   {{CodeSource | Linux kernel | Documentation/devicetree/bindings/watchdog/st,stpmic1-wdt.txt}}
   
 
==== Input driver ====
 
==== Input driver ====
Line 100: Line 95:
   
 
Bindings are described in:
 
Bindings are described in:
   {{CodeSource | Linux kernel | Documentation/devicetree/bindings/input/stpmic1-onkey.txt}}
+
   {{CodeSource | Linux kernel | Documentation/devicetree/bindings/input/st,stpmic1-onkey.txt}}
   
 
==== Kernel Configuration ====
 
==== Kernel Configuration ====
Line 116: Line 111:
 
* Trace pmic startup reason
 
* Trace pmic startup reason
   
STMPIC is supported with existing uclass of the 'Driver Model' described in {{CodeSource | U-Boot | doc/driver-model/pmic-framework.txt}}.
+
STMPIC is supported with existing uclass of the 'Driver Model' described in {{CodeSource | U-Boot | doc/driver-model/pmic-framework.rst}}.
 
* pmic :
 
* pmic :
 
** uclass: {{CodeSource | U-Boot | drivers/power/regulator/regulator-uclass.c}}, CONFIG_DM_PMIC
 
** uclass: {{CodeSource | U-Boot | drivers/power/regulator/regulator-uclass.c}}, CONFIG_DM_PMIC
Line 133: Line 128:
   
 
SPTMIC1 driver supports configuration via device-tree; the bindings, same as kernel, are described in:
 
SPTMIC1 driver supports configuration via device-tree; the bindings, same as kernel, are described in:
: {{CodeSource | U-Boot | doc/device-tree-bindings/mfd/stpmic1.txt}}
+
  {{CodeSource | Linux kernel | Documentation/devicetree/bindings/regulator/st,stpmic1-regulator.txt}}
   
 
=== Support in Cortex-A7 Secure ===
 
=== Support in Cortex-A7 Secure ===
Line 146: Line 141:
   
 
SPTMIC1 driver supports configuration via device-tree, bindings are described in:
 
SPTMIC1 driver supports configuration via device-tree, bindings are described in:
   {{CodeSource | TF-A | docs/fdts/stm32mp/st,stpmic1.txt}}
+
   {{CodeSource | TF-A | docs/devicetree/bindings/power/st,stpmic1.txt}}
  +
 
  +
An example of PMIC configuration with device tree can be found in this file, node &i2c4:
  +
  {{CodeSource | TF-A | fdts/stm32mp15xx-edx.dtsi}}
  +
 
  +
When using a PMIC on a board, TF-A is configured to use a secure I²C (I2C4 or I2C6). By default on STMicroelectronics boards, I2C4 is used.
  +
 
  +
 
  +
Using another I²C (non-secure) is not supported in the TF-A implementation made by STMicroelectronics. But it is possible to modify the code and device tree files to support it.
  +
 
  +
Here is an example with I2C2:
  +
* Copy the chosen I²C node from Linux device tree in the TF-A device tree file for your board, as well as its dependencies (like pinctrl). You can also remove the properties not used by TF-A as done in the example below
  +
/ {
  +
...
  +
soc {
  +
...
  +
  + i2c2: i2c@40013000 {
  +
  + compatible = "st,stm32mp15-i2c";
  +
  + reg = <0x40013000 0x400>;
  +
  + clocks = <&rcc I2C2_K>;
  +
  + resets = <&rcc I2C2_R>;
  +
  + #address-cells = <1>;
  +
  + #size-cells = <0>;
  +
  + status = "disabled";
  +
  + };
  +
 
  +
* change pmic node parent to this newly added I²C
  +
& i2c2 {
  +
...
  +
pmic: stpmic@33 {  # You may also require to change this I²C address (33)
  +
...
  +
};
  +
 
  +
* remove in PMIC node the property:
  +
secure-status = "okay";
  +
 
  +
* Add this I²C base address in {{CodeSource | TF-A | plat/st/stm32mp1/stm32mp1_def.h}}:
  +
#define I2C2_BASE U(0x40013000)
  +
* Add a case for this I²C in register_periph_iomem() function, in the file {{CodeSource | TF-A | plat/st/stm32mp1/stm32mp1_shared_resources.c}}. It should be placed with the other non-secure peripherals (UARTs and IWDG2):
  +
case UART7_BASE:
  +
case UART8_BASE:
  +
case IWDG2_BASE:
  +
+ case I2C2_BASE:
  +
/* Allow drivers to register some non secure resources */
  +
VERBOSE("IO for non secure resource 0x%x\n",
  +
(unsigned int)base);
  +
 
  +
* Add the clock of this I²C in the stm32mp1_clk_gate[] table in the file {{CodeSource | TF-A | drivers/st/clk/stm32mp1_clk.c}}
  +
+ _CLK_SC_SELEC(RCC_MP_APB1ENSETR, 22, I2C2_K, _I2C12_SEL),
  +
 
  +
* Regarding the GPIO ports used by I2C2: in this stm32mp1_clk_gate[] table, remove the #ifdef IMAGE_BL2 around GPIO banks entries if present
   
 
==== OP-TEE ====
 
==== OP-TEE ====
Line 154: Line 199:
 
   {{CodeSource | OP-TEE_OS | core/include/drivers/stpmic1.h}}  
 
   {{CodeSource | OP-TEE_OS | core/include/drivers/stpmic1.h}}  
 
   {{CodeSource | OP-TEE_OS | core/drivers/stpmic1.c}}
 
   {{CodeSource | OP-TEE_OS | core/drivers/stpmic1.c}}
  +
  +
<noinclude>
  +
[[Category:Power and Thermal hardware components]]
  +
{{PublicationRequestId | 10277 | 2019-01-17 | BrunoB}}
  +
{{ArticleBasedOnModel | Hardware components article model}}
  +
</noinclude>