124e2d05dSBjorn Andersson.. SPDX-License-Identifier: GPL-2.0
224e2d05dSBjorn Andersson
324e2d05dSBjorn Andersson==============================
424e2d05dSBjorn AnderssonKernel driver for Qualcomm LPG
524e2d05dSBjorn Andersson==============================
624e2d05dSBjorn Andersson
724e2d05dSBjorn AnderssonDescription
824e2d05dSBjorn Andersson-----------
924e2d05dSBjorn Andersson
1024e2d05dSBjorn AnderssonThe Qualcomm LPG can be found in a variety of Qualcomm PMICs and consists of a
1124e2d05dSBjorn Anderssonnumber of PWM channels, a programmable pattern lookup table and a RGB LED
1224e2d05dSBjorn Anderssoncurrent sink.
1324e2d05dSBjorn Andersson
1424e2d05dSBjorn AnderssonTo facilitate the various use cases, the LPG channels can be exposed as
1524e2d05dSBjorn Anderssonindividual LEDs, grouped together as RGB LEDs or otherwise be accessed as PWM
1624e2d05dSBjorn Anderssonchannels. The output of each PWM channel is routed to other hardware
1724e2d05dSBjorn Anderssonblocks, such as the RGB current sink, GPIO pins etc.
1824e2d05dSBjorn Andersson
1924e2d05dSBjorn AnderssonThe each PWM channel can operate with a period between 27us and 384 seconds and
2024e2d05dSBjorn Anderssonhas a 9 bit resolution of the duty cycle.
2124e2d05dSBjorn Andersson
2224e2d05dSBjorn AnderssonIn order to provide support for status notifications with the CPU subsystem in
2324e2d05dSBjorn Anderssondeeper idle states the LPG provides pattern support. This consists of a shared
2424e2d05dSBjorn Anderssonlookup table of brightness values and per channel properties to select the
2524e2d05dSBjorn Anderssonrange within the table to use, the rate and if the pattern should repeat.
2624e2d05dSBjorn Andersson
2724e2d05dSBjorn AnderssonThe pattern for a channel can be programmed using the "pattern" trigger, using
2824e2d05dSBjorn Anderssonthe hw_pattern attribute.
2924e2d05dSBjorn Andersson
3024e2d05dSBjorn Andersson/sys/class/leds/<led>/hw_pattern
3124e2d05dSBjorn Andersson--------------------------------
3224e2d05dSBjorn Andersson
3324e2d05dSBjorn AnderssonSpecify a hardware pattern for a Qualcomm LPG LED.
3424e2d05dSBjorn Andersson
3524e2d05dSBjorn AnderssonThe pattern is a series of brightness and hold-time pairs, with the hold-time
3624e2d05dSBjorn Anderssonexpressed in milliseconds. The hold time is a property of the pattern and must
37*4aea8f30SRandy Dunlaptherefore be identical for each element in the pattern (except for the pauses
38e98a860fSBjorn Anderssondescribed below). As the LPG hardware is not able to perform the linear
39e98a860fSBjorn Anderssontransitions expected by the leds-trigger-pattern format, each entry in the
40e98a860fSBjorn Anderssonpattern must be followed a zero-length entry of the same brightness.
4124e2d05dSBjorn Andersson
4224e2d05dSBjorn AnderssonSimple pattern::
4324e2d05dSBjorn Andersson
44e98a860fSBjorn Andersson    "255 500 255 0 0 500 0 0"
4524e2d05dSBjorn Andersson
4624e2d05dSBjorn Andersson        ^
4724e2d05dSBjorn Andersson        |
4824e2d05dSBjorn Andersson    255 +----+    +----+
4924e2d05dSBjorn Andersson        |    |    |    |      ...
5024e2d05dSBjorn Andersson      0 |    +----+    +----
5124e2d05dSBjorn Andersson        +---------------------->
5224e2d05dSBjorn Andersson        0    5   10   15     time (100ms)
5324e2d05dSBjorn Andersson
5424e2d05dSBjorn AnderssonThe LPG supports specifying a longer hold-time for the first and last element
5524e2d05dSBjorn Anderssonin the pattern, the so called "low pause" and "high pause".
5624e2d05dSBjorn Andersson
5724e2d05dSBjorn AnderssonLow-pause pattern::
5824e2d05dSBjorn Andersson
59e98a860fSBjorn Andersson    "255 1000 255 0 0 500 0 0 255 500 255 0 0 500 0 0"
6024e2d05dSBjorn Andersson
6124e2d05dSBjorn Andersson        ^
6224e2d05dSBjorn Andersson        |
6324e2d05dSBjorn Andersson    255 +--------+    +----+    +----+    +--------+
6424e2d05dSBjorn Andersson        |        |    |    |    |    |    |        |      ...
6524e2d05dSBjorn Andersson      0 |        +----+    +----+    +----+        +----
6624e2d05dSBjorn Andersson        +----------------------------->
6724e2d05dSBjorn Andersson        0    5   10   15  20   25   time (100ms)
6824e2d05dSBjorn Andersson
69*4aea8f30SRandy DunlapSimilarly, the last entry can be stretched by using a higher hold-time on the
7024e2d05dSBjorn Anderssonlast entry.
7124e2d05dSBjorn Andersson
7224e2d05dSBjorn AnderssonIn order to save space in the shared lookup table the LPG supports "ping-pong"
7324e2d05dSBjorn Anderssonmode, in which case each run through the pattern is performed by first running
7424e2d05dSBjorn Anderssonthe pattern forward, then backwards. This mode is automatically used by the
7524e2d05dSBjorn Anderssondriver when the given pattern is a palindrome. In this case the "high pause"
7624e2d05dSBjorn Anderssondenotes the wait time before the pattern is run in reverse and as such the
7724e2d05dSBjorn Anderssonspecified hold-time of the middle item in the pattern is allowed to have a
7824e2d05dSBjorn Anderssondifferent hold-time.
79