[thirdparty/kernel/stable.git] / Documentation / hwmon / acpi_power_meter.rst

Kernel driver power_meter
=========================

This driver talks to ACPI 4.0 power meters.

Supported systems:

  * Any recent system with ACPI 4.0.

    Prefix: 'power_meter'

    Datasheet: http://acpi.info/, section 10.4.

Author: Darrick J. Wong

Description
-----------

This driver implements sensor reading support for the power meters exposed in
the ACPI 4.0 spec (Chapter 10.4).  These devices have a simple set of
features--a power meter that returns average power use over a configurable
interval, an optional capping mechanism, and a couple of trip points.  The
sysfs interface conforms with the specification outlined in the "Power" section
of Documentation/hwmon/sysfs-interface.rst.

Special Features
----------------

The `power[1-*]_is_battery` knob indicates if the power supply is a battery.
Both `power[1-*]_average_{min,max}` must be set before the trip points will work.
When both of them are set, an ACPI event will be broadcast on the ACPI netlink
socket and a poll notification will be sent to the appropriate
`power[1-*]_average` sysfs file.

The `power[1-*]_{model_number, serial_number, oem_info}` fields display
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
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.

There are a few other ACPI notifications that can be sent by the firmware.  In
all cases the ACPI event will be broadcast on the ACPI netlink event socket as
well as sent as a poll notification to a sysfs file.  The events are as
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.
Commit	Line	Data
de584afa DW	1	Kernel driver power_meter
	2	=========================
	3
	4	This driver talks to ACPI 4.0 power meters.
	5
	6	Supported systems:
b04f2f7d	7
de584afa	8	* Any recent system with ACPI 4.0.
b04f2f7d	9
de584afa	10	Prefix: 'power_meter'
b04f2f7d	11
de584afa DW	12	Datasheet: http://acpi.info/, section 10.4.
	13
	14	Author: Darrick J. Wong
	15
	16	Description
	17	-----------
	18
	19	This driver implements sensor reading support for the power meters exposed in
	20	the ACPI 4.0 spec (Chapter 10.4). These devices have a simple set of
	21	features--a power meter that returns average power use over a configurable
	22	interval, an optional capping mechanism, and a couple of trip points. The
	23	sysfs interface conforms with the specification outlined in the "Power" section
7ebd8b66	24	of Documentation/hwmon/sysfs-interface.rst.
de584afa DW	25
	26	Special Features
	27	----------------
	28
b04f2f7d MCC	29	The `power[1-*]_is_battery` knob indicates if the power supply is a battery.
b04f2f7d MCC	30	Both `power[1-*]_average_{min,max}` must be set before the trip points will work.
de584afa DW	31	When both of them are set, an ACPI event will be broadcast on the ACPI netlink
de584afa DW	32	socket and a poll notification will be sent to the appropriate
b04f2f7d	33	`power[1-*]_average` sysfs file.
de584afa	34
b04f2f7d MCC	35	The `power[1-*]_{model_number, serial_number, oem_info}` fields display
	36	arbitrary strings that ACPI provides with the meter. The measures/ directory
	37	contains symlinks to the devices that this meter measures.
de584afa DW	38
de584afa DW	39	Some computers have the ability to enforce a power cap in hardware. If this is
b04f2f7d	40	the case, the `power[1-*]_cap` and related sysfs files will appear. When the
de584afa DW	41	average power consumption exceeds the cap, an ACPI event will be broadcast on
de584afa DW	42	the netlink event socket and a poll notification will be sent to the
b04f2f7d	43	appropriate `power[1-*]_alarm` file to indicate that capping has begun, and the
de584afa DW	44	hardware has taken action to reduce power consumption. Most likely this will
	45	result in reduced performance.
	46
	47	There are a few other ACPI notifications that can be sent by the firmware. In
	48	all cases the ACPI event will be broadcast on the ACPI netlink event socket as
	49	well as sent as a poll notification to a sysfs file. The events are as
	50	follows:
	51
b04f2f7d MCC	52	`power[1-*]_cap` will be notified if the firmware changes the power cap.
b04f2f7d MCC	53	`power[1-*]_interval` will be notified if the firmware changes the averaging
de584afa	54	interval.