[PATCH 0/2] acpi: document sysfs interfaces

[PATCH 0/2] acpi: document sysfs interfaces

[Aishwarya Pant]

Patchset contains documentation for two acpi drivers- dock and dptf. Description
was collected from git history and reading through code. This might be useful
for tracking changes in the ABI.

Aishwarya Pant (2):
  acpi/dptf: document sysfs atttributes
  acpi/dock: document sysfs interface

 .../ABI/testing/sysfs-devices-platform-dock        | 38 ++++++++++++++++++++++
 Documentation/ABI/testing/sysfs-platform-dptf      | 30 +++++++++++++++++
 2 files changed, 68 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-devices-platform-dock
 create mode 100644 Documentation/ABI/testing/sysfs-platform-dptf

-- 
2.16.1

[PATCH 1/2] acpi/dptf: document sysfs atttributes

[Aishwarya Pant]

The descriptions have been collected from git commit logs and reading
through code.

Signed-off-by: Aishwarya Pant <aishpant@gmail.com>
---
 Documentation/ABI/testing/sysfs-platform-dptf | 30 +++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-platform-dptf

diff --git a/Documentation/ABI/testing/sysfs-platform-dptf b/Documentation/ABI/testing/sysfs-platform-dptf
new file mode 100644
index 000000000000..e8168e5198d7
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-dptf
@@ -0,0 +1,30 @@
+sysfs interface for ACPI DPTF platform power driver
+---------------------------------------------------
+
+What:		/sys/bus/platform/devices/INT3407:00/dptf_power/charger_type
+What:		/sys/bus/platform/devices/INT3407:00/dptf_power/adapter_rating_mw
+What:		/sys/bus/platform/devices/INT3407:00/dptf_power/max_platform_power_mw
+What:		/sys/bus/platform/devices/INT3407:00/dptf_power/platform_power_source
+What:		/sys/bus/platform/devices/INT3407:00/dptf_power/battery_steady_power
+Date:		Jul, 2016
+KernelVersion:	v4.10
+Contact:	linux-acpi@vger.kernel.org
+Description:
+		charger_type:		(RO) The charger type- Traditional,
+					Hybrid or NVDC.
+
+		adapter_rating_mw:	(RO) Adapter rating in milliwatts (the
+					maximum Adapter power). Must be 0 if no
+					AC Adaptor is plugged in.
+
+		max_platform_power_mw:	(RO) Maximum platform power that can be
+					supported by the battery in milliwatts.
+
+		platform_power_source:	(RO) Display the platform power source
+					0x00 = DC
+					0x01 = AC
+					0x02 = USB
+					0x03 = Wireless Charger
+
+		battery_steady_power_mw:(RO) The maximum sustained power for
+					battery in milliwatts.
-- 
2.16.1

[PATCH v1 2/2] acpi/dock: document sysfs interface

[Aishwarya Pant]

Description has been collected from git commit history and reading
through code.

Signed-off-by: Aishwarya Pant <aishpant@gmail.com>
---
 .../ABI/testing/sysfs-devices-platform-dock        | 38 ++++++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-devices-platform-dock

diff --git a/Documentation/ABI/testing/sysfs-devices-platform-dock b/Documentation/ABI/testing/sysfs-devices-platform-dock
new file mode 100644
index 000000000000..0bb0d42e9126
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-platform-dock
@@ -0,0 +1,38 @@
+sysfs interface for ACPI dock station driver
+--------------------------------------------
+
+What:		/sys/devices/platform/dock.N/docked
+What:		/sys/devices/platform/dock.N/undock
+Date:		Dec, 2006
+KernelVersion:	2.6.19
+Contact:	linux-acpi@vger.kernel.org
+Description:
+		docked: (RO) Value 1 or 0 indicates whether the software
+		believes the laptop is docked in a docking station.
+
+		undock: (WO) Writing to this file causes the software to
+		initiate an undock request to the firmware.
+
+What:		/sys/devices/platform/dock.N/uid
+Date:		Feb, 2007
+KernelVersion:	v2.6.21
+Contact:	linux-acpi@vger.kernel.org
+Description:
+		(RO) Displays the docking station the laptop is docked to.
+
+What:		/sys/devices/platform/dock.N/flags
+Date:		May, 2007
+KernelVersion:	v2.6.21
+Contact:	linux-acpi@vger.kernel.org
+Description:
+		(RO) Show dock station flags, useful for checking if undock
+		request has been made by the user (from the immediate_undock
+		option).
+
+What:		/sys/devices/platform/dock.N/type
+Date:		Aug, 2008
+KernelVersion:	v2.6.27
+Contact:	linux-acpi@vger.kernel.org
+Description:
+		(RO) Display the dock station type- dock_station, ata_bay or
+		battery_bay.
-- 
2.16.1

Re: [PATCH v1 2/2] acpi/dock: document sysfs interface

[Rafael J. Wysocki]

On Wed, Feb 7, 2018 at 2:18 PM, Aishwarya Pant <aishpant@gmail.com> wrote:
> Description has been collected from git commit history and reading
> through code.
>
> Signed-off-by: Aishwarya Pant <aishpant@gmail.com>
> ---
>  .../ABI/testing/sysfs-devices-platform-dock        | 38 ++++++++++++++++++++++
>  1 file changed, 38 insertions(+)
>  create mode 100644 Documentation/ABI/testing/sysfs-devices-platform-dock
>
> diff --git a/Documentation/ABI/testing/sysfs-devices-platform-dock b/Documentation/ABI/testing/sysfs-devices-platform-dock
> new file mode 100644
> index 000000000000..0bb0d42e9126
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-devices-platform-dock
> @@ -0,0 +1,38 @@
> +sysfs interface for ACPI dock station driver
> +--------------------------------------------
> +
> +What:          /sys/devices/platform/dock.N/docked
> +What:          /sys/devices/platform/dock.N/undock
> +Date:          Dec, 2006
> +KernelVersion: 2.6.19
> +Contact:       linux-acpi@vger.kernel.org
> +Description:
> +               docked: (RO) Value 1 or 0 indicates whether the software
> +               believes the laptop is docked in a docking station.
> +
> +               undock: (WO) Writing to this file causes the software to
> +               initiate an undock request to the firmware.

Please split the above into two entries.

Apart from that it looks OK to me.

Re: [PATCH 1/2] acpi/dptf: document sysfs atttributes

[Rafael J. Wysocki]

On Wed, Feb 7, 2018 at 2:18 PM, Aishwarya Pant <aishpant@gmail.com> wrote:
> The descriptions have been collected from git commit logs and reading
> through code.
>
> Signed-off-by: Aishwarya Pant <aishpant@gmail.com>
> ---
>  Documentation/ABI/testing/sysfs-platform-dptf | 30 +++++++++++++++++++++++++++
>  1 file changed, 30 insertions(+)
>  create mode 100644 Documentation/ABI/testing/sysfs-platform-dptf
>
> diff --git a/Documentation/ABI/testing/sysfs-platform-dptf b/Documentation/ABI/testing/sysfs-platform-dptf
> new file mode 100644
> index 000000000000..e8168e5198d7
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-platform-dptf
> @@ -0,0 +1,30 @@
> +sysfs interface for ACPI DPTF platform power driver
> +---------------------------------------------------

The header isn't necessary.

> +
> +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/charger_type
> +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/adapter_rating_mw
> +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/max_platform_power_mw
> +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/platform_power_source
> +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/battery_steady_power

There should be one entry per attribute AFAICS.

Also I need Srinivas to tell me whether or not the descriptions are
accurate enough.

> +Date:          Jul, 2016
> +KernelVersion: v4.10
> +Contact:       linux-acpi@vger.kernel.org
> +Description:
> +               charger_type:           (RO) The charger type- Traditional,
> +                                       Hybrid or NVDC.
> +
> +               adapter_rating_mw:      (RO) Adapter rating in milliwatts (the
> +                                       maximum Adapter power). Must be 0 if no
> +                                       AC Adaptor is plugged in.
> +
> +               max_platform_power_mw:  (RO) Maximum platform power that can be
> +                                       supported by the battery in milliwatts.
> +
> +               platform_power_source:  (RO) Display the platform power source
> +                                       0x00 = DC
> +                                       0x01 = AC
> +                                       0x02 = USB
> +                                       0x03 = Wireless Charger
> +
> +               battery_steady_power_mw:(RO) The maximum sustained power for
> +                                       battery in milliwatts.
> --

Re: [PATCH 1/2] acpi/dptf: document sysfs atttributes

[Aishwarya Pant]

On Fri, Feb 09, 2018 at 11:31:35AM +0100, Rafael J. Wysocki wrote:
> On Wed, Feb 7, 2018 at 2:18 PM, Aishwarya Pant <aishpant@gmail.com> wrote:
> > The descriptions have been collected from git commit logs and reading
> > through code.
> >
> > Signed-off-by: Aishwarya Pant <aishpant@gmail.com>
> > ---
> >  Documentation/ABI/testing/sysfs-platform-dptf | 30 +++++++++++++++++++++++++++
> >  1 file changed, 30 insertions(+)
> >  create mode 100644 Documentation/ABI/testing/sysfs-platform-dptf
> >
> > diff --git a/Documentation/ABI/testing/sysfs-platform-dptf b/Documentation/ABI/testing/sysfs-platform-dptf
> > new file mode 100644
> > index 000000000000..e8168e5198d7
> > --- /dev/null
> > +++ b/Documentation/ABI/testing/sysfs-platform-dptf
> > @@ -0,0 +1,30 @@
> > +sysfs interface for ACPI DPTF platform power driver
> > +---------------------------------------------------
> 
> The header isn't necessary.
> 
> > +
> > +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/charger_type
> > +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/adapter_rating_mw
> > +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/max_platform_power_mw
> > +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/platform_power_source
> > +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/battery_steady_power
> 
> There should be one entry per attribute AFAICS.

I grouped attributes by the date in which they were added for brevity, because
otherwise fields like Date added, KernelVersion and Contact information are the
same.

I can split them up if it makes more sense...

Aishwarya

> 
> Also I need Srinivas to tell me whether or not the descriptions are
> accurate enough.
> 
> > +Date:          Jul, 2016
> > +KernelVersion: v4.10
> > +Contact:       linux-acpi@vger.kernel.org
> > +Description:
> > +               charger_type:           (RO) The charger type- Traditional,
> > +                                       Hybrid or NVDC.
> > +
> > +               adapter_rating_mw:      (RO) Adapter rating in milliwatts (the
> > +                                       maximum Adapter power). Must be 0 if no
> > +                                       AC Adaptor is plugged in.
> > +
> > +               max_platform_power_mw:  (RO) Maximum platform power that can be
> > +                                       supported by the battery in milliwatts.
> > +
> > +               platform_power_source:  (RO) Display the platform power source
> > +                                       0x00 = DC
> > +                                       0x01 = AC
> > +                                       0x02 = USB
> > +                                       0x03 = Wireless Charger
> > +
> > +               battery_steady_power_mw:(RO) The maximum sustained power for
> > +                                       battery in milliwatts.
> > --

Re: [PATCH 1/2] acpi/dptf: document sysfs atttributes

[Rafael J. Wysocki]

On Fri, Feb 9, 2018 at 11:54 AM, Aishwarya Pant <aishpant@gmail.com> wrote:
> On Fri, Feb 09, 2018 at 11:31:35AM +0100, Rafael J. Wysocki wrote:
>> On Wed, Feb 7, 2018 at 2:18 PM, Aishwarya Pant <aishpant@gmail.com> wrote:
>> > The descriptions have been collected from git commit logs and reading
>> > through code.
>> >
>> > Signed-off-by: Aishwarya Pant <aishpant@gmail.com>
>> > ---
>> >  Documentation/ABI/testing/sysfs-platform-dptf | 30 +++++++++++++++++++++++++++
>> >  1 file changed, 30 insertions(+)
>> >  create mode 100644 Documentation/ABI/testing/sysfs-platform-dptf
>> >
>> > diff --git a/Documentation/ABI/testing/sysfs-platform-dptf b/Documentation/ABI/testing/sysfs-platform-dptf
>> > new file mode 100644
>> > index 000000000000..e8168e5198d7
>> > --- /dev/null
>> > +++ b/Documentation/ABI/testing/sysfs-platform-dptf
>> > @@ -0,0 +1,30 @@
>> > +sysfs interface for ACPI DPTF platform power driver
>> > +---------------------------------------------------
>>
>> The header isn't necessary.
>>
>> > +
>> > +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/charger_type
>> > +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/adapter_rating_mw
>> > +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/max_platform_power_mw
>> > +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/platform_power_source
>> > +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/battery_steady_power
>>
>> There should be one entry per attribute AFAICS.
>
> I grouped attributes by the date in which they were added for brevity, because
> otherwise fields like Date added, KernelVersion and Contact information are the
> same.
>
> I can split them up if it makes more sense...

That's what the format is from looking at the existing files.

Re: [PATCH 1/2] acpi/dptf: document sysfs atttributes

[Srinivas Pandruvada]

On Fri, 2018-02-09 at 11:31 +0100, Rafael J. Wysocki wrote:
> On Wed, Feb 7, 2018 at 2:18 PM, Aishwarya Pant <aishpant@gmail.com>
> wrote:
> > The descriptions have been collected from git commit logs and
> > reading
> > through code.
> > 
> > Signed-off-by: Aishwarya Pant <aishpant@gmail.com>
> > ---
> >  Documentation/ABI/testing/sysfs-platform-dptf | 30
> > +++++++++++++++++++++++++++
> >  1 file changed, 30 insertions(+)
> >  create mode 100644 Documentation/ABI/testing/sysfs-platform-dptf
> > 
> > diff --git a/Documentation/ABI/testing/sysfs-platform-dptf
> > b/Documentation/ABI/testing/sysfs-platform-dptf
> > new file mode 100644
> > index 000000000000..e8168e5198d7
> > --- /dev/null
> > +++ b/Documentation/ABI/testing/sysfs-platform-dptf
> > @@ -0,0 +1,30 @@
> > +sysfs interface for ACPI DPTF platform power driver
> > +---------------------------------------------------
> 
> The header isn't necessary.
> 
> > +
> > +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/cha
> > rger_type
> > +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/ada
> > pter_rating_mw
> > +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/max
> > _platform_power_mw
> > +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/pla
> > tform_power_source
> > +What:          /sys/bus/platform/devices/INT3407:00/dptf_power/bat
> > tery_steady_power
> 
> There should be one entry per attribute AFAICS.
> 
> Also I need Srinivas to tell me whether or not the descriptions are
> accurate enough.
Descriptions are correct.

Thanks,
Srinivas

> 
> > +Date:          Jul, 2016
> > +KernelVersion: v4.10
> > +Contact:       linux-acpi@vger.kernel.org
> > +Description:
> > +               charger_type:           (RO) The charger type-
> > Traditional,
> > +                                       Hybrid or NVDC.
> > +
> > +               adapter_rating_mw:      (RO) Adapter rating in
> > milliwatts (the
> > +                                       maximum Adapter power).
> > Must be 0 if no
> > +                                       AC Adaptor is plugged in.
> > +
> > +               max_platform_power_mw:  (RO) Maximum platform power
> > that can be
> > +                                       supported by the battery in
> > milliwatts.
> > +
> > +               platform_power_source:  (RO) Display the platform
> > power source
> > +                                       0x00 = DC
> > +                                       0x01 = AC
> > +                                       0x02 = USB
> > +                                       0x03 = Wireless Charger
> > +
> > +               battery_steady_power_mw:(RO) The maximum sustained
> > power for
> > +                                       battery in milliwatts.
> > --