About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / hwmon / hwmon-kernel-api.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog