From nobody Mon Feb 9 04:13:51 2026 Received: from mail-pl1-f196.google.com (mail-pl1-f196.google.com [209.85.214.196]) (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 DC7442DA763 for ; Tue, 30 Dec 2025 00:33:30 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.214.196 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1767054812; cv=none; b=GEMCpJLN9x4O3nhzOyZDdebV53xyN3hTGWkPKdiY6yS3PPc/W+ONKoUoKWiQGpVj2MXkhjSbcqLBJaTlR6fsT5KZ6N62HqrFzdWrEbexH+M5Euhlq3Dp6p3oUYlg/EF8shaz+Ix55A4IB1dYNVmN+1sen1wwk+HLIBE8nZ1IE8Y= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1767054812; c=relaxed/simple; bh=39ba9wue30A1aWTeAfgL3s9LMi8ZQBWqzHOGtGyy7Nw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=bqeOrt9g51EQK6JdbUd/gs2+YNZQPhsQWrriUzZJHI+zruWqt5xweiskviBjxlJ5Hg9kRDGOWgnlfYY/jChwlBGRXuJaXFW0U+TJ2P5Q7ZTk2wbsMgkkOC2vzXci21zQVZaNjN1kziTiQV1CS506rTe+ZzGNMtJq+Jkx44Rs7ws= 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=EIpUzR20; arc=none smtp.client-ip=209.85.214.196 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="EIpUzR20" Received: by mail-pl1-f196.google.com with SMTP id d9443c01a7336-2a0d6f647e2so153843935ad.1 for ; Mon, 29 Dec 2025 16:33:30 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1767054810; x=1767659610; 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=EIpUzR20Z/bJJgMwk6r8RM5cpCfX9hWXVcO4XDGlPjnZLJYMFiW7dA83yNhzYv+7Lt kWg6HIX29UqU596jGPTaQGbHic7SHocf6c7Apw8n4uFwcMCH3O+do2Aee4gdP0Ksdd7I zhy2eAorx/56cCx1XcrCK2l05T+DmPnMkxR3pvMeR6XdDfM90nJddTkMmITiJtqWnCUm 6eWbZGNZ4qX6TLczmPG8dZJ9ykod+d8p0rG6X4gBjUuxBkz0MhNNl8tfP0HiUsPjAOk2 Ybo5w11v5BqmAaYvDkuS7c5Ueegh081L8IbJ9MQ2bee0/WelKYAUT4QX3OwBeYahbVq8 810A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1767054810; x=1767659610; 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=rqz+NvPD4aoiVU8+o+vAxQp9xbPOzuz+SuviY3sRQt1ZbJPePXxCFXfTWHApY/Ylj5 EEPuurl29PYSdv1ngpk09s4XRqEsuQ9Q8+TPydYw77IxZ/ph/ZHIdBY5eJRIwvr/3i3H TR+OeOZX5/85k9HBMkhovorO/4Z+27UZ4EVADdFbB7JBd8/BqXzQZBEMI74r3HqXIula VKKUwWXs1g5B4o+Z6Mmb9kyLfvf+/gJ6NgcKdBM3SXGF6qCiRnHvTz0hwzoiHeWZrY7K cQ5z1d1P3Z6IU/dLK+ORCacGvsIkRlxnlRMcr1HBiZqzXRLb3j0qOEkhwAtMKicbuJp+ KPbQ== X-Forwarded-Encrypted: i=1; AJvYcCUXcGXPEVjuU+OFISK6EzWs/DDdI5Q4uTmlidqnZFyybjFmBEvN8Eo0VnU+uEovr2rG29YBv/rjXSPjhkU=@vger.kernel.org X-Gm-Message-State: AOJu0Ywd1lnr4oPfaYP+G8ftITGik9Zpf8VprNiSizj1elMItnQylw7S UXPocNKMxlghNNS9ZbXfYpsuFkbkbx47qPpmnz8zsxeaH/jEH7IQ/pND X-Gm-Gg: AY/fxX6DYWsv8Kc2/7qcmT5x0UVWQjKz6esE/3IEj17lWoJTahwvAmzMqzzwUNaC7tr EVUks3jIxexJCfzDt/C0GQj75CKh3OP6qs6ud18Et11PAFkBabJrNVD9PBVcqoJfxdx7Gsym+ra KOdclutEP5xHfmtMRk1BrDm0RT/qb/0Dn8XaW0LnEiZJS77q5LhGFSbvLZnzlB2ptGocL8HGcY2 /ffCSzy+jVCm80gNmsGLn7HHgWNwdFGMtjdKZwL6F5Ewfa4QRnfmUC8aZX/3+MRKf8VoHbnu81K PhhoJAHkVZ0zvZROqhyS0SEa6Sjo6d/eKT7TNfOJY383Ou/k7Hx7W1Q70k65f+vQmvyV5AUbcMr T6qmBu/zKzs4ErQQJPgUtMFoc2aB2fxSDhYvlsQ8IW4cIrcztwl//A63mRFtS2Vp7RyUDrPjnRP sGqgelxm+YpBgUBjmiaMw3xNo7EiIqYuOb X-Google-Smtp-Source: AGHT+IGr2nJFr0T7IhUA7WIZsjwAsp6TZX9YYkR4ycf2KPIvjWfeVIrCdbsDlrO+a6tFrYlEnslK9Q== X-Received: by 2002:a17:903:b8b:b0:298:2cdf:56c8 with SMTP id d9443c01a7336-2a2f2a565e3mr246004765ad.60.1767054810027; Mon, 29 Dec 2025 16:33:30 -0800 (PST) Received: from MRSPARKLE.localdomain ([150.228.155.85]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-7ff7e8947a1sm30241562b3a.67.2025.12.29.16.33.25 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 29 Dec 2025 16:33:29 -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 v4 4/7] ABI: Add sysfs documentation for leds-group-virtualcolor Date: Tue, 30 Dec 2025 13:32:41 +1300 Message-ID: <20251230003250.1197744-5-professorjonny98@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20251230003250.1197744-1-professorjonny98@gmail.com> References: <20251230003250.1197744-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