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

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

[Björn Persson]

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

The description in uleds.rst omits the field max_brightness and claims
falsely that the maximum brightness is always 255. Leaving max_brightness
uninitialized or omitting it when writing to /dev/uleds won't work. It
must be given a value, and that value becomes the maximum brightness.

The document is also wrong about the type of brightness values. It says
that a single byte shall be read at a time. That's actually not allowed.
Then the word "unsigned" gives the impression that the type is unsigned.
In fact a signed type is used even though the values are never negative.

Change the document to describe the true API.

Signed-off-by: Björn Persson <Bjorn@Rombobjörn.se>
---
Changes in v2:
Replaced "given" with "specified" to prevent misinterpretation of "given name", avoided mentioning a type name outside of C code fragments, and rewrote the commit message to read more like speech, as requested.

 Documentation/leds/uleds.rst | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/Documentation/leds/uleds.rst b/Documentation/leds/uleds.rst
index 83221098009c..f985048c641f 100644
--- a/Documentation/leds/uleds.rst
+++ b/Documentation/leds/uleds.rst
@@ -17,16 +17,23 @@ 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 specified 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 signed, only positive values are valid: 1 to INT_MAX.
+
+The current brightness shall be read from the character device like so::
+
+    int brightness;
+    result = read(file, &brightness, sizeof(brightness));
+
+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.54.0

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

[Lee Jones]

On Mon, 22 Jun 2026, Björn Persson wrote:

> From: Björn Persson <Bjorn@Rombobjörn.se>
> 
> The description in uleds.rst omits the field max_brightness and claims
> falsely that the maximum brightness is always 255. Leaving max_brightness
> uninitialized or omitting it when writing to /dev/uleds won't work. It
> must be given a value, and that value becomes the maximum brightness.
> 
> The document is also wrong about the type of brightness values. It says
> that a single byte shall be read at a time. That's actually not allowed.
> Then the word "unsigned" gives the impression that the type is unsigned.
> In fact a signed type is used even though the values are never negative.
> 
> Change the document to describe the true API.
> 
> Signed-off-by: Björn Persson <Bjorn@Rombobjörn.se>
> ---
> Changes in v2:
> Replaced "given" with "specified" to prevent misinterpretation of "given name", avoided mentioning a type name outside of C code fragments, and rewrote the commit message to read more like speech, as requested.
> 
>  Documentation/leds/uleds.rst | 21 ++++++++++++++-------
>  1 file changed, 14 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/leds/uleds.rst b/Documentation/leds/uleds.rst
> index 83221098009c..f985048c641f 100644
> --- a/Documentation/leds/uleds.rst
> +++ b/Documentation/leds/uleds.rst
> @@ -17,16 +17,23 @@ 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 specified 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 signed, only positive values are valid: 1 to INT_MAX.
> +
> +The current brightness shall be read from the character device like so::
> +
> +    int brightness;
> +    result = read(file, &brightness, sizeof(brightness));
> +
> +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.

b4 isn't loving this patch:

Fetching patch(es)
Looking up https://lore.kernel.org/all/20260622125516.25EC8F47BE9@tag.xn--rombobjrn-67a.se/
Analyzing 1 messages in the thread
Analyzing 0 code-review messages
Checking attestation on all messages, may take a moment...
---
  ✓ [PATCH v2] docs: leds: uleds: Make the documentation match the code.
    + Link: https://patch.msgid.link/20260622125516.25EC8F47BE9@tag.xn--rombobjrn-67a.se
    + Signed-off-by: Lee Jones <lee@kernel.org>
Traceback (most recent call last):
  File "/home/joneslee/projects/b4/src/b4/command.py", line 535, in <module>
    cmd()
    ~~~^^
  File "/home/joneslee/projects/b4/src/b4/command.py", line 518, in cmd
    cmdargs.func(cmdargs)
    ~~~~~~~~~~~~^^^^^^^^^
  File "/home/joneslee/projects/b4/src/b4/command.py", line 103, in cmd_am
    b4.mbox.main(cmdargs)
    ~~~~~~~~~~~~^^^^^^^^^
  File "/home/joneslee/projects/b4/src/b4/mbox.py", line 1246, in main
    make_am(msgs, cmdargs, msgid)
    ~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
  File "/home/joneslee/projects/b4/src/b4/mbox.py", line 238, in make_am
    am_msgs = lser.get_am_ready(noaddtrailers=cmdargs.noaddtrailers, addmysob=cmdargs.addmysob, addlink=cmdargs.addlink,
                                cherrypick=cherrypick, copyccs=cmdargs.copyccs, allowbadchars=cmdargs.allowbadchars,
                                showchecks=cmdargs.check)
  File "/home/joneslee/projects/b4/src/b4/__init__.py", line 972, in get_am_ready
    msg = lmsg.get_am_message(add_trailers=add_trailers, extras=extras, copyccs=copyccs,
                              addmysob=addmysob, allowbadchars=allowbadchars)
  File "/home/joneslee/projects/b4/src/b4/__init__.py", line 2888, in get_am_message
    hfrom = format_addrs([(str(i.get('Author', '')), str(i.get('Email')))])
  File "/home/joneslee/projects/b4/src/b4/__init__.py", line 4233, in format_addrs
    addrs.append(email.utils.formataddr(pair))
                 ~~~~~~~~~~~~~~~~~~~~~~^^^^^^
  File "/usr/lib/python3.13/email/utils.py", line 87, in formataddr
    address.encode('ascii')
    ~~~~~~~~~~~~~~^^^^^^^^^
UnicodeEncodeError: 'ascii' codec can't encode character '\xf6' in position 13: ordinal not in range(128)

-- 
Lee Jones