Re: [PATCH v2 1/4] platform/x86: Add lenovo-wmi drivers Documentation

[Armin Wolf <W_Armin@gmx.de>]

Am 10.01.25 um 23:41 schrieb Derek John Clark:

> On Thu, Jan 9, 2025 at 1:37 PM Armin Wolf <W_Armin@gmx.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.

OK.

>>> 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@gmail.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

That is fine.

Thanks,
Armin Wolf

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