From nobody Sun Feb 8 14:12:53 2026 Received: from mail-pl1-f195.google.com (mail-pl1-f195.google.com [209.85.214.195]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 8117D304976 for ; Tue, 30 Dec 2025 08:24:15 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.214.195 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1767083057; cv=none; b=IvzCu7DGhc9jUHVcgV2wsg0wwkoNRN7oTVoKi28LW4nSTBGBcIkg1QYyclDYt2mcO5ATCypAQJdyJJdiF4Nmlm2P0RJz5xNbeFwep2tDDXxvzuIzZGYysi1YsflR8ZgKtk07w5nhRwEU/o8iOWrYEabet78xqmUTsZL5/xVpZQg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1767083057; c=relaxed/simple; bh=39ba9wue30A1aWTeAfgL3s9LMi8ZQBWqzHOGtGyy7Nw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=qt37e+jk1ZC+mR0hhS1VvVdxXEIdhDlMVqFnGrpixPjIiLN6lVKst4olyG68UyGHgN0d3YL/L9pNSHO5yerVuODc9iinjctgTvil6ojzdUzuxKWuKTpTuq46N/SF4fwEUf1FwKdt6gCtsBa1bsK8SpTvFb7N/QJm1qI51YJFyDE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=A873qr4i; arc=none smtp.client-ip=209.85.214.195 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="A873qr4i" Received: by mail-pl1-f195.google.com with SMTP id d9443c01a7336-29f102b013fso121580735ad.2 for ; Tue, 30 Dec 2025 00:24:15 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1767083054; x=1767687854; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=ugSCWrsJRygqnHc991VxzRvXCpP5GFtf/Wie/j+cCEo=; b=A873qr4iIvMeRTunaJVm6098+W3Be4nAjhV7RerAgcRfaEu9xRxr0GaDLO95bs9SUs Ux5PYXiuweEk0ty5RwgwyVvsdcb7qnpaUNGVYCtW4OzG4S2spU2TX3ElyD+8H65WOXfd WTaIcJ41amFBWxYCJH+tBkyoZ0eH8Q7ivhAXtFgbhMGQ+I9smqulIm9p1eEl+XGY8IBV eC+5wMGR/auKocE/Hn86Bat4pWRaUmXUdr+P3Lg1p8zomhnG5ESpUdQP3/6FTWSbwTzb DNXVNxvgZJAB1bRH9z0oSV85fvJPqJ9k/FBlVZYFNhATvpKA1HdEI42dI2TUqcHxXpok ZP5A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1767083054; x=1767687854; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=ugSCWrsJRygqnHc991VxzRvXCpP5GFtf/Wie/j+cCEo=; b=rnIFsN97wsdpXss0X82qhFsfbmu5ClaeZHYrZtOvxNITAr7rcJoWnFwnWKxbnej5kR 4Nn8OdeV7MAe5L3JsmkhubHSt8Q3PjZMt3L+EVWYae6UdTYEc69IQwMftvWYdLyz2tKM cfsANFuQCZ/cG3c5x5w+NSDJEi3Eif34XVgh/Unwdqb0prbVs/csRQP9HTw7zd5E9TvU h23QytMlgnCHGmKdG9D886OAvqII7PUXdZfqAijuPlQMd4p8c+c2x7HHIoXm65yRo8uy jHQgzcHfBs+BB7Dw+v4sdGjHwGQQmBo+alcNdhuGOnzJUL7JZpuW/KPEh5cB/AScYpta orgQ== X-Forwarded-Encrypted: i=1; AJvYcCWiX0aJDGqh+WNJ509bfSrUqFnQuWyAbjfpF1h/tqaL7W9XvBt3vzhDY3Bwop+mh47wzX1FHOcoXTBsHDI=@vger.kernel.org X-Gm-Message-State: AOJu0YxmJ8rNdVScWRsKQPwnThbWJdrxtEH6r7f+xTfxsfpeln4Ku4kX 5NfTINxP8TX0RjK93PqIG7IzXq+mGNZAH43MUwfI6nn9b7/YeGtcL6kWC91vh7pz X-Gm-Gg: AY/fxX6nhX14vZ2eWEvL0vm6vmzNyk2SHk2Pmfub4vvuX5/xV15CrAKxAuzSdpi2+Ch a4JFl/mtfjCyOGOnFUvmCgJXXEEHYYka2VeU9GsgMXDWOpuqpNYT9JL5CJRXnVD4R9FOx08VOQ6 Mv6iqlX65m7vLRxUeXnVjaTwCXEMfESvn4BG20uHIcO73YYt+S2vWPcOPDK25mkHRMwRsf4Cduv wg0gkBK5mZ77xoTb485AunhiHuxuo6sL22Ow5wh3KrKwvlWTo1WeBkJciAvT93PT6eJCjO8ZMzZ Gx4c9VVZxKezyOEhbtZDKhznTphl2c88zakIEHpINfnNvKKeLbB8XPAyx56eL1qRi4Q7UHi/LGd f7YUG5MBx6AdcEZtCOSCZHEeyCnzA6iP016RuOuzQwBgItsqzeEXuRMH3sreLyMZmiqonZAi24s O30T0ImFXG+xi8eELooO7RzlUoUU3xrNdn X-Google-Smtp-Source: AGHT+IEfyveC6SXvwjrSjDZuZe24/t+dHtcajKoN+qJVB1dwZv7JEOXhFD3Ft886hclfPko6+3BGzg== X-Received: by 2002:a17:903:1b65:b0:297:e69d:86ac with SMTP id d9443c01a7336-2a2f2836516mr331771855ad.39.1767083054471; Tue, 30 Dec 2025 00:24:14 -0800 (PST) Received: from MRSPARKLE.localdomain ([150.228.155.85]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-2a2f3d76ceesm296667165ad.91.2025.12.30.00.24.09 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 30 Dec 2025 00:24:14 -0800 (PST) From: Jonathan Brophy To: lee Jones , Pavel Machek , Andriy Shevencho , Jonathan Brophy , Rob Herring , Krzysztof Kozlowski , Conor Dooley , Radoslav Tsvetkov Cc: devicetree@vger.kernel.org, linux-kernel@vger.kernel.org, linux-leds@vger.kernel.org Subject: [PATCH v5 4/7] ABI: Add sysfs documentation for leds-group-virtualcolor Date: Tue, 30 Dec 2025 21:23:17 +1300 Message-ID: <20251230082336.3308403-5-professorjonny98@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20251230082336.3308403-1-professorjonny98@gmail.com> References: <20251230082336.3308403-1-professorjonny98@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" From: Jonathan Brophy Document the sysfs ABI for the virtual LED group driver, including: - mc/multi_intensity: Per-channel intensity control (0-255) - mc/multi_index: Channel-to-color-ID mapping (read-only) - mc/multi_multipliers: Per-channel scale factors (read-only) - brightness: Master brightness control with arbitration trigger - max_brightness: Maximum brightness value (mode-dependent) Channel ordering is deterministic, sorted by ascending LED_COLOR_ID value. For RGBW LEDs, white (ID=3D0) appears first, followed by RGB. The multi_intensity attribute is rate-limited to 100 updates/second per virtual LED by default, with counters visible in debugfs when CONFIG_DEBUG_FS is enabled. Co-developed-by: Radoslav Tsvetkov Signed-off-by: Radoslav Tsvetkov Signed-off-by: Jonathan Brophy --- .../sysfs-class-led-driver-virtualcolor | 168 ++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-class-led-driver-virtua= lcolor diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-virtualcolor = b/Documentation/ABI/testing/sysfs-class-led-driver-virtualcolor new file mode 100644 index 000000000000..704f2e5f2af7 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led-driver-virtualcolor @@ -0,0 +1,168 @@ +What: /sys/class/leds//mc/multi_intensity +Date: December 2024 +KernelVersion: 6.x +Contact: Jonathan Brophy +Description: + Control the intensity values for each color channel in a + virtual multicolor LED. + + Reading returns space-separated intensity values (0-255) for + each configured color channel. Channel order is deterministic, + sorted by ascending LED_COLOR_ID value. Use multi_index to + determine which color corresponds to each position. + + Writing accepts space-separated intensity values to set the + per-channel intensities. The number of values must match the + number of channels. Values must be ordered to match multi_index. + + Channel ordering examples: + RGB LED (no white): + multi_index shows "1 2 3" + Order is: red (ID 1), green (ID 2), blue (ID 3) + + RGBW LED (with white): + multi_index shows "0 1 2 3" + Order is: white (ID 0), red (ID 1), green (ID 2), blue (ID 3) + Note: White comes FIRST because LED_COLOR_ID_WHITE =3D 0 + + Example (RGB LED with 3 channels): + $ cat /sys/class/leds/myled/mc/multi_index + 1 2 3 + $ cat /sys/class/leds/myled/mc/multi_intensity + 255 128 0 + $ echo "128 64 200" > /sys/class/leds/myled/mc/multi_intensity + + Note: In standard mode (led-mode =3D "standard"), intensity + changes are rejected with -EPERM and the color is fixed by the + channel multipliers defined in the device tree. In multicolor + mode (led-mode =3D "multicolor", default), intensity can be + freely modified. + + This attribute is rate-limited to prevent system overload + (default: 100 updates/second per virtual LED). Excessive + updates will be silently dropped with incremented rate limit + counters (visible in debugfs when CONFIG_DEBUG_FS enabled). + +What: /sys/class/leds//mc/multi_index +Date: December 2024 +KernelVersion: 6.x +Contact: Jonathan Brophy +Description: + Read-only attribute showing the LED color IDs for each channel + in the virtual LED. + + Returns space-separated LED_COLOR_ID_* values (integers) + corresponding to each channel. Channels are ordered by + ascending color ID value (0, 1, 2, 3, ...). + + See include/dt-bindings/leds/common.h for color ID definitions. + + Common color ID values: + - 0: LED_COLOR_ID_WHITE + - 1: LED_COLOR_ID_RED + - 2: LED_COLOR_ID_GREEN + - 3: LED_COLOR_ID_BLUE + - 4: LED_COLOR_ID_AMBER + - 5: LED_COLOR_ID_VIOLET + - 6: LED_COLOR_ID_YELLOW + - 7: LED_COLOR_ID_IR + - 8: LED_COLOR_ID_MULTI + - 9: LED_COLOR_ID_RGB + - 10: LED_COLOR_ID_UV + + Example (RGB LED): + $ cat /sys/class/leds/myled/mc/multi_index + 1 2 3 + (Shows: red=3D1, green=3D2, blue=3D3) + + Example (RGBW LED): + $ cat /sys/class/leds/myled/mc/multi_index + 0 1 2 3 + (Shows: white=3D0, red=3D1, green=3D2, blue=3D3) + + This attribute is essential for correctly indexing the + multi_intensity and mc-channel-multipliers arrays, especially + when white LEDs are present (which come first due to ID=3D0). + +What: /sys/class/leds//mc/multi_multipliers +Date: December 2024 +KernelVersion: 6.x +Contact: Jonathan Brophy +Description: + Read-only attribute showing the scale/multiplier values (0-255) + for each color channel. + + Multipliers are defined in device tree via the + "mc-channel-multipliers" property and must be ordered to match + the channel order (sorted by LED_COLOR_ID). + + In multicolor mode, these scale the intensity values: + final =3D (intensity * multiplier / 255) * brightness / max_brightness + + In standard mode, these define the fixed color mix: + final =3D multiplier * brightness / max_brightness + + Returns space-separated values (0-255), one per channel, in the + same order as multi_index. + + Example (RGB LED): + $ cat /sys/class/leds/myled/mc/multi_index + 1 2 3 + $ cat /sys/class/leds/myled/mc/multi_multipliers + 255 200 150 + (Shows: red=3D255, green=3D200, blue=3D150) + + Example (RGBW warm white): + $ cat /sys/class/leds/myled/mc/multi_index + 0 1 2 3 + $ cat /sys/class/leds/myled/mc/multi_multipliers + 180 255 200 100 + (Shows: white=3D180, red=3D255, green=3D200, blue=3D100) + +What: /sys/class/leds//brightness +Date: December 2024 +KernelVersion: 6.x +Contact: Jonathan Brophy +Description: + Control the overall brightness of the virtual LED. + + This is the standard LED class attribute. For virtual grouped + LEDs, this controls the master brightness that scales all + physical LEDs assigned to this virtual LED after per-channel + intensity and multipliers are applied. + + Writing brightness triggers the winner-takes-all arbitration + engine which determines which virtual LED controls the hardware + based on: + 1. Priority (higher wins) + 2. Sequence number (most recent wins on tie) + 3. Only virtual LEDs with brightness > 0 participate + + The winner controls ALL physical LEDs. Physical LEDs not used + by the winner are turned off. + + Range: 0 to max_brightness (typically 0-255) + + Reading returns the current brightness setting. + + Example: + $ echo 128 > /sys/class/leds/myled/brightness + $ cat /sys/class/leds/myled/brightness + 128 + +What: /sys/class/leds//max_brightness +Date: December 2024 +KernelVersion: 6.x +Contact: Jonathan Brophy +Description: + Read-only attribute showing the maximum brightness value. + + For multicolor mode virtual LEDs, this is always 255 to provide + full 8-bit resolution for color mixing. + + For standard mode virtual LEDs, this is the minimum max_brightness + among all physical LEDs referenced by the virtual LED. + + Example: + $ cat /sys/class/leds/myled/max_brightness + 255 -- 2.43.0