From f680b2845694a197e7bfc9f56b241f9a3f17296e Mon Sep 17 00:00:00 2001 From: Guenter Roeck Date: Sun, 20 Nov 2016 02:55:45 -0800 Subject: hwmon: (core) Clarify when read and write callbacks are mandatory The callback descrption in hwmon.h was misleading and stated that read and write callbacks would be optional. More accurate is is that the callbacks are mandatory if readable / writeable attributes are present. Signed-off-by: Guenter Roeck --- include/linux/hwmon.h | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'include/linux') diff --git a/include/linux/hwmon.h b/include/linux/hwmon.h index 9d2f8bde7d12..b6a86aa4a9e2 100644 --- a/include/linux/hwmon.h +++ b/include/linux/hwmon.h @@ -298,8 +298,7 @@ enum hwmon_pwm_attributes { * Channel number * The function returns the file permissions. * If the return value is 0, no attribute will be created. - * @read: Read callback. Optional. If not provided, attributes - * will not be readable. + * @read: Read callback. Mandatory if readable attributes are present. * Parameters are: * @dev: Pointer to hardware monitoring device * @type: Sensor type @@ -308,8 +307,7 @@ enum hwmon_pwm_attributes { * Channel number * @val: Pointer to returned value * The function returns 0 on success or a negative error number. - * @write: Write callback. Optional. If not provided, attributes - * will not be writable. + * @write: Write callback. Mandatory if writeable attributes are present. * Parameters are: * @dev: Pointer to hardware monitoring device * @type: Sensor type -- cgit v1.2.3 From e159ab5cb1afb519601a961405933c61cdd5a56a Mon Sep 17 00:00:00 2001 From: Guenter Roeck Date: Sun, 7 Aug 2016 20:51:25 -0700 Subject: hwmon: (core) Add support for string attributes to new API The new API is so far only suited for data attributes and does not work well for string attributes, specifically for the 'label' attributes. Provide a separate callback function for those. Signed-off-by: Guenter Roeck --- drivers/hwmon/hwmon.c | 33 +++++++++++++++++++++++++++++++-- include/linux/hwmon.h | 19 +++++++++++++++++-- 2 files changed, 48 insertions(+), 4 deletions(-) (limited to 'include/linux') diff --git a/drivers/hwmon/hwmon.c b/drivers/hwmon/hwmon.c index a74c075a30ec..491231fa0580 100644 --- a/drivers/hwmon/hwmon.c +++ b/drivers/hwmon/hwmon.c @@ -178,6 +178,22 @@ static ssize_t hwmon_attr_show(struct device *dev, return sprintf(buf, "%ld\n", val); } +static ssize_t hwmon_attr_show_string(struct device *dev, + struct device_attribute *devattr, + char *buf) +{ + struct hwmon_device_attribute *hattr = to_hwmon_attr(devattr); + char *s; + int ret; + + ret = hattr->ops->read_string(dev, hattr->type, hattr->attr, + hattr->index, &s); + if (ret < 0) + return ret; + + return sprintf(buf, "%s\n", s); +} + static ssize_t hwmon_attr_store(struct device *dev, struct device_attribute *devattr, const char *buf, size_t count) @@ -205,6 +221,17 @@ static int hwmon_attr_base(enum hwmon_sensor_types type) return 1; } +static bool is_string_attr(enum hwmon_sensor_types type, u32 attr) +{ + return (type == hwmon_temp && attr == hwmon_temp_label) || + (type == hwmon_in && attr == hwmon_in_label) || + (type == hwmon_curr && attr == hwmon_curr_label) || + (type == hwmon_power && attr == hwmon_power_label) || + (type == hwmon_energy && attr == hwmon_energy_label) || + (type == hwmon_humidity && attr == hwmon_humidity_label) || + (type == hwmon_fan && attr == hwmon_fan_label); +} + static struct attribute *hwmon_genattr(struct device *dev, const void *drvdata, enum hwmon_sensor_types type, @@ -218,6 +245,7 @@ static struct attribute *hwmon_genattr(struct device *dev, struct attribute *a; umode_t mode; char *name; + bool is_string = is_string_attr(type, attr); /* The attribute is invisible if there is no template string */ if (!template) @@ -227,7 +255,8 @@ static struct attribute *hwmon_genattr(struct device *dev, if (!mode) return ERR_PTR(-ENOENT); - if ((mode & S_IRUGO) && !ops->read) + if ((mode & S_IRUGO) && ((is_string && !ops->read_string) || + (!is_string && !ops->read))) return ERR_PTR(-EINVAL); if ((mode & S_IWUGO) && !ops->write) return ERR_PTR(-EINVAL); @@ -252,7 +281,7 @@ static struct attribute *hwmon_genattr(struct device *dev, hattr->ops = ops; dattr = &hattr->dev_attr; - dattr->show = hwmon_attr_show; + dattr->show = is_string ? hwmon_attr_show_string : hwmon_attr_show; dattr->store = hwmon_attr_store; a = &dattr->attr; diff --git a/include/linux/hwmon.h b/include/linux/hwmon.h index b6a86aa4a9e2..e68334aede4c 100644 --- a/include/linux/hwmon.h +++ b/include/linux/hwmon.h @@ -298,7 +298,8 @@ enum hwmon_pwm_attributes { * Channel number * The function returns the file permissions. * If the return value is 0, no attribute will be created. - * @read: Read callback. Mandatory if readable attributes are present. + * @read: Read callback for data attributes. Mandatory if readable + * data attributes are present. * Parameters are: * @dev: Pointer to hardware monitoring device * @type: Sensor type @@ -307,7 +308,19 @@ enum hwmon_pwm_attributes { * Channel number * @val: Pointer to returned value * The function returns 0 on success or a negative error number. - * @write: Write callback. Mandatory if writeable attributes are present. + * @read_string: + * Read callback for string attributes. Mandatory if string + * attributes are present. + * Parameters are: + * @dev: Pointer to hardware monitoring device + * @type: Sensor type + * @attr: Sensor attribute + * @channel: + * Channel number + * @str: Pointer to returned string + * The function returns 0 on success or a negative error number. + * @write: Write callback for data attributes. Mandatory if writeable + * data attributes are present. * Parameters are: * @dev: Pointer to hardware monitoring device * @type: Sensor type @@ -322,6 +335,8 @@ struct hwmon_ops { u32 attr, int channel); int (*read)(struct device *dev, enum hwmon_sensor_types type, u32 attr, int channel, long *val); + int (*read_string)(struct device *dev, enum hwmon_sensor_types type, + u32 attr, int channel, char **str); int (*write)(struct device *dev, enum hwmon_sensor_types type, u32 attr, int channel, long val); }; -- cgit v1.2.3 From af1bd36c06b5fad33baa7ee16820226efbd96cd9 Mon Sep 17 00:00:00 2001 From: Guenter Roeck Date: Sun, 16 Oct 2016 11:31:08 -0700 Subject: hwmon: (core) Deprecate hwmon_device_register() Inform the user that hwmon_device_register() is deprecated, and suggest conversion to the newest API. Also remove hwmon_device_register() from the kernel API documentation. Note that hwmon_device_register() is not marked as __deprecated() since doing so might result in build errors. Signed-off-by: Guenter Roeck --- Documentation/hwmon/hwmon-kernel-api.txt | 34 +++++++++++++------------------- drivers/hwmon/hwmon.c | 3 +++ include/linux/hwmon.h | 2 ++ 3 files changed, 19 insertions(+), 20 deletions(-) (limited to 'include/linux') diff --git a/Documentation/hwmon/hwmon-kernel-api.txt b/Documentation/hwmon/hwmon-kernel-api.txt index 562ef44adb5e..633fa90909eb 100644 --- a/Documentation/hwmon/hwmon-kernel-api.txt +++ b/Documentation/hwmon/hwmon-kernel-api.txt @@ -23,7 +23,6 @@ Each hardware monitoring driver must #include and, in most cases, . 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, @@ -50,24 +49,19 @@ devm_hwmon_device_register_with_info(struct device *dev, 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 +hwmon_device_register_with_groups registers a hardware monitoring device. +The first parameter of this function is a pointer to the parent device. +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. +This function returns a pointer to the newly created hardware monitoring device +or PTR_ERR for failure. devm_hwmon_device_register_with_groups is similar to hwmon_device_register_with_groups. However, it is device managed, meaning the @@ -87,13 +81,13 @@ 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, hwmon_device_register_with_groups, or -hwmon_device_register_with_info. +hwmon_device_register_with_groups or hwmon_device_register_with_info. 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 and if the automatic -(device managed) removal would be too late. +the call to devm_hwmon_device_register_with_groups or +hwmon_device_register_with_info and if the automatic (device managed) +removal would be too late. Using devm_hwmon_device_register_with_info() -------------------------------------------- diff --git a/drivers/hwmon/hwmon.c b/drivers/hwmon/hwmon.c index 112aae60f51f..971c9eb78e6a 100644 --- a/drivers/hwmon/hwmon.c +++ b/drivers/hwmon/hwmon.c @@ -691,6 +691,9 @@ EXPORT_SYMBOL_GPL(hwmon_device_register_with_info); */ struct device *hwmon_device_register(struct device *dev) { + dev_warn(dev, + "hwmon_device_register() is deprecated. Please convert the driver to use hwmon_device_register_with_info().\n"); + return hwmon_device_register_with_groups(dev, NULL, NULL, NULL); } EXPORT_SYMBOL_GPL(hwmon_device_register); diff --git a/include/linux/hwmon.h b/include/linux/hwmon.h index e68334aede4c..2588e6ee7660 100644 --- a/include/linux/hwmon.h +++ b/include/linux/hwmon.h @@ -362,7 +362,9 @@ struct hwmon_chip_info { const struct hwmon_channel_info **info; }; +/* hwmon_device_register() is deprecated */ struct device *hwmon_device_register(struct device *dev); + struct device * hwmon_device_register_with_groups(struct device *dev, const char *name, void *drvdata, -- cgit v1.2.3 From 848ba0a2f20dc121a3ef5272a24641d2bd963d8b Mon Sep 17 00:00:00 2001 From: Guenter Roeck Date: Sun, 16 Oct 2016 17:20:43 -0700 Subject: hwmon: (core) Rename groups parameter in API to extra_groups The 'groups' parameter of hwmon_device_register_with_info() and devm_hwmon_device_register_with_info() is only necessary if extra non-standard attributes need to be provided. Rename the parameter to extra_groups and clarify the documentation. Signed-off-by: Guenter Roeck --- Documentation/hwmon/hwmon-kernel-api.txt | 22 +++++++++++----------- drivers/hwmon/hwmon.c | 8 ++++---- include/linux/hwmon.h | 8 ++++---- 3 files changed, 19 insertions(+), 19 deletions(-) (limited to 'include/linux') diff --git a/Documentation/hwmon/hwmon-kernel-api.txt b/Documentation/hwmon/hwmon-kernel-api.txt index 633fa90909eb..2505ae67e2b6 100644 --- a/Documentation/hwmon/hwmon-kernel-api.txt +++ b/Documentation/hwmon/hwmon-kernel-api.txt @@ -37,14 +37,14 @@ struct device * hwmon_device_register_with_info(struct device *dev, const char *name, void *drvdata, const struct hwmon_chip_info *info, - const struct attribute_group **groups); + const struct attribute_group **extra_groups); struct device * devm_hwmon_device_register_with_info(struct device *dev, - const char *name, - void *drvdata, - const struct hwmon_chip_info *info, - const struct attribute_group **groups); + const char *name, + void *drvdata, + const struct hwmon_chip_info *info, + const struct attribute_group **extra_groups); void hwmon_device_unregister(struct device *dev); void devm_hwmon_device_unregister(struct device *dev); @@ -100,9 +100,9 @@ const char *name Device name void *drvdata Driver private data const struct hwmon_chip_info *info Pointer to chip description. -const struct attribute_group **groups - Null-terminated list of additional sysfs attribute - groups. +const struct attribute_group **extra_groups + Null-terminated list of additional non-standard + sysfs attribute groups. This function returns a pointer to the created hardware monitoring device on success and a negative error code for failure. @@ -287,9 +287,9 @@ Driver-provided sysfs attributes If the hardware monitoring device is registered with hwmon_device_register_with_info or devm_hwmon_device_register_with_info, -it is most likely not necessary to provide sysfs attributes. Only non-standard -sysfs attributes need to be provided when one of those registration functions -is used. +it is most likely not necessary to provide sysfs attributes. Only additional +non-standard sysfs attributes need to be provided when one of those registration +functions is used. The header file linux/hwmon-sysfs.h provides a number of useful macros to declare and use hardware monitoring sysfs attributes. diff --git a/drivers/hwmon/hwmon.c b/drivers/hwmon/hwmon.c index 8dc0466a9307..58c328f4508d 100644 --- a/drivers/hwmon/hwmon.c +++ b/drivers/hwmon/hwmon.c @@ -659,8 +659,8 @@ EXPORT_SYMBOL_GPL(hwmon_device_register_with_groups); * @dev: the parent device * @name: hwmon name attribute * @drvdata: driver data to attach to created device - * @info: Pointer to hwmon chip information - * @groups - pointer to list of driver specific attribute groups + * @info: pointer to hwmon chip information + * @extra_groups: pointer to list of additional non-standard attribute groups * * hwmon_device_unregister() must be called when the device is no * longer needed. @@ -671,12 +671,12 @@ struct device * hwmon_device_register_with_info(struct device *dev, const char *name, void *drvdata, const struct hwmon_chip_info *chip, - const struct attribute_group **groups) + const struct attribute_group **extra_groups) { if (chip && (!chip->ops || !chip->ops->is_visible || !chip->info)) return ERR_PTR(-EINVAL); - return __hwmon_device_register(dev, name, drvdata, chip, groups); + return __hwmon_device_register(dev, name, drvdata, chip, extra_groups); } EXPORT_SYMBOL_GPL(hwmon_device_register_with_info); diff --git a/include/linux/hwmon.h b/include/linux/hwmon.h index 2588e6ee7660..78d59dba563e 100644 --- a/include/linux/hwmon.h +++ b/include/linux/hwmon.h @@ -377,12 +377,12 @@ struct device * hwmon_device_register_with_info(struct device *dev, const char *name, void *drvdata, const struct hwmon_chip_info *info, - const struct attribute_group **groups); + const struct attribute_group **extra_groups); struct device * devm_hwmon_device_register_with_info(struct device *dev, - const char *name, void *drvdata, - const struct hwmon_chip_info *info, - const struct attribute_group **groups); + const char *name, void *drvdata, + const struct hwmon_chip_info *info, + const struct attribute_group **extra_groups); void hwmon_device_unregister(struct device *dev); void devm_hwmon_device_unregister(struct device *dev); -- cgit v1.2.3