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