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