Documentation/hwmon/hwmon-kernel-api.rst

   1 The Linux Hardware Monitoring kernel API
   2 ========================================
   3
   4 Guenter Roeck
   5
   6 Introduction
   7 ------------
   8
   9 This document describes the API that can be used by hardware monitoring
  10 drivers that want to use the hardware monitoring framework.
  11
  12 This document does not describe what a hardware monitoring (hwmon) Driver or
  13 Device is. It also does not describe the API which can be used by user space
  14 to communicate with a hardware monitoring device. If you want to know this
  15 then please read the following file: Documentation/hwmon/sysfs-interface.rst.
  16
  17 For additional guidelines on how to write and improve hwmon drivers, please
  18 also read Documentation/hwmon/submitting-patches.rst.
  19
  20 The API
  21 -------
  22 Each hardware monitoring driver must #include <linux/hwmon.h> and, in some
  23 cases, <linux/hwmon-sysfs.h>. linux/hwmon.h declares the following
  24 register/unregister functions::
  25
  26   struct device *
  27   hwmon_device_register_with_info(struct device *dev,
  28                                   const char *name, void *drvdata,
  29                                   const struct hwmon_chip_info *info,
  30                                   const struct attribute_group **extra_groups);
  31
  32   struct device *
  33   devm_hwmon_device_register_with_info(struct device *dev,
  34                                        const char *name,
  35                                        void *drvdata,
  36                                        const struct hwmon_chip_info *info,
  37                                        const struct attribute_group **extra_groups);
  38
  39   void hwmon_device_unregister(struct device *dev);
  40
  41   char *hwmon_sanitize_name(const char *name);
  42
  43   char *devm_hwmon_sanitize_name(struct device *dev, const char *name);
  44
  45 hwmon_device_register_with_info registers a hardware monitoring device.
  46 It creates the standard sysfs attributes in the hardware monitoring core,
  47 letting the driver focus on reading from and writing to the chip instead
  48 of having to bother with sysfs attributes. The parent device parameter
  49 as well as the chip parameter must not be NULL. Its parameters are described
  50 in more detail below.
  51
  52 devm_hwmon_device_register_with_info is similar to
  53 hwmon_device_register_with_info. However, it is device managed, meaning the
  54 hwmon device does not have to be removed explicitly by the removal function.
  55
  56 All other hardware monitoring device registration functions are deprecated
  57 and must not be used in new drivers.
  58
  59 hwmon_device_unregister deregisters a registered hardware monitoring device.
  60 The parameter of this function is the pointer to the registered hardware
  61 monitoring device structure. This function must be called from the driver
  62 remove function if the hardware monitoring device was registered with
  63 hwmon_device_register_with_info.
  64
  65 All supported hwmon device registration functions only accept valid device
  66 names. Device names including invalid characters (whitespace, '*', or '-')
  67 will be rejected. The 'name' parameter is mandatory.
  68
  69 If the driver doesn't use a static device name (for example it uses
  70 dev_name()), and therefore cannot make sure the name only contains valid
  71 characters, hwmon_sanitize_name can be used. This convenience function
  72 will duplicate the string and replace any invalid characters with an
  73 underscore. It will allocate memory for the new string and it is the
  74 responsibility of the caller to release the memory when the device is
  75 removed.
  76
  77 devm_hwmon_sanitize_name is the resource managed version of
  78 hwmon_sanitize_name; the memory will be freed automatically on device
  79 removal.
  80
  81 Using devm_hwmon_device_register_with_info()
  82 --------------------------------------------
  83
  84 hwmon_device_register_with_info() registers a hardware monitoring device.
  85 The parameters to this function are
  86
  87 =============================================== ===============================================
  88 `struct device *dev`                            Pointer to parent device
  89 `const char *name`                              Device name
  90 `void *drvdata`                                 Driver private data
  91 `const struct hwmon_chip_info *info`            Pointer to chip description.
  92 `const struct attribute_group **extra_groups`   Null-terminated list of additional non-standard
  93                                                 sysfs attribute groups.
  94 =============================================== ===============================================
  95
  96 This function returns a pointer to the created hardware monitoring device
  97 on success and a negative error code for failure.
  98
  99 The hwmon_chip_info structure looks as follows::
 100
 101         struct hwmon_chip_info {
 102                 const struct hwmon_ops *ops;
 103                 const struct hwmon_channel_info * const *info;
 104         };
 105
 106 It contains the following fields:
 107
 108 * ops:
 109         Pointer to device operations.
 110 * info:
 111         NULL-terminated list of device channel descriptors.
 112
 113 The list of hwmon operations is defined as::
 114
 115   struct hwmon_ops {
 116         umode_t (*is_visible)(const void *, enum hwmon_sensor_types type,
 117                               u32 attr, int);
 118         int (*read)(struct device *, enum hwmon_sensor_types type,
 119                     u32 attr, int, long *);
 120         int (*write)(struct device *, enum hwmon_sensor_types type,
 121                      u32 attr, int, long);
 122   };
 123
 124 It defines the following operations.
 125
 126 * is_visible:
 127     Pointer to a function to return the file mode for each supported
 128     attribute. This function is mandatory.
 129
 130 * read:
 131     Pointer to a function for reading a value from the chip. This function
 132     is optional, but must be provided if any readable attributes exist.
 133
 134 * write:
 135     Pointer to a function for writing a value to the chip. This function is
 136     optional, but must be provided if any writeable attributes exist.
 137
 138 Each sensor channel is described with struct hwmon_channel_info, which is
 139 defined as follows::
 140
 141         struct hwmon_channel_info {
 142                 enum hwmon_sensor_types type;
 143                 u32 *config;
 144         };
 145
 146 It contains following fields:
 147
 148 * type:
 149     The hardware monitoring sensor type.
 150
 151     Supported sensor types are
 152
 153      ================== ==================================================
 154      hwmon_chip         A virtual sensor type, used to describe attributes
 155                         which are not bound to a specific input or output
 156      hwmon_temp         Temperature sensor
 157      hwmon_in           Voltage sensor
 158      hwmon_curr         Current sensor
 159      hwmon_power                Power sensor
 160      hwmon_energy       Energy sensor
 161      hwmon_humidity     Humidity sensor
 162      hwmon_fan          Fan speed sensor
 163      hwmon_pwm          PWM control
 164      ================== ==================================================
 165
 166 * config:
 167     Pointer to a 0-terminated list of configuration values for each
 168     sensor of the given type. Each value is a combination of bit values
 169     describing the attributes supposed by a single sensor.
 170
 171 As an example, here is the complete description file for a LM75 compatible
 172 sensor chip. The chip has a single temperature sensor. The driver wants to
 173 register with the thermal subsystem (HWMON_C_REGISTER_TZ), and it supports
 174 the update_interval attribute (HWMON_C_UPDATE_INTERVAL). The chip supports
 175 reading the temperature (HWMON_T_INPUT), it has a maximum temperature
 176 register (HWMON_T_MAX) as well as a maximum temperature hysteresis register
 177 (HWMON_T_MAX_HYST)::
 178
 179         static const u32 lm75_chip_config[] = {
 180                 HWMON_C_REGISTER_TZ | HWMON_C_UPDATE_INTERVAL,
 181                 0
 182         };
 183
 184         static const struct hwmon_channel_info lm75_chip = {
 185                 .type = hwmon_chip,
 186                 .config = lm75_chip_config,
 187         };
 188
 189         static const u32 lm75_temp_config[] = {
 190                 HWMON_T_INPUT | HWMON_T_MAX | HWMON_T_MAX_HYST,
 191                 0
 192         };
 193
 194         static const struct hwmon_channel_info lm75_temp = {
 195                 .type = hwmon_temp,
 196                 .config = lm75_temp_config,
 197         };
 198
 199         static const struct hwmon_channel_info * const lm75_info[] = {
 200                 &lm75_chip,
 201                 &lm75_temp,
 202                 NULL
 203         };
 204
 205         The HWMON_CHANNEL_INFO() macro can and should be used when possible.
 206         With this macro, the above example can be simplified to
 207
 208         static const struct hwmon_channel_info * const lm75_info[] = {
 209                 HWMON_CHANNEL_INFO(chip,
 210                                 HWMON_C_REGISTER_TZ | HWMON_C_UPDATE_INTERVAL),
 211                 HWMON_CHANNEL_INFO(temp,
 212                                 HWMON_T_INPUT | HWMON_T_MAX | HWMON_T_MAX_HYST),
 213                 NULL
 214         };
 215
 216         The remaining declarations are as follows.
 217
 218         static const struct hwmon_ops lm75_hwmon_ops = {
 219                 .is_visible = lm75_is_visible,
 220                 .read = lm75_read,
 221                 .write = lm75_write,
 222         };
 223
 224         static const struct hwmon_chip_info lm75_chip_info = {
 225                 .ops = &lm75_hwmon_ops,
 226                 .info = lm75_info,
 227         };
 228
 229 A complete list of bit values indicating individual attribute support
 230 is defined in include/linux/hwmon.h. Definition prefixes are as follows.
 231
 232 =============== =================================================
 233 HWMON_C_xxxx    Chip attributes, for use with hwmon_chip.
 234 HWMON_T_xxxx    Temperature attributes, for use with hwmon_temp.
 235 HWMON_I_xxxx    Voltage attributes, for use with hwmon_in.
 236 HWMON_C_xxxx    Current attributes, for use with hwmon_curr.
 237                 Notice the prefix overlap with chip attributes.
 238 HWMON_P_xxxx    Power attributes, for use with hwmon_power.
 239 HWMON_E_xxxx    Energy attributes, for use with hwmon_energy.
 240 HWMON_H_xxxx    Humidity attributes, for use with hwmon_humidity.
 241 HWMON_F_xxxx    Fan speed attributes, for use with hwmon_fan.
 242 HWMON_PWM_xxxx  PWM control attributes, for use with hwmon_pwm.
 243 =============== =================================================
 244
 245 Driver callback functions
 246 -------------------------
 247
 248 Each driver provides is_visible, read, and write functions. Parameters
 249 and return values for those functions are as follows::
 250
 251   umode_t is_visible_func(const void *data, enum hwmon_sensor_types type,
 252                           u32 attr, int channel)
 253
 254 Parameters:
 255         data:
 256                 Pointer to device private data structure.
 257         type:
 258                 The sensor type.
 259         attr:
 260                 Attribute identifier associated with a specific attribute.
 261                 For example, the attribute value for HWMON_T_INPUT would be
 262                 hwmon_temp_input. For complete mappings of bit fields to
 263                 attribute values please see include/linux/hwmon.h.
 264         channel:
 265                 The sensor channel number.
 266
 267 Return value:
 268         The file mode for this attribute. Typically, this will be 0 (the
 269         attribute will not be created), 0444, or 0644.
 270
 271 ::
 272
 273         int read_func(struct device *dev, enum hwmon_sensor_types type,
 274                       u32 attr, int channel, long *val)
 275
 276 Parameters:
 277         dev:
 278                 Pointer to the hardware monitoring device.
 279         type:
 280                 The sensor type.
 281         attr:
 282                 Attribute identifier associated with a specific attribute.
 283                 For example, the attribute value for HWMON_T_INPUT would be
 284                 hwmon_temp_input. For complete mappings please see
 285                 include/linux/hwmon.h.
 286         channel:
 287                 The sensor channel number.
 288         val:
 289                 Pointer to attribute value.
 290
 291 Return value:
 292         0 on success, a negative error number otherwise.
 293
 294 ::
 295
 296         int write_func(struct device *dev, enum hwmon_sensor_types type,
 297                        u32 attr, int channel, long val)
 298
 299 Parameters:
 300         dev:
 301                 Pointer to the hardware monitoring device.
 302         type:
 303                 The sensor type.
 304         attr:
 305                 Attribute identifier associated with a specific attribute.
 306                 For example, the attribute value for HWMON_T_INPUT would be
 307                 hwmon_temp_input. For complete mappings please see
 308                 include/linux/hwmon.h.
 309         channel:
 310                 The sensor channel number.
 311         val:
 312                 The value to write to the chip.
 313
 314 Return value:
 315         0 on success, a negative error number otherwise.
 316
 317
 318 Driver-provided sysfs attributes
 319 --------------------------------
 320
 321 In most situations it should not be necessary for a driver to provide sysfs
 322 attributes since the hardware monitoring core creates those internally.
 323 Only additional non-standard sysfs attributes need to be provided.
 324
 325 The header file linux/hwmon-sysfs.h provides a number of useful macros to
 326 declare and use hardware monitoring sysfs attributes.
 327
 328 In many cases, you can use the existing define DEVICE_ATTR or its variants
 329 DEVICE_ATTR_{RW,RO,WO} to declare such attributes. This is feasible if an
 330 attribute has no additional context. However, in many cases there will be
 331 additional information such as a sensor index which will need to be passed
 332 to the sysfs attribute handling function.
 333
 334 SENSOR_DEVICE_ATTR and SENSOR_DEVICE_ATTR_2 can be used to define attributes
 335 which need such additional context information. SENSOR_DEVICE_ATTR requires
 336 one additional argument, SENSOR_DEVICE_ATTR_2 requires two.
 337
 338 Simplified variants of SENSOR_DEVICE_ATTR and SENSOR_DEVICE_ATTR_2 are available
 339 and should be used if standard attribute permissions and function names are
 340 feasible. Standard permissions are 0644 for SENSOR_DEVICE_ATTR[_2]_RW,
 341 0444 for SENSOR_DEVICE_ATTR[_2]_RO, and 0200 for SENSOR_DEVICE_ATTR[_2]_WO.
 342 Standard functions, similar to DEVICE_ATTR_{RW,RO,WO}, have _show and _store
 343 appended to the provided function name.
 344
 345 SENSOR_DEVICE_ATTR and its variants define a struct sensor_device_attribute
 346 variable. This structure has the following fields::
 347
 348         struct sensor_device_attribute {
 349                 struct device_attribute dev_attr;
 350                 int index;
 351         };
 352
 353 You can use to_sensor_dev_attr to get the pointer to this structure from the
 354 attribute read or write function. Its parameter is the device to which the
 355 attribute is attached.
 356
 357 SENSOR_DEVICE_ATTR_2 and its variants define a struct sensor_device_attribute_2
 358 variable, which is defined as follows::
 359
 360         struct sensor_device_attribute_2 {
 361                 struct device_attribute dev_attr;
 362                 u8 index;
 363                 u8 nr;
 364         };
 365
 366 Use to_sensor_dev_attr_2 to get the pointer to this structure. Its parameter
 367 is the device to which the attribute is attached.