| hwmon-kernel-api.rst (629f57a7d5b9533313f41c79f8ae52c953b261f6) | hwmon-kernel-api.rst (aededf875a233b2b890af0000aa1b8f17b5351a0) |
|---|---|
| 1The Linux Hardware Monitoring kernel API 2======================================== 3 4Guenter Roeck 5 6Introduction 7------------ 8 --- 5 unchanged lines hidden (view full) --- 14to communicate with a hardware monitoring device. If you want to know this 15then please read the following file: Documentation/hwmon/sysfs-interface.rst. 16 17For additional guidelines on how to write and improve hwmon drivers, please 18also read Documentation/hwmon/submitting-patches.rst. 19 20The API 21------- | 1The Linux Hardware Monitoring kernel API 2======================================== 3 4Guenter Roeck 5 6Introduction 7------------ 8 --- 5 unchanged lines hidden (view full) --- 14to communicate with a hardware monitoring device. If you want to know this 15then please read the following file: Documentation/hwmon/sysfs-interface.rst. 16 17For additional guidelines on how to write and improve hwmon drivers, please 18also read Documentation/hwmon/submitting-patches.rst. 19 20The API 21------- |
| 22Each hardware monitoring driver must #include <linux/hwmon.h> and, in most | 22Each hardware monitoring driver must #include <linux/hwmon.h> and, in some |
| 23cases, <linux/hwmon-sysfs.h>. linux/hwmon.h declares the following 24register/unregister functions:: 25 26 struct device * | 23cases, <linux/hwmon-sysfs.h>. linux/hwmon.h declares the following 24register/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, --- 4 unchanged lines hidden (view full) --- 49 void hwmon_device_unregister(struct device *dev); 50 51 void devm_hwmon_device_unregister(struct device *dev); 52 53 char *hwmon_sanitize_name(const char *name); 54 55 char *devm_hwmon_sanitize_name(struct device *dev, const char *name); 56 | 27 hwmon_device_register_with_info(struct device *dev, 28 const char *name, void *drvdata, 29 const struct hwmon_chip_info *info, 30 const struct attribute_group **extra_groups); 31 32 struct device * 33 devm_hwmon_device_register_with_info(struct device *dev, 34 const char *name, --- 4 unchanged lines hidden (view full) --- 39 void hwmon_device_unregister(struct device *dev); 40 41 void devm_hwmon_device_unregister(struct device *dev); 42 43 char *hwmon_sanitize_name(const char *name); 44 45 char *devm_hwmon_sanitize_name(struct device *dev, const char *name); 46 |
| 57hwmon_device_register_with_groups registers a hardware monitoring device. 58The first parameter of this function is a pointer to the parent device. 59The name parameter is a pointer to the hwmon device name. The registration 60function will create a name sysfs attribute pointing to this name. 61The drvdata parameter is the pointer to the local driver data. 62hwmon_device_register_with_groups will attach this pointer to the newly 63allocated hwmon device. The pointer can be retrieved by the driver using 64dev_get_drvdata() on the hwmon device pointer. The groups parameter is 65a pointer to a list of sysfs attribute groups. The list must be NULL terminated. 66hwmon_device_register_with_groups creates the hwmon device with name attribute 67as well as all sysfs attributes attached to the hwmon device. 68This function returns a pointer to the newly created hardware monitoring device 69or PTR_ERR for failure. | 47hwmon_device_register_with_info registers a hardware monitoring device. 48It creates the standard sysfs attributes in the hardware monitoring core, 49letting the driver focus on reading from and writing to the chip instead 50of having to bother with sysfs attributes. The parent device parameter 51as well as the chip parameter must not be NULL. Its parameters are described 52in more detail below. |
| 70 | 53 |
| 71devm_hwmon_device_register_with_groups is similar to 72hwmon_device_register_with_groups. However, it is device managed, meaning the 73hwmon device does not have to be removed explicitly by the removal function. 74 75hwmon_device_register_with_info is the most comprehensive and preferred means 76to register a hardware monitoring device. It creates the standard sysfs 77attributes in the hardware monitoring core, letting the driver focus on reading 78from and writing to the chip instead of having to bother with sysfs attributes. 79The parent device parameter as well as the chip parameter must not be NULL. Its 80parameters are described in more detail below. 81 | |
| 82devm_hwmon_device_register_with_info is similar to 83hwmon_device_register_with_info. However, it is device managed, meaning the 84hwmon device does not have to be removed explicitly by the removal function. 85 | 54devm_hwmon_device_register_with_info is similar to 55hwmon_device_register_with_info. However, it is device managed, meaning the 56hwmon device does not have to be removed explicitly by the removal function. 57 |
| 58All other hardware monitoring device registration functions are deprecated 59and must not be used in new drivers. 60 |
|
| 86hwmon_device_unregister deregisters a registered hardware monitoring device. 87The parameter of this function is the pointer to the registered hardware 88monitoring device structure. This function must be called from the driver 89remove function if the hardware monitoring device was registered with | 61hwmon_device_unregister deregisters a registered hardware monitoring device. 62The parameter of this function is the pointer to the registered hardware 63monitoring device structure. This function must be called from the driver 64remove function if the hardware monitoring device was registered with |
| 90hwmon_device_register_with_groups or hwmon_device_register_with_info. | 65hwmon_device_register_with_info. |
| 91 92devm_hwmon_device_unregister does not normally have to be called. It is only 93needed for error handling, and only needed if the driver probe fails after | 66 67devm_hwmon_device_unregister does not normally have to be called. It is only 68needed for error handling, and only needed if the driver probe fails after |
| 94the call to devm_hwmon_device_register_with_groups or 95hwmon_device_register_with_info and if the automatic (device managed) 96removal would be too late. | 69the call to hwmon_device_register_with_info and if the automatic (device 70managed) removal would be too late. |
| 97 98All supported hwmon device registration functions only accept valid device 99names. Device names including invalid characters (whitespace, '*', or '-') 100will be rejected. The 'name' parameter is mandatory. 101 102If the driver doesn't use a static device name (for example it uses 103dev_name()), and therefore cannot make sure the name only contains valid 104characters, hwmon_sanitize_name can be used. This convenience function --- 241 unchanged lines hidden (view full) --- 346 347Return value: 348 0 on success, a negative error number otherwise. 349 350 351Driver-provided sysfs attributes 352-------------------------------- 353 | 71 72All supported hwmon device registration functions only accept valid device 73names. Device names including invalid characters (whitespace, '*', or '-') 74will be rejected. The 'name' parameter is mandatory. 75 76If the driver doesn't use a static device name (for example it uses 77dev_name()), and therefore cannot make sure the name only contains valid 78characters, hwmon_sanitize_name can be used. This convenience function --- 241 unchanged lines hidden (view full) --- 320 321Return value: 322 0 on success, a negative error number otherwise. 323 324 325Driver-provided sysfs attributes 326-------------------------------- 327 |
| 354If the hardware monitoring device is registered with 355hwmon_device_register_with_info or devm_hwmon_device_register_with_info, 356it is most likely not necessary to provide sysfs attributes. Only additional 357non-standard sysfs attributes need to be provided when one of those registration 358functions is used. | 328In most situations it should not be necessary for a driver to provide sysfs 329attributes since the hardware monitoring core creates those internally. 330Only additional non-standard sysfs attributes need to be provided. |
| 359 360The header file linux/hwmon-sysfs.h provides a number of useful macros to 361declare and use hardware monitoring sysfs attributes. 362 363In many cases, you can use the existing define DEVICE_ATTR or its variants 364DEVICE_ATTR_{RW,RO,WO} to declare such attributes. This is feasible if an 365attribute has no additional context. However, in many cases there will be 366additional information such as a sensor index which will need to be passed --- 36 unchanged lines hidden --- | 331 332The header file linux/hwmon-sysfs.h provides a number of useful macros to 333declare and use hardware monitoring sysfs attributes. 334 335In many cases, you can use the existing define DEVICE_ATTR or its variants 336DEVICE_ATTR_{RW,RO,WO} to declare such attributes. This is feasible if an 337attribute has no additional context. However, in many cases there will be 338additional information such as a sensor index which will need to be passed --- 36 unchanged lines hidden --- |