tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
hwmon: Document hwmon kernel API
The hwmon subsystem has been around for a while. Time to document
its kernel API.
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Guenter Roeck <linux@roeck-us.net>
+107
+107
Documentation/hwmon/hwmon-kernel-api.txt
+107
Documentation/hwmon/hwmon-kernel-api.txt
···
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.