Message-ID: <a568a6b7-64d0-4ac1-86ed-19fd96887241@gmx.de>
Date: Thu, 9 Jan 2025 22:36:38 +0100
From: Armin Wolf <W_Armin@....de>
To: "Derek J. Clark" <derekjohn.clark@...il.com>,
 Hans de Goede <hdegoede@...hat.com>,
 Ilpo Järvinen <ilpo.jarvinen@...ux.intel.com>
Cc: 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
Subject: Re: [PATCH v2 1/4] platform/x86: Add lenovo-wmi drivers Documentation

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.

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

> +
> +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.

> +
> +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.

> +
> +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.

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