Re: [PATCH v10 3/4] docs: ABI: Document LP5812 LED sysfs interfaces

[Lee Jones <lee@kernel.org>]

On Thu, 19 Jun 2025, Nam Tran wrote:

> The LP5812 is a 4x3 matrix RGB LED driver with autonomous animation
> engine control.
> 
> The driver provides interfaces to configure LED modes manual/autonomous,
> set PWM/DC values, and manage autonomous animation engines.

How many of these can be swapped out for already existing sysfs
attributes, I wonder.

Let's start with the basics first.  Just to get the device working.
This is a huge change with massive impact and it all needs to be well
thought through before we start doing anything drastic like introducing
massive amounts of stable ABI !!

> Signed-off-by: Nam Tran <trannamatk@gmail.com>
> ---
>  .../ABI/testing/sysfs-bus-i2c-devices-lp5812  |  40 ++++++
>  .../ABI/testing/sysfs-class-led-lp5812        | 120 ++++++++++++++++++
>  MAINTAINERS                                   |   2 +
>  3 files changed, 162 insertions(+)
>  create mode 100644 Documentation/ABI/testing/sysfs-bus-i2c-devices-lp5812
>  create mode 100644 Documentation/ABI/testing/sysfs-class-led-lp5812
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-lp5812 b/Documentation/ABI/testing/sysfs-bus-i2c-devices-lp5812
> new file mode 100644
> index 000000000000..a8b1d5c52a82
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-lp5812
> @@ -0,0 +1,40 @@
> +What:		/sys/bus/i2c/devices/.../lp5812_chip_setup/dev_config
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		Configures drive mode and scan order. (WO)
> +		Some valid values: tcmscan:4:0:1:2:3 (default), tcmscan:3:0:1:2, mixscan:2:2:0:3, mixscan:3:0:1:2:3
> +
> +What:		/sys/bus/i2c/devices/.../lp5812_chip_setup/device_command
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		Issues device-level commands. (WO)
> +		Valid values: "update", "start", "stop", "pause", "continue"
> +
> +What:		/sys/bus/i2c/devices/.../lp5812_chip_setup/sw_reset
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		Triggers a software reset of the device. (WO)
> +		1 - resets device
> +		0 - does not reset device
> +
> +What:		/sys/bus/i2c/devices/.../lp5812_chip_setup/fault_clear
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		Clears fault status. (WO)
> +		1 - clears fault status
> +		0 - does not clear fault status
> +
> +What:		/sys/bus/i2c/devices/.../lp5812_chip_setup/tsd_config_status
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		Report the current thermal shutdown config status. (RO)
> diff --git a/Documentation/ABI/testing/sysfs-class-led-lp5812 b/Documentation/ABI/testing/sysfs-class-led-lp5812
> new file mode 100644
> index 000000000000..a6cb49fb523f
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-class-led-lp5812
> @@ -0,0 +1,120 @@
> +What:		/sys/class/leds/led_<id>/activate
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		Activate or deactivate the specified LED channel. (WO)
> +		1 - Activate
> +		0 - Deactivate
> +
> +What:		/sys/class/leds/led_<id>/mode
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		Selects LED operation mode. (WO)
> +		Valid values: "manual", "autonomous"
> +
> +What:		/sys/class/leds/led_<id>/led_current
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		DC current level. (WO)
> +		Valid values: 0 - 255
> +
> +What:		/sys/class/leds/led_<id>/max_current
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		Shows maximum DC current bit setting. (RO)
> +		0 (default) means the LED maximum current is set to 25.5 mA.
> +		1 means the LED maximum current is set to 51 mA.
> +
> +What:		/sys/class/leds/led_<id>/pwm_dimming_scale
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		PWM dimming scale type. (WO)
> +		Valid values: "linear", "exponential"
> +
> +What:		/sys/class/leds/led_<id>/pwm_phase_align
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		Configures PWM phase alignment. (WO)
> +		Valid values: "forward", "middle", "backward"
> +
> +What:		/sys/class/leds/led_<id>/auto_time_pause_at_start
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		Controls start pause time. (WO)
> +		Valid values: 0 - 15
> +
> +What:		/sys/class/leds/led_<id>/auto_time_pause_at_stop
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		Controls stop pause time. (WO)
> +		Valid values: 0 - 15
> +
> +What:		/sys/class/leds/led_<id>/auto_playback_eau_number
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		Active AEU number of led_<id> selection. (WO)
> +		Valid values: 0 - 3
> +		0 - only use AEU1
> +		1 - use AEU1 and AEU2
> +		2 - use AEU1, AEU2 and AEU3
> +		3 - use AEU1, AEU2 and AEU3 (the same as 2)
> +
> +What:		/sys/class/leds/led_<id>/auto_playback_time
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		Animation pattern playback times of led_<id>. (WO)
> +		Valid values: 0 - 15
> +		0 - 14 means 0 - 14 times, 15 means infinite times
> +
> +What:		/sys/class/leds/led_<id>/aeu_playback_time
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		AEU pattern playback times of led_<id>. (WO)
> +		Format: aeu<x>:<y> where x (1 - 3) indicates the AEU number,
> +		y (0 - 3) indicates the number of playback times.
> +
> +What:		/sys/class/leds/led_<id>/aeu_pwm_<pwm_id>
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		AEU PWM duty cycle setting. (WO)
> +		Format: aeu<x>:<y> where x (1 - 3) indicates the AEU number,
> +		y (0 - 255) indicates pwm value.
> +
> +What:		/sys/class/leds/led_<id>/aeu_slop_time_<st_id>
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		AEU slop time setting. (WO)
> +		Format: aeu<x>:<y> where x (1 - 3) indicates the AEU number,
> +		y (0 - 15) indicates the slop time value.
> +
> +What:		/sys/class/leds/led_<id>/lod_lsd
> +Date:		July 2025
> +KernelVersion:	6.17
> +Contact:	Nam Tran <trannamatk@gmail.com>
> +Description:
> +		0 0 mean no lod and lsd fault detected, 1 1 mean lod and lsd fault detected (RO)
> diff --git a/MAINTAINERS b/MAINTAINERS
> index b4eb3265c800..cdba86f1768b 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -24565,6 +24565,8 @@ TEXAS INSTRUMENTS' LP5812 RGB LED DRIVER
>  M:	Nam Tran <trannamatk@gmail.com>
>  L:	linux-leds@vger.kernel.org
>  S:	Maintained
> +F:	Documentation/ABI/testing/sysfs-bus-i2c-devices-lp5812
> +F:	Documentation/ABI/testing/sysfs-class-led-lp5812
>  F:	Documentation/devicetree/bindings/leds/ti,lp5812.yaml
>  F:	drivers/leds/rgb/Kconfig
>  F:	drivers/leds/rgb/Makefile
> -- 
> 2.25.1
> 

-- 
Lee Jones [李琼斯]