1.. SPDX-License-Identifier: GPL-2.0
2
3==============================
4Kernel driver for Qualcomm LPG
5==============================
6
7Description
8-----------
9
10The Qualcomm LPG can be found in a variety of Qualcomm PMICs and consists of a
11number of PWM channels, a programmable pattern lookup table and a RGB LED
12current sink.
13
14To facilitate the various use cases, the LPG channels can be exposed as
15individual LEDs, grouped together as RGB LEDs or otherwise be accessed as PWM
16channels. The output of each PWM channel is routed to other hardware
17blocks, such as the RGB current sink, GPIO pins etc.
18
19The each PWM channel can operate with a period between 27us and 384 seconds and
20has a 9 bit resolution of the duty cycle.
21
22In order to provide support for status notifications with the CPU subsystem in
23deeper idle states the LPG provides pattern support. This consists of a shared
24lookup table of brightness values and per channel properties to select the
25range within the table to use, the rate and if the pattern should repeat.
26
27The pattern for a channel can be programmed using the "pattern" trigger, using
28the hw_pattern attribute.
29
30/sys/class/leds/<led>/hw_pattern
31--------------------------------
32
33Specify a hardware pattern for a Qualcomm LPG LED.
34
35The pattern is a series of brightness and hold-time pairs, with the hold-time
36expressed in milliseconds. The hold time is a property of the pattern and must
37therefore be identical for each element in the pattern (except for the pauses
38described below). As the LPG hardware is not able to perform the linear
39transitions expected by the leds-trigger-pattern format, each entry in the
40pattern must be followed a zero-length entry of the same brightness.
41
42Simple pattern::
43
44    "255 500 255 0 0 500 0 0"
45
46        ^
47        |
48    255 +----+    +----+
49        |    |    |    |      ...
50      0 |    +----+    +----
51        +---------------------->
52        0    5   10   15     time (100ms)
53
54The LPG supports specifying a longer hold-time for the first and last element
55in the pattern, the so called "low pause" and "high pause".
56
57Low-pause pattern::
58
59    "255 1000 255 0 0 500 0 0 255 500 255 0 0 500 0 0"
60
61        ^
62        |
63    255 +--------+    +----+    +----+    +--------+
64        |        |    |    |    |    |    |        |      ...
65      0 |        +----+    +----+    +----+        +----
66        +----------------------------->
67        0    5   10   15  20   25   time (100ms)
68
69Similarly, the last entry can be stretched by using a higher hold-time on the
70last entry.
71
72In order to save space in the shared lookup table the LPG supports "ping-pong"
73mode, in which case each run through the pattern is performed by first running
74the pattern forward, then backwards. This mode is automatically used by the
75driver when the given pattern is a palindrome. In this case the "high pause"
76denotes the wait time before the pattern is run in reverse and as such the
77specified hold-time of the middle item in the pattern is allowed to have a
78different hold-time.
79