Message-ID: <CAFqHKTkkchsFOq2oZuuLNNxDuy9i5L-kpcD0+0_9NCNUxLirSA@mail.gmail.com>
Date: Fri, 10 Jan 2025 14:41:17 -0800
From: Derek John Clark <derekjohn.clark@...il.com>
To: Armin Wolf <W_Armin@....de>
Cc: Hans de Goede <hdegoede@...hat.com>, Ilpo Järvinen <ilpo.jarvinen@...ux.intel.com>, 
	Jonathan Corbet <corbet@....net>, Mario Limonciello <superm1@...nel.org>, Luke Jones <luke@...nes.dev>, 
	Xino Ni <nijs1@...ovo.com>, Zhixin Zhang <zhangzx36@...ovo.com>, Mia Shao <shaohz1@...ovo.com>, 
	Mark Pearson <mpearson-lenovo@...ebb.ca>, 
	"Pierre-Loup A . Griffais" <pgriffais@...vesoftware.com>, "Cody T . -H . Chiu" <codyit@...il.com>, 
	John Martens <johnfanv2@...il.com>, platform-driver-x86@...r.kernel.org, 
	linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, aichao@...inos.cn
Subject: Re: [PATCH v2 1/4] platform/x86: Add lenovo-wmi drivers Documentation

On Thu, Jan 9, 2025 at 1:37 PM Armin Wolf <W_Armin@....de> wrote:
>
> Am 02.01.25 um 01:47 schrieb Derek J. Clark:
>
> > Adds documentation for all lenovo-wmi* drivers.
>
> Hi,
>
> while i would prefer separate documentation files for each driver, grouping them together for now
> is also fine. We can split them later should the combined file become to big.

I don't have an issue with separating them. Once I add the MOF info
this file will become large.

> >
> > v2:
> > - Update description of Custom Profile to include the need to manually
> >    set it.
> > - Remove all references to Legion hardware.
> > - Add section for lemovo-wmi-camera.c driver as it follows the same
> >    naming convention.
> >
> > Signed-off-by: Derek J. Clark <derekjohn.clark@...il.com>
> > ---
> >   Documentation/wmi/devices/lenovo-wmi.rst | 104 +++++++++++++++++++++++
> >   1 file changed, 104 insertions(+)
> >   create mode 100644 Documentation/wmi/devices/lenovo-wmi.rst
> >
> > diff --git a/Documentation/wmi/devices/lenovo-wmi.rst b/Documentation/wmi/devices/lenovo-wmi.rst
> > new file mode 100644
> > index 000000000000..62c2ec9505bd
> > --- /dev/null
> > +++ b/Documentation/wmi/devices/lenovo-wmi.rst
> > @@ -0,0 +1,104 @@
> > +.. SPDX-License-Identifier: GPL-2.0-or-later
> > +======================================================
> > +Lenovo WMI Interface Drivers (lenovo-wmi)
>
> Since we are talking about multiple drivers, i suggest you change this line to:
>
>         Lenovo WMI Interface Drivers (lenovo-wmi-*)
>
> > +======================================================
> > +
> > +Introduction
> > +============
> > +Lenovo WMI interfaces are broken up into multiple GUIDs, some of which
> > +require cross-references between GUIDs for some functionality. The "Custom
> > +Mode" interface is a legacy interface for managing and displaying CPU & GPU
> > +power and hwmon settings and readings. The "Other Method" interface is a
> > +modern interface that replaces most "Custom Mode" interface methods. The
> > +"GameZone" interface adds advanced features such as fan profiles and
> > +overclocking. The "Lighting" interface adds control of various status
> > +lights related to different hardware components.
> > +
> > +Each interface has a different data structure associated with it that
> > +provides detailed information about each attribute provided by the
> > +interface. These data structs are retrieved from additional WMI device
> > +data block GUIDs:
> > + - "Custom Mode" uses LENOVO_FAN_TABLE_DATA, LENOVO_FAN_TEST_DATA,
> > +   LENOVO_CPU_OVERCLOCKING_DATA, LENOVO_DISCRETE_DATA, and
> > +   LENOVO_GPU_OVERCLOCKING_DATA depending on the feature.
> > + - "Other Method" uses LENOVO_CAPABILITY_DATA_00,
> > +   LENOVO_CAPABILITY_DATA_01, and LENOVO_CAPABILITY_DATA_02 depending on
> > +   the feature.
> > + - "GameZone" uses LENOVO_GAMEZONE_CPU_OC_DATA and
> > +   LENOVO_GAMEZONE_GPU_OC_DATA depending on the feature.
> > + - The "Lighting" interface uses LENOVO_LIGHTING_DATA.
> > +
> > +.. note::
> > +   Currently only the "GameZone", "Other Method", and
> > +   LENOVO_CAPABILITY_DATA_01 interfaces are implemented by these drivers.
> > +
> > +GameZone
> > +--------
> > +WMI GUID "887B54E3-DDDC-4B2C-8B88-68A26A8835D0"
>
> Please add the MOF of the WMI class here so that future developers know which methods, etc
> the WMI interface supports.
>

Ack

> > +
> > +The GameZone WMI interface provides platform-profile and fan curve settings
> > +for devices that fall under the "Gaming Series" of Lenovo devices.
> > +
> > +The following platform profiles are supported:
> > + - quiet
> > + - balanced
> > + - performance
> > + - custom
>
> Please add some technical documentation about the WMI methods used by those functions. You can take a look at
> Documentation/wmi/devices/msi-wmi-platform.rst for inspiration.
>

Ack

> > +
> > +Custom Profile
> > +~~~~~~~~~~~~~~
> > +The custom profile represents a hardware mode on Lenovo devices that enables
> > +user modifications to Package Power Tracking (PPT) settings. When an
> > +attribute exposed by the "Other Method" WMI interface is to be modified,
> > +the GameZone driver must first be switched to the "custom" profile manually
> > +or the setting will have no effect. If another profile is set from the list
> > +of supported profiles, the BIOS will override any user PPT settings when
> > +switching to that profile.
> > +
> > +
> > +Other Method
> > +----------
> > +WMI GUID "DC2A8805-3A8C-41BA-A6F7-092E0089CD3B"
> > +
> > +The Other Method WMI interface uses the fw_attributes class to expose
> > +various WMI attributes provided by the interface in the sysfs. This enables
> > +CPU and GPU power limit tuning as well as various other attributes for
> > +devices that fall under the "Gaming Series" of Lenovo devices. Each
> > +attribute exposed by the Other Method interface has corresponding
> > +capability data blocks which allow the driver to probe details about the
> > +attribute. Each attibute has multiple pages, one for each of the platform
> > +profiles managed by the "GameZone" interface. For all properties only the
> > +"Custom" profile values are reported by this driver to ensure any userspace
> > +applications reading them have accurate tunable value ranges. Attributes
> > +are exposed in sysfs under the following path:
> > +/sys/class/firmware-attributes/lenovo-wmi-other/attributes
>
> Same as above.
>

Ack

> > +
> > +LENOVO_CAPABILITY_DATA_01
> > +~~~~~~~~~~~~~~~~~~~~~~~~~
> > +WMI GUID "7A8F5407-CB67-4D6E-B547-39B3BE018154"
> > +
> > +The LENOVO_CAPABILITY_DATA_01 interface provides information on various
> > +power limits of integrated CPU and GPU components.
> > +
> > +The following attributes are supported:
> > + - ppt_pl1_spl: Platform Profile Tracking Sustained Power Limit
> > + - ppt_pl2_sppt: Platform Profile Tracking Slow Package Power Tracking
> > + - ppt_pl3_fppt: Platform Profile Tracking Fast Package Power Tracking
> > +
> > +Each attribute has the following properties:
> > + - current_value
> > + - default_value
> > + - display_name
> > + - max_value
> > + - min_value
> > + - scalar_increment
> > + - type
> > +
> > +
> > + Camera
> > + ______
>
> I get the following error when trying to build the documentation:
>
>         Sphinx parallel build error:
>         docutils.utils.SystemMessage: /home/wolf/Dokumente/Kernel/platform-drivers-x86/Documentation/wmi/devices/lenovo-wmi.rst:99: (SEVERE/4) Unexpected section title.
>
> Please fix this.
>
> Also please add some technical details here to. However in this case this is optional since this patch series focuses
> on the Gaming Series drivers.

Since I'm splitting the files I'll drop this one and let Ai Chao (+cc)
take care of that as the module author. I don't have any of the
technical documentation for that interface.

Thanks Armin,
Derek

> Thanks,
> Armin Wolf
>
> > + WMI GUID "50C76F1F-D8E4-D895-0A3D-62F4EA400013"
> > +
> > + The Camera driver provides WMI event notifications for camera button
> > + toggling.
> > +

Powered by blists - more mailing lists