0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ==============================
0004 Kernel driver for Qualcomm LPG
0005 ==============================
0006
0007 Description
0008 -----------
0009
0010 The Qualcomm LPG can be found in a variety of Qualcomm PMICs and consists of a
0011 number of PWM channels, a programmable pattern lookup table and a RGB LED
0012 current sink.
0013
0014 To facilitate the various use cases, the LPG channels can be exposed as
0015 individual LEDs, grouped together as RGB LEDs or otherwise be accessed as PWM
0016 channels. The output of each PWM channel is routed to other hardware
0017 blocks, such as the RGB current sink, GPIO pins etc.
0018
0019 The each PWM channel can operate with a period between 27us and 384 seconds and
0020 has a 9 bit resolution of the duty cycle.
0021
0022 In order to provide support for status notifications with the CPU subsystem in
0023 deeper idle states the LPG provides pattern support. This consists of a shared
0024 lookup table of brightness values and per channel properties to select the
0025 range within the table to use, the rate and if the pattern should repeat.
0026
0027 The pattern for a channel can be programmed using the "pattern" trigger, using
0028 the hw_pattern attribute.
0029
0030 /sys/class/leds/<led>/hw_pattern
0031 --------------------------------
0032
0033 Specify a hardware pattern for a Qualcomm LPG LED.
0034
0035 The pattern is a series of brightness and hold-time pairs, with the hold-time
0036 expressed in milliseconds. The hold time is a property of the pattern and must
0037 therefor be identical for each element in the pattern (except for the pauses
0038 described below). As the LPG hardware is not able to perform the linear
0039 transitions expected by the leds-trigger-pattern format, each entry in the
0040 pattern must be followed a zero-length entry of the same brightness.
0041
0042 Simple pattern::
0043
0044 "255 500 255 0 0 500 0 0"
0045
0046 ^
0047 |
0048 255 +----+ +----+
0049 | | | | ...
0050 0 | +----+ +----
0051 +---------------------->
0052 0 5 10 15 time (100ms)
0053
0054 The LPG supports specifying a longer hold-time for the first and last element
0055 in the pattern, the so called "low pause" and "high pause".
0056
0057 Low-pause pattern::
0058
0059 "255 1000 255 0 0 500 0 0 255 500 255 0 0 500 0 0"
0060
0061 ^
0062 |
0063 255 +--------+ +----+ +----+ +--------+
0064 | | | | | | | | ...
0065 0 | +----+ +----+ +----+ +----
0066 +----------------------------->
0067 0 5 10 15 20 25 time (100ms)
0068
0069 Similarily, the last entry can be stretched by using a higher hold-time on the
0070 last entry.
0071
0072 In order to save space in the shared lookup table the LPG supports "ping-pong"
0073 mode, in which case each run through the pattern is performed by first running
0074 the pattern forward, then backwards. This mode is automatically used by the
0075 driver when the given pattern is a palindrome. In this case the "high pause"
0076 denotes the wait time before the pattern is run in reverse and as such the
0077 specified hold-time of the middle item in the pattern is allowed to have a
0078 different hold-time.
