18dab9197SMauro Carvalho Chehab============================== 28dab9197SMauro Carvalho ChehabFlash LED handling under Linux 38dab9197SMauro Carvalho Chehab============================== 48dab9197SMauro Carvalho Chehab 58dab9197SMauro Carvalho ChehabSome LED devices provide two modes - torch and flash. In the LED subsystem 68dab9197SMauro Carvalho Chehabthose modes are supported by LED class (see Documentation/leds/leds-class.rst) 78dab9197SMauro Carvalho Chehaband LED Flash class respectively. The torch mode related features are enabled 88dab9197SMauro Carvalho Chehabby default and the flash ones only if a driver declares it by setting 98dab9197SMauro Carvalho ChehabLED_DEV_CAP_FLASH flag. 108dab9197SMauro Carvalho Chehab 118dab9197SMauro Carvalho ChehabIn order to enable the support for flash LEDs CONFIG_LEDS_CLASS_FLASH symbol 128dab9197SMauro Carvalho Chehabmust be defined in the kernel config. A LED Flash class driver must be 138dab9197SMauro Carvalho Chehabregistered in the LED subsystem with led_classdev_flash_register function. 148dab9197SMauro Carvalho Chehab 158dab9197SMauro Carvalho ChehabFollowing sysfs attributes are exposed for controlling flash LED devices: 168dab9197SMauro Carvalho Chehab(see Documentation/ABI/testing/sysfs-class-led-flash) 178dab9197SMauro Carvalho Chehab 188dab9197SMauro Carvalho Chehab - flash_brightness 198dab9197SMauro Carvalho Chehab - max_flash_brightness 208dab9197SMauro Carvalho Chehab - flash_timeout 218dab9197SMauro Carvalho Chehab - max_flash_timeout 228dab9197SMauro Carvalho Chehab - flash_strobe 238dab9197SMauro Carvalho Chehab - flash_fault 248dab9197SMauro Carvalho Chehab 258dab9197SMauro Carvalho Chehab 268dab9197SMauro Carvalho ChehabV4L2 flash wrapper for flash LEDs 278dab9197SMauro Carvalho Chehab================================= 288dab9197SMauro Carvalho Chehab 298dab9197SMauro Carvalho ChehabA LED subsystem driver can be controlled also from the level of VideoForLinux2 308dab9197SMauro Carvalho Chehabsubsystem. In order to enable this CONFIG_V4L2_FLASH_LED_CLASS symbol has to 318dab9197SMauro Carvalho Chehabbe defined in the kernel config. 328dab9197SMauro Carvalho Chehab 338dab9197SMauro Carvalho ChehabThe driver must call the v4l2_flash_init function to get registered in the 348dab9197SMauro Carvalho ChehabV4L2 subsystem. The function takes six arguments: 358dab9197SMauro Carvalho Chehab 368dab9197SMauro Carvalho Chehab- dev: 378dab9197SMauro Carvalho Chehab flash device, e.g. an I2C device 388dab9197SMauro Carvalho Chehab- of_node: 398dab9197SMauro Carvalho Chehab of_node of the LED, may be NULL if the same as device's 408dab9197SMauro Carvalho Chehab- fled_cdev: 418dab9197SMauro Carvalho Chehab LED flash class device to wrap 428dab9197SMauro Carvalho Chehab- iled_cdev: 438dab9197SMauro Carvalho Chehab LED flash class device representing indicator LED associated with 448dab9197SMauro Carvalho Chehab fled_cdev, may be NULL 458dab9197SMauro Carvalho Chehab- ops: 468dab9197SMauro Carvalho Chehab V4L2 specific ops 478dab9197SMauro Carvalho Chehab 488dab9197SMauro Carvalho Chehab * external_strobe_set 498dab9197SMauro Carvalho Chehab defines the source of the flash LED strobe - 508dab9197SMauro Carvalho Chehab V4L2_CID_FLASH_STROBE control or external source, typically 518dab9197SMauro Carvalho Chehab a sensor, which makes it possible to synchronise the flash 528dab9197SMauro Carvalho Chehab strobe start with exposure start, 538dab9197SMauro Carvalho Chehab * intensity_to_led_brightness and led_brightness_to_intensity 548dab9197SMauro Carvalho Chehab perform 558dab9197SMauro Carvalho Chehab enum led_brightness <-> V4L2 intensity conversion in a device 568dab9197SMauro Carvalho Chehab specific manner - they can be used for devices with non-linear 578dab9197SMauro Carvalho Chehab LED current scale. 588dab9197SMauro Carvalho Chehab- config: 598dab9197SMauro Carvalho Chehab configuration for V4L2 Flash sub-device 608dab9197SMauro Carvalho Chehab 618dab9197SMauro Carvalho Chehab * dev_name 628dab9197SMauro Carvalho Chehab the name of the media entity, unique in the system, 638dab9197SMauro Carvalho Chehab * flash_faults 648dab9197SMauro Carvalho Chehab bitmask of flash faults that the LED flash class 658dab9197SMauro Carvalho Chehab device can report; corresponding LED_FAULT* bit definitions are 668dab9197SMauro Carvalho Chehab available in <linux/led-class-flash.h>, 678dab9197SMauro Carvalho Chehab * torch_intensity 688dab9197SMauro Carvalho Chehab constraints for the LED in TORCH mode 698dab9197SMauro Carvalho Chehab in microamperes, 708dab9197SMauro Carvalho Chehab * indicator_intensity 718dab9197SMauro Carvalho Chehab constraints for the indicator LED 728dab9197SMauro Carvalho Chehab in microamperes, 738dab9197SMauro Carvalho Chehab * has_external_strobe 748dab9197SMauro Carvalho Chehab determines whether the flash strobe source 758dab9197SMauro Carvalho Chehab can be switched to external, 768dab9197SMauro Carvalho Chehab 778dab9197SMauro Carvalho ChehabOn remove the v4l2_flash_release function has to be called, which takes one 788dab9197SMauro Carvalho Chehabargument - struct v4l2_flash pointer returned previously by v4l2_flash_init. 798dab9197SMauro Carvalho ChehabThis function can be safely called with NULL or error pointer argument. 808dab9197SMauro Carvalho Chehab 818dab9197SMauro Carvalho ChehabPlease refer to drivers/leds/leds-max77693.c for an exemplary usage of the 828dab9197SMauro Carvalho Chehabv4l2 flash wrapper. 838dab9197SMauro Carvalho Chehab 848dab9197SMauro Carvalho ChehabOnce the V4L2 sub-device is registered by the driver which created the Media 858dab9197SMauro Carvalho Chehabcontroller device, the sub-device node acts just as a node of a native V4L2 868dab9197SMauro Carvalho Chehabflash API device would. The calls are simply routed to the LED flash API. 878dab9197SMauro Carvalho Chehab 888dab9197SMauro Carvalho ChehabOpening the V4L2 flash sub-device makes the LED subsystem sysfs interface 898dab9197SMauro Carvalho Chehabunavailable. The interface is re-enabled after the V4L2 flash sub-device 908dab9197SMauro Carvalho Chehabis closed. 91