^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) .. _flash-controls:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ***********************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) Flash Control Reference
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) ***********************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) The V4L2 flash controls are intended to provide generic access to flash
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) controller devices. Flash controller devices are typically used in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) digital cameras.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) The interface can support both LED and xenon flash devices. As of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) writing this, there is no xenon flash driver using this interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) .. _flash-controls-use-cases:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) Supported use cases
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) Unsynchronised LED flash (software strobe)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) ------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) Unsynchronised LED flash is controlled directly by the host as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) sensor. The flash must be enabled by the host before the exposure of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) image starts and disabled once it ends. The host is fully responsible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) for the timing of the flash.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) Example of such device: Nokia N900.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) Synchronised LED flash (hardware strobe)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) ----------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) The synchronised LED flash is pre-programmed by the host (power and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) timeout) but controlled by the sensor through a strobe signal from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) sensor to the flash.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) The sensor controls the flash duration and timing. This information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) typically must be made available to the sensor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) LED flash as torch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) LED flash may be used as torch in conjunction with another use case
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) involving camera or individually.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) .. _flash-control-id:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) Flash Control IDs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) ``V4L2_CID_FLASH_CLASS (class)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) The FLASH class descriptor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) ``V4L2_CID_FLASH_LED_MODE (menu)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) Defines the mode of the flash LED, the high-power white LED attached
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) to the flash controller. Setting this control may not be possible in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) presence of some faults. See V4L2_CID_FLASH_FAULT.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) .. flat-table::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) * - ``V4L2_FLASH_LED_MODE_NONE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) - Off.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) * - ``V4L2_FLASH_LED_MODE_FLASH``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) - Flash mode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) * - ``V4L2_FLASH_LED_MODE_TORCH``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) ``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) Defines the source of the flash LED strobe.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) .. tabularcolumns:: |p{7.5cm}|p{10.0cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) .. flat-table::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) * - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) - The flash strobe is triggered by using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) V4L2_CID_FLASH_STROBE control.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) * - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) - The flash strobe is triggered by an external source. Typically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) this is a sensor, which makes it possible to synchronise the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) flash strobe start to exposure start.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) ``V4L2_CID_FLASH_STROBE (button)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) control may not be possible in presence of some faults. See
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) V4L2_CID_FLASH_FAULT.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) ``V4L2_CID_FLASH_STROBE_STOP (button)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) Stop flash strobe immediately.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) ``V4L2_CID_FLASH_STROBE_STATUS (boolean)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) Strobe status: whether the flash is strobing at the moment or not.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) This is a read-only control.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) ``V4L2_CID_FLASH_TIMEOUT (integer)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) Hardware timeout for flash. The flash strobe is stopped after this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) period of time has passed from the start of the strobe.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) ``V4L2_CID_FLASH_INTENSITY (integer)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) Intensity of the flash strobe when the flash LED is in flash mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) if possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) ``V4L2_CID_FLASH_TORCH_INTENSITY (integer)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) Intensity of the flash LED in torch mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) if possible. Setting this control may not be possible in presence of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) some faults. See V4L2_CID_FLASH_FAULT.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) ``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) Intensity of the indicator LED. The indicator LED may be fully
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) independent of the flash LED. The unit should be microamps (uA) if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) ``V4L2_CID_FLASH_FAULT (bitmask)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) Faults related to the flash. The faults tell about specific problems
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) in the flash chip itself or the LEDs attached to it. Faults may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) prevent further use of some of the flash controls. In particular,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) if the fault affects the flash LED. Exactly which faults have such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) an effect is chip dependent. Reading the faults resets the control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) and returns the chip to a usable state if possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) .. tabularcolumns:: |p{8.4cm}|p{9.1cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) .. flat-table::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) * - ``V4L2_FLASH_FAULT_OVER_VOLTAGE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) - Flash controller voltage to the flash LED has exceeded the limit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) specific to the flash controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) * - ``V4L2_FLASH_FAULT_TIMEOUT``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) - The flash strobe was still on when the timeout set by the user ---
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) controllers may set this in all such conditions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) * - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) - The flash controller has overheated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) * - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) - The short circuit protection of the flash controller has been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) triggered.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) * - ``V4L2_FLASH_FAULT_OVER_CURRENT``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) - Current in the LED power supply has exceeded the limit specific to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) the flash controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) * - ``V4L2_FLASH_FAULT_INDICATOR``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) - The flash controller has detected a short or open circuit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) condition on the indicator LED.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) * - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) - Flash controller voltage to the flash LED has been below the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) minimum limit specific to the flash controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) * - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) - The input voltage of the flash controller is below the limit under
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) which strobing the flash at full current will not be possible.The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) condition persists until this flag is no longer set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) * - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) - The temperature of the LED has exceeded its allowed upper limit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) ``V4L2_CID_FLASH_CHARGE (boolean)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) Enable or disable charging of the xenon flash capacitor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) ``V4L2_CID_FLASH_READY (boolean)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) Is the flash ready to strobe? Xenon flashes require their capacitors
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) charged before strobing. LED flashes often require a cooldown period
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) after strobe during which another strobe will not be possible. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) is a read-only control.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags