From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 5349D39F160; Thu, 30 Apr 2026 09:25:14 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777541114; cv=none; b=Oy9rOT7uq29qmOu+lsNwCmZQP6iisSLoB7GQobdRMl9iwPlQmm6/fY3Qw3oNsU9ld2hM9nKcXCm9cKZEm0sWGryos9vY96hP/4MiULfcDg+Qz6jyGi45OsxIyDDDdVUZg8yPJe47guJ+g3NuP7svsUChZHgdKNt8mBQMvULx9JU= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777541114; c=relaxed/simple; bh=zsvjEg5G040K3j1nWisvbk6/AZCHJNwK5aizXgBsEeA=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=ZLXQx8fNaVws/NfPKIYhm81MNncF6TLdxQDWR8z2s7uUjj07QuBVgRx4FX+XAlR46kshfiIeAFmbrW5qfXNOd+Iwz3+06j8FoeVDChGS1XLctpbGGVPeFEYf0kMQmSOqtZAjI0hAaFiYYUvJ8KluMiSgbSXmhbBggyI60UkeRv8= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ZM8IhKCc; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="ZM8IhKCc" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B398FC2BCB3; Thu, 30 Apr 2026 09:25:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1777541114; bh=zsvjEg5G040K3j1nWisvbk6/AZCHJNwK5aizXgBsEeA=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=ZM8IhKCczQuHkYXyCrzYAwaaemdQcN4w7CBnop5ZZuDchp0kbXUFB5oU10daK751k PgI+Vi1xOdMGO7UNq1CAGdjIVZi9g8FB0hJqJSezLtfnDOYD2l4G8IYGsOFxhblv7A dObApNe8ivL1j4wF0kryP+bj2dRs4h80K0GWKqauY6D2VND2yVbXddbZ8zTxt2B/GJ o+a7tsRGB0nVh9n4gdtSOcU6utgoJlCSoyS9ugOotvrH0heH64w5nhVCeQMMd8sZ4L LJLVJ4lPvqb7uAXMMbESQLZMJ7MzBrpZV0Gjns3Q97Y0pkEZ/AYU8G8B6mo+UakzJi /cP/MKRBnpffw== Date: Thu, 30 Apr 2026 10:25:08 +0100 From: Lee Jones To: Hans de Goede Cc: Pavel Machek , Jonathan Corbet , Shuah Khan , Rishit Bansal , Carlos Ferreira , Edip Hazuri , Mustafa =?utf-8?B?RWvFn2k=?= , Xavier Bestel , linux-leds@vger.kernel.org, linux-doc@vger.kernel.org Subject: Re: [PATCH 1/1] Documentation: leds: leds-class: Document keyboard backlight LED class naming Message-ID: <20260430092508.GF1806155@google.com> References: <20260406174638.320135-1-johannes.goede@oss.qualcomm.com> <20260406174638.320135-2-johannes.goede@oss.qualcomm.com> Precedence: bulk X-Mailing-List: linux-leds@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20260406174638.320135-2-johannes.goede@oss.qualcomm.com> On Mon, 06 Apr 2026, Hans de Goede wrote: > From: Carlos Ferreira > > Document the existing practice of always using 'kbd_backlight' for > the function part of LED class device names for LED class devices which > control single-zone keyboard backlights. > > Also extend this existing practice with a new naming scheme for keyboards > with zoned backlight control. There are several drivers in the works (see > the Link:tags below) which offer backlight control for keyboards where > the keyboard backlight is divided in a limited number of zones, e.g. > "main", "cursor" and "numpad" zones. > > It is important to agree on a consistent naming scheme for these now, > so that userspace can support multiple different models / vendors through > a single unified naming scheme. > > Link: https://lore.kernel.org/platform-driver-x86/20230131235027.36304-1-rishitbansal0@gmail.com/ > Link: https://lore.kernel.org/platform-driver-x86/20240719100011.16656-1-carlosmiguelferreira.2003@gmail.com/ > Link: https://lore.kernel.org/platform-driver-x86/20260304105831.119349-3-edip@medip.dev/ > Link: https://lore.kernel.org/platform-driver-x86/20240806205001.191551-2-mustafa.eskieksi@gmail.com/ > Link: https://lore.kernel.org/linux-input/20260402075239.3829699-1-xav@bes.tel/ > Signed-off-by: Carlos Ferreira > Co-authored-by: Hans de Goede > Signed-off-by: Hans de Goede The premise is fine I think. > --- > Documentation/leds/leds-class.rst | 63 +++++++++++++++++++++++++++++++ > 1 file changed, 63 insertions(+) > > diff --git a/Documentation/leds/leds-class.rst b/Documentation/leds/leds-class.rst > index 5db620ed27aa..d2b042519a66 100644 > --- a/Documentation/leds/leds-class.rst > +++ b/Documentation/leds/leds-class.rst > @@ -116,6 +116,69 @@ above leaves scope for further attributes should they be needed. If sections > of the name don't apply, just leave that section blank. > > > +Keyboard backlight control LED Device Naming > +============================================ > + > +For backlit keyboards with a single brightness / color settings a single > +(multicolor) LED class device should be used to allow userspace to change > +the backlight brightness (and if possible the color). This LED class device > +must use "kbd_backlight" for the function part of the LED class device name. > +IOW the name must end with ":kbd_backlight". > + > +For backlit keyboards with multiple control zones, one (multicolor) LED class > +device should be used per zone. These LED class devices' name must follow: > + > + "::kbd_zoned_backlight-" > + > +and must be the same for all zones of the same keyboard. > + > + should be descriptive of which part of the keyboard backlight > +the zone covers and should be suitable for userspace to show to an end user > +in an UI for controlling the zones. > + > +Where possible should be a value already used by other > +zoned keyboards with a similar or identical zone layout, e.g.: > + > +::kbd_zoned_backlight-right > +::kbd_zoned_backlight-middle > +::kbd_zoned_backlight-left > +::kbd_zoned_backlight-corners > +::kbd_zoned_backlight-wasd > + > +or: > + > +::kbd_zoned_backlight-main > +::kbd_zoned_backlight-cursor > +::kbd_zoned_backlight-numpad > +::kbd_zoned_backlight-corners > +::kbd_zoned_backlight-wasd > + > +Note that this is intended for keyboards with a limited number of zones, > +keyboards with per key addressable backlighting must not use LED class devices > +since the sysfs API is not suitable for rapidly change multiple LEDs in one > +"commit" as is necessary to do animations / special effects on such keyboards. > + > +An exception to the rule that all zones must follow: > + > + "::kbd_zoned_backlight-" > + > +is made for the special case where there is a single big zone which controls > +the backlighting of almost all of the keyboard and there are some small areas > +with separate control, like just the 4 cursor keys, or the WASD keys. In this > +case the main zone should use 'kbd_backlight' for the function part of the name > +for compatiblity with (older) userspace code which is not aware of Nit: compatibility There may be others. Please run it through a spell checker. > +the "kbd_zoned_backlight-" function naming scheme. > + > +While the smaller zones should use the new zoned naming scheme. Such a setup > +would result in e.g.: > + > +::kbd_backlight > +::kbd_zoned_backlight-wasd > + > +"kbd_zoned_backlight-" aware userspace should be aware of this > +exception and check for a main zone with a "kbd_backlight" function-name. > + > + > Brightness setting API > ====================== > > -- > 2.53.0 > -- Lee Jones