Re: [PATCH v2 8/9] hwmon: (core) Document new kernel API

[Jonathan Cameron]

On 17/07/16 06:30, Guenter Roeck wrote:
> Describe the new registration API function as well as the data
> structures it requires.
> 
> Acked-by: Punit Agrawal 
> Signed-off-by: Guenter Roeck 
Straight forward and clear.  Just what is wanted from documentation.

Reviewed-by: Jonathan Cameron 

Feel free to add reviewed by's for the other patches,
but seemed a bit superfluous given how simple they are :)

All seemed fine to me.  I should in theory get
around to converting over my one and only hwmon driver,
but to do that I'd feel I had to find the hardware so
might be a while.  Perhaps someone who has worked on it
more recently might do it *crosses fingers*
(sht15)

Hmm, could do iio-hwmon as well but you have touched that
more recently than I have *resorts to playground tactics*

Jonathan
> ---
> v2: Fixed typos
> 
>  Documentation/hwmon/hwmon-kernel-api.txt | 229 
> ++-
>  1 file changed, 227 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/hwmon/hwmon-kernel-api.txt 
> b/Documentation/hwmon/hwmon-kernel-api.txt
> index 2ecdbfc85ecf..f60a29ce7592 100644
> --- a/Documentation/hwmon/hwmon-kernel-api.txt
> +++ b/Documentation/hwmon/hwmon-kernel-api.txt
> @@ -34,6 +34,19 @@ devm_hwmon_device_register_with_groups(struct device *dev,
>  const char *name, void *drvdata,
>  const struct attribute_group **groups);
>  
> +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);
> +
> +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);
> +
>  void hwmon_device_unregister(struct device *dev);
>  void devm_hwmon_device_unregister(struct device *dev);
>  
> @@ -60,15 +73,227 @@ 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_register_with_info is the most comprehensive and preferred means
> +to register a hardware monitoring device. It creates the standard sysfs
> +attributes in the hardware monitoring core, letting the driver focus on 
> reading
> +from and writing to the chip instead of having to bother with sysfs 
> attributes.
> +Its parameters are described in more detail below.
> +
> +devm_hwmon_device_register_with_info is similar to
> +hwmon_device_register_with_info. 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.
> +hwmon_device_register, 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.
> +the call to devm_hwmon_device_register_with_groups and if the automatic
> +(device managed) removal would be too late.
> +
> +Using devm_hwmon_device_register_with_info()
> +
> +
> +hwmon_device_register_with_info() registers a hardware monitoring device.
> +The parameters to this function are
> +
> +struct device *dev   Pointer to parent device
> +const char *name Device name
> +void *drvdataDriver 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.
> +
> +This function returns a pointer to the created hardware monitoring device
> +on success and a negative error code for failure.
> +
> +The hwmon_chip_info structure looks as follows.
> +
> +struct hwmon_chip_info {
> + const struct hwmon_ops *ops;
> + const struct hwmon_channel_info **info;
> +};
> +
> +It contains the following fields:
> +
> +* ops:   Pointer to device operations.
> +* info: NULL-terminated list of device channel descriptors.
> +
> +The list of hwmon 

Re: [PATCH v2 8/9] hwmon: (core) Document new kernel API

[Jonathan Cameron]

On 17/07/16 06:30, Guenter Roeck wrote:
> Describe the new registration API function as well as the data
> structures it requires.
> 
> Acked-by: Punit Agrawal 
> Signed-off-by: Guenter Roeck 
Straight forward and clear.  Just what is wanted from documentation.

Reviewed-by: Jonathan Cameron 

Feel free to add reviewed by's for the other patches,
but seemed a bit superfluous given how simple they are :)

All seemed fine to me.  I should in theory get
around to converting over my one and only hwmon driver,
but to do that I'd feel I had to find the hardware so
might be a while.  Perhaps someone who has worked on it
more recently might do it *crosses fingers*
(sht15)

Hmm, could do iio-hwmon as well but you have touched that
more recently than I have *resorts to playground tactics*

Jonathan
> ---
> v2: Fixed typos
> 
>  Documentation/hwmon/hwmon-kernel-api.txt | 229 
> ++-
>  1 file changed, 227 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/hwmon/hwmon-kernel-api.txt 
> b/Documentation/hwmon/hwmon-kernel-api.txt
> index 2ecdbfc85ecf..f60a29ce7592 100644
> --- a/Documentation/hwmon/hwmon-kernel-api.txt
> +++ b/Documentation/hwmon/hwmon-kernel-api.txt
> @@ -34,6 +34,19 @@ devm_hwmon_device_register_with_groups(struct device *dev,
>  const char *name, void *drvdata,
>  const struct attribute_group **groups);
>  
> +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);
> +
> +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);
> +
>  void hwmon_device_unregister(struct device *dev);
>  void devm_hwmon_device_unregister(struct device *dev);
>  
> @@ -60,15 +73,227 @@ 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_register_with_info is the most comprehensive and preferred means
> +to register a hardware monitoring device. It creates the standard sysfs
> +attributes in the hardware monitoring core, letting the driver focus on 
> reading
> +from and writing to the chip instead of having to bother with sysfs 
> attributes.
> +Its parameters are described in more detail below.
> +
> +devm_hwmon_device_register_with_info is similar to
> +hwmon_device_register_with_info. 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.
> +hwmon_device_register, 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.
> +the call to devm_hwmon_device_register_with_groups and if the automatic
> +(device managed) removal would be too late.
> +
> +Using devm_hwmon_device_register_with_info()
> +
> +
> +hwmon_device_register_with_info() registers a hardware monitoring device.
> +The parameters to this function are
> +
> +struct device *dev   Pointer to parent device
> +const char *name Device name
> +void *drvdataDriver 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.
> +
> +This function returns a pointer to the created hardware monitoring device
> +on success and a negative error code for failure.
> +
> +The hwmon_chip_info structure looks as follows.
> +
> +struct hwmon_chip_info {
> + const struct hwmon_ops *ops;
> + const struct hwmon_channel_info **info;
> +};
> +
> +It contains the following fields:
> +
> +* ops:   Pointer to device operations.
> +* info: NULL-terminated list of device channel descriptors.
> +
> +The list of hwmon operations is defined as:
> +
> +struct hwmon_ops {
> + umode_t 

[PATCH v2 8/9] hwmon: (core) Document new kernel API

[Guenter Roeck]

Describe the new registration API function as well as the data
structures it requires.

Acked-by: Punit Agrawal 
Signed-off-by: Guenter Roeck 
---
v2: Fixed typos

 Documentation/hwmon/hwmon-kernel-api.txt | 229 ++-
 1 file changed, 227 insertions(+), 2 deletions(-)

diff --git a/Documentation/hwmon/hwmon-kernel-api.txt 
b/Documentation/hwmon/hwmon-kernel-api.txt
index 2ecdbfc85ecf..f60a29ce7592 100644
--- a/Documentation/hwmon/hwmon-kernel-api.txt
+++ b/Documentation/hwmon/hwmon-kernel-api.txt
@@ -34,6 +34,19 @@ devm_hwmon_device_register_with_groups(struct device *dev,
   const char *name, void *drvdata,
   const struct attribute_group **groups);
 
+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);
+
+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);
+
 void hwmon_device_unregister(struct device *dev);
 void devm_hwmon_device_unregister(struct device *dev);
 
@@ -60,15 +73,227 @@ 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_register_with_info is the most comprehensive and preferred means
+to register a hardware monitoring device. It creates the standard sysfs
+attributes in the hardware monitoring core, letting the driver focus on reading
+from and writing to the chip instead of having to bother with sysfs attributes.
+Its parameters are described in more detail below.
+
+devm_hwmon_device_register_with_info is similar to
+hwmon_device_register_with_info. 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.
+hwmon_device_register, 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.
+the call to devm_hwmon_device_register_with_groups and if the automatic
+(device managed) removal would be too late.
+
+Using devm_hwmon_device_register_with_info()
+
+
+hwmon_device_register_with_info() registers a hardware monitoring device.
+The parameters to this function are
+
+struct device *dev Pointer to parent device
+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.
+
+This function returns a pointer to the created hardware monitoring device
+on success and a negative error code for failure.
+
+The hwmon_chip_info structure looks as follows.
+
+struct hwmon_chip_info {
+   const struct hwmon_ops *ops;
+   const struct hwmon_channel_info **info;
+};
+
+It contains the following fields:
+
+* ops: Pointer to device operations.
+* info: NULL-terminated list of device channel descriptors.
+
+The list of hwmon operations is defined as:
+
+struct hwmon_ops {
+   umode_t (*is_visible)(const void *, enum hwmon_sensor_types type,
+ u32 attr, int);
+   int (*read)(struct device *, enum hwmon_sensor_types type,
+   u32 attr, int, long *);
+   int (*write)(struct device *, enum hwmon_sensor_types type,
+u32 attr, int, long);
+};
+
+It defines the following operations.
+
+* is_visible: Pointer to a function to return the file mode for each supported
+  attribute. This function is mandatory.
+
+* read: Pointer to a function for reading a value from the chip. This function
+  is optional, but must be provided if any readable attributes exist.
+
+* write: Pointer to a function for writing a value to the chip. This function 
is
+  optional, but must be provided if any writeable 

[PATCH v2 8/9] hwmon: (core) Document new kernel API

[Guenter Roeck]

Describe the new registration API function as well as the data
structures it requires.

Acked-by: Punit Agrawal 
Signed-off-by: Guenter Roeck 
---
v2: Fixed typos

 Documentation/hwmon/hwmon-kernel-api.txt | 229 ++-
 1 file changed, 227 insertions(+), 2 deletions(-)

diff --git a/Documentation/hwmon/hwmon-kernel-api.txt 
b/Documentation/hwmon/hwmon-kernel-api.txt
index 2ecdbfc85ecf..f60a29ce7592 100644
--- a/Documentation/hwmon/hwmon-kernel-api.txt
+++ b/Documentation/hwmon/hwmon-kernel-api.txt
@@ -34,6 +34,19 @@ devm_hwmon_device_register_with_groups(struct device *dev,
   const char *name, void *drvdata,
   const struct attribute_group **groups);
 
+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);
+
+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);
+
 void hwmon_device_unregister(struct device *dev);
 void devm_hwmon_device_unregister(struct device *dev);
 
@@ -60,15 +73,227 @@ 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_register_with_info is the most comprehensive and preferred means
+to register a hardware monitoring device. It creates the standard sysfs
+attributes in the hardware monitoring core, letting the driver focus on reading
+from and writing to the chip instead of having to bother with sysfs attributes.
+Its parameters are described in more detail below.
+
+devm_hwmon_device_register_with_info is similar to
+hwmon_device_register_with_info. 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.
+hwmon_device_register, 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.
+the call to devm_hwmon_device_register_with_groups and if the automatic
+(device managed) removal would be too late.
+
+Using devm_hwmon_device_register_with_info()
+
+
+hwmon_device_register_with_info() registers a hardware monitoring device.
+The parameters to this function are
+
+struct device *dev Pointer to parent device
+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.
+
+This function returns a pointer to the created hardware monitoring device
+on success and a negative error code for failure.
+
+The hwmon_chip_info structure looks as follows.
+
+struct hwmon_chip_info {
+   const struct hwmon_ops *ops;
+   const struct hwmon_channel_info **info;
+};
+
+It contains the following fields:
+
+* ops: Pointer to device operations.
+* info: NULL-terminated list of device channel descriptors.
+
+The list of hwmon operations is defined as:
+
+struct hwmon_ops {
+   umode_t (*is_visible)(const void *, enum hwmon_sensor_types type,
+ u32 attr, int);
+   int (*read)(struct device *, enum hwmon_sensor_types type,
+   u32 attr, int, long *);
+   int (*write)(struct device *, enum hwmon_sensor_types type,
+u32 attr, int, long);
+};
+
+It defines the following operations.
+
+* is_visible: Pointer to a function to return the file mode for each supported
+  attribute. This function is mandatory.
+
+* read: Pointer to a function for reading a value from the chip. This function
+  is optional, but must be provided if any readable attributes exist.
+
+* write: Pointer to a function for writing a value to the chip. This function 
is
+  optional, but must be provided if any writeable attributes exist.
+
+Each sensor channel is