Documentation/hwmon/occ.rst

   1 Kernel driver occ-hwmon
   2 =======================
   3
   4 Supported chips:
   5
   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
  41 temp[1-n]_label
  42         OCC sensor ID.
  43
  44 [with temperature sensor version 1]
  45
  46     temp[1-n]_input
  47                         Measured temperature of the component in millidegrees
  48                         Celsius.
  49
  50 [with temperature sensor version >= 2]
  51
  52     temp[1-n]_type
  53                                 The FRU (Field Replaceable Unit) type
  54                                 (represented by an integer) for the component
  55                                 that this sensor measures.
  56     temp[1-n]_fault
  57                                 Temperature sensor fault boolean; 1 to indicate
  58                                 that a fault is present or 0 to indicate that
  59                                 no fault is present.
  60
  61     [with type == 3 (FRU type is VRM)]
  62
  63         temp[1-n]_alarm
  64                                 VRM temperature alarm boolean; 1 to indicate
  65                                 alarm, 0 to indicate no alarm
  66
  67     [else]
  68
  69         temp[1-n]_input
  70                                 Measured temperature of the component in
  71                                 millidegrees Celsius.
  72
  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
  79                         microwatts.
  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
  84                                 was taken in microseconds.
  85
  86 [with power sensor version < 2]
  87
  88     power[1-n]_label
  89                         OCC sensor ID.
  90
  91 [with power sensor version >= 2]
  92
  93     power[1-n]_label
  94                         OCC sensor ID + function ID + channel in the form
  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.
  98
  99 [with power sensor version 0xa0]
 100
 101     power[1-n]_label
 102                         OCC sensor ID + sensor type in the form of a string,
 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.
 107
 108 [present only on "master" OCC; represents the whole system power; only one of
 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
 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.
 132
 133     [with caps sensor version > 1]
 134
 135         power[1-n]_cap_user_source
 136                                         Indicates how the user power cap was
 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
 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
 149                         type of the label attribute; 1 for sensor ID, 0 for
 150                         ASCII ID. Other bits are reserved.
 151 extn[1-n]_input
 152                         6 bytes of hexadecimal data, with a meaning defined by
 153                         the sensor ID.