From patchwork Thu May 25 14:53:51 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Christian Marangi X-Patchwork-Id: 99064 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:994d:0:b0:3d9:f83d:47d9 with SMTP id k13csp436364vqr; Thu, 25 May 2023 08:02:30 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ4jlpErHmu9VC3qLBiHSVTEfv90zY+clQXSe3mJefHl9IbIaZIquizaOPYEOSc7dFDGTm/2 X-Received: by 2002:a17:90a:9bc4:b0:252:75ed:eff5 with SMTP id b4-20020a17090a9bc400b0025275edeff5mr2056067pjw.30.1685026949972; Thu, 25 May 2023 08:02:29 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1685026949; cv=none; d=google.com; s=arc-20160816; b=Md+E661P/PnnTqqk0yB6vkK0IMluGSr96N9VQ2+ytNd3e+EoetS4fByHRy88tR7ZyR BZfmjNikfWNjiFm4cBHl2dKLpW+eIhsrb3xsAXQfr57RHxXnz92ERrEnHW+JjYy1yyqE ftkhJ9HgZWcofzozDPtwBN3telWtWVJkV9EJLD5Q5fVrK0eg5W96W+oPZR8tCZfyEguR zZ/3DGBtD6y7D5C/M5a8oL0foDWXo71VGo7VzU3nr/1ZziAzqCCQjI7gwvq6T/SY8Y+B PA827ldUSfhz7U18yRlTp9Bb37KZ4l4NL7WJyOdf2yRbivJHCFR8daW2ZHuO9imoY194 qtlQ== 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 :references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=MgugxQZ+bMvGGxcEF4OyoNgsowC99irm6wJEB6lkhic=; b=vT095ydocHntiQZDUD+RDeasAD2wA9Ww6sbALOy6+xYbioNzI6+L58XB94Dz9yddXx D5MNL6t8lLX+z7XG0TMBKON+HcRzl+pjeN83hSKQ83ICKC6K1HR+qHMsq9ud90htwQxq f91RQjsEFy6VNmsYW5Xb1iiaeHbE41conWm1rq0nGdM7LyEzyNkmmcJIy0zP6g86yUzi Di+0j9D/wCd26ly9OCM24GSx9DyJOcF1fd2FxRVNRvkWAgt6J26Jr3sx4WXo43lA6uqB rB12VmQqzoVCtYexFc1y0pjHk0fCE78h5Tkljco41G9WgSW5h96BpCHE7qQw/55Ryg3R KvmA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gmail.com header.s=20221208 header.b=jwrCSAKy; 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; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id x22-20020a17090a789600b002505f319c27si3201107pjk.100.2023.05.25.08.02.17; Thu, 25 May 2023 08:02:29 -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=20221208 header.b=jwrCSAKy; 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; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S241693AbjEYOzH (ORCPT + 99 others); Thu, 25 May 2023 10:55:07 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37530 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S241494AbjEYOy5 (ORCPT ); Thu, 25 May 2023 10:54:57 -0400 Received: from mail-wr1-x431.google.com (mail-wr1-x431.google.com [IPv6:2a00:1450:4864:20::431]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 0D67E19A; Thu, 25 May 2023 07:54:56 -0700 (PDT) Received: by mail-wr1-x431.google.com with SMTP id ffacd0b85a97d-309553c5417so2182781f8f.2; Thu, 25 May 2023 07:54:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1685026494; x=1687618494; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=MgugxQZ+bMvGGxcEF4OyoNgsowC99irm6wJEB6lkhic=; b=jwrCSAKy7iZ9UPxpT/b8WHG4OXncdijOovtoR+94BKAZHN8hcwBZfnmvWeyC1bq10X eMsavHmidOJozl7XbGDg480/ueANtV+5WVCJt7sX+ZIIVJsEeqvu7k318JypjUSGRfyi 63gmG6Sc1QmoByGFZ7vv8lPOEFU6nvx/0NvJO9HeLd1gfZZCldEPBIKtFdLVW8dbqoy8 TjBOfnewvFV322koPdoIwRCw4tB6RySI/cUKPLV3uOi9bNsI64Ax8viC1NLz9EVcGSEk o1AfhZzUzL/jU8jUXH1w+QQbMiYKz1N05QafNGy1HEFQzJkmlynlXobDYNwt7XOfF953 fsyA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1685026494; x=1687618494; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=MgugxQZ+bMvGGxcEF4OyoNgsowC99irm6wJEB6lkhic=; b=L9uiy+FFaBUWOOYWNCu+LxIBPELVx7wQxegJ9ktv7a6shBwBQP25tXH1NA0+zZM151 Pdw8I7X2FvNdfpnvsN5c5eFLq5IFHwsfeNF7TX2nH8r1BsdfRaEL3ZlwTGhgu7Z/Aq20 u5+eG4MGbIPRmjh7vGomXgax9V6/kP23LposalQbM744cfL/7BbKKsE7BfhnezGB8fTo nIKlDs+K6AW1R2krWwGb1XDB0cnDuAOWKmylVl+T/fshSedEpqSx4viLUJ/xHaiKtA9b WyAUmqRljISXBbrSg7NGpVrH0HT7hSNcUOLtBGkLJshs5RPseBOgTTz+NuKwxvUse+Z6 1mbg== X-Gm-Message-State: AC+VfDxNGEzttim01VAVQFVlX8Ml5aGF6fFyueAE2vvzSdA4XkMnBJLk Jjduu1RB24Q6KWDdR6zWM50= X-Received: by 2002:adf:f2ca:0:b0:306:36b5:8ada with SMTP id d10-20020adff2ca000000b0030636b58adamr2761281wrp.29.1685026494299; Thu, 25 May 2023 07:54:54 -0700 (PDT) Received: from localhost.localdomain (93-34-93-173.ip49.fastwebnet.it. [93.34.93.173]) by smtp.googlemail.com with ESMTPSA id t11-20020a5d49cb000000b0030732d6e104sm2048043wrs.105.2023.05.25.07.54.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 25 May 2023 07:54:53 -0700 (PDT) From: Christian Marangi To: Pavel Machek , Lee Jones , Jonathan Corbet , Andrew Lunn , Florian Fainelli , Vladimir Oltean , "David S. Miller" , Eric Dumazet , Jakub Kicinski , Paolo Abeni , Christian Marangi , linux-leds@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org Subject: [net-next PATCH v2 03/13] Documentation: leds: leds-class: Document new Hardware driven LEDs APIs Date: Thu, 25 May 2023 16:53:51 +0200 Message-Id: <20230525145401.27007-4-ansuelsmth@gmail.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230525145401.27007-1-ansuelsmth@gmail.com> References: <20230525145401.27007-1-ansuelsmth@gmail.com> MIME-Version: 1.0 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_FROM, RCVD_IN_DNSWL_NONE,SPF_HELO_NONE,SPF_PASS,T_SCC_BODY_TEXT_LINE autolearn=ham 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?1766878819262282505?= X-GMAIL-MSGID: =?utf-8?q?1766878819262282505?= Document new Hardware driven LEDs APIs. Some LEDs can be programmed to be driven by hardware. This is not limited to blink but also to turn off or on autonomously. To support this feature, a LED needs to implement various additional ops and needs to declare specific support for the supported triggers. Add documentation for each required value and API to make hw control possible and implementable by both LEDs and triggers. Signed-off-by: Christian Marangi --- Documentation/leds/leds-class.rst | 80 +++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/Documentation/leds/leds-class.rst b/Documentation/leds/leds-class.rst index cd155ead8703..3d7874c18982 100644 --- a/Documentation/leds/leds-class.rst +++ b/Documentation/leds/leds-class.rst @@ -169,6 +169,86 @@ Setting the brightness to zero with brightness_set() callback function should completely turn off the LED and cancel the previously programmed hardware blinking function, if any. +Hardware driven LEDs +==================== + +Some LEDs can be programmed to be driven by hardware. This is not +limited to blink but also to turn off or on autonomously. +To support this feature, a LED needs to implement various additional +ops and needs to declare specific support for the supported triggers. + +With hw control we refer to the LED driven by hardware. + +LED driver must define the following value to support hw control: + + - hw_control_trigger: + unique trigger name supported by the LED in hw control + mode. + +LED driver must implement the following API to support hw control: + - hw_control_is_supported: + check if the flags passed by the supported trigger can + be parsed and activate hw control on the LED. + + Return 0 if the passed flags mask is supported and + can be set with hw_control_set(). + + If the passed flags mask is not supported -EOPNOTSUPP + must be returned, the LED trigger will use software + fallback in this case. + + Return a negative error in case of any other error like + device not ready or timeouts. + + - hw_control_set: + activate hw control. LED driver will use the provided + flags passed from the supported trigger, parse them to + a set of mode and setup the LED to be driven by hardware + following the requested modes. + + Set LED_OFF via the brightness_set to deactivate hw control. + + Return 0 on success, a negative error number on flags apply + fail. + + - hw_control_get: + get active modes from a LED already in hw control, parse + them and set in flags the current active flags for the + supported trigger. + + Return 0 on success, a negative error number on failing + parsing the initial mode. + Error from this function is NOT FATAL as the device may + be in a not supported initial state by the attached LED + trigger. + + - hw_control_get_device: + return the device associated with the LED driver in + hw control. A trigger might use this to match the + returned device from this function with a configured + device for the trigger as the source for blinking + events and correctly enable hw control. + (example a netdev trigger configured to blink for a + particular dev match the returned dev from get_device + to set hw control) + + Return a device or NULL if nothing is currently attached. + +LED driver can activate additional modes by default to workaround the +impossibility of supporting each different mode on the supported trigger. +Example are hardcoding the blink speed to a set interval, enable special +feature like bypassing blink if some requirements are not met. + +A trigger should first check if the hw control API are supported by the LED +driver and check if the trigger is supported to verify if hw control is possible, +use hw_control_is_supported to check if the flags are supported and only at +the end use hw_control_set to activate hw control. + +A trigger can use hw_control_get to check if a LED is already in hw control +and init their flags. + +When the LED is in hw control, no software blink is possible and doing so +will effectively disable hw control. Known Issues ============