From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753461AbbIWJYL (ORCPT ); Wed, 23 Sep 2015 05:24:11 -0400 Received: from mailout4.w1.samsung.com ([210.118.77.14]:62165 "EHLO mailout4.w1.samsung.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753115AbbIWJYH (ORCPT ); Wed, 23 Sep 2015 05:24:07 -0400 X-AuditID: cbfec7f4-f79c56d0000012ee-d8-56026fb4223a Message-id: <56026FB1.20804@samsung.com> Date: Wed, 23 Sep 2015 11:24:01 +0200 From: Jacek Anaszewski User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130804 Thunderbird/17.0.8 MIME-version: 1.0 To: Andrew Lunn Cc: linux-leds@vger.kernel.org, linux-kernel@vger.kernel.org, sakari.ailus@linux.intel.com Subject: Re: [PATCH 2/5] Documentation: leds: Add description of brightness setting API References: <1442845770-17800-1-git-send-email-j.anaszewski@samsung.com> <1442845770-17800-3-git-send-email-j.anaszewski@samsung.com> <20150922192750.GG20029@lunn.ch> In-reply-to: <20150922192750.GG20029@lunn.ch> Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7bit X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFjrMLMWRmVeSWpSXmKPExsVy+t/xK7pb8pnCDE7vFbU4f/cQs8XlXXPY LLa+Wcdo8WnLNyYHFo95JwM9du74zOTxeZNcAHMUl01Kak5mWWqRvl0CV0bvila2gqXCFS9O XGBsYNzF38XIySEhYCLx6u1+dghbTOLCvfVsXYxcHEICSxkltlzvZ4ZwnjFK3Fh1mg2kildA Q+LR5mMsIDaLgKrEyqbJYHE2AUOJny9eM4HYogIREn9O72OFqBeU+DH5Hli9iICCxJSTf8Di zAIxEkff/garFxaIlPj6GKQGZNkqoM1PIE7iFNCVmLv3BCNEg7XEyknboGx5ic1r3jJPYBSY hWTHLCRls5CULWBkXsUomlqaXFCclJ5rqFecmFtcmpeul5yfu4kRErRfdjAuPmZ1iFGAg1GJ h9fiO2OYEGtiWXFl7iFGCQ5mJRHepwFMYUK8KYmVValF+fFFpTmpxYcYpTlYlMR55+56HyIk kJ5YkpqdmlqQWgSTZeLglGpgnGHckDO34Oy33FUO76NOXg47sq5K6e+SRwJZwTLyJmUBWqsE OjQ/X7+jmKgsErvgV6Txf62JsvMvB5/LfRa5obcjdOX6OzOTApeVrrBKV9984jTvteblXv+j NU/eSew+kX46ic9cNHP19dk8Mxy953pc+eEgnPfnufCtM+/Y7fvvL/h7q3WHsBJLcUaioRZz UXEiADWUzN5WAgAA Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On 09/22/2015 09:27 PM, Andrew Lunn wrote: > On Mon, Sep 21, 2015 at 04:29:27PM +0200, Jacek Anaszewski wrote: >> This patch adds description of the LED subsystem API for >> setting an LED brightness. >> >> Signed-off-by: Jacek Anaszewski >> --- >> Documentation/leds/leds-class.txt | 21 +++++++++++++++++++++ >> 1 file changed, 21 insertions(+) >> >> diff --git a/Documentation/leds/leds-class.txt b/Documentation/leds/leds-class.txt >> index 62261c0..2cc38fa 100644 >> --- a/Documentation/leds/leds-class.txt >> +++ b/Documentation/leds/leds-class.txt >> @@ -52,6 +52,27 @@ above leaves scope for further attributes should they be needed. If sections >> of the name don't apply, just leave that section blank. >> >> >> +Brightness setting API >> +====================== >> + >> +LED subsystem core exposes following API for setting brightness: >> + >> + - led_set_brightness : if necessary, cancels the software blink timer that >> + implements blinking when the hardware doesn't; it is guaranteed >> + not to sleep > > I would put this in the reverse order. Not sleeping is the most > important bit. OK. > Also, stopping blinking should also happen if the > hardware is performing the blinking. There is no need to mention > software blinking, that is an implementation detail. OK. > > which implies the possibility of delegating the >> + job to a work queue task (uses led_set_brightness_nosleep >> + underneath - see below), > > This bit is also an implementation detail and not relevant to the API. > > >> + - led_set_brightness_sync : for use cases when immediate effect is desired; >> + it can block the caller for the time required for accessing >> + device registers and can sleep, > > In fact, i would probably have a separate paragraph that says passing > LED_OFF to either of these two functions stops blinking. In case of led_set_brightness_sync passing LED_OFF will disable only hardware blinking. I noticed this discrepancy before a while. We can't disable soft blinking, because we would have to do it in a work queue task, which would in turn compromise the contract offering by the API, i.e. brightness is guaranteed to be set after function returns. Since Sakari proposed to return error from the function if soft blinking is on, then this has to be explicitly stated here too. -- Best Regards, Jacek Anaszewski