]>
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 | ||
a9622663 GR |
26 | struct device * |
27 | hwmon_device_register_with_groups(struct device *dev, const char *name, | |
28 | void *drvdata, | |
29 | const struct attribute_group **groups); | |
30 | ||
31 | struct device * | |
32 | devm_hwmon_device_register_with_groups(struct device *dev, | |
33 | const char *name, void *drvdata, | |
34 | const struct attribute_group **groups); | |
35 | ||
bf7153fd GR |
36 | struct device * |
37 | hwmon_device_register_with_info(struct device *dev, | |
38 | const char *name, void *drvdata, | |
39 | const struct hwmon_chip_info *info, | |
848ba0a2 | 40 | const struct attribute_group **extra_groups); |
bf7153fd GR |
41 | |
42 | struct device * | |
43 | devm_hwmon_device_register_with_info(struct device *dev, | |
848ba0a2 GR |
44 | const char *name, |
45 | void *drvdata, | |
46 | const struct hwmon_chip_info *info, | |
47 | const struct attribute_group **extra_groups); | |
bf7153fd | 48 | |
a9622663 GR |
49 | void hwmon_device_unregister(struct device *dev); |
50 | void devm_hwmon_device_unregister(struct device *dev); | |
51 | ||
af1bd36c GR |
52 | hwmon_device_register_with_groups registers a hardware monitoring device. |
53 | The first parameter of this function is a pointer to the parent device. | |
54 | The name parameter is a pointer to the hwmon device name. The registration | |
55 | function wil create a name sysfs attribute pointing to this name. | |
56 | The drvdata parameter is the pointer to the local driver data. | |
57 | hwmon_device_register_with_groups will attach this pointer to the newly | |
58 | allocated hwmon device. The pointer can be retrieved by the driver using | |
59 | dev_get_drvdata() on the hwmon device pointer. The groups parameter is | |
a9622663 GR |
60 | a pointer to a list of sysfs attribute groups. The list must be NULL terminated. |
61 | hwmon_device_register_with_groups creates the hwmon device with name attribute | |
62 | as well as all sysfs attributes attached to the hwmon device. | |
af1bd36c GR |
63 | This function returns a pointer to the newly created hardware monitoring device |
64 | or PTR_ERR for failure. | |
a9622663 GR |
65 | |
66 | devm_hwmon_device_register_with_groups is similar to | |
67 | hwmon_device_register_with_groups. However, it is device managed, meaning the | |
68 | hwmon device does not have to be removed explicitly by the removal function. | |
69 | ||
bf7153fd GR |
70 | hwmon_device_register_with_info is the most comprehensive and preferred means |
71 | to register a hardware monitoring device. It creates the standard sysfs | |
72 | attributes in the hardware monitoring core, letting the driver focus on reading | |
73 | from and writing to the chip instead of having to bother with sysfs attributes. | |
74 | Its parameters are described in more detail below. | |
75 | ||
76 | devm_hwmon_device_register_with_info is similar to | |
77 | hwmon_device_register_with_info. However, it is device managed, meaning the | |
78 | hwmon device does not have to be removed explicitly by the removal function. | |
79 | ||
a9622663 GR |
80 | hwmon_device_unregister deregisters a registered hardware monitoring device. |
81 | The parameter of this function is the pointer to the registered hardware | |
82 | monitoring device structure. This function must be called from the driver | |
83 | remove function if the hardware monitoring device was registered with | |
af1bd36c | 84 | hwmon_device_register_with_groups or hwmon_device_register_with_info. |
a9622663 GR |
85 | |
86 | devm_hwmon_device_unregister does not normally have to be called. It is only | |
87 | needed for error handling, and only needed if the driver probe fails after | |
af1bd36c GR |
88 | the call to devm_hwmon_device_register_with_groups or |
89 | hwmon_device_register_with_info and if the automatic (device managed) | |
90 | removal would be too late. | |
bf7153fd GR |
91 | |
92 | Using devm_hwmon_device_register_with_info() | |
93 | -------------------------------------------- | |
94 | ||
95 | hwmon_device_register_with_info() registers a hardware monitoring device. | |
96 | The parameters to this function are | |
97 | ||
98 | struct device *dev Pointer to parent device | |
99 | const char *name Device name | |
100 | void *drvdata Driver private data | |
101 | const struct hwmon_chip_info *info | |
102 | Pointer to chip description. | |
848ba0a2 GR |
103 | const struct attribute_group **extra_groups |
104 | Null-terminated list of additional non-standard | |
105 | sysfs attribute groups. | |
bf7153fd GR |
106 | |
107 | This function returns a pointer to the created hardware monitoring device | |
108 | on success and a negative error code for failure. | |
109 | ||
110 | The hwmon_chip_info structure looks as follows. | |
111 | ||
112 | struct hwmon_chip_info { | |
113 | const struct hwmon_ops *ops; | |
114 | const struct hwmon_channel_info **info; | |
115 | }; | |
116 | ||
117 | It contains the following fields: | |
118 | ||
119 | * ops: Pointer to device operations. | |
120 | * info: NULL-terminated list of device channel descriptors. | |
121 | ||
122 | The list of hwmon operations is defined as: | |
123 | ||
124 | struct hwmon_ops { | |
125 | umode_t (*is_visible)(const void *, enum hwmon_sensor_types type, | |
126 | u32 attr, int); | |
127 | int (*read)(struct device *, enum hwmon_sensor_types type, | |
128 | u32 attr, int, long *); | |
129 | int (*write)(struct device *, enum hwmon_sensor_types type, | |
130 | u32 attr, int, long); | |
131 | }; | |
132 | ||
133 | It defines the following operations. | |
134 | ||
135 | * is_visible: Pointer to a function to return the file mode for each supported | |
136 | attribute. This function is mandatory. | |
137 | ||
138 | * read: Pointer to a function for reading a value from the chip. This function | |
139 | is optional, but must be provided if any readable attributes exist. | |
140 | ||
141 | * write: Pointer to a function for writing a value to the chip. This function is | |
142 | optional, but must be provided if any writeable attributes exist. | |
143 | ||
144 | Each sensor channel is described with struct hwmon_channel_info, which is | |
145 | defined as follows. | |
146 | ||
147 | struct hwmon_channel_info { | |
148 | enum hwmon_sensor_types type; | |
149 | u32 *config; | |
150 | }; | |
151 | ||
152 | It contains following fields: | |
153 | ||
154 | * type: The hardware monitoring sensor type. | |
155 | Supported sensor types are | |
156 | * hwmon_chip A virtual sensor type, used to describe attributes | |
f4d325d5 | 157 | * which are not bound to a specific input or output |
bf7153fd GR |
158 | * hwmon_temp Temperature sensor |
159 | * hwmon_in Voltage sensor | |
160 | * hwmon_curr Current sensor | |
161 | * hwmon_power Power sensor | |
162 | * hwmon_energy Energy sensor | |
163 | * hwmon_humidity Humidity sensor | |
164 | * hwmon_fan Fan speed sensor | |
f9f7bb3a | 165 | * hwmon_pwm PWM control |
bf7153fd GR |
166 | |
167 | * config: 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 *lm75_info[] = { | |
200 | &lm75_chip, | |
201 | &lm75_temp, | |
202 | NULL | |
203 | }; | |
204 | ||
205 | static const struct hwmon_ops lm75_hwmon_ops = { | |
206 | .is_visible = lm75_is_visible, | |
207 | .read = lm75_read, | |
208 | .write = lm75_write, | |
209 | }; | |
210 | ||
211 | static const struct hwmon_chip_info lm75_chip_info = { | |
212 | .ops = &lm75_hwmon_ops, | |
213 | .info = lm75_info, | |
214 | }; | |
215 | ||
216 | A complete list of bit values indicating individual attribute support | |
217 | is defined in include/linux/hwmon.h. Definition prefixes are as follows. | |
218 | ||
219 | HWMON_C_xxxx Chip attributes, for use with hwmon_chip. | |
220 | HWMON_T_xxxx Temperature attributes, for use with hwmon_temp. | |
221 | HWMON_I_xxxx Voltage attributes, for use with hwmon_in. | |
222 | HWMON_C_xxxx Current attributes, for use with hwmon_curr. | |
223 | Notice the prefix overlap with chip attributes. | |
224 | HWMON_P_xxxx Power attributes, for use with hwmon_power. | |
225 | HWMON_E_xxxx Energy attributes, for use with hwmon_energy. | |
226 | HWMON_H_xxxx Humidity attributes, for use with hwmon_humidity. | |
227 | HWMON_F_xxxx Fan speed attributes, for use with hwmon_fan. | |
f9f7bb3a | 228 | HWMON_PWM_xxxx PWM control attributes, for use with hwmon_pwm. |
bf7153fd GR |
229 | |
230 | Driver callback functions | |
231 | ------------------------- | |
232 | ||
233 | Each driver provides is_visible, read, and write functions. Parameters | |
234 | and return values for those functions are as follows. | |
235 | ||
236 | umode_t is_visible_func(const void *data, enum hwmon_sensor_types type, | |
237 | u32 attr, int channel) | |
238 | ||
239 | Parameters: | |
240 | data: Pointer to device private data structure. | |
241 | type: The sensor type. | |
242 | attr: Attribute identifier associated with a specific attribute. | |
243 | For example, the attribute value for HWMON_T_INPUT would be | |
244 | hwmon_temp_input. For complete mappings of bit fields to | |
245 | attribute values please see include/linux/hwmon.h. | |
246 | channel:The sensor channel number. | |
247 | ||
248 | Return value: | |
249 | The file mode for this attribute. Typically, this will be 0 (the | |
250 | attribute will not be created), S_IRUGO, or 'S_IRUGO | S_IWUSR'. | |
251 | ||
252 | int read_func(struct device *dev, enum hwmon_sensor_types type, | |
253 | u32 attr, int channel, long *val) | |
254 | ||
255 | Parameters: | |
256 | dev: Pointer to the hardware monitoring device. | |
257 | type: The sensor type. | |
258 | attr: Attribute identifier associated with a specific attribute. | |
259 | For example, the attribute value for HWMON_T_INPUT would be | |
260 | hwmon_temp_input. For complete mappings please see | |
261 | include/linux/hwmon.h. | |
262 | channel:The sensor channel number. | |
263 | val: Pointer to attribute value. | |
264 | ||
265 | Return value: | |
266 | 0 on success, a negative error number otherwise. | |
267 | ||
268 | int write_func(struct device *dev, enum hwmon_sensor_types type, | |
269 | u32 attr, int channel, long val) | |
270 | ||
271 | Parameters: | |
272 | dev: Pointer to the hardware monitoring device. | |
273 | type: The sensor type. | |
274 | attr: Attribute identifier associated with a specific attribute. | |
275 | For example, the attribute value for HWMON_T_INPUT would be | |
276 | hwmon_temp_input. For complete mappings please see | |
277 | include/linux/hwmon.h. | |
278 | channel:The sensor channel number. | |
279 | val: The value to write to the chip. | |
280 | ||
281 | Return value: | |
282 | 0 on success, a negative error number otherwise. | |
283 | ||
284 | ||
285 | Driver-provided sysfs attributes | |
286 | -------------------------------- | |
287 | ||
288 | If the hardware monitoring device is registered with | |
289 | hwmon_device_register_with_info or devm_hwmon_device_register_with_info, | |
848ba0a2 GR |
290 | it is most likely not necessary to provide sysfs attributes. Only additional |
291 | non-standard sysfs attributes need to be provided when one of those registration | |
292 | functions is used. | |
a9622663 GR |
293 | |
294 | The header file linux/hwmon-sysfs.h provides a number of useful macros to | |
295 | declare and use hardware monitoring sysfs attributes. | |
296 | ||
297 | In many cases, you can use the exsting define DEVICE_ATTR to declare such | |
298 | attributes. This is feasible if an attribute has no additional context. However, | |
299 | in many cases there will be additional information such as a sensor index which | |
300 | will need to be passed to the sysfs attribute handling function. | |
301 | ||
302 | SENSOR_DEVICE_ATTR and SENSOR_DEVICE_ATTR_2 can be used to define attributes | |
303 | which need such additional context information. SENSOR_DEVICE_ATTR requires | |
304 | one additional argument, SENSOR_DEVICE_ATTR_2 requires two. | |
305 | ||
306 | SENSOR_DEVICE_ATTR defines a struct sensor_device_attribute variable. | |
307 | This structure has the following fields. | |
308 | ||
309 | struct sensor_device_attribute { | |
310 | struct device_attribute dev_attr; | |
311 | int index; | |
312 | }; | |
313 | ||
314 | You can use to_sensor_dev_attr to get the pointer to this structure from the | |
315 | attribute read or write function. Its parameter is the device to which the | |
316 | attribute is attached. | |
317 | ||
318 | SENSOR_DEVICE_ATTR_2 defines a struct sensor_device_attribute_2 variable, | |
319 | which is defined as follows. | |
320 | ||
321 | struct sensor_device_attribute_2 { | |
322 | struct device_attribute dev_attr; | |
323 | u8 index; | |
324 | u8 nr; | |
325 | }; | |
326 | ||
327 | Use to_sensor_dev_attr_2 to get the pointer to this structure. Its parameter | |
328 | is the device to which the attribute is attached. |