^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) The Linux Hardware Monitoring kernel API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) ========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) Guenter Roeck
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) This document describes the API that can be used by hardware monitoring
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) drivers that want to use the hardware monitoring framework.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) This document does not describe what a hardware monitoring (hwmon) Driver or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) Device is. It also does not describe the API which can be used by user space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) to communicate with a hardware monitoring device. If you want to know this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) then please read the following file: Documentation/hwmon/sysfs-interface.rst.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) For additional guidelines on how to write and improve hwmon drivers, please
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) also read Documentation/hwmon/submitting-patches.rst.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) The API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) Each hardware monitoring driver must #include <linux/hwmon.h> and, in most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) cases, <linux/hwmon-sysfs.h>. linux/hwmon.h declares the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) register/unregister functions::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) struct device *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) hwmon_device_register_with_groups(struct device *dev, const char *name,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) void *drvdata,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) const struct attribute_group **groups);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) struct device *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) devm_hwmon_device_register_with_groups(struct device *dev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) const char *name, void *drvdata,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) const struct attribute_group **groups);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) struct device *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) hwmon_device_register_with_info(struct device *dev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) const char *name, void *drvdata,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) const struct hwmon_chip_info *info,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) const struct attribute_group **extra_groups);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) struct device *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) devm_hwmon_device_register_with_info(struct device *dev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) const char *name,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) void *drvdata,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) const struct hwmon_chip_info *info,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) const struct attribute_group **extra_groups);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) void hwmon_device_unregister(struct device *dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) void devm_hwmon_device_unregister(struct device *dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) hwmon_device_register_with_groups registers a hardware monitoring device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) The first parameter of this function is a pointer to the parent device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) The name parameter is a pointer to the hwmon device name. The registration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) function wil create a name sysfs attribute pointing to this name.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) The drvdata parameter is the pointer to the local driver data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) hwmon_device_register_with_groups will attach this pointer to the newly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) allocated hwmon device. The pointer can be retrieved by the driver using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) dev_get_drvdata() on the hwmon device pointer. The groups parameter is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) a pointer to a list of sysfs attribute groups. The list must be NULL terminated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) hwmon_device_register_with_groups creates the hwmon device with name attribute
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) as well as all sysfs attributes attached to the hwmon device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) This function returns a pointer to the newly created hardware monitoring device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) or PTR_ERR for failure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) devm_hwmon_device_register_with_groups is similar to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) hwmon_device_register_with_groups. However, it is device managed, meaning the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) hwmon device does not have to be removed explicitly by the removal function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) hwmon_device_register_with_info is the most comprehensive and preferred means
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) to register a hardware monitoring device. It creates the standard sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) attributes in the hardware monitoring core, letting the driver focus on reading
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) from and writing to the chip instead of having to bother with sysfs attributes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) The parent device parameter cannot be NULL with non-NULL chip info. Its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) parameters are described in more detail below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) devm_hwmon_device_register_with_info is similar to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) hwmon_device_register_with_info. However, it is device managed, meaning the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) hwmon device does not have to be removed explicitly by the removal function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) hwmon_device_unregister deregisters a registered hardware monitoring device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) The parameter of this function is the pointer to the registered hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) monitoring device structure. This function must be called from the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) remove function if the hardware monitoring device was registered with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) hwmon_device_register_with_groups or hwmon_device_register_with_info.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) devm_hwmon_device_unregister does not normally have to be called. It is only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) needed for error handling, and only needed if the driver probe fails after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) the call to devm_hwmon_device_register_with_groups or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) hwmon_device_register_with_info and if the automatic (device managed)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) removal would be too late.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) All supported hwmon device registration functions only accept valid device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) names. Device names including invalid characters (whitespace, '*', or '-')
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) will be rejected. The 'name' parameter is mandatory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) Using devm_hwmon_device_register_with_info()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) --------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) hwmon_device_register_with_info() registers a hardware monitoring device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) The parameters to this function are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) =============================================== ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) `struct device *dev` Pointer to parent device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) `const char *name` Device name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) `void *drvdata` Driver private data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) `const struct hwmon_chip_info *info` Pointer to chip description.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) `const struct attribute_group **extra_groups` Null-terminated list of additional non-standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) sysfs attribute groups.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) =============================================== ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) This function returns a pointer to the created hardware monitoring device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) on success and a negative error code for failure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) The hwmon_chip_info structure looks as follows::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) struct hwmon_chip_info {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) const struct hwmon_ops *ops;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) const struct hwmon_channel_info **info;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) It contains the following fields:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) * ops:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) Pointer to device operations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) * info:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) NULL-terminated list of device channel descriptors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) The list of hwmon operations is defined as::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) struct hwmon_ops {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) umode_t (*is_visible)(const void *, enum hwmon_sensor_types type,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) u32 attr, int);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) int (*read)(struct device *, enum hwmon_sensor_types type,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) u32 attr, int, long *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) int (*write)(struct device *, enum hwmon_sensor_types type,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) u32 attr, int, long);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) It defines the following operations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) * is_visible:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) Pointer to a function to return the file mode for each supported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) attribute. This function is mandatory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) * read:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) Pointer to a function for reading a value from the chip. This function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) is optional, but must be provided if any readable attributes exist.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) * write:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) Pointer to a function for writing a value to the chip. This function is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) optional, but must be provided if any writeable attributes exist.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) Each sensor channel is described with struct hwmon_channel_info, which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) defined as follows::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) struct hwmon_channel_info {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) enum hwmon_sensor_types type;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) u32 *config;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) It contains following fields:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) * type:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) The hardware monitoring sensor type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) Supported sensor types are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) ================== ==================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) hwmon_chip A virtual sensor type, used to describe attributes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) which are not bound to a specific input or output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) hwmon_temp Temperature sensor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) hwmon_in Voltage sensor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) hwmon_curr Current sensor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) hwmon_power Power sensor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) hwmon_energy Energy sensor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) hwmon_humidity Humidity sensor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) hwmon_fan Fan speed sensor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) hwmon_pwm PWM control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) ================== ==================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) * config:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) Pointer to a 0-terminated list of configuration values for each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) sensor of the given type. Each value is a combination of bit values
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) describing the attributes supposed by a single sensor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) As an example, here is the complete description file for a LM75 compatible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) sensor chip. The chip has a single temperature sensor. The driver wants to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) register with the thermal subsystem (HWMON_C_REGISTER_TZ), and it supports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) the update_interval attribute (HWMON_C_UPDATE_INTERVAL). The chip supports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) reading the temperature (HWMON_T_INPUT), it has a maximum temperature
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) register (HWMON_T_MAX) as well as a maximum temperature hysteresis register
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) (HWMON_T_MAX_HYST)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) static const u32 lm75_chip_config[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) HWMON_C_REGISTER_TZ | HWMON_C_UPDATE_INTERVAL,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) static const struct hwmon_channel_info lm75_chip = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) .type = hwmon_chip,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) .config = lm75_chip_config,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) static const u32 lm75_temp_config[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) HWMON_T_INPUT | HWMON_T_MAX | HWMON_T_MAX_HYST,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) static const struct hwmon_channel_info lm75_temp = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) .type = hwmon_temp,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) .config = lm75_temp_config,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) static const struct hwmon_channel_info *lm75_info[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) &lm75_chip,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) &lm75_temp,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) NULL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) The HWMON_CHANNEL_INFO() macro can and should be used when possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) With this macro, the above example can be simplified to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) static const struct hwmon_channel_info *lm75_info[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) HWMON_CHANNEL_INFO(chip,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) HWMON_C_REGISTER_TZ | HWMON_C_UPDATE_INTERVAL),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) HWMON_CHANNEL_INFO(temp,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) HWMON_T_INPUT | HWMON_T_MAX | HWMON_T_MAX_HYST),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) NULL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) The remaining declarations are as follows.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) static const struct hwmon_ops lm75_hwmon_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) .is_visible = lm75_is_visible,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) .read = lm75_read,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) .write = lm75_write,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) static const struct hwmon_chip_info lm75_chip_info = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) .ops = &lm75_hwmon_ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) .info = lm75_info,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) A complete list of bit values indicating individual attribute support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) is defined in include/linux/hwmon.h. Definition prefixes are as follows.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) =============== =================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) HWMON_C_xxxx Chip attributes, for use with hwmon_chip.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) HWMON_T_xxxx Temperature attributes, for use with hwmon_temp.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) HWMON_I_xxxx Voltage attributes, for use with hwmon_in.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) HWMON_C_xxxx Current attributes, for use with hwmon_curr.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) Notice the prefix overlap with chip attributes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) HWMON_P_xxxx Power attributes, for use with hwmon_power.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) HWMON_E_xxxx Energy attributes, for use with hwmon_energy.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) HWMON_H_xxxx Humidity attributes, for use with hwmon_humidity.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) HWMON_F_xxxx Fan speed attributes, for use with hwmon_fan.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) HWMON_PWM_xxxx PWM control attributes, for use with hwmon_pwm.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) =============== =================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) Driver callback functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) Each driver provides is_visible, read, and write functions. Parameters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) and return values for those functions are as follows::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) umode_t is_visible_func(const void *data, enum hwmon_sensor_types type,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) u32 attr, int channel)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) Parameters:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) data:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) Pointer to device private data structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) type:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) The sensor type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) attr:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) Attribute identifier associated with a specific attribute.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) For example, the attribute value for HWMON_T_INPUT would be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) hwmon_temp_input. For complete mappings of bit fields to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) attribute values please see include/linux/hwmon.h.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) channel:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) The sensor channel number.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) Return value:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) The file mode for this attribute. Typically, this will be 0 (the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) attribute will not be created), S_IRUGO, or 'S_IRUGO | S_IWUSR'.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) int read_func(struct device *dev, enum hwmon_sensor_types type,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) u32 attr, int channel, long *val)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) Parameters:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) dev:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) Pointer to the hardware monitoring device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) type:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) The sensor type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) attr:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) Attribute identifier associated with a specific attribute.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) For example, the attribute value for HWMON_T_INPUT would be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) hwmon_temp_input. For complete mappings please see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) include/linux/hwmon.h.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) channel:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) The sensor channel number.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) val:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) Pointer to attribute value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) Return value:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) 0 on success, a negative error number otherwise.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) int write_func(struct device *dev, enum hwmon_sensor_types type,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) u32 attr, int channel, long val)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) Parameters:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) dev:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) Pointer to the hardware monitoring device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) type:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) The sensor type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) attr:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) Attribute identifier associated with a specific attribute.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) For example, the attribute value for HWMON_T_INPUT would be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) hwmon_temp_input. For complete mappings please see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) include/linux/hwmon.h.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) channel:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) The sensor channel number.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) val:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) The value to write to the chip.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) Return value:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) 0 on success, a negative error number otherwise.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) Driver-provided sysfs attributes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) If the hardware monitoring device is registered with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) hwmon_device_register_with_info or devm_hwmon_device_register_with_info,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) it is most likely not necessary to provide sysfs attributes. Only additional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) non-standard sysfs attributes need to be provided when one of those registration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) functions is used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) The header file linux/hwmon-sysfs.h provides a number of useful macros to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) declare and use hardware monitoring sysfs attributes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) In many cases, you can use the exsting define DEVICE_ATTR or its variants
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) DEVICE_ATTR_{RW,RO,WO} to declare such attributes. This is feasible if an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) attribute has no additional context. However, in many cases there will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) additional information such as a sensor index which will need to be passed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) to the sysfs attribute handling function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) SENSOR_DEVICE_ATTR and SENSOR_DEVICE_ATTR_2 can be used to define attributes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) which need such additional context information. SENSOR_DEVICE_ATTR requires
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) one additional argument, SENSOR_DEVICE_ATTR_2 requires two.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) Simplified variants of SENSOR_DEVICE_ATTR and SENSOR_DEVICE_ATTR_2 are available
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) and should be used if standard attribute permissions and function names are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) feasible. Standard permissions are 0644 for SENSOR_DEVICE_ATTR[_2]_RW,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) 0444 for SENSOR_DEVICE_ATTR[_2]_RO, and 0200 for SENSOR_DEVICE_ATTR[_2]_WO.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) Standard functions, similar to DEVICE_ATTR_{RW,RO,WO}, have _show and _store
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) appended to the provided function name.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) SENSOR_DEVICE_ATTR and its variants define a struct sensor_device_attribute
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) variable. This structure has the following fields::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) struct sensor_device_attribute {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) struct device_attribute dev_attr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) int index;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) You can use to_sensor_dev_attr to get the pointer to this structure from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) attribute read or write function. Its parameter is the device to which the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) attribute is attached.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) SENSOR_DEVICE_ATTR_2 and its variants define a struct sensor_device_attribute_2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) variable, which is defined as follows::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) struct sensor_device_attribute_2 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) struct device_attribute dev_attr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) u8 index;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) u8 nr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) Use to_sensor_dev_attr_2 to get the pointer to this structure. Its parameter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) is the device to which the attribute is attached.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags