Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1229431 > unrolled thread

[PATCH 2/5] Documentation: leds: Add description of brightness setting API

Started byJacek Anaszewski <j.anaszewski@samsung.com>
First post2015-09-21 16:40 +0200
Last post2015-09-23 11:30 +0200
Articles 5 — 3 participants

Back to article view | Back to linux.kernel

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  [PATCH 2/5] Documentation: leds: Add description of brightness setting  API Jacek Anaszewski <j.anaszewski@samsung.com> - 2015-09-21 16:40 +0200
    Re: [PATCH 2/5] Documentation: leds: Add description of brightness  setting API Sakari Ailus <sakari.ailus@linux.intel.com> - 2015-09-22 12:30 +0200
      Re: [PATCH 2/5] Documentation: leds: Add description of brightness  setting API Jacek Anaszewski <j.anaszewski@samsung.com> - 2015-09-22 13:10 +0200
    Re: [PATCH 2/5] Documentation: leds: Add description of brightness  setting API Andrew Lunn <andrew@lunn.ch> - 2015-09-22 21:40 +0200
      Re: [PATCH 2/5] Documentation: leds: Add description of brightness  setting API Jacek Anaszewski <j.anaszewski@samsung.com> - 2015-09-23 11:30 +0200

#1229431 — [PATCH 2/5] Documentation: leds: Add description of brightness setting API

FromJacek Anaszewski <j.anaszewski@samsung.com>
Date2015-09-21 16:40 +0200
Subject[PATCH 2/5] Documentation: leds: Add description of brightness setting API
Message-ID<qbaq6-Zi-9@gated-at.bofh.it>
This patch adds description of the LED subsystem API for
setting an LED brightness.

Signed-off-by: Jacek Anaszewski <j.anaszewski@samsung.com>
---
 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, which implies the possibility of delegating the
+		job to a work queue task (uses led_set_brightness_nosleep
+		underneath - see below),
+    - 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,
+    - led_set_brightness_nosleep : sets an LEDs brightness using either
+		brightness_set op, which is guaranteed not to sleep, or, if only
+		brightness_set_blocking op is available, delegates it to a work
+		queue task; this API is inteded for use by LED core and
+		led-triggers, as they can be called from atomic context, and thus
+		cannot sleep.
+
+
 Hardware accelerated blink of LEDs
 ==================================
 
-- 
1.7.9.5

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [next] | [standalone]

#1230054 — Re: [PATCH 2/5] Documentation: leds: Add description of brightness setting API

FromSakari Ailus <sakari.ailus@linux.intel.com>
Date2015-09-22 12:30 +0200
SubjectRe: [PATCH 2/5] Documentation: leds: Add description of brightness setting API
Message-ID<qbsZI-2zG-5@gated-at.bofh.it>
In reply to#1229431
Hi Jacek,

Jacek Anaszewski wrote:
> This patch adds description of the LED subsystem API for
> setting an LED brightness.
> 
> Signed-off-by: Jacek Anaszewski <j.anaszewski@samsung.com>
> ---
>  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, which implies the possibility of delegating the
> +		job to a work queue task (uses led_set_brightness_nosleep
> +		underneath - see below),
> +    - 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,
> +    - led_set_brightness_nosleep : sets an LEDs brightness using either
> +		brightness_set op, which is guaranteed not to sleep, or, if only
> +		brightness_set_blocking op is available, delegates it to a work
> +		queue task; this API is inteded for use by LED core and
> +		led-triggers, as they can be called from atomic context, and thus
> +		cannot sleep.

led_set_brightness_nosleep() isn't part of the API intended to be used
outside the LED framework --- I wouldn't document it here, only the part
relevant for users outside the LED class and triggers frameworks.

> +
> +
>  Hardware accelerated blink of LEDs
>  ==================================
>  
> 


-- 
Kind regards,

Sakari Ailus
sakari.ailus@linux.intel.com
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [prev] | [next] | [standalone]

#1230081 — Re: [PATCH 2/5] Documentation: leds: Add description of brightness setting API

FromJacek Anaszewski <j.anaszewski@samsung.com>
Date2015-09-22 13:10 +0200
SubjectRe: [PATCH 2/5] Documentation: leds: Add description of brightness setting API
Message-ID<qbtCp-3y2-11@gated-at.bofh.it>
In reply to#1230054
Hi Sakari,

On 09/22/2015 12:26 PM, Sakari Ailus wrote:
> Hi Jacek,
>
> Jacek Anaszewski wrote:
>> This patch adds description of the LED subsystem API for
>> setting an LED brightness.
>>
>> Signed-off-by: Jacek Anaszewski <j.anaszewski@samsung.com>
>> ---
>>   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, which implies the possibility of delegating the
>> +		job to a work queue task (uses led_set_brightness_nosleep
>> +		underneath - see below),
>> +    - 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,
>> +    - led_set_brightness_nosleep : sets an LEDs brightness using either
>> +		brightness_set op, which is guaranteed not to sleep, or, if only
>> +		brightness_set_blocking op is available, delegates it to a work
>> +		queue task; this API is inteded for use by LED core and
>> +		led-triggers, as they can be called from atomic context, and thus
>> +		cannot sleep.
>
> led_set_brightness_nosleep() isn't part of the API intended to be used
> outside the LED framework --- I wouldn't document it here, only the part
> relevant for users outside the LED class and triggers frameworks.

OK, I'll move this description to drivers/leds/leds.h, next to the
function declaration.

>> +
>> +
>>   Hardware accelerated blink of LEDs
>>   ==================================
>>
>>
>
>


-- 
Best Regards,
Jacek Anaszewski
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [prev] | [next] | [standalone]

#1230865 — Re: [PATCH 2/5] Documentation: leds: Add description of brightness setting API

FromAndrew Lunn <andrew@lunn.ch>
Date2015-09-22 21:40 +0200
SubjectRe: [PATCH 2/5] Documentation: leds: Add description of brightness setting API
Message-ID<qbBzY-6tc-27@gated-at.bofh.it>
In reply to#1229431
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 <j.anaszewski@samsung.com>
> ---
>  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. 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.

                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.

	Andrew
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [prev] | [next] | [standalone]

#1231279 — Re: [PATCH 2/5] Documentation: leds: Add description of brightness setting API

FromJacek Anaszewski <j.anaszewski@samsung.com>
Date2015-09-23 11:30 +0200
SubjectRe: [PATCH 2/5] Documentation: leds: Add description of brightness setting API
Message-ID<qbOxc-8rA-13@gated-at.bofh.it>
In reply to#1230865
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 <j.anaszewski@samsung.com>
>> ---
>>   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
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web