[PATCH] docs: leds: uleds: Make the documentation match the code.

[PATCH] docs: leds: uleds: Make the documentation match the code.

[Björn Persson]

From: Björn Persson <Bjorn@Rombobjörn.se>

· max_brightness must be set. Leaving it uninitialized or just omitting it
  won't work.

· The maximum brightness is not 255 but the value given to max_brightness.

· Brightness values must be read as ints, not bytes.

· The ints are signed, so the word "unsigned" is misleading.

Signed-off-by: Björn Persson <Bjorn@Rombobjörn.se>
---
 Documentation/leds/uleds.rst | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/Documentation/leds/uleds.rst b/Documentation/leds/uleds.rst
index 83221098009c..9875a0fa4185 100644
--- a/Documentation/leds/uleds.rst
+++ b/Documentation/leds/uleds.rst
@@ -17,16 +17,20 @@ structure to it (found in kernel public header file linux/uleds.h)::
 
     struct uleds_user_dev {
 	char name[LED_MAX_NAME_SIZE];
+	int max_brightness;
     };
 
-A new LED class device will be created with the name given. The name can be
-any valid sysfs device node name, but consider using the LED class naming
-convention of "devicename:color:function".
+A new LED class device will be created with the given name and maximum
+brightness. The name can be any valid sysfs device node name, but consider
+using the LED class naming convention of "devicename:color:function".
 
-The current brightness is found by reading a single byte from the character
-device. Values are unsigned: 0 to 255. Reading will block until the brightness
-changes. The device node can also be polled to notify when the brightness value
-changes.
+Although max_brightness is a signed int, only positive values are valid:
+1 to INT_MAX.
+
+The current brightness is found by reading a whole int from the character
+device. The possible values are 0 to max_brightness. Reading will block until
+the brightness changes. The device node can also be polled to notify when the
+brightness value changes.
 
 The LED class device will be removed when the open file handle to /dev/uleds
 is closed.
-- 
2.53.0

Re: [PATCH] docs: leds: uleds: Make the documentation match the code.

[Lee Jones]

On Thu, 02 Apr 2026, Björn Persson wrote:

> From: Björn Persson <Bjorn@Rombobjörn.se>
> 
> · max_brightness must be set. Leaving it uninitialized or just omitting it
>   won't work.

What are these points?  How do you even type one of those?

Anyway, proper sentences / paragraphs is better.

> · The maximum brightness is not 255 but the value given to max_brightness.
> 
> · Brightness values must be read as ints, not bytes.
> 
> · The ints are signed, so the word "unsigned" is misleading.
> 
> Signed-off-by: Björn Persson <Bjorn@Rombobjörn.se>
> ---
>  Documentation/leds/uleds.rst | 18 +++++++++++-------
>  1 file changed, 11 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/leds/uleds.rst b/Documentation/leds/uleds.rst
> index 83221098009c..9875a0fa4185 100644
> --- a/Documentation/leds/uleds.rst
> +++ b/Documentation/leds/uleds.rst
> @@ -17,16 +17,20 @@ structure to it (found in kernel public header file linux/uleds.h)::
>  
>      struct uleds_user_dev {
>  	char name[LED_MAX_NAME_SIZE];
> +	int max_brightness;
>      };
>  
> -A new LED class device will be created with the name given. The name can be
> -any valid sysfs device node name, but consider using the LED class naming
> -convention of "devicename:color:function".
> +A new LED class device will be created with the given name and maximum

Did you mean to revers "name given"?  A "given name" usually means
something else.

> +brightness. The name can be any valid sysfs device node name, but consider
> +using the LED class naming convention of "devicename:color:function".
>  
> -The current brightness is found by reading a single byte from the character
> -device. Values are unsigned: 0 to 255. Reading will block until the brightness
> -changes. The device node can also be polled to notify when the brightness value
> -changes.
> +Although max_brightness is a signed int, only positive values are valid:
> +1 to INT_MAX.

What about 0?

> +The current brightness is found by reading a whole int from the character

Try not to shorten names in documentation "integer".

Why do we need to specify "whole"?

> +device. The possible values are 0 to max_brightness. Reading will block until
> +the brightness changes. The device node can also be polled to notify when the
> +brightness value changes.
>  
>  The LED class device will be removed when the open file handle to /dev/uleds
>  is closed.
> -- 
> 2.53.0
> 

-- 
Lee Jones [李琼斯]