^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) LED handling under Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) In its simplest form, the LED class just allows control of LEDs from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) userspace. LEDs appear in /sys/class/leds/. The maximum brightness of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) LED is defined in max_brightness file. The brightness file will set the brightness
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) of the LED (taking a value 0-max_brightness). Most LEDs don't have hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) brightness support so will just be turned on for non-zero brightness settings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) The class also introduces the optional concept of an LED trigger. A trigger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) is a kernel based source of led events. Triggers can either be simple or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) complex. A simple trigger isn't configurable and is designed to slot into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) existing subsystems with minimal additional code. Examples are the disk-activity,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) nand-disk and sharpsl-charge triggers. With led triggers disabled, the code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) optimises away.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) Complex triggers while available to all LEDs have LED specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) parameters and work on a per LED basis. The timer trigger is an example.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) The timer trigger will periodically change the LED brightness between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) LED_OFF and the current brightness setting. The "on" and "off" time can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) be specified via /sys/class/leds/<device>/delay_{on,off} in milliseconds.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) You can change the brightness value of a LED independently of the timer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) trigger. However, if you set the brightness value to LED_OFF it will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) also disable the timer trigger.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) You can change triggers in a similar manner to the way an IO scheduler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) is chosen (via /sys/class/leds/<device>/trigger). Trigger specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) parameters can appear in /sys/class/leds/<device> once a given trigger is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) selected.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) Design Philosophy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) The underlying design philosophy is simplicity. LEDs are simple devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) and the aim is to keep a small amount of code giving as much functionality
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) as possible. Please keep this in mind when suggesting enhancements.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) LED Device Naming
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) Is currently of the form:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) "devicename:color:function"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) - devicename:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) it should refer to a unique identifier created by the kernel,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) like e.g. phyN for network devices or inputN for input devices, rather
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) than to the hardware; the information related to the product and the bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) to which given device is hooked is available in sysfs and can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) retrieved using get_led_device_info.sh script from tools/leds; generally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) this section is expected mostly for LEDs that are somehow associated with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) other devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) - color:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) one of LED_COLOR_ID_* definitions from the header
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) include/dt-bindings/leds/common.h.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) - function:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) one of LED_FUNCTION_* definitions from the header
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) include/dt-bindings/leds/common.h.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) If required color or function is missing, please submit a patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) to linux-leds@vger.kernel.org.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) It is possible that more than one LED with the same color and function will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) be required for given platform, differing only with an ordinal number.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) In this case it is preferable to just concatenate the predefined LED_FUNCTION_*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) name with required "-N" suffix in the driver. fwnode based drivers can use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) function-enumerator property for that and then the concatenation will be handled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) automatically by the LED core upon LED class device registration.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) LED subsystem has also a protection against name clash, that may occur
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) when LED class device is created by a driver of hot-pluggable device and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) it doesn't provide unique devicename section. In this case numerical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) suffix (e.g. "_1", "_2", "_3" etc.) is added to the requested LED class
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) device name.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) There might be still LED class drivers around using vendor or product name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) for devicename, but this approach is now deprecated as it doesn't convey
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) any added value. Product information can be found in other places in sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) (see tools/leds/get_led_device_info.sh).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) Examples of proper LED names:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) - "red:disk"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) - "white:flash"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) - "red:indicator"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) - "phy1:green:wlan"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) - "phy3::wlan"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) - ":kbd_backlight"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) - "input5::kbd_backlight"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) - "input3::numlock"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) - "input3::scrolllock"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) - "input3::capslock"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) - "mmc1::status"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) - "white:status"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) get_led_device_info.sh script can be used for verifying if the LED name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) meets the requirements pointed out here. It performs validation of the LED class
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) devicename sections and gives hints on expected value for a section in case
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) the validation fails for it. So far the script supports validation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) of associations between LEDs and following types of devices:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) - input devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) - ieee80211 compliant USB devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) The script is open to extensions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) There have been calls for LED properties such as color to be exported as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) individual led class attributes. As a solution which doesn't incur as much
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) overhead, I suggest these become part of the device name. The naming scheme
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) above leaves scope for further attributes should they be needed. If sections
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) of the name don't apply, just leave that section blank.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) Brightness setting API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) LED subsystem core exposes following API for setting brightness:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) - led_set_brightness:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) it is guaranteed not to sleep, passing LED_OFF stops
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) blinking,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) - led_set_brightness_sync:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) for use cases when immediate effect is desired -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) it can block the caller for the time required for accessing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) device registers and can sleep, passing LED_OFF stops hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) blinking, returns -EBUSY if software blink fallback is enabled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) LED registration API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) A driver wanting to register a LED classdev for use by other drivers /
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) userspace needs to allocate and fill a led_classdev struct and then call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) `[devm_]led_classdev_register`. If the non devm version is used the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) must call led_classdev_unregister from its remove function before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) free-ing the led_classdev struct.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) If the driver can detect hardware initiated brightness changes and thus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) wants to have a brightness_hw_changed attribute then the LED_BRIGHT_HW_CHANGED
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) flag must be set in flags before registering. Calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) led_classdev_notify_brightness_hw_changed on a classdev not registered with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) the LED_BRIGHT_HW_CHANGED flag is a bug and will trigger a WARN_ON.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) Hardware accelerated blink of LEDs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) Some LEDs can be programmed to blink without any CPU interaction. To
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) support this feature, a LED driver can optionally implement the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) blink_set() function (see <linux/leds.h>). To set an LED to blinking,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) however, it is better to use the API function led_blink_set(), as it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) will check and implement software fallback if necessary.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) To turn off blinking, use the API function led_brightness_set()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) with brightness value LED_OFF, which should stop any software
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) timers that may have been required for blinking.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) The blink_set() function should choose a user friendly blinking value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) if it is called with `*delay_on==0` && `*delay_off==0` parameters. In this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) case the driver should give back the chosen value through delay_on and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) delay_off parameters to the leds subsystem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) Setting the brightness to zero with brightness_set() callback function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) should completely turn off the LED and cancel the previously programmed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) hardware blinking function, if any.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) Known Issues
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) The LED Trigger core cannot be a module as the simple trigger functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) would cause nightmare dependency issues. I see this as a minor issue
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) compared to the benefits the simple trigger functionality brings. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) rest of the LED subsystem can be modular.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) Future Development
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) At the moment, a trigger can't be created specifically for a single LED.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) There are a number of cases where a trigger might only be mappable to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) particular LED (ACPI?). The addition of triggers provided by the LED driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) should cover this option and be possible to add without breaking the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) current interface.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags