[linux-2.6-block.git] / Documentation / hwmon / occ.rst

Kernel driver occ-hwmon
=======================

Supported chips:

  * POWER8
  * POWER9

Author: Eddie James <eajames@linux.ibm.com>

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

This driver supports hardware monitoring for the On-Chip Controller (OCC)
embedded on POWER processors. The OCC is a device that collects and aggregates
sensor data from the processor and the system. The OCC can provide the raw
sensor data as well as perform thermal and power management on the system.

The P8 version of this driver is a client driver of I2C. It may be probed
manually if an "ibm,p8-occ-hwmon" compatible device is found under the
appropriate I2C bus node in the device-tree.

The P9 version of this driver is a client driver of the FSI-based OCC driver.
It will be probed automatically by the FSI-based OCC driver.

Sysfs entries
-------------

The following attributes are supported. All attributes are read-only unless
specified.

The OCC sensor ID is an integer that represents the unique identifier of the
sensor with respect to the OCC. For example, a temperature sensor for the third
DIMM slot in the system may have a sensor ID of 7. This mapping is unavailable
to the device driver, which must therefore export the sensor ID as-is.

Some entries are only present with certain OCC sensor versions or only on
certain OCCs in the system. The version number is not exported to the user
but can be inferred.

temp[1-n]_label
	OCC sensor ID.

[with temperature sensor version 1]

    temp[1-n]_input
			Measured temperature of the component in millidegrees
			Celsius.

[with temperature sensor version >= 2]

    temp[1-n]_type
				The FRU (Field Replaceable Unit) type
				(represented by an integer) for the component
				that this sensor measures.
    temp[1-n]_fault
				Temperature sensor fault boolean; 1 to indicate
				that a fault is present or 0 to indicate that
				no fault is present.

    [with type == 3 (FRU type is VRM)]

	temp[1-n]_alarm
				VRM temperature alarm boolean; 1 to indicate
				alarm, 0 to indicate no alarm

    [else]

	temp[1-n]_input
				Measured temperature of the component in
				millidegrees Celsius.

freq[1-n]_label
			OCC sensor ID.
freq[1-n]_input
			Measured frequency of the component in MHz.
power[1-n]_input
			Latest measured power reading of the component in
			microwatts.
power[1-n]_average
			Average power of the component in microwatts.
power[1-n]_average_interval
				The amount of time over which the power average
				was taken in microseconds.

[with power sensor version < 2]

    power[1-n]_label
			OCC sensor ID.

[with power sensor version >= 2]

    power[1-n]_label
			OCC sensor ID + function ID + channel in the form
			of a string, delimited by underscores, i.e. "0_15_1".
			Both the function ID and channel are integers that
			further identify the power sensor.

[with power sensor version 0xa0]

    power[1-n]_label
			OCC sensor ID + sensor type in the form of a string,
			delimited by an underscore, i.e. "0_system". Sensor
			type will be one of "system", "proc", "vdd" or "vdn".
			For this sensor version, OCC sensor ID will be the same
			for all power sensors.

[present only on "master" OCC; represents the whole system power; only one of
this type of power sensor will be present]

    power[1-n]_label
				"system"
    power[1-n]_input
				Latest system output power in microwatts.
    power[1-n]_cap
				Current system power cap in microwatts.
    power[1-n]_cap_not_redundant
				System power cap in microwatts when
				there is not redundant power.
    power[1-n]_cap_max
				Maximum power cap that the OCC can enforce in
				microwatts.
    power[1-n]_cap_min		Minimum power cap that the OCC can enforce in
				microwatts.
    power[1-n]_cap_user		The power cap set by the user, in microwatts.
				This attribute will return 0 if no user power
				cap has been set. This attribute is read-write,
				but writing any precision below watts will be
				ignored, i.e. requesting a power cap of
				500900000 microwatts will result in a power cap
				request of 500 watts.

    [with caps sensor version > 1]

	power[1-n]_cap_user_source
					Indicates how the user power cap was
					set. This is an integer that maps to
					system or firmware components that can
					set the user power cap.

The following "extn" sensors are exported as a way for the OCC to provide data
that doesn't fit anywhere else. The meaning of these sensors is entirely
dependent on their data, and cannot be statically defined.

extn[1-n]_label
			ASCII ID or OCC sensor ID.
extn[1-n]_flags
			This is one byte hexadecimal value. Bit 7 indicates the
			type of the label attribute; 1 for sensor ID, 0 for
			ASCII ID. Other bits are reserved.
extn[1-n]_input
			6 bytes of hexadecimal data, with a meaning defined by
			the sensor ID.
Commit	Line	Data
cd261c98 EJ	1	Kernel driver occ-hwmon
	2	=======================
	3
	4	Supported chips:
b04f2f7d	5
cd261c98 EJ	6	* POWER8
	7	* POWER9
	8
	9	Author: Eddie James <eajames@linux.ibm.com>
	10
	11	Description
	12	-----------
	13
	14	This driver supports hardware monitoring for the On-Chip Controller (OCC)
	15	embedded on POWER processors. The OCC is a device that collects and aggregates
	16	sensor data from the processor and the system. The OCC can provide the raw
	17	sensor data as well as perform thermal and power management on the system.
	18
	19	The P8 version of this driver is a client driver of I2C. It may be probed
	20	manually if an "ibm,p8-occ-hwmon" compatible device is found under the
	21	appropriate I2C bus node in the device-tree.
	22
	23	The P9 version of this driver is a client driver of the FSI-based OCC driver.
	24	It will be probed automatically by the FSI-based OCC driver.
	25
	26	Sysfs entries
	27	-------------
	28
	29	The following attributes are supported. All attributes are read-only unless
	30	specified.
	31
	32	The OCC sensor ID is an integer that represents the unique identifier of the
	33	sensor with respect to the OCC. For example, a temperature sensor for the third
	34	DIMM slot in the system may have a sensor ID of 7. This mapping is unavailable
	35	to the device driver, which must therefore export the sensor ID as-is.
	36
	37	Some entries are only present with certain OCC sensor versions or only on
	38	certain OCCs in the system. The version number is not exported to the user
	39	but can be inferred.
	40
b04f2f7d MCC	41	temp[1-n]_label
	42	OCC sensor ID.
	43
cd261c98	44	[with temperature sensor version 1]
b04f2f7d MCC	45
	46	temp[1-n]_input
	47	Measured temperature of the component in millidegrees
cd261c98	48	Celsius.
b04f2f7d	49
cd261c98	50	[with temperature sensor version >= 2]
b04f2f7d MCC	51
	52	temp[1-n]_type
	53	The FRU (Field Replaceable Unit) type
cd261c98 EJ	54	(represented by an integer) for the component
cd261c98 EJ	55	that this sensor measures.
b04f2f7d MCC	56	temp[1-n]_fault
b04f2f7d MCC	57	Temperature sensor fault boolean; 1 to indicate
cd261c98 EJ	58	that a fault is present or 0 to indicate that
cd261c98 EJ	59	no fault is present.
b04f2f7d	60
cd261c98	61	[with type == 3 (FRU type is VRM)]
b04f2f7d MCC	62
	63	temp[1-n]_alarm
	64	VRM temperature alarm boolean; 1 to indicate
cd261c98	65	alarm, 0 to indicate no alarm
b04f2f7d	66
cd261c98	67	[else]
cd261c98	68
b04f2f7d MCC	69	temp[1-n]_input
	70	Measured temperature of the component in
	71	millidegrees Celsius.
cd261c98	72
b04f2f7d MCC	73	freq[1-n]_label
	74	OCC sensor ID.
	75	freq[1-n]_input
	76	Measured frequency of the component in MHz.
	77	power[1-n]_input
	78	Latest measured power reading of the component in
cd261c98	79	microwatts.
b04f2f7d MCC	80	power[1-n]_average
	81	Average power of the component in microwatts.
	82	power[1-n]_average_interval
	83	The amount of time over which the power average
cd261c98	84	was taken in microseconds.
b04f2f7d	85
cd261c98	86	[with power sensor version < 2]
b04f2f7d MCC	87
	88	power[1-n]_label
	89	OCC sensor ID.
	90
cd261c98	91	[with power sensor version >= 2]
b04f2f7d MCC	92
	93	power[1-n]_label
	94	OCC sensor ID + function ID + channel in the form
cd261c98 EJ	95	of a string, delimited by underscores, i.e. "0_15_1".
	96	Both the function ID and channel are integers that
	97	further identify the power sensor.
b04f2f7d	98
cd261c98	99	[with power sensor version 0xa0]
b04f2f7d MCC	100
	101	power[1-n]_label
	102	OCC sensor ID + sensor type in the form of a string,
cd261c98 EJ	103	delimited by an underscore, i.e. "0_system". Sensor
	104	type will be one of "system", "proc", "vdd" or "vdn".
	105	For this sensor version, OCC sensor ID will be the same
	106	for all power sensors.
b04f2f7d	107
cd261c98	108	[present only on "master" OCC; represents the whole system power; only one of
b04f2f7d MCC	109	this type of power sensor will be present]
	110
	111	power[1-n]_label
	112	"system"
	113	power[1-n]_input
	114	Latest system output power in microwatts.
	115	power[1-n]_cap
	116	Current system power cap in microwatts.
	117	power[1-n]_cap_not_redundant
	118	System power cap in microwatts when
	119	there is not redundant power.
	120	power[1-n]_cap_max
	121	Maximum power cap that the OCC can enforce in
cd261c98 EJ	122	microwatts.
	123	power[1-n]_cap_min Minimum power cap that the OCC can enforce in
	124	microwatts.
	125	power[1-n]_cap_user The power cap set by the user, in microwatts.
	126	This attribute will return 0 if no user power
	127	cap has been set. This attribute is read-write,
	128	but writing any precision below watts will be
	129	ignored, i.e. requesting a power cap of
	130	500900000 microwatts will result in a power cap
	131	request of 500 watts.
b04f2f7d	132
cd261c98	133	[with caps sensor version > 1]
b04f2f7d MCC	134
	135	power[1-n]_cap_user_source
	136	Indicates how the user power cap was
cd261c98 EJ	137	set. This is an integer that maps to
	138	system or firmware components that can
	139	set the user power cap.
	140
	141	The following "extn" sensors are exported as a way for the OCC to provide data
	142	that doesn't fit anywhere else. The meaning of these sensors is entirely
	143	dependent on their data, and cannot be statically defined.
	144
b04f2f7d MCC	145	extn[1-n]_label
	146	ASCII ID or OCC sensor ID.
	147	extn[1-n]_flags
	148	This is one byte hexadecimal value. Bit 7 indicates the
cd261c98 EJ	149	type of the label attribute; 1 for sensor ID, 0 for
cd261c98 EJ	150	ASCII ID. Other bits are reserved.
b04f2f7d MCC	151	extn[1-n]_input
b04f2f7d MCC	152	6 bytes of hexadecimal data, with a meaning defined by
cd261c98	153	the sensor ID.