[PATCH] doc: hwmon: acpi_power_meter: Add information about enabling the power capping feature.

[PATCH] doc: hwmon: acpi_power_meter: Add information about enabling the power capping feature.

[Shinji Nomoto]

To enable the power capping feature of the acpi_power_meter driver on
systems other than IBM products, you must explicitly specify
the force_cap_on module parameter.

Add information to the documentation about enabling the power capping
feature with this driver, including the above, to improve user convenience.

Signed-off-by: Shinji Nomoto <fj5851bi@fujitsu.com>
---
 Documentation/hwmon/acpi_power_meter.rst | 25 +++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/Documentation/hwmon/acpi_power_meter.rst b/Documentation/hwmon/acpi_power_meter.rst
index 8628c1161015..334054afc498 100644
--- a/Documentation/hwmon/acpi_power_meter.rst
+++ b/Documentation/hwmon/acpi_power_meter.rst
@@ -37,9 +37,16 @@ arbitrary strings that ACPI provides with the meter.  The measures/ directory
 contains symlinks to the devices that this meter measures.
 
 Some computers have the ability to enforce a power cap in hardware.  If this is
-the case, the `power[1-*]_cap` and related sysfs files will appear.  When the
-average power consumption exceeds the cap, an ACPI event will be broadcast on
-the netlink event socket and a poll notification will be sent to the
+the case, the `power[1-*]_cap` and related sysfs files will appear.
+For information on enabling the power cap feature, refer to the description
+of the "force_on_cap" option in the "Module Parameters" chapter.
+To use the power cap feature properly, you need to set appropriate value
+(in microWatts) to the `power[1-*]_cap` sysfs files.
+The value must be within the range between the minimum value at `power[1-]_cap_min`
+and the maximum value at `power[1-]_cap_max (both in microWatts)`.
+
+When the average power consumption exceeds the cap, an ACPI event will be
+broadcast on the netlink event socket and a poll notification will be sent to the
 appropriate `power[1-*]_alarm` file to indicate that capping has begun, and the
 hardware has taken action to reduce power consumption.  Most likely this will
 result in reduced performance.
@@ -52,3 +59,15 @@ follows:
 `power[1-*]_cap` will be notified if the firmware changes the power cap.
 `power[1-*]_interval` will be notified if the firmware changes the averaging
 interval.
+
+Module Parameters
+-----------------
+
+* force_cap_on: bool
+                        Forcefully enable the power capping feature to specify
+                        the upper limit of the system's power consumption.
+
+                        By default, the driver's power capping feature is only
+                        enabled on IBM products.
+                        Therefore, on other systems that support power capping,
+                        you will need to use the option to enable it.
-- 
2.43.0

Re: [PATCH] doc: hwmon: acpi_power_meter: Add information about enabling the power capping feature.

[Guenter Roeck]

On 5/19/25 00:27, Shinji Nomoto wrote:
> To enable the power capping feature of the acpi_power_meter driver on
> systems other than IBM products, you must explicitly specify
> the force_cap_on module parameter.
> 
> Add information to the documentation about enabling the power capping
> feature with this driver, including the above, to improve user convenience.
> 
> Signed-off-by: Shinji Nomoto <fj5851bi@fujitsu.com>
> ---
>   Documentation/hwmon/acpi_power_meter.rst | 25 +++++++++++++++++++++---
>   1 file changed, 22 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/hwmon/acpi_power_meter.rst b/Documentation/hwmon/acpi_power_meter.rst
> index 8628c1161015..334054afc498 100644
> --- a/Documentation/hwmon/acpi_power_meter.rst
> +++ b/Documentation/hwmon/acpi_power_meter.rst
> @@ -37,9 +37,16 @@ arbitrary strings that ACPI provides with the meter.  The measures/ directory
>   contains symlinks to the devices that this meter measures.
>   
>   Some computers have the ability to enforce a power cap in hardware.  If this is
> -the case, the `power[1-*]_cap` and related sysfs files will appear.  When the
> -average power consumption exceeds the cap, an ACPI event will be broadcast on
> -the netlink event socket and a poll notification will be sent to the
> +the case, the `power[1-*]_cap` and related sysfs files will appear.
> +For information on enabling the power cap feature, refer to the description
> +of the "force_on_cap" option in the "Module Parameters" chapter.
> +To use the power cap feature properly, you need to set appropriate value
> +(in microWatts) to the `power[1-*]_cap` sysfs files.
> +The value must be within the range between the minimum value at `power[1-]_cap_min`
> +and the maximum value at `power[1-]_cap_max (both in microWatts)`.
> +
> +When the average power consumption exceeds the cap, an ACPI event will be
> +broadcast on the netlink event socket and a poll notification will be sent to the
>   appropriate `power[1-*]_alarm` file to indicate that capping has begun, and the
>   hardware has taken action to reduce power consumption.  Most likely this will
>   result in reduced performance.
> @@ -52,3 +59,15 @@ follows:
>   `power[1-*]_cap` will be notified if the firmware changes the power cap.
>   `power[1-*]_interval` will be notified if the firmware changes the averaging
>   interval.
> +
> +Module Parameters
> +-----------------
> +
> +* force_cap_on: bool
> +                        Forcefully enable the power capping feature to specify
> +                        the upper limit of the system's power consumption.
> +
> +                        By default, the driver's power capping feature is only
> +                        enabled on IBM products.
> +                        Therefore, on other systems that support power capping,
> +                        you will need to use the option to enable it .

This is potentially unsafe if not really supported, which needs to be mentioned.

FWIW, if there are other systems known to support power cap in hardware, they
should be added to the driver in the dmi table. A more generic solution should
check if the _GHL and _SHL methods exist to enable the attributes. force_cap_on
should be the last resort to enable it.

Guenter

RE: [PATCH] doc: hwmon: acpi_power_meter: Add information about enabling the power capping feature.

[Shinji Nomoto (Fujitsu)]

Guenter wrote:
> This is potentially unsafe if not really supported, which needs to be mentioned.

Thank you for your comment.

I will add a note of "potentially unsafe" in v2.
We are considering installing ACPI power meter on a machine under development, but I believe that the DMI (SYS_VENDOR) check included in the driver has too broad a scope.
I will update the code if the appropriate conditinon is determined, but I would like to correct the document first.

Shinji

Re: [PATCH] doc: hwmon: acpi_power_meter: Add information about enabling the power capping feature.

[Guenter Roeck]

On 5/19/25 19:54, Shinji Nomoto (Fujitsu) wrote:
> Guenter wrote:
>> This is potentially unsafe if not really supported, which needs to be mentioned.
> 
> Thank you for your comment.
> 
> I will add a note of "potentially unsafe" in v2.
> We are considering installing ACPI power meter on a machine under development, but I believe that the DMI (SYS_VENDOR) check included in the driver has too broad a scope.

Sorry, you lost me. Presumably your system would not be an IBM system.
Nothing prevents you from adding a more specific DMI entry (or more
than one). Many DMI matches are for the system vendor, the board vendor,
the product name, or even the BIOS vendor, date, and/or version. Every
value in enum dmi_field can be matched.

Guenter

RE: [PATCH] doc: hwmon: acpi_power_meter: Add information about enabling the power capping feature.

[Shinji Nomoto (Fujitsu)]

Guenter wrotes:
> Sorry, you lost me. Presumably your system would not be an IBM system.
> Nothing prevents you from adding a more specific DMI entry (or more than one). Many DMI matches are for the system vendor, the board vendor, the product name, or even the BIOS vendor, date, > and/or version. Every value in enum dmi_field can be matched.

Thanks for information. I will investigate it.
Still, I think it would be informative for user to update the document itself. Please pick v2 if it is ok.

Shinji