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