Date:   Wed, 15 Mar 2023 14:45:43 -0700
From:   Guenter Roeck <linux@...ck-us.net>
To:     Jean Delvare <jdelvare@...e.com>
Cc:     Jonathan Corbet <corbet@....net>, linux-hwmon@...r.kernel.org,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        Guenter Roeck <linux@...ck-us.net>
Subject: [PATCH] Documentation/hwmon: Remove description of deprecated registration functions

Remove description of deprecated registration functions from the hardware
monitoring kernel API documentation to help ensure that no attempts are
made to use them in new drivers.

Signed-off-by: Guenter Roeck <linux@...ck-us.net>
---
 Documentation/hwmon/hwmon-kernel-api.rst | 60 +++++++-----------------
 1 file changed, 16 insertions(+), 44 deletions(-)

diff --git a/Documentation/hwmon/hwmon-kernel-api.rst b/Documentation/hwmon/hwmon-kernel-api.rst
index 5451a6d4c874..dbd68d7b033a 100644
--- a/Documentation/hwmon/hwmon-kernel-api.rst
+++ b/Documentation/hwmon/hwmon-kernel-api.rst
@@ -19,20 +19,10 @@ also read Documentation/hwmon/submitting-patches.rst.
 
 The API
 -------
-Each hardware monitoring driver must #include <linux/hwmon.h> and, in most
+Each hardware monitoring driver must #include <linux/hwmon.h> and, in some
 cases, <linux/hwmon-sysfs.h>. linux/hwmon.h declares the following
 register/unregister functions::
 
-  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);
-
   struct device *
   hwmon_device_register_with_info(struct device *dev,
 				  const char *name, void *drvdata,
@@ -54,46 +44,30 @@ register/unregister functions::
 
   char *devm_hwmon_sanitize_name(struct device *dev, const char *name);
 
-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 will 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
-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.
-The parent device parameter as well as the chip parameter must not be NULL. Its
-parameters are described in more detail below.
+hwmon_device_register_with_info registers 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. The parent device parameter
+as well as the chip parameter must not be NULL. 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.
 
+All other hardware monitoring device registration functions are deprecated
+and must not be used in new drivers.
+
 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_with_groups or hwmon_device_register_with_info.
+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 or
-hwmon_device_register_with_info and if the automatic (device managed)
-removal would be too late.
+the call to hwmon_device_register_with_info and if the automatic (device
+managed) removal would be too late.
 
 All supported hwmon device registration functions only accept valid device
 names. Device names including invalid characters (whitespace, '*', or '-')
@@ -351,11 +325,9 @@ Return value:
 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 additional
-non-standard sysfs attributes need to be provided when one of those registration
-functions is used.
+In most situations it should not be necessary for a driver to provide sysfs
+attributes since the hardware monitoring core creates those internally.
+Only additional non-standard sysfs attributes need to be provided.
 
 The header file linux/hwmon-sysfs.h provides a number of useful macros to
 declare and use hardware monitoring sysfs attributes.
-- 
2.39.2

Powered by blists - more mailing lists