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

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