[v4,3/3] Documentation: power: rt9471: Document exported sysfs entries

From: ChiYuan Huang <cy_huang@richtek.com>

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

Signed-off-by: ChiYuan Huang <cy_huang@richtek.com>
---
 Documentation/ABI/testing/sysfs-class-power | 44 +++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

Hi,

On Mon, Aug 29, 2022 at 11:06:31AM +0800, cy_huang wrote:
> From: ChiYuan Huang <cy_huang@richtek.com>
> 
> Document the settings exported by rt9471 charger driver through sysfs entries:
> - sysoff_enable
> - charge_term_enable
> - port_detect_enable
> 
> Signed-off-by: ChiYuan Huang <cy_huang@richtek.com>
> ---
>  Documentation/ABI/testing/sysfs-class-power | 44 +++++++++++++++++++++++++++++
>  1 file changed, 44 insertions(+)
> 
> diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
> index a9ce63c..1f8afe5 100644
> --- a/Documentation/ABI/testing/sysfs-class-power
> +++ b/Documentation/ABI/testing/sysfs-class-power
> @@ -768,3 +768,47 @@ Description:
>  
>  		Access: Read
>  		Valid values: 1-31
> +
> +What:		/sys/class/power_supply/rt9471-*/sysoff_enable
> +Date:		Sep 2022
> +KernelVersion:	6.1
> +Contact:	ChiYuan Huang <cy_huang@richtek.com>
> +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.
> +
> +		Access: Read, Write
> +		Valid values:
> +		- 1: enabled
> +		- 0: disabled

This is not a very good description of what the control does. When
do you expect users to control this?

> +What:		/sys/class/power_supply/rt9471-*/charge_term_enable
> +Date:		Sep 2022
> +KernelVersion:	6.1
> +Contact:	ChiYuan Huang <cy_huang@richtek.com>
> +Description:
> +		This entry allows enabling the charge termination function of rt9471 charger
> +		devices. If enabled, the battery charging current, and the battery voltage
> +		reachs charge termination condition, the internal battery FET will be turned off
> +		to optimize the battery life. See device datasheet for details.
> +
> +		Access: Read, Write
> +		Valid values:
> +		- 1: enabled
> +		- 0: disabled

Just write 0 to .../charge_term_current to disable it.
No need for a custom property.

> +What:		/sys/class/power_supply/rt9471-*/port_detect_enable
> +Date:		Sep 2022
> +KernelVersion:	6.1
> +Contact:	ChiYuan Huang <cy_huang@richtek.com>
> +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.
> +
> +		Access: Read, Write
> +		Valid values:
> +		- 1: enabled
> +		- 0: disabled

Why would one want to disable this?
Can't the driver just enable it unconditionally?

-- Sebastian

Hi,

On Mon, Sep 12, 2022 at 01:12:01PM +0200, Sebastian Reichel wrote:
> On Mon, Aug 29, 2022 at 11:06:31AM +0800, cy_huang wrote:
> > From: ChiYuan Huang <cy_huang@richtek.com>
> > 
> > Document the settings exported by rt9471 charger driver through sysfs entries:
> > - sysoff_enable
> > - charge_term_enable
> > - port_detect_enable
> > 
> > Signed-off-by: ChiYuan Huang <cy_huang@richtek.com>
> > ---
> >  Documentation/ABI/testing/sysfs-class-power | 44 +++++++++++++++++++++++++++++
> >  1 file changed, 44 insertions(+)

I forgot to mention: custom driver properties are described in their
own files, see Documentation/ABI/testing/sysfs-class-power-*. But
are to be avoided if possible. So first of all I want to make sure
you actually need any of these.

-- Sebastian

> > 
> > diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
> > index a9ce63c..1f8afe5 100644
> > --- a/Documentation/ABI/testing/sysfs-class-power
> > +++ b/Documentation/ABI/testing/sysfs-class-power
> > @@ -768,3 +768,47 @@ Description:
> >  
> >  		Access: Read
> >  		Valid values: 1-31
> > +
> > +What:		/sys/class/power_supply/rt9471-*/sysoff_enable
> > +Date:		Sep 2022
> > +KernelVersion:	6.1
> > +Contact:	ChiYuan Huang <cy_huang@richtek.com>
> > +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.
> > +
> > +		Access: Read, Write
> > +		Valid values:
> > +		- 1: enabled
> > +		- 0: disabled
> 
> This is not a very good description of what the control does. When
> do you expect users to control this?
> 
> > +What:		/sys/class/power_supply/rt9471-*/charge_term_enable
> > +Date:		Sep 2022
> > +KernelVersion:	6.1
> > +Contact:	ChiYuan Huang <cy_huang@richtek.com>
> > +Description:
> > +		This entry allows enabling the charge termination function of rt9471 charger
> > +		devices. If enabled, the battery charging current, and the battery voltage
> > +		reachs charge termination condition, the internal battery FET will be turned off
> > +		to optimize the battery life. See device datasheet for details.
> > +
> > +		Access: Read, Write
> > +		Valid values:
> > +		- 1: enabled
> > +		- 0: disabled
> 
> Just write 0 to .../charge_term_current to disable it.
> No need for a custom property.
> 
> > +What:		/sys/class/power_supply/rt9471-*/port_detect_enable
> > +Date:		Sep 2022
> > +KernelVersion:	6.1
> > +Contact:	ChiYuan Huang <cy_huang@richtek.com>
> > +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.
> > +
> > +		Access: Read, Write
> > +		Valid values:
> > +		- 1: enabled
> > +		- 0: disabled
> 
> Why would one want to disable this?
> Can't the driver just enable it unconditionally?
> 
> -- Sebastian

Sebastian Reichel <sebastian.reichel@collabora.com> 於 2022年9月12日 週一 晚上7:29寫道：
>
> Hi,
>
> On Mon, Sep 12, 2022 at 01:12:01PM +0200, Sebastian Reichel wrote:
> > On Mon, Aug 29, 2022 at 11:06:31AM +0800, cy_huang wrote:
> > > From: ChiYuan Huang <cy_huang@richtek.com>
> > >
> > > Document the settings exported by rt9471 charger driver through sysfs entries:
> > > - sysoff_enable
> > > - charge_term_enable
> > > - port_detect_enable
> > >
> > > Signed-off-by: ChiYuan Huang <cy_huang@richtek.com>
> > > ---
> > >  Documentation/ABI/testing/sysfs-class-power | 44 +++++++++++++++++++++++++++++
> > >  1 file changed, 44 insertions(+)
>
> I forgot to mention: custom driver properties are described in their
> own files, see Documentation/ABI/testing/sysfs-class-power-*. But
> are to be avoided if possible. So first of all I want to make sure
> you actually need any of these.
>
OK, it means I need to new a file  sysfs-class-power-rt9471.
> -- Sebastian
>
> > >
> > > diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
> > > index a9ce63c..1f8afe5 100644
> > > --- a/Documentation/ABI/testing/sysfs-class-power
> > > +++ b/Documentation/ABI/testing/sysfs-class-power
> > > @@ -768,3 +768,47 @@ Description:
> > >
> > >             Access: Read
> > >             Valid values: 1-31
> > > +
> > > +What:              /sys/class/power_supply/rt9471-*/sysoff_enable
> > > +Date:              Sep 2022
> > > +KernelVersion:     6.1
> > > +Contact:   ChiYuan Huang <cy_huang@richtek.com>
> > > +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.
> > > +
> > > +           Access: Read, Write
> > > +           Valid values:
> > > +           - 1: enabled
> > > +           - 0: disabled
> >
> > This is not a very good description of what the control does. When
> > do you expect users to control this?
When products leaves the factory and enter shipping stage.
> >
> > > +What:              /sys/class/power_supply/rt9471-*/charge_term_enable
> > > +Date:              Sep 2022
> > > +KernelVersion:     6.1
> > > +Contact:   ChiYuan Huang <cy_huang@richtek.com>
> > > +Description:
> > > +           This entry allows enabling the charge termination function of rt9471 charger
> > > +           devices. If enabled, the battery charging current, and the battery voltage
> > > +           reachs charge termination condition, the internal battery FET will be turned off
> > > +           to optimize the battery life. See device datasheet for details.
> > > +
> > > +           Access: Read, Write
> > > +           Valid values:
> > > +           - 1: enabled
> > > +           - 0: disabled
> >
> > Just write 0 to .../charge_term_current to disable it.
> > No need for a custom property.
OK, I will merge this 'TE' switch directly into 'charge_term_current' property.
> >
> > > +What:              /sys/class/power_supply/rt9471-*/port_detect_enable
> > > +Date:              Sep 2022
> > > +KernelVersion:     6.1
> > > +Contact:   ChiYuan Huang <cy_huang@richtek.com>
> > > +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.
> > > +
> > > +           Access: Read, Write
> > > +           Valid values:
> > > +           - 1: enabled
> > > +           - 0: disabled
> >
> > Why would one want to disable this?
> > Can't the driver just enable it unconditionally?
The current product may use the typec port.
This make the user can control bc12 port detection switch.
If bc12 port detect always on, for some cases like as power role swap
or hard reset, it will cause bc12 port detect be retriggered.
USB communication will be affected.

> >
> > -- Sebastian
>
>