From patchwork Wed Mar 15 21:45:43 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Guenter Roeck X-Patchwork-Id: 70475 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:604a:0:0:0:0:0 with SMTP id j10csp142263wrt; Wed, 15 Mar 2023 14:53:53 -0700 (PDT) X-Google-Smtp-Source: AK7set+o2NMT7lvPifTqaZIg5OpzV1IZNcg6KXwwKiliLTGCjn/nRw7h6/ivy2Xsxsj3chFVRE0j X-Received: by 2002:a17:90a:764a:b0:23f:ed7:4774 with SMTP id s10-20020a17090a764a00b0023f0ed74774mr1289187pjl.7.1678917233393; Wed, 15 Mar 2023 14:53:53 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1678917233; cv=none; d=google.com; s=arc-20160816; b=xnC9+BCZDHnxGJYkCDy+/6vwIRoRhL5MuHxaLNzzNu3euEVfsi0aKndA6YOGK/rjfx 3GUZQSDpG88mrJG4iErUzI0yaELuL7GYBShfDQH48SuNafMzY8sm093B9xpXz/X+C8Z4 Y4dI3YghZqIobqtFwDr9jq7eyV2wbfWZF2cZN738/xcLHRDcq3tdslwhENmgDJaJs0B9 yauiynkaPk+2x0AbxRwPRlo+pNoH/DjMgdlb028Rq0XyRoOpBtt4WxeyNOXziUK7f2KN Od5mYY/CuAmg/bGMH+3Dv0V/SCHa26pp7DiuSWpAgZ/EJSbe3PRNemG6XhQDVHDX3slt yJNg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :message-id:date:subject:cc:to:from:sender:dkim-signature; bh=sCKgG+rjS0qruOZo3hjzG2lpfhG7a6+ZuOs9wue/0iQ=; b=IxbQI+b+AZXLQSVLlDtWKEEgnNQ1D6yY74MI0Y6Dwph2a2fellQQty+Bxhr4+eE6Be SuWyqNswU9Ph6oV/9Vz8VMu5EtTywszmVXwr5dnZiXGXjxhrnym23kLc0Ndk3zSdPUor t4Cs+jjtnEW22DmSwqVcj9Kkki6Hm0DrwgfOm7ylX6sV6lCuaWy9/xZhE47znNLiggIR 9A75HllyD7G2UAVYe0r25Qr13ZSfrpottJjr/RFVleQN1ayX5snz2czdmn2wQEPcYXek mY6BBToC6zlbsQqF5FXnKhpI+RBxljwlgsEGgD34gyy11oMAfKMNdO5bjhVH5PADH5TZ Q/Og== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gmail.com header.s=20210112 header.b=ffnp4rZg; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id b4-20020a170902e94400b0019a9834bb23si6096711pll.192.2023.03.15.14.53.40; Wed, 15 Mar 2023 14:53:53 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@gmail.com header.s=20210112 header.b=ffnp4rZg; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232856AbjCOVpu (ORCPT + 99 others); Wed, 15 Mar 2023 17:45:50 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49094 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232817AbjCOVpt (ORCPT ); Wed, 15 Mar 2023 17:45:49 -0400 Received: from mail-il1-x131.google.com (mail-il1-x131.google.com [IPv6:2607:f8b0:4864:20::131]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C8AB497FD0; Wed, 15 Mar 2023 14:45:47 -0700 (PDT) Received: by mail-il1-x131.google.com with SMTP id r4so11141170ila.2; Wed, 15 Mar 2023 14:45:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; t=1678916747; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:sender:from:to:cc:subject:date:message-id:reply-to; bh=sCKgG+rjS0qruOZo3hjzG2lpfhG7a6+ZuOs9wue/0iQ=; b=ffnp4rZgxR/X+1FCGrFXzsH83QspJwmHUJ0dybY+guIRNGUmCQc2hwfbCpOc3SE/hk Vs70XTZmMFg1+DyWal1bgo2paQgPULEk6FQiORa5dauDNv++oX1esKpn1INEyYqJFQ6+ 2tPpqpuykQrGhPwEiF95xxtif7joEzAIdM95DA6WNZw0jyAIQKVOZo0BVhsMNGqWo/RH QHjjW7djECiu3WCrMtlaOTD75Rvm8UYvVKapz8NsByDqmhCgdnS8fVKWiFyBhZWVhYcn tPOEOETPog9ITDQmdLHoc4L80oFLDDdUghhzwmCy86uZ/lHmec/6jxauSMDOE2Eo/Kid 9Htg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1678916747; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:sender:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=sCKgG+rjS0qruOZo3hjzG2lpfhG7a6+ZuOs9wue/0iQ=; b=ZJliQ42T0XfNUGgrix7F5paHH40k5oIskCyI4bUn2/kpv7AJCKpaSCoGXLVkNY/fEw Elgave2YQWNRezGjblDnSGYw4sjhMnh37PHO4t1a1VDeTgvOW67Is1WQtPmHhdKIhFix VyfZUEj0fYrG2KQSoe6tWGgyeczgi0hGznJbhJ6Xff+qIAyJ8grOIix4EcQRAu7BmrQi zhPkm/IjJC0RGUXjCqhbHixWWHOu7lyJLd5dz9smdZABPKflpQAAp/0q6LUllFaUseMi hg2UT+0Oj8R/nBbj27CAMrlZGi911afB4imhIgxQutIkMj3zS+j9vTgQBA/NBqK2CMyg DDdg== X-Gm-Message-State: AO0yUKVWbxhxsWSQETUubhHAYAX98BesePuw2wx9SkW6tiPEUvC3aT6v r/wnsLUJmxsNyMLc2V5ZxgOnftAAA9U= X-Received: by 2002:a92:c269:0:b0:318:1cff:5e18 with SMTP id h9-20020a92c269000000b003181cff5e18mr5220397ild.3.1678916747165; Wed, 15 Mar 2023 14:45:47 -0700 (PDT) Received: from server.roeck-us.net ([2600:1700:e321:62f0:329c:23ff:fee3:9d7c]) by smtp.gmail.com with ESMTPSA id g4-20020a056638060400b003ffa2c6f598sm1967566jar.86.2023.03.15.14.45.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 15 Mar 2023 14:45:46 -0700 (PDT) Sender: Guenter Roeck From: Guenter Roeck To: Jean Delvare Cc: Jonathan Corbet , linux-hwmon@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Guenter Roeck Subject: [PATCH] Documentation/hwmon: Remove description of deprecated registration functions Date: Wed, 15 Mar 2023 14:45:43 -0700 Message-Id: <20230315214543.3966258-1-linux@roeck-us.net> X-Mailer: git-send-email 2.39.2 MIME-Version: 1.0 X-Spam-Status: No, score=-1.2 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_EF,FREEMAIL_ENVFROM_END_DIGIT, FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM,HEADER_FROM_DIFFERENT_DOMAINS, RCVD_IN_DNSWL_NONE,SPF_HELO_NONE,SPF_PASS autolearn=no autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1760472316992476794?= X-GMAIL-MSGID: =?utf-8?q?1760472316992476794?= 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 --- 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 and, in most +Each hardware monitoring driver must #include and, in some cases, . 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.