123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107 |
- The Linux Hardware Monitoring kernel API.
- =========================================
- Guenter Roeck
- Introduction
- ------------
- This document describes the API that can be used by hardware monitoring
- drivers that want to use the hardware monitoring framework.
- This document does not describe what a hardware monitoring (hwmon) Driver or
- Device is. It also does not describe the API which can be used by user space
- to communicate with a hardware monitoring device. If you want to know this
- then please read the following file: Documentation/hwmon/sysfs-interface.
- For additional guidelines on how to write and improve hwmon drivers, please
- also read Documentation/hwmon/submitting-patches.
- The API
- -------
- Each hardware monitoring driver must #include <linux/hwmon.h> and, in most
- cases, <linux/hwmon-sysfs.h>. linux/hwmon.h declares the following
- register/unregister functions:
- struct device *hwmon_device_register(struct device *dev);
- struct device *
- hwmon_device_register_with_groups(struct device *dev, const char *name,
- void *drvdata,
- const struct attribute_group **groups);
- struct device *
- devm_hwmon_device_register_with_groups(struct device *dev,
- const char *name, void *drvdata,
- const struct attribute_group **groups);
- void hwmon_device_unregister(struct device *dev);
- void devm_hwmon_device_unregister(struct device *dev);
- hwmon_device_register registers a hardware monitoring device. The parameter
- of this function is a pointer to the parent device.
- This function returns a pointer to the newly created hardware monitoring device
- or PTR_ERR for failure. If this registration function is used, hardware
- monitoring sysfs attributes are expected to have been created and attached to
- the parent device prior to calling hwmon_device_register. A name attribute must
- have been created by the caller.
- hwmon_device_register_with_groups is similar to hwmon_device_register. However,
- it has additional parameters. The name parameter is a pointer to the hwmon
- device name. The registration function wil create a name sysfs attribute
- pointing to this name. The drvdata parameter is the pointer to the local
- driver data. hwmon_device_register_with_groups will attach this pointer
- to the newly allocated hwmon device. The pointer can be retrieved by the driver
- using dev_get_drvdata() on the hwmon device pointer. The groups parameter is
- a pointer to a list of sysfs attribute groups. The list must be NULL terminated.
- hwmon_device_register_with_groups creates the hwmon device with name attribute
- as well as all sysfs attributes attached to the hwmon device.
- devm_hwmon_device_register_with_groups is similar to
- hwmon_device_register_with_groups. However, it is device managed, meaning the
- hwmon device does not have to be removed explicitly by the removal function.
- hwmon_device_unregister deregisters a registered hardware monitoring device.
- The parameter of this function is the pointer to the registered hardware
- monitoring device structure. This function must be called from the driver
- remove function if the hardware monitoring device was registered with
- hwmon_device_register or with hwmon_device_register_with_groups.
- devm_hwmon_device_unregister does not normally have to be called. It is only
- needed for error handling, and only needed if the driver probe fails after
- the call to devm_hwmon_device_register_with_groups.
- The header file linux/hwmon-sysfs.h provides a number of useful macros to
- declare and use hardware monitoring sysfs attributes.
- In many cases, you can use the exsting define DEVICE_ATTR to declare such
- attributes. This is feasible if an attribute has no additional context. However,
- in many cases there will be additional information such as a sensor index which
- will need to be passed to the sysfs attribute handling function.
- SENSOR_DEVICE_ATTR and SENSOR_DEVICE_ATTR_2 can be used to define attributes
- which need such additional context information. SENSOR_DEVICE_ATTR requires
- one additional argument, SENSOR_DEVICE_ATTR_2 requires two.
- SENSOR_DEVICE_ATTR defines a struct sensor_device_attribute variable.
- This structure has the following fields.
- struct sensor_device_attribute {
- struct device_attribute dev_attr;
- int index;
- };
- You can use to_sensor_dev_attr to get the pointer to this structure from the
- attribute read or write function. Its parameter is the device to which the
- attribute is attached.
- SENSOR_DEVICE_ATTR_2 defines a struct sensor_device_attribute_2 variable,
- which is defined as follows.
- struct sensor_device_attribute_2 {
- struct device_attribute dev_attr;
- u8 index;
- u8 nr;
- };
- Use to_sensor_dev_attr_2 to get the pointer to this structure. Its parameter
- is the device to which the attribute is attached.
|