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