Add Richtek RT9471 3A battery charger support

From: ChiYuan Huang <[email protected]>

Add bindings for the Richtek RT9471 I2C controlled battery charger.

Reviewed-by Krzysztof Kozlowski <[email protected]>

Co-developed-by Alina Yu <[email protected]>

Signed-off-by Alina Yu <[email protected]>

Signed-off-by ChiYuan Huang <[email protected]>

---
Since v3
- Move unevaluatedProperties line after $ref for binding patch.
- Add Reviewed-by tag for binding patch.

Since v2
- Remove the properties for interrupt controller things in the binding documentation.
- Fix dtc error for typo, it's 'regulator-name', not 'regulator-compatible'.
- Add regulator min/max microamp to allow otg vbus current adjustable in example.
- Specify the active-level for charge-enable-gpios in binding example.

---
 .../bindings/power/supply/richtek,rt9471.yaml      | 73 ++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/power/supply/richtek,rt9471.yaml

Quoted 19 lines · cy_huang

From: ChiYuan Huang <[email protected]>

Add bindings for the Richtek RT9471 I2C controlled battery charger.

Reviewed-by Krzysztof Kozlowski <[email protected]>

Co-developed-by Alina Yu <[email protected]>

Signed-off-by Alina Yu <[email protected]>

Signed-off-by ChiYuan Huang <[email protected]>

---
Since v3
- Move unevaluatedProperties line after $ref for binding patch.
- Add Reviewed-by tag for binding patch.

Since v2
- Remove the properties for interrupt controller things in the binding documentation.
- Fix dtc error for typo, it's 'regulator-name', not 'regulator-compatible'.
- Add regulator min/max microamp to allow otg vbus current adjustable in example.
- Specify the active-level for charge-enable-gpios in binding example.

Quoted 5 lines

---
 .../bindings/power/supply/richtek,rt9471.yaml      | 73 ++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/power/supply/richtek,rt9471.yaml

My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check' on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:

dtschema/dtc warnings/errors:
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/dma/renesas,rzn1-dmamux.example.dtb: dma-router@a0: dma-masters:0: [4294967295, 4294967295] is too long
From schema: /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/dma/renesas,rzn1-dmamux.yaml
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/dma/renesas,rzn1-dmamux.example.dtb: dma-router@a0: dma-masters:0: [4294967295, 4294967295] is too long
From schema: /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/dma/dma-router.yaml
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/dma/st,stm32-dmamux.example.dtb: dma-router@40020800: dma-masters:0: [4294967295, 4294967295] is too long
From schema: /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/dma/dma-router.yaml
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/dma/st,stm32-dmamux.example.dtb: dma-router@40020800: dma-masters:0: [4294967295, 4294967295] is too long
From schema: /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/dma/st,stm32-dmamux.yaml
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/dma/st,stm32-dmamux.example.dtb: dma-router@40020800: Unevaluated properties are not allowed ('dma-channels', 'dma-masters', 'dma-requests' were unexpected)
From schema: /builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/dma/st,stm32-dmamux.yaml

From: ChiYuan Huang <[email protected]>

Add support for the RT9471 3A 1-Cell Li+ battery charger.

The RT9471 is a highly-integrated 3A switch mode battery charger with low impedance power path to better optimize the charging efficiency.

Co-developed-by Alina Yu <[email protected]>

Signed-off-by Alina Yu <[email protected]>

Signed-off-by ChiYuan Huang <[email protected]>

---
[...]

drivers/power/supply/rt9471.c new file +7 -0

+static DEVICE_ATTR_RW(sysoff_enable);
+static DEVICE_ATTR_RW(port_detect_enable);
+
+static struct attribute *rt9471_sysfs_entries[] = {
+	&dev_attr_sysoff_enable.attr,
+	&dev_attr_port_detect_enable.attr,
+	NULL

From: ChiYuan Huang <[email protected]>

Document the settings exported by rt9471 charger driver through sysfs entries:
- sysoff_enable
- port_detect_enable

Signed-off-by ChiYuan Huang <[email protected]>

---
Since v5:
- Recover all the change in sysfs-class-power.
- New a sysfs-class-power-rt9471 file.
- Remove 'charge_term_enable' sysfs entry, directly integrate it in 'charge_term_current' power supply property control.

---
 Documentation/ABI/testing/sysfs-class-power-rt9471 | 29 ++++++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-class-power-rt9471

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +4 -0

new file mode 100644
index 00000000..ad5b049
@@ -0,0 +1,29 @@
+What:		/sys/class/power_supply/rt9471-*/sysoff_enable
+Date:		Oct 2022
+KernelVersion:	6.1
+Contact:	ChiYuan Huang <[email protected]>

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +4 -0

+What:		/sys/class/power_supply/rt9471-*/port_detect_enable
+Date:		Oct 2022
+KernelVersion:	6.1
+Contact:	ChiYuan Huang <[email protected]>

Hi,

Quoted 35 lines · cy_huang

From: ChiYuan Huang <[email protected]>

Document the settings exported by rt9471 charger driver through sysfs entries:
- sysoff_enable
- port_detect_enable

Signed-off-by ChiYuan Huang <[email protected]>

---
Since v5:
- Recover all the change in sysfs-class-power.
- New a sysfs-class-power-rt9471 file.
- Remove 'charge_term_enable' sysfs entry, directly integrate it in 'charge_term_current' power supply property control.

---
 Documentation/ABI/testing/sysfs-class-power-rt9471 | 29 ++++++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-class-power-rt9471

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +10 -0

new file mode 100644
index 00000000..ad5b049
@@ -0,0 +1,29 @@
+What:                /sys/class/power_supply/rt9471-*/sysoff_enable
+Date:                Oct 2022
+KernelVersion:       6.1
+Contact:     ChiYuan Huang <[email protected]>
+Description:
+             This entry allows enabling the sysoff mode of rt9471 charger devices.
+             If enabled and the input is removed, the internal battery FET is turned
+             off to reduce the leakage from the BAT pin. See device datasheet for details.
+             It's commonly used when the product enter shipping stage.
+

Documentation/ABI/testing/sysfs-class-power-rt9471 line 14

Quoted 4 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +4 -0

+             Access: Read, Write
+             Valid values:
+             - 1: enabled
+             - 0: disabled

I still fail to see why this needs to be controllable at runtime. This looks like a hardware property. Are there any known products, which need this disabled?

Quoted 13 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +12 -0

+What:                /sys/class/power_supply/rt9471-*/port_detect_enable
+Date:                Oct 2022
+KernelVersion:       6.1
+Contact:     ChiYuan Huang <[email protected]>
+Description:
+             This entry allows enabling the USB BC12 port detect function of rt9471 charger
+             devices. If enabled and VBUS is inserted, device will start to do the BC12
+             port detect and report the usb port type when port detect is done. See
+             datasheet for details. Normally controlled when TypeC/USBPD port integrated.
+
+             Access: Read, Write
+             Valid values:

Documentation/ABI/testing/sysfs-class-power-rt9471 line 28

Quoted 2 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +2 -0

+             - 1: enabled
+             - 0: disabled

So basically this depends on the hardware integration (e.g. it should be disabled when power source is a DC barrel jack instead of USB) and is not supposed to change at all during runtime? Then the information wether it needs to be enabled should be derived from the device tree.

-- Sebastian

Sebastian Reichel <[email protected]> 於 2022年9月17日 週六 上午9:19寫道：

Quoted 36 lines · cy_huang

Quoted 35 lines

From: ChiYuan Huang <[email protected]>

Document the settings exported by rt9471 charger driver through sysfs entries:
- sysoff_enable
- port_detect_enable

Signed-off-by ChiYuan Huang <[email protected]>

---
Since v5:
- Recover all the change in sysfs-class-power.
- New a sysfs-class-power-rt9471 file.
- Remove 'charge_term_enable' sysfs entry, directly integrate it in 'charge_term_current' power supply property control.

---
 Documentation/ABI/testing/sysfs-class-power-rt9471 | 29 ++++++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-class-power-rt9471

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +10 -0

new file mode 100644
index 00000000..ad5b049
@@ -0,0 +1,29 @@
+What:                /sys/class/power_supply/rt9471-*/sysoff_enable
+Date:                Oct 2022
+KernelVersion:       6.1
+Contact:     ChiYuan Huang <[email protected]>
+Description:
+             This entry allows enabling the sysoff mode of rt9471 charger devices.
+             If enabled and the input is removed, the internal battery FET is turned
+             off to reduce the leakage from the BAT pin. See device datasheet for details.
+             It's commonly used when the product enter shipping stage.
+

Quoted 8 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 line 14

Quoted 4 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +4 -0

+             Access: Read, Write
+             Valid values:
+             - 1: enabled
+             - 0: disabled

I still fail to see why this needs to be controllable at runtime. This looks like a hardware property. Are there any known products, which need this disabled?

It's just a switch, actually 'disabled' is not needed.
For the enabled case, mostly used in below scenarios
1. Online testing, USB IN -> Factory testing -> write 1 to enable -> USB out -> immediately VSYS off -> pack
2. Offline testing no vbus -> Factory testing -> write 1 to enable -> immediately VSYS off -> pack

The 'disable" can use to cancel the shipping mode in case 1 before USB out. It's more like the testing.

Like as you said, shipping BATFET_OFF is all the hardware behavior. To leave this mode after VSYS off, there're three ways
1. power key pressed
2. VBUS IN
3. control BATFET_OFF to 0 (But it need SOC to be alive, at the time, VSYS off, no one can execute this I2C command)

If what you care is no need to mention 'disable', then just remove it. It's fine.

Quoted 13 lines

Quoted 13 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +12 -0

+What:                /sys/class/power_supply/rt9471-*/port_detect_enable
+Date:                Oct 2022
+KernelVersion:       6.1
+Contact:     ChiYuan Huang <[email protected]>
+Description:
+             This entry allows enabling the USB BC12 port detect function of rt9471 charger
+             devices. If enabled and VBUS is inserted, device will start to do the BC12
+             port detect and report the usb port type when port detect is done. See
+             datasheet for details. Normally controlled when TypeC/USBPD port integrated.
+
+             Access: Read, Write
+             Valid values:

Quoted 8 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 line 28

Quoted 2 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +2 -0

+             - 1: enabled
+             - 0: disabled

So basically this depends on the hardware integration (e.g. it should be disabled when power source is a DC barrel jack instead of USB) and is not supposed to change at all during runtime? Then the information wether it needs to be enabled should be derived from the device tree.

It's a switching charger integrates OTG boost.
For the case 'DC Jack', there's no need to use this kind of product.

With typec integration, at most time, it still need bc12 to be enabled by default. Just in some case, like as power role swap (SNK -> SRC -> SNK), to automatically identify the USB port, this may interrupt USB communication.

So as my understanding, keep it enabled by default, just in some case, it my need to control at runtime.

Hi,

Quoted 55 lines · ChiYuan Huang

Sebastian Reichel <[email protected]> 於 2022年9月17日 週六 上午9:19寫道：

Quoted 36 lines · cy_huang

Quoted 35 lines

From: ChiYuan Huang <[email protected]>

Document the settings exported by rt9471 charger driver through sysfs entries:
- sysoff_enable
- port_detect_enable

Signed-off-by ChiYuan Huang <[email protected]>

---
Since v5:
- Recover all the change in sysfs-class-power.
- New a sysfs-class-power-rt9471 file.
- Remove 'charge_term_enable' sysfs entry, directly integrate it in 'charge_term_current' power supply property control.

---
 Documentation/ABI/testing/sysfs-class-power-rt9471 | 29 ++++++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-class-power-rt9471

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +10 -0

new file mode 100644
index 00000000..ad5b049
@@ -0,0 +1,29 @@
+What:                /sys/class/power_supply/rt9471-*/sysoff_enable
+Date:                Oct 2022
+KernelVersion:       6.1
+Contact:     ChiYuan Huang <[email protected]>
+Description:
+             This entry allows enabling the sysoff mode of rt9471 charger devices.
+             If enabled and the input is removed, the internal battery FET is turned
+             off to reduce the leakage from the BAT pin. See device datasheet for details.
+             It's commonly used when the product enter shipping stage.
+

Quoted 8 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 line 14

Quoted 4 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +4 -0

+             Access: Read, Write
+             Valid values:
+             - 1: enabled
+             - 0: disabled

I still fail to see why this needs to be controllable at runtime. This looks like a hardware property. Are there any known products, which need this disabled?

It's just a switch, actually 'disabled' is not needed.
For the enabled case, mostly used in below scenarios
1. Online testing, USB IN -> Factory testing -> write 1 to enable -> USB out -> immediately VSYS off -> pack
2. Offline testing no vbus -> Factory testing -> write 1 to enable -> immediately VSYS off -> pack

The 'disable" can use to cancel the shipping mode in case 1 before USB out. It's more like the testing.

Quoted 6 lines

Like as you said, shipping BATFET_OFF is all the hardware behavior. To leave this mode after VSYS off, there're three ways
1. power key pressed
2. VBUS IN
3. control BATFET_OFF to 0 (But it need SOC to be alive, at the time, VSYS off, no one can execute this I2C command)

If factory testing and preperation is the only use case, I don't think exposing this in sysfs and creating userspace ABI is worth it. Just tell factory to use i2c-dev and poke the correct registers.

Quoted 31 lines

If what you care is no need to mention 'disable', then just remove it. It's fine.

Quoted 13 lines

Quoted 13 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +12 -0

+What:                /sys/class/power_supply/rt9471-*/port_detect_enable
+Date:                Oct 2022
+KernelVersion:       6.1
+Contact:     ChiYuan Huang <[email protected]>
+Description:
+             This entry allows enabling the USB BC12 port detect function of rt9471 charger
+             devices. If enabled and VBUS is inserted, device will start to do the BC12
+             port detect and report the usb port type when port detect is done. See
+             datasheet for details. Normally controlled when TypeC/USBPD port integrated.
+
+             Access: Read, Write
+             Valid values:

Quoted 8 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 line 28

Quoted 2 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +2 -0

+             - 1: enabled
+             - 0: disabled

So basically this depends on the hardware integration (e.g. it should be disabled when power source is a DC barrel jack instead of USB) and is not supposed to change at all during runtime? Then the information wether it needs to be enabled should be derived from the device tree.

It's a switching charger integrates OTG boost.
For the case 'DC Jack', there's no need to use this kind of product.

With typec integration, at most time, it still need bc12 to be enabled by default. Just in some case, like as power role swap (SNK -> SRC -> SNK), to automatically identify the USB port, this may interrupt USB communication.

Quoted 2 lines

So as my understanding, keep it enabled by default, just in some case, it my need to control at runtime.

This should be part of the description. You can drop the sentence "Normally controlled when TypeC/USBPD port integrated.", since that's hard to comprehend. Instead add the information that this is supposed to be always enabled, but can be disabled to avoid USB link loss (?) when doing a USB PD role swap.

-- Sebastian

Sebastian Reichel <[email protected]> 於 2022年10月2日 週日 凌晨4:58寫道：

Quoted 66 lines

Hi,

Quoted 55 lines · ChiYuan Huang

Sebastian Reichel <[email protected]> 於 2022年9月17日 週六 上午9:19寫道：

Quoted 36 lines · cy_huang

Quoted 35 lines

From: ChiYuan Huang <[email protected]>

Document the settings exported by rt9471 charger driver through sysfs entries:
- sysoff_enable
- port_detect_enable

Signed-off-by ChiYuan Huang <[email protected]>

---
Since v5:
- Recover all the change in sysfs-class-power.
- New a sysfs-class-power-rt9471 file.
- Remove 'charge_term_enable' sysfs entry, directly integrate it in 'charge_term_current' power supply property control.

---
 Documentation/ABI/testing/sysfs-class-power-rt9471 | 29 ++++++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-class-power-rt9471

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +10 -0

new file mode 100644
index 00000000..ad5b049
@@ -0,0 +1,29 @@
+What:                /sys/class/power_supply/rt9471-*/sysoff_enable
+Date:                Oct 2022
+KernelVersion:       6.1
+Contact:     ChiYuan Huang <[email protected]>
+Description:
+             This entry allows enabling the sysoff mode of rt9471 charger devices.
+             If enabled and the input is removed, the internal battery FET is turned
+             off to reduce the leakage from the BAT pin. See device datasheet for details.
+             It's commonly used when the product enter shipping stage.
+

Quoted 8 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 line 14

Quoted 4 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +4 -0

+             Access: Read, Write
+             Valid values:
+             - 1: enabled
+             - 0: disabled

I still fail to see why this needs to be controllable at runtime. This looks like a hardware property. Are there any known products, which need this disabled?

It's just a switch, actually 'disabled' is not needed.
For the enabled case, mostly used in below scenarios
1. Online testing, USB IN -> Factory testing -> write 1 to enable -> USB out -> immediately VSYS off -> pack
2. Offline testing no vbus -> Factory testing -> write 1 to enable -> immediately VSYS off -> pack

The 'disable" can use to cancel the shipping mode in case 1 before USB out. It's more like the testing.

Quoted 6 lines

Like as you said, shipping BATFET_OFF is all the hardware behavior. To leave this mode after VSYS off, there're three ways
1. power key pressed
2. VBUS IN
3. control BATFET_OFF to 0 (But it need SOC to be alive, at the time, VSYS off, no one can execute this I2C command)

Quoted 4 lines

If factory testing and preperation is the only use case, I don't think exposing this in sysfs and creating userspace ABI is worth it. Just tell factory to use i2c-dev and poke the correct registers.

I agree your comment if there's only this case will use it.

So I ask our HW members about this.
They said there's still one case I didn't consider about. It's the dual charger scenario.
If the charging process is entering CV mode, the slave charger is no need to join the charging.
Then in common case, slave charger need to minimize the battery leakage. And the BATFET_OFF is needed to lower the battery leakage.

They think this sysfs entry is needed. Can this persuade you?

Quoted 31 lines

Quoted 31 lines

If what you care is no need to mention 'disable', then just remove it. It's fine.

Quoted 13 lines

Quoted 13 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +12 -0

+What:                /sys/class/power_supply/rt9471-*/port_detect_enable
+Date:                Oct 2022
+KernelVersion:       6.1
+Contact:     ChiYuan Huang <[email protected]>
+Description:
+             This entry allows enabling the USB BC12 port detect function of rt9471 charger
+             devices. If enabled and VBUS is inserted, device will start to do the BC12
+             port detect and report the usb port type when port detect is done. See
+             datasheet for details. Normally controlled when TypeC/USBPD port integrated.
+
+             Access: Read, Write
+             Valid values:

Quoted 8 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 line 28

Quoted 2 lines

Documentation/ABI/testing/sysfs-class-power-rt9471 new file +2 -0

+             - 1: enabled
+             - 0: disabled

So basically this depends on the hardware integration (e.g. it should be disabled when power source is a DC barrel jack instead of USB) and is not supposed to change at all during runtime? Then the information wether it needs to be enabled should be derived from the device tree.

It's a switching charger integrates OTG boost.
For the case 'DC Jack', there's no need to use this kind of product.

With typec integration, at most time, it still need bc12 to be enabled by default. Just in some case, like as power role swap (SNK -> SRC -> SNK), to automatically identify the USB port, this may interrupt USB communication.

Quoted 9 lines

Quoted 2 lines

So as my understanding, keep it enabled by default, just in some case, it my need to control at runtime.

This should be part of the description. You can drop the sentence "Normally controlled when TypeC/USBPD port integrated.", since that's hard to comprehend. Instead add the information that this is supposed to be always enabled, but can be disabled to avoid USB link loss (?) when doing a USB PD role swap.

Thanks for the comment.

I'll rewrite it as below
'It's supposed to be always enabled, but can be disabled to avoid usb link interruption especially when doing a USBPD 'power' role swap.'

Sorry, due to the long reply period, I already sent v6/v7/v8 to fix some coding like as missing header and irq wakeup check. Actually only missing header change is needed.
Please ignore these noise.

And after the sysfs reviewing is finished, you can just review the revision v9.

Thanks.

Quoted 1 line

-- Sebastian