diff options
Diffstat (limited to 'Documentation/leds')
| -rw-r--r-- | Documentation/leds/index.rst | 7 | ||||
| -rw-r--r-- | Documentation/leds/leds-blinkm.rst | 31 | ||||
| -rw-r--r-- | Documentation/leds/leds-cht-wcove.rst | 38 | ||||
| -rw-r--r-- | Documentation/leds/leds-class-multicolor.rst | 106 | ||||
| -rw-r--r-- | Documentation/leds/leds-class.rst | 91 | ||||
| -rw-r--r-- | Documentation/leds/leds-el15203000.rst | 140 | ||||
| -rw-r--r-- | Documentation/leds/leds-lm3556.rst | 28 | ||||
| -rw-r--r-- | Documentation/leds/leds-mlxcpld.rst | 2 | ||||
| -rw-r--r-- | Documentation/leds/leds-mt6370-rgb.rst | 64 | ||||
| -rw-r--r-- | Documentation/leds/leds-qcom-lpg.rst | 78 | ||||
| -rw-r--r-- | Documentation/leds/leds-sc27xx.rst | 27 | ||||
| -rw-r--r-- | Documentation/leds/leds-st1202.rst | 34 | ||||
| -rw-r--r-- | Documentation/leds/ledtrig-oneshot.rst | 2 | ||||
| -rw-r--r-- | Documentation/leds/ledtrig-transient.rst | 9 | ||||
| -rw-r--r-- | Documentation/leds/well-known-leds.txt | 111 |
15 files changed, 730 insertions, 38 deletions
diff --git a/Documentation/leds/index.rst b/Documentation/leds/index.rst index 060f4e485897..76fae171039c 100644 --- a/Documentation/leds/index.rst +++ b/Documentation/leds/index.rst @@ -9,6 +9,7 @@ LEDs leds-class leds-class-flash + leds-class-multicolor ledtrig-oneshot ledtrig-transient ledtrig-usbport @@ -16,6 +17,8 @@ LEDs uleds leds-blinkm + leds-cht-wcove + leds-el15203000 leds-lm3556 leds-lp3944 leds-lp5521 @@ -23,3 +26,7 @@ LEDs leds-lp5562 leds-lp55xx leds-mlxcpld + leds-mt6370-rgb + leds-sc27xx + leds-st1202 + leds-qcom-lpg diff --git a/Documentation/leds/leds-blinkm.rst b/Documentation/leds/leds-blinkm.rst index c74b5bc877b1..647be1c6c552 100644 --- a/Documentation/leds/leds-blinkm.rst +++ b/Documentation/leds/leds-blinkm.rst @@ -7,15 +7,37 @@ The leds-blinkm driver supports the devices of the BlinkM family. They are RGB-LED modules driven by a (AT)tiny microcontroller and communicate through I2C. The default address of these modules is 0x09 but this can be changed through a command. By this you could -dasy-chain up to 127 BlinkMs on an I2C bus. +daisy-chain up to 127 BlinkMs on an I2C bus. The device accepts RGB and HSB color values through separate commands. Also you can store blinking sequences as "scripts" in the controller and run them. Also fading is an option. -The interface this driver provides is 2-fold: +The interface this driver provides is 3-fold: -a) LED class interface for use with triggers +a) LED multicolor class interface for use with triggers +####################################################### + +The registration follows the scheme:: + + blinkm-<i2c-bus-nr>-<i2c-device-nr>:rgb:indicator + + $ ls -h /sys/class/leds/blinkm-1-9:rgb:indicator + brightness device max_brightness multi_index multi_intensity power subsystem trigger uevent + +Hue is controlled by the multi_intensity file and lightness is controlled by +the brightness file. + +The order in which to write the intensity values can be found in multi_index. +Exactly three values between 0 and 255 must be written to multi_intensity to +change the color:: + + $ echo 255 100 50 > multi_intensity + +The overall lightness be changed by writing a value between 0 and 255 to the +brightness file. + +b) LED class interface for use with triggers ############################################ The registration follows the scheme:: @@ -79,6 +101,7 @@ E.g.:: -as of 6/2012 +as of 07/2024 dl9pf <at> gmx <dot> de +jstrauss <at> mailbox <dot> org diff --git a/Documentation/leds/leds-cht-wcove.rst b/Documentation/leds/leds-cht-wcove.rst new file mode 100644 index 000000000000..5ec7cb60c4aa --- /dev/null +++ b/Documentation/leds/leds-cht-wcove.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================================================== +Kernel driver for Intel Cherry Trail Whiskey Cove PMIC LEDs +=========================================================== + +/sys/class/leds/<led>/hw_pattern +-------------------------------- + +Specify a hardware pattern for the Whiskey Cove PMIC LEDs. + +The only supported pattern is hardware breathing mode:: + + "0 2000 1 2000" + + ^ + | + Max-| --- + | / \ + | / \ + | / \ / + | / \ / + Min-|- --- + | + 0------2------4--> time (sec) + +The rise and fall times must be the same value. +Supported values are 2000, 1000, 500 and 250 for +breathing frequencies of 1/4, 1/2, 1 and 2 Hz. + +The set pattern only controls the timing. For max brightness the last +set brightness is used and the max brightness can be changed +while breathing by writing the brightness attribute. + +This is just like how blinking works in the LED subsystem, +for both sw and hw blinking the brightness can also be changed +while blinking. Breathing on this hw really is just a variant +mode of blinking. diff --git a/Documentation/leds/leds-class-multicolor.rst b/Documentation/leds/leds-class-multicolor.rst new file mode 100644 index 000000000000..c6b47b4093c4 --- /dev/null +++ b/Documentation/leds/leds-class-multicolor.rst @@ -0,0 +1,106 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================================== +Multicolor LED handling under Linux +==================================== + +Description +=========== +The multicolor class groups monochrome LEDs and allows controlling two +aspects of the final combined color: hue and lightness. The former is +controlled via the multi_intensity array file and the latter is controlled +via brightness file. + +Multicolor Class Control +======================== +The multicolor class presents files that groups the colors as indexes in an +array. These files are children under the LED parent node created by the +led_class framework. The led_class framework is documented in led-class.rst +within this documentation directory. + +Each colored LED will be indexed under the ``multi_*`` files. The order of the +colors will be arbitrary. The ``multi_index`` file can be read to determine the +color name to indexed value. + +The ``multi_index`` file is an array that contains the string list of the colors as +they are defined in each ``multi_*`` array file. + +The ``multi_intensity`` is an array that can be read or written to for the +individual color intensities. All elements within this array must be written in +order for the color LED intensities to be updated. + +Directory Layout Example +======================== +.. code-block:: console + + root:/sys/class/leds/multicolor:status# ls -lR + -rw-r--r-- 1 root root 4096 Oct 19 16:16 brightness + -r--r--r-- 1 root root 4096 Oct 19 16:16 max_brightness + -r--r--r-- 1 root root 4096 Oct 19 16:16 multi_index + -rw-r--r-- 1 root root 4096 Oct 19 16:16 multi_intensity + +.. + +Multicolor Class Brightness Control +=================================== +The brightness level for each LED is calculated based on the color LED +intensity setting divided by the global max_brightness setting multiplied by +the requested brightness. + +``led_brightness = brightness * multi_intensity/max_brightness`` + +Example: +A user first writes the multi_intensity file with the brightness levels +for each LED that are necessary to achieve a certain color output from a +multicolor LED group. + +.. code-block:: console + + # cat /sys/class/leds/multicolor:status/multi_index + green blue red + + # echo 43 226 138 > /sys/class/leds/multicolor:status/multi_intensity + + red - + intensity = 138 + max_brightness = 255 + green - + intensity = 43 + max_brightness = 255 + blue - + intensity = 226 + max_brightness = 255 + +.. + +The user can control the brightness of that multicolor LED group by writing the +global 'brightness' control. Assuming a max_brightness of 255 the user +may want to dim the LED color group to half. The user would write a value of +128 to the global brightness file then the values written to each LED will be +adjusted base on this value. + +.. code-block:: console + + # cat /sys/class/leds/multicolor:status/max_brightness + 255 + # echo 128 > /sys/class/leds/multicolor:status/brightness + +.. + +.. code-block:: none + + adjusted_red_value = 128 * 138/255 = 69 + adjusted_green_value = 128 * 43/255 = 21 + adjusted_blue_value = 128 * 226/255 = 113 + +.. + +Reading the global brightness file will return the current brightness value of +the color LED group. + +.. code-block:: console + + # cat /sys/class/leds/multicolor:status/brightness + 128 + +.. diff --git a/Documentation/leds/leds-class.rst b/Documentation/leds/leds-class.rst index a0708d3f3d0b..5db620ed27aa 100644 --- a/Documentation/leds/leds-class.rst +++ b/Documentation/leds/leds-class.rst @@ -169,6 +169,87 @@ Setting the brightness to zero with brightness_set() callback function should completely turn off the LED and cancel the previously programmed hardware blinking function, if any. +Hardware driven LEDs +==================== + +Some LEDs can be programmed to be driven by hardware. This is not +limited to blink but also to turn off or on autonomously. +To support this feature, a LED needs to implement various additional +ops and needs to declare specific support for the supported triggers. + +With hw control we refer to the LED driven by hardware. + +LED driver must define the following value to support hw control: + + - hw_control_trigger: + unique trigger name supported by the LED in hw control + mode. + +LED driver must implement the following API to support hw control: + - hw_control_is_supported: + check if the flags passed by the supported trigger can + be parsed and activate hw control on the LED. + + Return 0 if the passed flags mask is supported and + can be set with hw_control_set(). + + If the passed flags mask is not supported -EOPNOTSUPP + must be returned, the LED trigger will use software + fallback in this case. + + Return a negative error in case of any other error like + device not ready or timeouts. + + - hw_control_set: + activate hw control. LED driver will use the provided + flags passed from the supported trigger, parse them to + a set of mode and setup the LED to be driven by hardware + following the requested modes. + + Set LED_OFF via the brightness_set to deactivate hw control. + + Return 0 on success, a negative error number on failing to + apply flags. + + - hw_control_get: + get active modes from a LED already in hw control, parse + them and set in flags the current active flags for the + supported trigger. + + Return 0 on success, a negative error number on failing + parsing the initial mode. + Error from this function is NOT FATAL as the device may + be in a not supported initial state by the attached LED + trigger. + + - hw_control_get_device: + return the device associated with the LED driver in + hw control. A trigger might use this to match the + returned device from this function with a configured + device for the trigger as the source for blinking + events and correctly enable hw control. + (example a netdev trigger configured to blink for a + particular dev match the returned dev from get_device + to set hw control) + + Returns a pointer to a struct device or NULL if nothing + is currently attached. + +LED driver can activate additional modes by default to workaround the +impossibility of supporting each different mode on the supported trigger. +Examples are hardcoding the blink speed to a set interval, enable special +feature like bypassing blink if some requirements are not met. + +A trigger should first check if the hw control API are supported by the LED +driver and check if the trigger is supported to verify if hw control is possible, +use hw_control_is_supported to check if the flags are supported and only at +the end use hw_control_set to activate hw control. + +A trigger can use hw_control_get to check if a LED is already in hw control +and init their flags. + +When the LED is in hw control, no software blink is possible and doing so +will effectively disable hw control. Known Issues ============ @@ -177,13 +258,3 @@ The LED Trigger core cannot be a module as the simple trigger functions would cause nightmare dependency issues. I see this as a minor issue compared to the benefits the simple trigger functionality brings. The rest of the LED subsystem can be modular. - - -Future Development -================== - -At the moment, a trigger can't be created specifically for a single LED. -There are a number of cases where a trigger might only be mappable to a -particular LED (ACPI?). The addition of triggers provided by the LED driver -should cover this option and be possible to add without breaking the -current interface. diff --git a/Documentation/leds/leds-el15203000.rst b/Documentation/leds/leds-el15203000.rst new file mode 100644 index 000000000000..12c23d79724d --- /dev/null +++ b/Documentation/leds/leds-el15203000.rst @@ -0,0 +1,140 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================== +Kernel driver for Crane EL15203000 +================================== + +/sys/class/leds/<led>/hw_pattern +-------------------------------- + +Specify a hardware pattern for the EL15203000 LED. + +The LEDs board supports only predefined patterns by firmware +for specific LEDs. + +Breathing mode for Screen frame light tube:: + + "0 4000 1 4000" + + ^ + | + Max-| --- + | / \ + | / \ + | / \ / + | / \ / + Min-|- --- + | + 0------4------8--> time (sec) + +Cascade mode for Pipe LED:: + + "1 800 2 800 4 800 8 800 16 800" + + ^ + | + 0 On -|----+ +----+ +--- + | | | | | + Off-| +-------------------+ +-------------------+ + | + 1 On -| +----+ +----+ + | | | | | + Off |----+ +-------------------+ +------------------ + | + 2 On -| +----+ +----+ + | | | | | + Off-|---------+ +-------------------+ +------------- + | + 3 On -| +----+ +----+ + | | | | | + Off-|--------------+ +-------------------+ +-------- + | + 4 On -| +----+ +----+ + | | | | | + Off-|-------------------+ +-------------------+ +--- + | + 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec) + +Inverted cascade mode for Pipe LED:: + + "30 800 29 800 27 800 23 800 15 800" + + ^ + | + 0 On -| +-------------------+ +-------------------+ + | | | | | + Off-|----+ +----+ +--- + | + 1 On -|----+ +-------------------+ +------------------ + | | | | | + Off | +----+ +----+ + | + 2 On -|---------+ +-------------------+ +------------- + | | | | | + Off-| +----+ +----+ + | + 3 On -|--------------+ +-------------------+ +-------- + | | | | | + Off-| +----+ +----+ + | + 4 On -|-------------------+ +-------------------+ +--- + | | | | | + Off-| +----+ +----+ + | + 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec) + +Bounce mode for Pipe LED:: + + "1 800 2 800 4 800 8 800 16 800 16 800 8 800 4 800 2 800 1 800" + + ^ + | + 0 On -|----+ +-------- + | | | + Off-| +---------------------------------------+ + | + 1 On -| +----+ +----+ + | | | | | + Off |----+ +-----------------------------+ +-------- + | + 2 On -| +----+ +----+ + | | | | | + Off-|---------+ +-------------------+ +------------- + | + 3 On -| +----+ +----+ + | | | | | + Off-|--------------+ +---------+ +------------------ + | + 4 On -| +---------+ + | | | + Off-|-------------------+ +----------------------- + | + 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec) + +Inverted bounce mode for Pipe LED:: + + "30 800 29 800 27 800 23 800 15 800 15 800 23 800 27 800 29 800 30 800" + + ^ + | + 0 On -| +---------------------------------------+ + | | | + Off-|----+ +-------- + | + 1 On -|----+ +-----------------------------+ +-------- + | | | | | + Off | +----+ +----+ + | + 2 On -|---------+ +-------------------+ +------------- + | | | | | + Off-| +----+ +----+ + | + 3 On -|--------------+ +---------+ +------------------ + | | | | | + Off-| +----+ +----+ + | + 4 On -|-------------------+ +----------------------- + | | | + Off-| +---------+ + | + 0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec) diff --git a/Documentation/leds/leds-lm3556.rst b/Documentation/leds/leds-lm3556.rst index 1ef17d7d800e..32e3983473ba 100644 --- a/Documentation/leds/leds-lm3556.rst +++ b/Documentation/leds/leds-lm3556.rst @@ -23,7 +23,7 @@ from 93.75 mA to 1500 mA.The Flash currents are adjusted via the CURRENT CONTROL REGISTER(0x09).Flash mode is activated by the ENABLE REGISTER(0x0A), or by pulling the STROBE pin HIGH. -LM3556 Flash can be controlled through sys/class/leds/flash/brightness file +LM3556 Flash can be controlled through /sys/class/leds/flash/brightness file * if STROBE pin is enabled, below example control brightness only, and ON / OFF will be controlled by STROBE pin. @@ -32,17 +32,17 @@ Flash Example: OFF:: - #echo 0 > sys/class/leds/flash/brightness + #echo 0 > /sys/class/leds/flash/brightness 93.75 mA:: - #echo 1 > sys/class/leds/flash/brightness + #echo 1 > /sys/class/leds/flash/brightness ... 1500 mA:: - #echo 16 > sys/class/leds/flash/brightness + #echo 16 > /sys/class/leds/flash/brightness Torch Mode ^^^^^^^^^^ @@ -51,7 +51,7 @@ In Torch Mode, the current source(LED) is programmed via the CURRENT CONTROL REGISTER(0x09).Torch Mode is activated by the ENABLE REGISTER(0x0A) or by the hardware TORCH input. -LM3556 torch can be controlled through sys/class/leds/torch/brightness file. +LM3556 torch can be controlled through /sys/class/leds/torch/brightness file. * if TORCH pin is enabled, below example control brightness only, and ON / OFF will be controlled by TORCH pin. @@ -59,22 +59,22 @@ Torch Example: OFF:: - #echo 0 > sys/class/leds/torch/brightness + #echo 0 > /sys/class/leds/torch/brightness 46.88 mA:: - #echo 1 > sys/class/leds/torch/brightness + #echo 1 > /sys/class/leds/torch/brightness ... 375 mA:: - #echo 8 > sys/class/leds/torch/brightness + #echo 8 > /sys/class/leds/torch/brightness Indicator Mode ^^^^^^^^^^^^^^ -Indicator pattern can be set through sys/class/leds/indicator/pattern file, +Indicator pattern can be set through /sys/class/leds/indicator/pattern file, and 4 patterns are pre-defined in indicator_pattern array. According to N-lank, Pulse time and N Period values, different pattern wiill @@ -87,13 +87,13 @@ Indicator pattern example: pattern 0:: - #echo 0 > sys/class/leds/indicator/pattern + #echo 0 > /sys/class/leds/indicator/pattern ... pattern 3:: - #echo 3 > sys/class/leds/indicator/pattern + #echo 3 > /sys/class/leds/indicator/pattern Indicator brightness can be controlled through sys/class/leds/indicator/brightness file. @@ -102,17 +102,17 @@ Example: OFF:: - #echo 0 > sys/class/leds/indicator/brightness + #echo 0 > /sys/class/leds/indicator/brightness 5.86 mA:: - #echo 1 > sys/class/leds/indicator/brightness + #echo 1 > /sys/class/leds/indicator/brightness ... 46.875mA:: - #echo 8 > sys/class/leds/indicator/brightness + #echo 8 > /sys/class/leds/indicator/brightness Notes ----- diff --git a/Documentation/leds/leds-mlxcpld.rst b/Documentation/leds/leds-mlxcpld.rst index 528582429e0b..c520a134d91e 100644 --- a/Documentation/leds/leds-mlxcpld.rst +++ b/Documentation/leds/leds-mlxcpld.rst @@ -115,4 +115,4 @@ Driver provides the following LEDs for the system "msn2100": - [1,1,1,1] = Blue blink 6Hz Driver supports HW blinking at 3Hz and 6Hz frequency (50% duty cycle). -For 3Hz duty cylce is about 167 msec, for 6Hz is about 83 msec. +For 3Hz duty cycle is about 167 msec, for 6Hz is about 83 msec. diff --git a/Documentation/leds/leds-mt6370-rgb.rst b/Documentation/leds/leds-mt6370-rgb.rst new file mode 100644 index 000000000000..152a2e592172 --- /dev/null +++ b/Documentation/leds/leds-mt6370-rgb.rst @@ -0,0 +1,64 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================================= +The device for Mediatek MT6370 RGB LED +========================================= + +Description +----------- + +The MT6370 integrates a four-channel RGB LED driver, designed to provide a +variety of lighting effect for mobile device applications. The RGB LED devices +includes a smart LED string controller and it can drive 3 channels of LEDs with +a sink current up to 24mA and a CHG_VIN power good indicator LED with sink +current up to 6mA. It provides three operation modes for RGB LEDs: +PWM Dimming mode, breath pattern mode, and constant current mode. The device +can increase or decrease the brightness of the RGB LED via an I2C interface. + +The breath pattern for a channel can be programmed using the "pattern" trigger, +using the hw_pattern attribute. + +/sys/class/leds/<led>/hw_pattern +-------------------------------- + +Specify a hardware breath pattern for a MT6370 RGB LED. + +The breath pattern is a series of timing pairs, with the hold-time expressed in +milliseconds. And the brightness is controlled by +'/sys/class/leds/<led>/brightness'. The pattern doesn't include the brightness +setting. Hardware pattern only controls the timing for each pattern stage +depending on the current brightness setting. + +Pattern diagram:: + + "0 Tr1 0 Tr2 0 Tf1 0 Tf2 0 Ton 0 Toff" --> '0' for dummy brightness code + + ^ + | ============ + | / \ / + Icurr | / \ / + | / \ / + | / \ / .....repeat + | / \ / + | --- --- --- + |--- --- --- + +----------------------------------============------------> Time + < Tr1><Tr2>< Ton ><Tf1><Tf2 >< Toff >< Tr1><Tr2> + +Timing description: + + * Tr1: First rising time for 0% - 30% load. + * Tr2: Second rising time for 31% - 100% load. + * Ton: On time for 100% load. + * Tf1: First falling time for 100% - 31% load. + * Tf2: Second falling time for 30% to 0% load. + * Toff: Off time for 0% load. + + * Tr1/Tr2/Tf1/Tf2/Ton: 125ms to 3125ms, 200ms per step. + * Toff: 250ms to 6250ms, 400ms per step. + +Pattern example:: + + "0 125 0 125 0 125 0 125 0 625 0 1050" + +This Will configure Tr1/Tr2/Tf1/Tf2 to 125m, Ton to 625ms, and Toff to 1050ms. diff --git a/Documentation/leds/leds-qcom-lpg.rst b/Documentation/leds/leds-qcom-lpg.rst new file mode 100644 index 000000000000..d6a76c38c581 --- /dev/null +++ b/Documentation/leds/leds-qcom-lpg.rst @@ -0,0 +1,78 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== +Kernel driver for Qualcomm LPG +============================== + +Description +----------- + +The Qualcomm LPG can be found in a variety of Qualcomm PMICs and consists of a +number of PWM channels, a programmable pattern lookup table and a RGB LED +current sink. + +To facilitate the various use cases, the LPG channels can be exposed as +individual LEDs, grouped together as RGB LEDs or otherwise be accessed as PWM +channels. The output of each PWM channel is routed to other hardware +blocks, such as the RGB current sink, GPIO pins etc. + +The each PWM channel can operate with a period between 27us and 384 seconds and +has a 9 bit resolution of the duty cycle. + +In order to provide support for status notifications with the CPU subsystem in +deeper idle states the LPG provides pattern support. This consists of a shared +lookup table of brightness values and per channel properties to select the +range within the table to use, the rate and if the pattern should repeat. + +The pattern for a channel can be programmed using the "pattern" trigger, using +the hw_pattern attribute. + +/sys/class/leds/<led>/hw_pattern +-------------------------------- + +Specify a hardware pattern for a Qualcomm LPG LED. + +The pattern is a series of brightness and hold-time pairs, with the hold-time +expressed in milliseconds. The hold time is a property of the pattern and must +therefore be identical for each element in the pattern (except for the pauses +described below). As the LPG hardware is not able to perform the linear +transitions expected by the leds-trigger-pattern format, each entry in the +pattern must be followed a zero-length entry of the same brightness. + +Simple pattern:: + + "255 500 255 0 0 500 0 0" + + ^ + | + 255 +----+ +----+ + | | | | ... + 0 | +----+ +---- + +----------------------> + 0 5 10 15 time (100ms) + +The LPG supports specifying a longer hold-time for the first and last element +in the pattern, the so called "low pause" and "high pause". + +Low-pause pattern:: + + "255 1000 255 0 0 500 0 0 255 500 255 0 0 500 0 0" + + ^ + | + 255 +--------+ +----+ +----+ +--------+ + | | | | | | | | ... + 0 | +----+ +----+ +----+ +---- + +-----------------------------> + 0 5 10 15 20 25 time (100ms) + +Similarly, the last entry can be stretched by using a higher hold-time on the +last entry. + +In order to save space in the shared lookup table the LPG supports "ping-pong" +mode, in which case each run through the pattern is performed by first running +the pattern forward, then backwards. This mode is automatically used by the +driver when the given pattern is a palindrome. In this case the "high pause" +denotes the wait time before the pattern is run in reverse and as such the +specified hold-time of the middle item in the pattern is allowed to have a +different hold-time. diff --git a/Documentation/leds/leds-sc27xx.rst b/Documentation/leds/leds-sc27xx.rst new file mode 100644 index 000000000000..6bdf6ba3c9fd --- /dev/null +++ b/Documentation/leds/leds-sc27xx.rst @@ -0,0 +1,27 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== +Kernel driver for Spreadtrum SC27XX +=================================== + +/sys/class/leds/<led>/hw_pattern +-------------------------------- + +Specify a hardware pattern for the SC27XX LED. For the SC27XX +LED controller, it only supports 4 stages to make a single +hardware pattern, which is used to configure the rise time, +high time, fall time and low time for the breathing mode. + +For the breathing mode, the SC27XX LED only expects one brightness +for the high stage. To be compatible with the hardware pattern +format, we should set brightness as 0 for rise stage, fall +stage and low stage. + +- Min stage duration: 125 ms +- Max stage duration: 31875 ms + +Since the stage duration step is 125 ms, the duration should be +a multiplier of 125, like 125ms, 250ms, 375ms, 500ms ... 31875ms. + +Thus the format of the hardware pattern values should be: +"0 rise_duration brightness high_duration 0 fall_duration 0 low_duration". diff --git a/Documentation/leds/leds-st1202.rst b/Documentation/leds/leds-st1202.rst new file mode 100644 index 000000000000..1a09fbfcedcf --- /dev/null +++ b/Documentation/leds/leds-st1202.rst @@ -0,0 +1,34 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================ +Kernel driver for STMicroelectronics LED1202 +============================================ + +/sys/class/leds/<led>/hw_pattern +-------------------------------- + +Specify a hardware pattern for the ST1202 LED. The LED controller +implements 12 low-side current generators with independent dimming +control. Internal volatile memory allows the user to store up to 8 +different patterns. Each pattern is a particular output configuration +in terms of PWM duty-cycle and duration (ms). + +To be compatible with the hardware pattern format, maximum 8 tuples of +brightness (PWM) and duration must be written to hw_pattern. + +- Min pattern duration: 22 ms +- Max pattern duration: 5660 ms + +The format of the hardware pattern values should be: +"brightness duration brightness duration ..." + +/sys/class/leds/<led>/repeat +---------------------------- + +Specify a pattern repeat number, which is common for all channels. +Default is 1; negative numbers and 0 are invalid. + +This file will always return the originally written repeat number. + +When the 255 value is written to it, all patterns will repeat +indefinitely. diff --git a/Documentation/leds/ledtrig-oneshot.rst b/Documentation/leds/ledtrig-oneshot.rst index 69fa3ea1d554..e044d69e9c0f 100644 --- a/Documentation/leds/ledtrig-oneshot.rst +++ b/Documentation/leds/ledtrig-oneshot.rst @@ -5,7 +5,7 @@ One-shot LED Trigger This is a LED trigger useful for signaling the user of an event where there are no clear trap points to put standard led-on and led-off settings. Using this trigger, the application needs only to signal the trigger when an event has -happened, than the trigger turns the LED on and than keeps it off for a +happened, then the trigger turns the LED on and then keeps it off for a specified amount of time. This trigger is meant to be usable both for sporadic and dense events. In the diff --git a/Documentation/leds/ledtrig-transient.rst b/Documentation/leds/ledtrig-transient.rst index d921dc830cd0..63072f310660 100644 --- a/Documentation/leds/ledtrig-transient.rst +++ b/Documentation/leds/ledtrig-transient.rst @@ -17,12 +17,6 @@ set a timer to hold a state, however when user space application crashes or goes away without deactivating the timer, the hardware will be left in that state permanently. -As a specific example of this use-case, let's look at vibrate feature on -phones. Vibrate function on phones is implemented using PWM pins on SoC or -PMIC. There is a need to activate one shot timer to control the vibrate -feature, to prevent user space crashes leaving the phone in vibrate mode -permanently causing the battery to drain. - Transient trigger addresses the need for one shot timer activation. The transient trigger can be enabled and disabled just like the other leds triggers. @@ -157,9 +151,8 @@ repeat the following step as needed:: echo 1 > activate - start timer = duration to run once echo none > trigger -This trigger is intended to be used for for the following example use cases: +This trigger is intended to be used for the following example use cases: - - Control of vibrate (phones, tablets etc.) hardware by user space app. - Use of LED by user space app as activity indicator. - Use of LED by user space app as a kind of watchdog indicator -- as long as the app is alive, it can keep the LED illuminated, if it dies diff --git a/Documentation/leds/well-known-leds.txt b/Documentation/leds/well-known-leds.txt new file mode 100644 index 000000000000..17ef78faf1f3 --- /dev/null +++ b/Documentation/leds/well-known-leds.txt @@ -0,0 +1,111 @@ +-*- org -*- + +It is somehow important to provide consistent interface to the +userland. LED devices have one problem there, and that is naming of +directories in /sys/class/leds. It would be nice if userland would +just know right "name" for given LED function, but situation got more +complex. + +Anyway, if backwards compatibility is not an issue, new code should +use one of the "good" names from this list, and you should extend the +list where applicable. + +Legacy names are listed, too; in case you are writing application that +wants to use particular feature, you should probe for good name, first, +but then try the legacy ones, too. + +Notice there's a list of functions in include/dt-bindings/leds/common.h . + +* Gamepads and joysticks + +Game controllers may feature LEDs to indicate a player number. This is commonly +used on game consoles in which multiple controllers can be connected to a system. +The "player LEDs" are then programmed with a pattern to indicate a particular +player. For example, a game controller with 4 LEDs, may be programmed with "x---" +to indicate player 1, "-x--" to indicate player 2 etcetera where "x" means on. +Input drivers can utilize the LED class to expose the individual player LEDs +of a game controller using the function "player". +Note: tracking and management of Player IDs is the responsibility of user space, +though drivers may pick a default value. + +Good: "input*:*:player-{1,2,3,4,5} + +* Keyboards + +Good: "input*:*:capslock" +Good: "input*:*:scrolllock" +Good: "input*:*:numlock" +Legacy: "shift-key-light" (Motorola Droid 4, capslock) + +Set of common keyboard LEDs, going back to PC AT or so. + +Legacy: "tpacpi::thinklight" (IBM/Lenovo Thinkpads) +Legacy: "lp5523:kb{1,2,3,4,5,6}" (Nokia N900) + +Frontlight/backlight of main keyboard. + +Legacy: "button-backlight" (Motorola Droid 4) + +Some phones have touch buttons below screen; it is different from main +keyboard. And this is their backlight. + +* Sound subsystem + +Good: "platform:*:mute" +Good: "platform:*:micmute" + +LEDs on notebook body, indicating that sound input / output is muted. + +* System notification + +Good: "rgb:status" +Legacy: "status-led:{red,green,blue}" (Motorola Droid 4) +Legacy: "lp5523:{r,g,b}" (Nokia N900) + +Phones usually have multi-color status LED. + +* Power management + +Good: "platform:*:charging" (allwinner sun50i, leds-cht-wcove) + +* Screen + +Good: ":backlight" (Motorola Droid 4) + +* Indicators + +Good: ":indicator" (Blinkm) + +* RGB + +Good: ":rgb" (Blinkm) + +* Ethernet LEDs + +Currently two types of Network LEDs are support, those controlled by +the PHY and those by the MAC. In theory both can be present at the +same time for one Linux netdev, hence the names need to differ between +MAC and PHY. + +Do not use the netdev name, such as eth0, enp1s0. These are not stable +and are not unique. They also don't differentiate between MAC and PHY. + +** MAC LEDs + +Good: f1070000.ethernet:white:WAN +Good: mdio_mux-0.1:00:green:left +Good: 0000:02:00.0:yellow:top + +The first part must uniquely name the MAC controller. Then follows the +colour. WAN/LAN should be used for a single LED. If there are +multiple LEDs, use left/right, or top/bottom to indicate their +position on the RJ45 socket. + +** PHY LEDs + +Good: f1072004.mdio-mii:00: white:WAN +Good: !mdio-mux!mdio@2!switch@0!mdio:01:green:right +Good: r8169-0-200:00:yellow:bottom + +The first part must uniquely name the PHY. This often means uniquely +identifying the MDIO bus controller, and the address on the bus. |