linux/Documentation/hwmon/hwmon-kernel-api.txt
<<
>>
Prefs
   1The Linux Hardware Monitoring kernel API.
   2=========================================
   3
   4Guenter Roeck
   5
   6Introduction
   7------------
   8
   9This document describes the API that can be used by hardware monitoring
  10drivers that want to use the hardware monitoring framework.
  11
  12This document does not describe what a hardware monitoring (hwmon) Driver or
  13Device is. It also does not describe the API which can be used by user space
  14to communicate with a hardware monitoring device. If you want to know this
  15then please read the following file: Documentation/hwmon/sysfs-interface.
  16
  17For additional guidelines on how to write and improve hwmon drivers, please
  18also read Documentation/hwmon/submitting-patches.
  19
  20The API
  21-------
  22Each hardware monitoring driver must #include <linux/hwmon.h> and, in most
  23cases, <linux/hwmon-sysfs.h>. linux/hwmon.h declares the following
  24register/unregister functions:
  25
  26struct device *hwmon_device_register(struct device *dev);
  27struct device *
  28hwmon_device_register_with_groups(struct device *dev, const char *name,
  29                                  void *drvdata,
  30                                  const struct attribute_group **groups);
  31
  32struct device *
  33devm_hwmon_device_register_with_groups(struct device *dev,
  34                                       const char *name, void *drvdata,
  35                                       const struct attribute_group **groups);
  36
  37void hwmon_device_unregister(struct device *dev);
  38void devm_hwmon_device_unregister(struct device *dev);
  39
  40hwmon_device_register registers a hardware monitoring device. The parameter
  41of this function is a pointer to the parent device.
  42This function returns a pointer to the newly created hardware monitoring device
  43or PTR_ERR for failure. If this registration function is used, hardware
  44monitoring sysfs attributes are expected to have been created and attached to
  45the parent device prior to calling hwmon_device_register. A name attribute must
  46have been created by the caller.
  47
  48hwmon_device_register_with_groups is similar to hwmon_device_register. However,
  49it has additional parameters. The name parameter is a pointer to the hwmon
  50device name. The registration function wil create a name sysfs attribute
  51pointing to this name. The drvdata parameter is the pointer to the local
  52driver data.  hwmon_device_register_with_groups will attach this pointer
  53to the newly allocated hwmon device. The pointer can be retrieved by the driver
  54using dev_get_drvdata() on the hwmon device pointer. The groups parameter is
  55a pointer to a list of sysfs attribute groups. The list must be NULL terminated.
  56hwmon_device_register_with_groups creates the hwmon device with name attribute
  57as well as all sysfs attributes attached to the hwmon device.
  58
  59devm_hwmon_device_register_with_groups is similar to
  60hwmon_device_register_with_groups. However, it is device managed, meaning the
  61hwmon device does not have to be removed explicitly by the removal function.
  62
  63hwmon_device_unregister deregisters a registered hardware monitoring device.
  64The parameter of this function is the pointer to the registered hardware
  65monitoring device structure. This function must be called from the driver
  66remove function if the hardware monitoring device was registered with
  67hwmon_device_register or with hwmon_device_register_with_groups.
  68
  69devm_hwmon_device_unregister does not normally have to be called. It is only
  70needed for error handling, and only needed if the driver probe fails after
  71the call to devm_hwmon_device_register_with_groups.
  72
  73The header file linux/hwmon-sysfs.h provides a number of useful macros to
  74declare and use hardware monitoring sysfs attributes.
  75
  76In many cases, you can use the exsting define DEVICE_ATTR to declare such
  77attributes. This is feasible if an attribute has no additional context. However,
  78in many cases there will be additional information such as a sensor index which
  79will need to be passed to the sysfs attribute handling function.
  80
  81SENSOR_DEVICE_ATTR and SENSOR_DEVICE_ATTR_2 can be used to define attributes
  82which need such additional context information. SENSOR_DEVICE_ATTR requires
  83one additional argument, SENSOR_DEVICE_ATTR_2 requires two.
  84
  85SENSOR_DEVICE_ATTR defines a struct sensor_device_attribute variable.
  86This structure has the following fields.
  87
  88struct sensor_device_attribute {
  89        struct device_attribute dev_attr;
  90        int index;
  91};
  92
  93You can use to_sensor_dev_attr to get the pointer to this structure from the
  94attribute read or write function. Its parameter is the device to which the
  95attribute is attached.
  96
  97SENSOR_DEVICE_ATTR_2 defines a struct sensor_device_attribute_2 variable,
  98which is defined as follows.
  99
 100struct sensor_device_attribute_2 {
 101        struct device_attribute dev_attr;
 102        u8 index;
 103        u8 nr;
 104};
 105
 106Use to_sensor_dev_attr_2 to get the pointer to this structure. Its parameter
 107is the device to which the attribute is attached.
 108